DOCSP-35951: write operations delete docs #2829

ccho-mongodb · 2024-04-08T04:56:15Z

JIRA:
https://jira.mongodb.org/browse/DOCSP-35951

Staging:
https://preview-mongodbcchomongodb.gatsbyjs.io/laravel/DOCSP-35951-write-operations-delete/fundamentals/write-operations/#delete-documents

Note:
This PR is stacked with all the write operations PRs and is the final section.

Relevant changes:

Content
Code

Checklist

Add tests and ensure they pass
Add an entry to the CHANGELOG.md file
Update documentation for new features

rustagir

a few small things!

rustagir · 2024-04-09T14:27:38Z

docs/fundamentals/write-operations.txt

+- :ref:`Pruning <laravel-model-pruning>`, which lets you define conditions
+  in which a document should be deleted automatically


Suggested change

- :ref:`Pruning <laravel-model-pruning>`, which lets you define conditions

in which a document should be deleted automatically

- :ref:`Pruning <laravel-model-pruning>`, which lets you define conditions

that mark documents for automatic deletion

Thanks for pointing out the unclear wording. Since the conditions don't mark documents directly, so maybe I'll use "define conditions that qualify a document for automatic deletion".

rustagir · 2024-04-09T14:27:54Z

docs/fundamentals/write-operations.txt

+- Call the  ``destroy()`` method on the model to delete a document by the
+  primary key.


Suggested change

- Call the ``destroy()`` method on the model to delete a document by the

primary key.

- Call the ``destroy()`` method on the model to delete a document by matching the

primary key.

I think the existing sentence and suggestion might be omitting a detail necessary to understand what to pass it, so I'll figure out how to reword. Will also update the description in the corresponding section for deleting multiple docs.

rustagir · 2024-04-09T14:32:47Z

docs/fundamentals/write-operations.txt

+The following example shows how to delete a document by calling ``delete()``
+on an instance of the model:


S: separate the three examples into subsections or move into bullet points, but as of now stacking them is a bit confusing

I agree with this and had considered earlier on, but wanted to keep all examples at the same heading level. Both Insert and Update use the same formatting with the same intention.

I think once these sections (Insert, Modify, Delete) are split into individual pages similar to drivers docs are separate pages, these can be their own sections.

In the meantime, I'll add literalinclude captions (including examples in the prior sections) to identify which method is being demonstrated.

rustagir · 2024-04-09T14:33:35Z

docs/fundamentals/write-operations.txt

+Delete Multiple Documents Examples
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can perform deletes on multiple documents in the following ways:


Suggested change

You can perform deletes on multiple documents in the following ways:

You can delete multiple documents in the following ways:

…operations-delete

rustagir

lgtm with a few last comments!

rustagir · 2024-04-10T14:42:48Z

docs/fundamentals/write-operations.txt

+- Call the ``destroy()`` method on the model and pass it a primary key to
+  delete the matching document.


S: revise to avoid the phrasing "pass it"
Ie

Suggested change

- Call the ``destroy()`` method on the model and pass it a primary key to

delete the matching document.

- Call the ``destroy()`` method on the model while passing a primary key to

delete the matching document.

Discussed on Slack. Replacing with a adverbial phrase to describe the first part of the sentence.

docs/fundamentals/write-operations.txt

GromNaN · 2024-04-11T16:44:08Z

docs/fundamentals/write-operations.txt

+- Call the ``destroy()`` method on the model, passing it the primary key of
+  the document to be deleted.
+- Call the ``delete()`` method on an instance of the model.
+- Chain methods to retrieve and delete an instance of a model by calling the
+  ``delete()`` method.


$model->delete() should be the first in the list as it's probably the more used.

The alternate Model::destroy($ids) accepts a single id, a list of ids, or a list of model intances.

Suggested change

- Call the ``destroy()`` method on the model, passing it the primary key of

the document to be deleted.

- Call the ``delete()`` method on an instance of the model.

