Skip to content

Commit 95a08ce

Browse files
author
Chris Cho
authored
DOCSP-35951: write operations delete docs (#2829)
* DOCSP-35948: Fundamentals > Write operations
1 parent acec97f commit 95a08ce

File tree

3 files changed

+335
-8
lines changed

3 files changed

+335
-8
lines changed

‎docs/fundamentals/write-operations.txt

Lines changed: 143 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Write Operations
99
:values: tutorial
1010

1111
.. meta::
12-
:keywords: insert, insert one, update, update one, upsert, code example, mass assignment, push, pull, eloquent model
12+
:keywords: insert, insert one, update, update one, upsert, code example, mass assignment, push, pull, delete, delete many, primary key, destroy, eloquent model
1313

1414
.. contents:: On this page
1515
:local:
@@ -28,7 +28,8 @@ This guide shows you how to perform the following tasks:
2828

2929
- :ref:`laravel-fundamentals-insert-documents`
3030
- :ref:`laravel-fundamentals-modify-documents`
31-
- Delete Documents
31+
- :ref:`laravel-fundamentals-delete-documents`
32+
3233

3334
.. _laravel-fundamentals-write-sample-model:
3435

@@ -98,6 +99,7 @@ This example code performs the following actions:
9899
:dedent:
99100
:start-after: begin model insert one
100101
:end-before: end model insert one
102+
:caption: Insert a document by calling the save() method on an instance.
101103

102104
You can retrieve the inserted document's ``_id`` value by accessing the model's
103105
``id`` member, as shown in the following code example:
@@ -189,6 +191,7 @@ of the model and calling its ``save()`` method:
189191
:dedent:
190192
:start-after: begin model update one save
191193
:end-before: end model update one save
194+
:caption: Update a document by calling the save() method on an instance.
192195

193196
When the ``save()`` method succeeds, the model instance on which you called the
194197
method contains the updated values.
@@ -203,13 +206,9 @@ retrieve and update the first matching document:
203206
:dedent:
204207
:start-after: begin model update one fluent
205208
:end-before: end model update one fluent
209+
:caption: Update the matching document by chaining the update() method.
206210

207-
.. note::
208-
209-
The ``orderBy()`` call sorts the results by the ``_id`` field to
210-
guarantee a consistent sort order. To learn more about sorting in MongoDB,
211-
see the :manual:`Natural order </reference/glossary/#std-term-natural-order>`
212-
glossary entry in the {+server-docs-name+}.
211+
.. include:: /includes/fact-orderby-id.rst
213212

214213
When the ``update()`` method succeeds, the operation returns the number of
215214
documents updated.
@@ -480,3 +479,139 @@ with ``"contemporary"`` in the ``genres`` array field. Click the
480479

481480
To learn more about array update operators, see :manual:`Array Update Operators </reference/operator/update-array/>`
482481
in the {+server-docs-name+}.
482+
483+
.. _laravel-fundamentals-delete-documents:
484+
485+
Delete Documents
486+
----------------
487+
488+
In this section, you can learn how to delete documents from a MongoDB collection
489+
by using {+odm-short+}. Use delete operations to remove data from your MongoDB
490+
database.
491+
492+
This section provides examples of the following delete operations:
493+
494+
- :ref:`Delete one document <laravel-fundamentals-delete-one>`
495+
- :ref:`Delete multiple documents <laravel-fundamentals-delete-many>`
496+
497+
To learn about the Laravel features available in {+odm-short+} that modify
498+
delete behavior, see the following sections:
499+
500+
- :ref:`Soft delete <laravel-model-soft-delete>`, which lets you mark
501+
documents as deleted instead of removing them from the database
502+
- :ref:`Pruning <laravel-model-pruning>`, which lets you define conditions
503+
that qualify a document for automatic deletion
504+
505+
.. _laravel-fundamentals-delete-one:
506+
507+
Delete a Document Examples
508+
~~~~~~~~~~~~~~~~~~~~~~~~~~
509+
510+
You can delete one document in the following ways:
511+
512+
- Call the ``$model->delete()`` method on an instance of the model.
513+
- Call the ``Model::destroy($id)`` method on the model, passing it the id of
514+
the document to be deleted.
515+
- Chain methods to retrieve and delete an instance of a model by calling the
516+
``delete()`` method.
517+
518+
The following example shows how to delete a document by calling ``$model->delete()``
519+
on an instance of the model:
520+
521+
.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php
522+
:language: php
523+
:dedent:
524+
:start-after: begin delete one model
525+
:end-before: end delete one model
526+
:caption: Delete the document by calling the delete() method on an instance.
527+
528+
When the ``delete()`` method succeeds, the operation returns the number of
529+
documents deleted.
530+
531+
If the retrieve part of the call does not match any documents in the collection,
532+
the operation returns ``0``.
533+
534+
The following example shows how to delete a document by passing the value of
535+
its id to the ``Model::destroy($id)`` method:
536+
537+
.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php
538+
:language: php
539+
:dedent:
540+
:start-after: begin model delete by id
541+
:end-before: end model delete by id
542+
:caption: Delete the document by its id value.
543+
544+
When the ``destroy()`` method succeeds, it returns the number of documents
545+
deleted.
546+
547+
If the id value does not match any documents, the ``destroy()`` method
548+
returns returns ``0``.
549+
550+
The following example shows how to chain calls to retrieve the first
551+
matching document and delete it:
552+
553+
.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php
554+
:language: php
555+
:dedent:
556+
:start-after: begin model delete one fluent
557+
:end-before: end model delete one fluent
558+
:caption: Delete the matching document by chaining the delete() method.
559+
560+
.. include:: /includes/fact-orderby-id.rst
561+
562+
When the ``delete()`` method succeeds, it returns the number of documents
563+
deleted.
564+
565+
If the ``where()`` method does not match any documents, the ``delete()`` method
566+
returns returns ``0``.
567+
568+
.. _laravel-fundamentals-delete-many:
569+
570+
Delete Multiple Documents Examples
571+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
572+
573+
You can delete multiple documents in the following ways:
574+
575+
576+
- Call the ``Model::destroy($ids)`` method, passing a list of the ids of the
577+
documents or model instances to be deleted.
578+
- Chain methods to retrieve a Laravel collection object that references
579+
multiple objects and delete them by calling the ``delete()`` method.
580+
581+
The following example shows how to delete a document by passing an array of
582+
id values, represented by ``$ids``, to the ``destroy()`` method:
583+
584+
.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php
585+
:language: php
586+
:dedent:
587+
:start-after: begin model delete multiple by id
588+
:end-before: end model delete multiple by id
589+
:caption: Delete documents by their ids.
590+
591+
.. tip::
592+
593+
The ``destroy()`` method performance suffers when passed large lists. For
594+
better performance, use ``Model::whereIn('id', $ids)->delete()`` instead.
595+
596+
When the ``destroy()`` method succeeds, it returns the number of documents
597+
deleted.
598+
599+
If the id values do not match any documents, the ``destroy()`` method
600+
returns returns ``0``.
601+
602+
The following example shows how to chain calls to retrieve matching documents
603+
and delete them:
604+
605+
.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php
606+
:language: php
607+
:dedent:
608+
:start-after: begin model delete multiple fluent
609+
:end-before: end model delete multiple fluent
610+
:caption: Chain calls to retrieve matching documents and delete them.
611+
612+
When the ``delete()`` method succeeds, it returns the number of documents
613+
deleted.
614+
615+
If the ``where()`` method does not match any documents, the ``delete()`` method
616+
returns ``0``.
617+

‎docs/includes/fact-orderby-id.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
.. note::
2+
3+
The ``orderBy()`` call sorts the results by the ``_id`` field to
4+
guarantee a consistent sort order. To learn more about sorting in MongoDB,
5+
see the :manual:`Natural order </reference/glossary/#std-term-natural-order>`
6+
glossary entry in the {+server-docs-name+}.

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

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -329,4 +329,190 @@ public function testModelPositional(): void
329329
$this->assertContains('contemporary', $result->genres);
330330
$this->assertFalse(in_array('dance-pop', $result->genres));
331331
}
332+
333+
public function testModelDeleteById(): void
334+
{
335+
require_once __DIR__ . '/Concert.php';
336+
Concert::truncate();
337+
338+
$data = [
339+
[
340+
'_id' => 'CH-0401242000',
341+
'performer' => 'Mitsuko Uchida',
342+
'venue' => 'Carnegie Hall',
343+
'genres' => ['classical'],
344+
'ticketsSold' => 2121,
345+
'performanceDate' => new UTCDateTime(Carbon::create(2024, 4, 1, 20, 0, 0, 'EST')),
346+
],
347+
[
348+
'_id' => 'MSG-0212252000',
349+
'performer' => 'Brad Mehldau',
350+
'venue' => 'Philharmonie de Paris',
351+
'genres' => [ 'jazz', 'post-bop' ],
352+
'ticketsSold' => 5745,
353+
'performanceDate' => new UTCDateTime(Carbon::create(2025, 2, 12, 20, 0, 0, 'CET')),
354+
],
355+
[
356+
'_id' => 'MSG-021222000',
357+
'performer' => 'Billy Joel',
358+
'venue' => 'Madison Square Garden',
359+
'genres' => [ 'rock', 'soft rock', 'pop rock' ],
360+
'ticketsSold' => 12852,
361+
'performanceDate' => new UTCDateTime(Carbon::create(2025, 2, 12, 20, 0, 0, 'CET')),
362+
],
363+
[
364+
'_id' => 'SF-06302000',
365+
'performer' => 'The Rolling Stones',
366+
'venue' => 'Soldier Field',
367+
'genres' => [ 'rock', 'pop', 'blues' ],
368+
'ticketsSold' => 59527,
369+
'performanceDate' => new UTCDateTime(Carbon::create(2024, 6, 30, 20, 0, 0, 'CDT')),
370+
],
371+
];
372+
Concert::insert($data);
373+
374+
$this->assertEquals(4, Concert::count());
375+
376+
$id = Concert::first()->id;
377+
378+
// begin model delete by id
379+
$id = 'MSG-0212252000';
380+
Concert::destroy($id);
381+
// end model delete by id
382+
383+
$this->assertEquals(3, Concert::count());
384+
$this->assertNull(Concert::find($id));
385+
}
386+
387+
public function testModelDeleteModel(): void
388+
{
389+
require_once __DIR__ . '/Concert.php';
390+
Concert::truncate();
391+
392+
$data = [
393+
[
394+
'performer' => 'Mitsuko Uchida',
395+
'venue' => 'Carnegie Hall',
396+
],
397+
];
398+
Concert::insert($data);
399+
400+
// begin delete one model
401+
$concert = Concert::first();
402+
$concert->delete();
403+
// end delete one model
404+
405+
$this->assertEquals(0, Concert::count());
406+
}
407+
408+
public function testModelDeleteFirst(): void
409+
{
410+
require_once __DIR__ . '/Concert.php';
411+
Concert::truncate();
412+
413+
$data = [
414+
[
415+
'performer' => 'Mitsuko Uchida',
416+
'venue' => 'Carnegie Hall',
417+
],
418+
[
419+
'performer' => 'Brad Mehldau',
420+
'venue' => 'Philharmonie de Paris',
421+
],
422+
[
423+
'performer' => 'Billy Joel',
424+
'venue' => 'Madison Square Garden',
425+
],
426+
[
427+
'performer' => 'The Rolling Stones',
428+
'venue' => 'Soldier Field',
429+
],
430+
];
431+
Concert::insert($data);
432+
433+
// begin model delete one fluent
434+
Concert::where('venue', 'Carnegie Hall')
435+
->limit(1)
436+
->delete();
437+
// end model delete one fluent
438+
439+
$this->assertEquals(3, Concert::count());
440+
}
441+
442+
public function testModelDeleteMultipleById(): void
443+
{
444+
require_once __DIR__ . '/Concert.php';
445+
Concert::truncate();
446+
$data = [
447+
[
448+
'_id' => 3,
449+
'performer' => 'Mitsuko Uchida',
450+
'venue' => 'Carnegie Hall',
451+
],
452+
[
453+
'_id' => 5,
454+
'performer' => 'Brad Mehldau',
455+
'venue' => 'Philharmonie de Paris',
456+
],
457+
[
458+
'_id' => 7,
459+
'performer' => 'Billy Joel',
460+
'venue' => 'Madison Square Garden',
461+
],
462+
[
463+
'_id' => 9,
464+
'performer' => 'The Rolling Stones',
465+
'venue' => 'Soldier Field',
466+
],
467+
];
468+
Concert::insert($data);
469+
470+
// begin model delete multiple by id
471+
$ids = [3, 5, 7, 9];
472+
Concert::destroy($ids);
473+
// end model delete multiple by id
474+
475+
$this->assertEquals(0, Concert::count());
476+
}
477+
478+
public function testModelDeleteMultiple(): void
479+
{
480+
require_once __DIR__ . '/Concert.php';
481+
Concert::truncate();
482+
483+
$data = [
484+
[
485+
'performer' => 'Mitsuko Uchida',
486+
'venue' => 'Carnegie Hall',
487+
'genres' => ['classical'],
488+
'ticketsSold' => 2121,
489+
],
490+
[
491+
'performer' => 'Brad Mehldau',
492+
'venue' => 'Philharmonie de Paris',
493+
'genres' => [ 'jazz', 'post-bop' ],
494+
'ticketsSold' => 5745,
495+
],
496+
[
497+
'performer' => 'Billy Joel',
498+
'venue' => 'Madison Square Garden',
499+
'genres' => [ 'rock', 'soft rock', 'pop rock' ],
500+
'ticketsSold' => 12852,
501+
],
502+
[
503+
'performer' => 'The Rolling Stones',
504+
'venue' => 'Soldier Field',
505+
'genres' => [ 'rock', 'pop', 'blues' ],
506+
'ticketsSold' => 59527,
507+
],
508+
];
509+
Concert::insert($data);
510+
511+
// begin model delete multiple fluent
512+
Concert::where('ticketsSold', '>', 7500)
513+
->delete();
514+
// end model delete multiple fluent
515+
516+
$this->assertEquals(2, Concert::count());
517+
}
332518
}

0 commit comments

Comments
 (0)