[5.x] Document new findOrFail methods on repositories (#1305)

* Tweak wording on "Entry Repository" page

* Document `findOrFail` on other repositories

Author: duncanmcclean

content/collections/repositories/asset-container-repository.md

@@ -26,6 +26,7 @@ use Statamic\Facades\AssetContainer;
 | `all()` | Get all AssetContainers |
 | `find($id)` | Get AssetContainer by `id` |
 | `findByHandle($handle)` | Get AssetContainer by `handle` |
+| `findOrFail($id)` | Get AssetContainer by `id`. Throws an `AssetContainerNotFoundException` when the asset container cannot be found. |
 | `queryAssets()` | Query Builder for the AssetContainer's [Assets](#assets) |
 | `make()` | Makes a new AssetContainer instance |
 
@@ -45,6 +46,12 @@ $videos->queryAssets()
     ->get();
 ```
 
+When an asset container can't be found, the `AssetContainer::find()` method will return `null`. If you'd prefer an exception be thrown, you may use the `findOrFail` method:
+
+```php
+AssetContainer::findOrFail('videos');
+```
+
 ## Creating
 
 Start by making an instance of an asset container with the `make` method. You can pass the handle into it.
@@ -71,4 +78,3 @@ Finally, save it.
 ```php
 $container->save();
 ```
-

content/collections/repositories/asset-repository.md

@@ -20,12 +20,13 @@ use Statamic\Facades\Asset;
 | Methods | Description |
 | ------- | ----------- |
 | `all()` | Get all Assets |
-| `find()` | Get Asset by `filename` |
-| `findByPath()` | Get Asset by `path` |
-| `findByUrl()` | Get Asset by `url` |
+| `find($filename)` | Get Asset by `filename` |
+| `findByPath($path)` | Get Asset by `path` |
+| `findByUrl($url)` | Get Asset by `url` |
+| `findOrFail($filename)` | Get Asset by `filename`. Throws an `AssetNotFoundException` when the asset cannot be found. |
 | `query()` | Query Builder |
-| `whereContainer()` | Find Assets by [AssetContainer](#asset-container) |
-| `whereFolder()` | Find Assets in a filesystem folder |
+| `whereContainer($container)` | Find Assets by [AssetContainer](#asset-container) |
+| `whereFolder($folder)` | Find Assets in a filesystem folder |
 | `make()` | Makes a new `Asset` instance |
 
 :::tip

content/collections/repositories/collection-repository.md

@@ -23,7 +23,8 @@ use Statamic\Facades\Collection;
 | `all()` | Get all Collections |
 | `find($id)` | Get Collection by `id` |
 | `findByHandle($handle)` | Get Collection by `handle` |
-| `findByMount($mount)` | Get Asset by mounted entry `id` |
+| `findByMount($mount)` | Get Collection by mounted entry `id` |
+| `findOrFail($id)` | Get Collection by `id`. Throws a `CollectionNotFoundException` when the collection cannot be found. |
 | `handleExists($handle)` | Check to see if `Collection` exists |
 | `handles()` | Get all `Collection` handles |
 | `queryEntries()` | Query Builder for [Entries](/repositories/entry-repository) |
@@ -44,6 +45,12 @@ $blog = Collection::find('blog');
 $blog->queryEntries()->get();
 ```
 
+When a collection can't be found, the `Collection::find()` method will return `null`. If you'd prefer an exception be thrown, you may use the `findOrFail` method:
+
+```php
+Collection::findOrFail('blog');
+```
+
 ## Creating
 
 Start by making an instance of a collection with the `make` method. You can pass the handle into it.

content/collections/repositories/entry-repository.md

@@ -22,7 +22,7 @@ use Statamic\Facades\Entry;
 | `all()` | Get all Entries |
 | `find($id)` | Get Entry by `id` |
 | `findByUri($uri, $site)` | Get Entry by `uri`, optionally in a site |
-| `findOrFail($id)` | Get Entry by `id`. Throws an `EntryNotFoundException` when entry can not be found. |
+| `findOrFail($id)` | Get Entry by `id`. Throws an `EntryNotFoundException` when the entry cannot be found. |
 | `query()` | Query Builder |
 | `whereCollection($handle)` | Get all Entries in a `Collection` |
 | `whereInCollection([$handles])` | Get all Entries in an array of `Collections` |
@@ -41,7 +41,7 @@ Entry::query()->where('id', 123)->first();
 Entry::find(123);
 ```
 
-When an entry can't be found, the `Entry::find()` method will return `null`. If you'd prefer an exception be thrown, you can use the `findOrFail` method:
+When an entry can't be found, the `Entry::find()` method will return `null`. If you'd prefer an exception be thrown, you may use the `findOrFail` method:
 
 ```php
 Entry::findOrFail(123);

content/collections/repositories/form-repository.md

@@ -20,6 +20,7 @@ use Statamic\Facades\Form;
 | ------- | ----------- |
 | `all()` | Get all Forms |
 | `find($handle)` | Get Form by `handle` |
+| `findOrFail($handle)` | Get Form by `handle`. Throws a `FormNotFoundException` when the form cannot be found. |
 | `make()` | Makes a new `Form` instance |
 
 :::tip
@@ -36,6 +37,12 @@ The `handle` is the name of the form's YAML file.
 Form::find('postbox');
 ```
 
+When a form can't be found, the `Form::find()` method will return `null`. If you'd prefer an exception be thrown, you may use the `findOrFail` method:
+
+```php
+Form::findOrFail('postbox');
+```
+
 #### Get all forms from your site
 
 ```php

content/collections/repositories/global-repository.md

@@ -20,6 +20,7 @@ use Statamic\Facades\GlobalSet;
 | `all()` | Get all GlobalSets |
 | `find($id)` | Get GlobalSets by `id` |
 | `findByHandle($handle)` | Get GlobalSets by `handle` |
+| `findOrFail($id)` | Get GlobalSets by `id`. Throws a `GlobalSetNotFoundException` when the global set cannot be found. |
 | `make()` | Makes a new `GlobalSet` instance |
 
 ## Querying

content/collections/repositories/taxonomy-repository.md

@@ -24,6 +24,7 @@ use Statamic\Facades\Taxonomy;
 | `find($id)` | Get Taxonomy by `id` |
 | `findByHandle($handle)` | Get Taxonomy by `handle` |
 | `findByUri($mount)` | Get Taxonomy by `uri` |
+| `findOrFail($id)` | Get Taxonomy by `id`. Throws a `TaxonomyNotFoundException` when the taxonomy cannot be found. |
 | `handleExists($handle)` | Check to see if `Taxonomy` exists |
 | `handles()` | Get all `Taxonomy` handles |
 | `queryTerms()` | Query Builder for [Terms](/content-queries/term-repository) |
@@ -43,6 +44,12 @@ $tags = Taxonomy::find('tags');
 $tags->queryTerms()->get();
 ```
 
+When a taxonomy can't be found, the `Taxonomy::find()` method will return `null`. If you'd prefer an exception be thrown, you may use the `findOrFail` method:
+
+```php
+Taxonomy::findOrFail('tags');
+```
+
 ## Creating
 
 Start by making an instance of a taxonomy with the `make` method. You can pass the handle into it.

content/collections/repositories/term-repository.md

@@ -23,6 +23,7 @@ use Statamic\Facades\Term;
 | `all()` | Get all Terms |
 | `find($id)` | Get Term by `id` |
 | `findByUri($uri)` | Get Term by `uri` |
+| `findOrFail($id)` | Get Term by `id`. Throws a `TermNotFoundException` when the term cannot be found. |
 | `query()` | Query Builder |
 | `make()` | Makes a new `Term` instance |
 

content/collections/repositories/user-repository.md

@@ -24,6 +24,7 @@ use Statamic\Facades\User;
 | `find($id)` | Get User by `id` |
 | `findByEmail($email)` | Get User by `email` |
 | `findByOAuthID($provider, $id)` | Get User by an ID from an OAuth provider  |
+| `findOrFail($id)` | Get User by `id`. Throws a `UserNotFoundException` when the user cannot be found. |
 | `query()` | Query Builder |
 | `make()` | Makes a new `User` instance |
 
@@ -40,6 +41,12 @@ User::query()
 User::find('abc123');
 ```
 
+When a user can't be found, the `User::find()` method will return `null`. If you'd prefer an exception be thrown, you may use the `findOrFail` method:
+
+```php
+User::findOrFail('abc123');
+```
+
 #### Get a user by email
 
 ```php