DOCSP-35951: write operations delete docs

docs/fundamentals/write-operations.txt

@@ -9,7 +9,7 @@ Write Operations
    :values: tutorial
 
 .. meta::
-   :keywords: insert, insert one, update, update one, upsert, code example, mass assignment, push, pull, eloquent model
+   :keywords: insert, insert one, update, update one, upsert, code example, mass assignment, push, pull, delete, delete many, primary key, destroy, eloquent model
 
 .. contents:: On this page
    :local:
@@ -28,7 +28,8 @@ This guide shows you how to perform the following tasks:
 
 - :ref:`laravel-fundamentals-insert-documents`
 - :ref:`laravel-fundamentals-modify-documents`
-- Delete Documents
+- :ref:`laravel-fundamentals-delete-documents`
+
 
 .. _laravel-fundamentals-write-sample-model:
 
@@ -98,6 +99,7 @@ This example code performs the following actions:
    :dedent:
    :start-after: begin model insert one
    :end-before: end model insert one
+   :caption: Insert a document by calling the save() method on an instance.
 
 You can retrieve the inserted document's ``_id`` value by accessing the model's
 ``id`` member, as shown in the following code example:
@@ -189,6 +191,7 @@ of the model and calling its ``save()`` method:
    :dedent:
    :start-after: begin model update one save
    :end-before: end model update one save
+   :caption: Update a document by calling the save() method on an instance.
 
 When the ``save()`` method succeeds, the model instance on which you called the
 method contains the updated values.
@@ -203,13 +206,9 @@ retrieve and update the first matching document:
    :dedent:
    :start-after: begin model update one fluent
    :end-before: end model update one fluent
+   :caption: Update the matching document by chaining the update() method.
 
-.. note::
-
-   The ``orderBy()`` call sorts the results by the ``_id`` field to
-   guarantee a consistent sort order. To learn more about sorting in MongoDB,
-   see the :manual:`Natural order </reference/glossary/#std-term-natural-order>`
-   glossary entry in the {+server-docs-name+}.
+.. include:: /includes/fact-orderby-id.rst
 
 When the ``update()`` method succeeds, the operation returns the number of
 documents updated.
@@ -480,3 +479,139 @@ with ``"contemporary"`` in the ``genres`` array field. Click the
 
 To learn more about array update operators, see :manual:`Array Update Operators </reference/operator/update-array/>`
 in the {+server-docs-name+}.