- Chain methods to retrieve and delete an instance of a model by calling the

``delete()`` method.

- Call the ``$model->delete()`` method on an instance of the model.

- Call the ``Model::destroy($ids)`` method on the model class, 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.

Question:
Is the "$model->delete()" a common way to represent a placeholder for an Eloquent model for a Laravel developer audience?

Otherwise, what would be a common way to explain calling on a method on an instance of a model? I could be wrong, but I suspect the current suggestion might be repetitive (the instance and method are shown, but it's still described as a method).

I believe that code is more explicit than words. This is the convention I use systematically on this project when I want to emphasize the scope of a method.

I've found examples of Model::method in Eloquent doc, but not $model->method. See https://laravel.com/docs/11.x/eloquent#deleting-models

I'm fine with changing conventions, but is this something we could come back to and decide later? I think it might involve updating several of the currently published docs to make them use it consistently. If so, I can ticket that.

docs/fundamentals/write-operations.txt

GromNaN · 2024-04-11T16:50:14Z

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

+
+        // begin model delete one fluent
+        Concert::where('venue', 'Carnegie Hall')
+            ->orderBy('_id')


I don't get the point of ordering for deleting. In fact, it's ignored:

laravel-mongodb/src/Query/Builder.php

Lines 787 to 814 in 95c5b4f

public function delete($id = null)

{

// If an ID is passed to the method, we will set the where clause to check

// the ID to allow developers to simply and quickly remove a single row

// from their database without manually specifying the where clauses.

if ($id !== null) {

$this->where('_id', '=', $id);

}

$wheres = $this->compileWheres();

$options = $this->inheritConnectionOptions();

if (is_int($this->limit)) {

if ($this->limit !== 1) {

throw new LogicException(sprintf('Delete limit can be 1 or null (unlimited). Got %d', $this->limit));

}

$result = $this->collection->deleteOne($wheres, $options);

} else {

$result = $this->collection->deleteMany($wheres, $options);

}

if ($result->isAcknowledged()) {

return $result->getDeletedCount();

}

return 0;

}

I see, so if the where() query filter matched multiple documents, wouldn't it be important to specify the sort order such that it's known which one will surface when calling limit(1), since that's the one that will be deleted? Does that mean that you can't use indexes with sort orders for the query filter part of the delete operation?

If not possible, I should probably include that information.

That's currently not possible. That could be a new feature PHPORM-169

Does that mean that you can't use indexes with sort orders for the query filter part of the delete operation?

Note: from the server's perspective, there is no way to specify an order with a delete operation.

Indexes can certainly be used (and hinted). In the case of a sparse index that might actually have an impact on which document(s) get selected for the deletion.

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

GromNaN · 2024-04-15T09:36:51Z

docs/fundamentals/write-operations.txt

+
+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 permanently.


"permanently" is wrong when the SoftDeletes trait is used. But you mention it just below, so maybe that's okay.

Thanks for providing that perspective, I'll update the text to make that more clear!

Chris Cho and others added 30 commits March 27, 2024 17:15

DOCSP-35948: Write operations

8fbbcc4

add examples

a5a75ca

apply phpcbf formatting

a678179

wip

eea96e5

apply phpcbf formatting

88024a5

add date info

24fdd13

apply phpcbf formatting

77bdbec

update title of read operations

831f06e

grammar fixes

d813f23

DOCSP-35947: write operations - modify documents

a194e60

apply phpcbf formatting

2582bd5

misc fixes

86ff663

rst fixes

4dc106a

fixes

678490e

fix

8ff6872

fix

44eb655

fix rst

60a6cfb

concise sentence

a9d072c

linebreaks

79037d2

double backslash

78bc0e7

fix

1d77153

DOCSP-35949: Write Operations - Upsert

39eb362

apply phpcbf formatting

dfe2019

fix io-codeblock

ebf1cc5

tweaks

2c339bd

apply phpcbf formatting

f2b0412

DOCSP-35946: write operations arrays

cd7f08a

fixes

9ba28be

remove emphasize lines

07530e6

PRR fixes

e6c162f

Chris Cho added 7 commits April 7, 2024 23:07

DOCSP-35951: Write operations - delete documents

4aa7e5c

add include, fix comment

bb3439b

fixes

25a3912

fixes

868d3a6

fix

aee0efe

another fix

2512f78

fix stray text

78df112

ccho-mongodb added the docs label Apr 8, 2024

rustagir requested changes Apr 9, 2024

View reviewed changes

Chris Cho and others added 2 commits April 9, 2024 14:05

PRR fixes

a69a0e7

Merge branch '4.1-base-docs-write-operations' into DOCSP-35951-write-…

022622f

…operations-delete

ccho-mongodb requested a review from rustagir April 9, 2024 18:28

rustagir approved these changes Apr 10, 2024

View reviewed changes

PRR fixes

1018c36

ccho-mongodb marked this pull request as ready for review April 10, 2024 16:15

ccho-mongodb requested a review from a team as a code owner April 10, 2024 16:15

ccho-mongodb requested review from jmikola and removed request for a team April 10, 2024 16:15

norareidy mentioned this pull request Apr 10, 2024

DOCSP-35973: Delete Many usage example #2837

Merged

3 tasks

GromNaN requested review from GromNaN and removed request for jmikola April 11, 2024 14:55

GromNaN reviewed Apr 11, 2024

View reviewed changes

PRR fixes

af90cb7

ccho-mongodb requested a review from GromNaN April 12, 2024 04:36

GromNaN reviewed Apr 12, 2024

View reviewed changes

docs/includes/fundamentals/write-operations/WriteOperationsTest.php Outdated Show resolved Hide resolved

PRR fixes - remove unused variables

8830948

ccho-mongodb requested a review from GromNaN April 12, 2024 13:47

GromNaN approved these changes Apr 15, 2024

View reviewed changes

update wording for delete operations

d07cb68

ccho-mongodb merged commit 95a08ce into mongodb:4.1-base-docs-write-operations Apr 15, 2024

		- :ref:`Pruning <laravel-model-pruning>`, which lets you define conditions
		in which a document should be deleted automatically

		- Call the ``destroy()`` method on the model to delete a document by the
		primary key.

		The following example shows how to delete a document by calling ``delete()``
		on an instance of the model:

	You can perform deletes on multiple documents in the following ways:
	You can delete multiple documents in the following ways:

		- Call the ``destroy()`` method on the model and pass it a primary key to
		delete the matching document.

	public function delete($id = null)
	{
	// If an ID is passed to the method, we will set the where clause to check
	// the ID to allow developers to simply and quickly remove a single row
	// from their database without manually specifying the where clauses.
	if ($id !== null) {
	$this->where('_id', '=', $id);
	}

	$wheres = $this->compileWheres();
	$options = $this->inheritConnectionOptions();

	if (is_int($this->limit)) {
	if ($this->limit !== 1) {
	throw new LogicException(sprintf('Delete limit can be 1 or null (unlimited). Got %d', $this->limit));
	}

	$result = $this->collection->deleteOne($wheres, $options);
	} else {
	$result = $this->collection->deleteMany($wheres, $options);
	}

	if ($result->isAcknowledged()) {
	return $result->getDeletedCount();
	}

	return 0;
	}

DOCSP-35951: write operations delete docs #2829

DOCSP-35951: write operations delete docs #2829

Uh oh!

Conversation

ccho-mongodb commented Apr 8, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Uh oh!

rustagir left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ccho-mongodb Apr 9, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rustagir left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ccho-mongodb Apr 12, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ccho-mongodb commented Apr 8, 2024 •

edited

Loading

ccho-mongodb Apr 9, 2024 •

edited

Loading

ccho-mongodb Apr 12, 2024 •

edited

Loading