[Pending PR] Document findOrNew, firstOrCreate & similar methods on Entry & Term query builders

content/collections/repositories/entry-repository.md

@@ -22,7 +22,12 @@ 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 the entry cannot be found. |
+| `findOrFail($id)` | Get Entry by `id`. Throws an `EntryNotFoundException` when entry can not be found. |
+| `findOrNew($id)` | Finds Entry by `id` or returns fresh `Entry` instance.  |
+| `findOr($id, $callback)` | Finds Entry by `id` or call a callback. |
+| `firstOrNew($attributes, $values)` | Finds entry with the provided `$attributes`. If one can't be found, a new `Entry` instance will be returned with `$values`. |
+| `firstOrCreate($attributes, $values)` | Finds entry with the provided `$attributes`. If one can't be found, a new `Entry` instance will be returned and saved with `$values`. |
+| `updateOrCreate($attributes, $values)` | Finds entry with the provided `$attributes` and updates it using provided `$values`. If one can't be found, a new `Entry` instance will be returned and saved. |
 | `query()` | Query Builder |
 | `whereCollection($handle)` | Get all Entries in a `Collection` |
 | `whereInCollection([$handles])` | Get all Entries in an array of `Collections` |
@@ -182,6 +187,31 @@ Entry::query()
 ```
 :::
 
+### Find entry or call a callback
+
+```php
+Entry::query()
+  ->where('collection', 'news')
+  ->findOr('my-entry', function () {
+    return Entry::make()->collection('news')->set('title', 'Breaking news');
+  );
+```
+
+This can also be simplified to `Entry::findOr('my-entry', ...)`.
+
+### Find entry or create an entry
+
+```php
+Entry::query()
+  ->where('collection', 'news')
+  ->firstOrCreate(
+    ['slug' => 'breaking-news'],
+    ['title' => 'Breaking News']
+  );
+```
+
+This can also be simplified to `Entry::firstOrCreate($attributes, $values)`
+
 ## Creating
 
 Start by making an instance of an entry with the `make` method.

content/collections/repositories/term-repository.md

@@ -24,6 +24,11 @@ use Statamic\Facades\Term;
 | `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. |
+| `findOrNew($id)` | Finds Term by `id` or returns fresh `Term` instance.  |
+| `findOr($id, $callback)` | Finds Term by `id` or call a callback. |
+| `firstOrNew($attributes, $values)` | Finds term with the provided `$attributes`. If one can't be found, a new `Term` instance will be returned with `$values`. |
+| `firstOrCreate($attributes, $values)` | Finds term with the provided `$attributes`. If one can't be found, a new `Term` instance will be returned and saved with `$values`. |
+| `updateOrCreate($attributes, $values)` | Finds term with the provided `$attributes` and updates it using provided `$values`. If one can't be found, a new `Term` instance will be returned and saved. |
 | `query()` | Query Builder |
 | `make()` | Makes a new `Term` instance |
 
@@ -83,6 +88,31 @@ Term::query()
     ->get();
 ```
 
+### Find term or call a callback
+
+```php
+Term::query()
+  ->where('taxonomy', 'tags')
+  ->findOr('my-term', function () {
+    return Term::make()->taxonomy('tags')->set('title', 'Blog');
+  );
+```
+
+This can also be simplified to `Term::findOr('my-term', ...)`.
+
+### Find entry or create an entry
+
+```php
+Term::query()
+  ->where('taxonomy', 'tags')
+  ->firstOrCreate(
+    ['slug' => 'blog'],
+    ['title' => 'Blog']
+  );
+```
+
+This can also be simplified to `Term::firstOrCreate($attributes, $values)`
+
 
 ## Creating