+
+.. _laravel-fundamentals-delete-documents:
+
+Delete Documents
+----------------
+
+In this section, you can learn how to delete documents from a MongoDB collection
+by using {+odm-short+}. Use delete operations to remove data from your MongoDB
+database.
+
+This section provides examples of the following delete operations:
+
+- :ref:`Delete one document <laravel-fundamentals-delete-one>`
+- :ref:`Delete multiple documents <laravel-fundamentals-delete-many>`
+
+To learn about the Laravel features available in {+odm-short+} that modify
+delete behavior, see the following sections:
+
+- :ref:`Soft delete <laravel-model-soft-delete>`, which lets you mark
+  documents as deleted instead of removing them from the database
+- :ref:`Pruning <laravel-model-pruning>`, which lets you define conditions
+  that qualify a document for automatic deletion
+
+.. _laravel-fundamentals-delete-one:
+
+Delete a Document Examples
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can delete one document in the following ways:
+
+- Call the ``$model->delete()`` method on an instance of the model.
+- Call the ``Model::destroy($id)`` method on the model, passing it the id of
+  the document to be deleted.
+- Chain methods to retrieve and delete an instance of a model by calling the
+  ``delete()`` method.
+
+The following example shows how to delete a document by calling ``$model->delete()``
+on an instance of the model:
+
+.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php
+   :language: php
+   :dedent:
+   :start-after: begin delete one model
+   :end-before: end delete one model
+   :caption: Delete the document by calling the delete() method on an instance.
+
+When the ``delete()`` method succeeds, the operation returns the number of
+documents deleted.
+
+If the retrieve part of the call does not match any documents in the collection,
+the operation returns ``0``.
+
+The following example shows how to delete a document by passing the value of
+its id to the ``Model::destroy($id)`` method:
+
+.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php
+   :language: php
+   :dedent:
+   :start-after: begin model delete by id
+   :end-before: end model delete by id
+   :caption: Delete the document by its id value.
+
+When the ``destroy()`` method succeeds, it returns the number of documents
+deleted.
+
+If the id value does not match any documents, the ``destroy()`` method
+returns returns ``0``.
+
+The following example shows how to chain calls to retrieve the first
+matching document and delete it:
+
+.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php
+   :language: php
+   :dedent:
+   :start-after: begin model delete one fluent
+   :end-before: end model delete one fluent
+   :caption: Delete the matching document by chaining the delete() method.
+
+.. include:: /includes/fact-orderby-id.rst
+
+When the ``delete()`` method succeeds, it returns the number of documents
+deleted.
+
+If the ``where()`` method does not match any documents, the ``delete()`` method
+returns returns ``0``.
+
+.. _laravel-fundamentals-delete-many:
+
+Delete Multiple Documents Examples
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can delete multiple documents in the following ways:
+
+
+- Call the ``Model::destroy($ids)`` method, passing a list of the ids of the
+  documents or model instances to be deleted.
+- Chain methods to retrieve a Laravel collection object that references
+  multiple objects and delete them by calling the ``delete()`` method.
+
+The following example shows how to delete a document by passing an array of
+id values, represented by ``$ids``, to the ``destroy()`` method:
+
+.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php
+   :language: php
+   :dedent:
+   :start-after: begin model delete multiple by id
+   :end-before: end model delete multiple by id
+   :caption: Delete documents by their ids.
+
+.. tip::
+
+   The ``destroy()`` method performance suffers when passed large lists. For
+   better performance, use ``Model::whereIn('id', $ids)->delete()`` instead.
+
+When the ``destroy()`` method succeeds, it returns the number of documents
+deleted.
+
+If the id values do not match any documents, the ``destroy()`` method
+returns returns ``0``.
+
+The following example shows how to chain calls to retrieve matching documents
+and delete them:
+
+.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php
+   :language: php
+   :dedent:
+   :start-after: begin model delete multiple fluent
+   :end-before: end model delete multiple fluent
+   :caption: Chain calls to retrieve matching documents and delete them.
+
+When the ``delete()`` method succeeds, it returns the number of documents
+deleted.
+
+If the ``where()`` method does not match any documents, the ``delete()`` method
+returns ``0``.
+

docs/includes/fact-orderby-id.rst

@@ -0,0 +1,6 @@
+.. note::
+
+   The ``orderBy()`` call sorts the results by the ``_id`` field to
+   guarantee a consistent sort order. To learn more about sorting in MongoDB,
+   see the :manual:`Natural order </reference/glossary/#std-term-natural-order>`
+   glossary entry in the {+server-docs-name+}.

docs/includes/fundamentals/write-operations/WriteOperationsTest.php

@@ -329,4 +329,190 @@ public function testModelPositional(): void
         $this->assertContains('contemporary', $result->genres);
         $this->assertFalse(in_array('dance-pop', $result->genres));
     }
+
+    public function testModelDeleteById(): void
+    {
+        require_once __DIR__ . '/Concert.php';
+        Concert::truncate();
+
+        $data = [
+            [
+                '_id' => 'CH-0401242000',
+                'performer' => 'Mitsuko Uchida',
+                'venue' => 'Carnegie Hall',
+                'genres' => ['classical'],
+                'ticketsSold' => 2121,
+                'performanceDate' => new UTCDateTime(Carbon::create(2024, 4, 1, 20, 0, 0, 'EST')),
+            ],
+            [
+                '_id' => 'MSG-0212252000',
+                'performer' => 'Brad Mehldau',
+                'venue' => 'Philharmonie de Paris',
+                'genres' => [ 'jazz', 'post-bop' ],
+                'ticketsSold' => 5745,
+                'performanceDate' => new UTCDateTime(Carbon::create(2025, 2, 12, 20, 0, 0, 'CET')),
+            ],
+            [
+                '_id' => 'MSG-021222000',
+                'performer' => 'Billy Joel',
+                'venue' => 'Madison Square Garden',
+                'genres' => [ 'rock', 'soft rock', 'pop rock' ],
+                'ticketsSold' => 12852,
+                'performanceDate' => new UTCDateTime(Carbon::create(2025, 2, 12, 20, 0, 0, 'CET')),
+            ],
+            [
+                '_id' => 'SF-06302000',
+                'performer' => 'The Rolling Stones',
+                'venue' => 'Soldier Field',
+                'genres' => [ 'rock', 'pop', 'blues' ],
+                'ticketsSold' => 59527,
+                'performanceDate' => new UTCDateTime(Carbon::create(2024, 6, 30, 20, 0, 0, 'CDT')),
+            ],
+        ];
+        Concert::insert($data);
+
+        $this->assertEquals(4, Concert::count());
+
+        $id = Concert::first()->id;
+
+        // begin model delete by id
+        $id = 'MSG-0212252000';
+        Concert::destroy($id);
+        // end model delete by id
+
+        $this->assertEquals(3, Concert::count());
+        $this->assertNull(Concert::find($id));
+    }
+
+    public function testModelDeleteModel(): void
+    {
+        require_once __DIR__ . '/Concert.php';
+        Concert::truncate();
+
+        $data = [
+            [
+                'performer' => 'Mitsuko Uchida',
+                'venue' => 'Carnegie Hall',
+            ],
+        ];
+        Concert::insert($data);
+
+        // begin delete one model
+        $concert = Concert::first();
+        $concert->delete();
+        // end delete one model
+
+        $this->assertEquals(0, Concert::count());
+    }
+
+    public function testModelDeleteFirst(): void
+    {
+        require_once __DIR__ . '/Concert.php';
+        Concert::truncate();
+
+        $data = [
+            [
+                'performer' => 'Mitsuko Uchida',
+                'venue' => 'Carnegie Hall',
+            ],
+            [
+                'performer' => 'Brad Mehldau',
+                'venue' => 'Philharmonie de Paris',
+            ],
+            [
+                'performer' => 'Billy Joel',
+                'venue' => 'Madison Square Garden',
+            ],
+            [
+                'performer' => 'The Rolling Stones',
+                'venue' => 'Soldier Field',
+            ],
+        ];
+        Concert::insert($data);
+
+        // begin model delete one fluent
+        Concert::where('venue', 'Carnegie Hall')
+            ->limit(1)
+            ->delete();
+        // end model delete one fluent
+
+        $this->assertEquals(3, Concert::count());
+    }
+
+    public function testModelDeleteMultipleById(): void
+    {
+        require_once __DIR__ . '/Concert.php';
+        Concert::truncate();
+        $data = [
+            [
+                '_id' => 3,
+                'performer' => 'Mitsuko Uchida',
+                'venue' => 'Carnegie Hall',
+            ],
+            [
+                '_id' => 5,
+                'performer' => 'Brad Mehldau',
+                'venue' => 'Philharmonie de Paris',
+            ],
+            [
+                '_id' => 7,
+                'performer' => 'Billy Joel',
+                'venue' => 'Madison Square Garden',
+            ],
+            [
+                '_id' => 9,
+                'performer' => 'The Rolling Stones',
+                'venue' => 'Soldier Field',
+            ],
+        ];
+        Concert::insert($data);
+
+        // begin model delete multiple by id
+        $ids = [3, 5, 7, 9];
+        Concert::destroy($ids);
+        // end model delete multiple by id
+
+        $this->assertEquals(0, Concert::count());
+    }
+
+    public function testModelDeleteMultiple(): void
+    {
+        require_once __DIR__ . '/Concert.php';
+        Concert::truncate();
+
+        $data = [
+            [
+                'performer' => 'Mitsuko Uchida',
+                'venue' => 'Carnegie Hall',
+                'genres' => ['classical'],
+                'ticketsSold' => 2121,
+            ],
+            [
+                'performer' => 'Brad Mehldau',
+                'venue' => 'Philharmonie de Paris',
+                'genres' => [ 'jazz', 'post-bop' ],
+                'ticketsSold' => 5745,
+            ],
+            [
+                'performer' => 'Billy Joel',
+                'venue' => 'Madison Square Garden',
+                'genres' => [ 'rock', 'soft rock', 'pop rock' ],
+                'ticketsSold' => 12852,
+            ],
+            [
+                'performer' => 'The Rolling Stones',
+                'venue' => 'Soldier Field',
+                'genres' => [ 'rock', 'pop', 'blues' ],
+                'ticketsSold' => 59527,
+            ],
+        ];
+        Concert::insert($data);
+
+        // begin model delete multiple fluent
+        Concert::where('ticketsSold', '>', 7500)
+            ->delete();
+        // end model delete multiple fluent
+
+        $this->assertEquals(2, Concert::count());
+    }
 }