diff --git a/docs/fundamentals.txt b/docs/fundamentals.txt new file mode 100644 index 000000000..041388350 --- /dev/null +++ b/docs/fundamentals.txt @@ -0,0 +1,25 @@ +.. _laravel_fundamentals: + +============ +Fundamentals +============ + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: php framework, odm + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /fundamentals/read-operations + /fundamentals/write-operations + +Learn how to use the {+odm-long+} to perform the following tasks: + +- :ref:`Read Operations ` +- :ref:`Write Operations ` + diff --git a/docs/retrieve.txt b/docs/fundamentals/read-operations.txt similarity index 99% rename from docs/retrieve.txt rename to docs/fundamentals/read-operations.txt index b607d3d4f..ff6c7814f 100644 --- a/docs/retrieve.txt +++ b/docs/fundamentals/read-operations.txt @@ -1,8 +1,9 @@ .. _laravel-fundamentals-retrieve: +.. _laravel-fundamentals-read-ops: -============== -Retrieve Data -============== +=============== +Read Operations +=============== .. facet:: :name: genre diff --git a/docs/fundamentals/write-operations.txt b/docs/fundamentals/write-operations.txt new file mode 100644 index 000000000..5afcc5010 --- /dev/null +++ b/docs/fundamentals/write-operations.txt @@ -0,0 +1,142 @@ +.. _laravel-fundamentals-write-ops: + +================ +Write Operations +================ + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :keywords: insert, insert one, update, update one, upsert, delete, delete many, code example, mass assignment, eloquent model + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to use {+odm-short+} to perform +**write operations** on your MongoDB collections. Write operations include +inserting, updating, and deleting data based on specified criteria. + +This guide shows you how to perform the following tasks: + +- :ref:`laravel-fundamentals-insert-documents` +- Modify Documents +- Delete Documents + +.. _laravel-fundamentals-insert-documents: + +Insert Documents +---------------- + +In this section, you can learn how to insert documents into MongoDB collections +from your Laravel application by using the {+odm-long+}. + +When you insert the documents, ensure the data does not violate any +unique indexes on the collection. When inserting the first document of a +collection or creating a new collection, MongoDB automatically creates a +unique index on the ``_id`` field. + +For more information on creating indexes on MongoDB collections by using the +Laravel schema builder, see the :ref:`laravel-eloquent-indexes` section +of the Schema Builder documentation. + +This section uses the following example model class to demonstrate how to +use Eloquent models to perform insert operations: + +.. literalinclude:: /includes/fundamentals/write-operations/Concert.php + :language: php + :dedent: + :caption: Concert.php + +.. tip:: + + The ``$fillable`` attribute lets you use Laravel mass assignment for insert + operations. To learn more about mass assignment, see :ref:`laravel-model-mass-assignment` + in the Eloquent Model Class documentation. + + The ``$casts`` attribute instructs Laravel to convert attributes to common + data types. To learn more, see `Attribute Casting `__ + in the Laravel documentation. + +To learn more about Eloquent models in {+odm-short+}, see the :ref:`laravel-eloquent-models` +section. + +Insert a Document Examples +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These examples show how to use the ``save()`` Eloquent method to insert an +instance of a ``Concert`` model as a MongoDB document. + +When the ``save()`` method succeeds, you can access the model instance on +which you called the method. If the operation fails, the model instance is +assigned ``null``. + +This example code performs the following actions: + +- Creates a new instance of the ``Concert`` model +- Assigns string values to the ``performer`` and ``venue`` fields +- Assigns a date to the ``performanceDate`` field by using the ``Carbon`` + package +- Inserts the document by calling the ``save()`` method + +.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php + :language: php + :dedent: + :start-after: begin model insert one + :end-before: end model insert one + +You can retrieve the inserted document's ``_id`` value by accessing the model's +``id`` member as shown in the following code example: + +.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php + :language: php + :dedent: + :start-after: begin inserted id + :end-before: end inserted id + +If you enable mass assignment by defining either the ``$fillable`` or +``$guarded`` attributes, you can use the Eloquent model ``create()`` method +to perform the insert in a single call as shown in the following example: + +.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php + :language: php + :dedent: + :start-after: begin model insert one mass assign + :end-before: end model insert one mass assign + +To learn more about the Carbon PHP API extension, see the +:github:`Carbon ` GitHub repository. + +Insert Multiple Documents Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This example shows how to use the ``insert()`` Eloquent method to insert +multiple instances of a ``Concert`` model as MongoDB documents. This bulk +insert method reduces the number of calls your application needs to make +to save the documents. + +When the ``insert()`` method succeeds, it returns the value ``1``. If it +fails, it throws an exception. + +The example code saves multiple models in a single call by passing them as +an array to the ``insert()`` method: + +.. note:: + + This example wraps the dates in the `MongoDB\BSON\UTCDateTime <{+phplib-api+}/class.mongodb-bson-utcdatetime.php>`__ + class to convert it to a type MongoDB can serialize because Laravel + skips attribute casting on bulk insert operations. + +.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php + :language: php + :dedent: + :start-after: begin model insert many + :end-before: end model insert many + diff --git a/docs/includes/fundamentals/write-operations/Concert.php b/docs/includes/fundamentals/write-operations/Concert.php new file mode 100644 index 000000000..9eaa51139 --- /dev/null +++ b/docs/includes/fundamentals/write-operations/Concert.php @@ -0,0 +1,12 @@ + 'datetime']; +} diff --git a/docs/includes/fundamentals/write-operations/WriteOperationsTest.php b/docs/includes/fundamentals/write-operations/WriteOperationsTest.php new file mode 100644 index 000000000..365d86dd3 --- /dev/null +++ b/docs/includes/fundamentals/write-operations/WriteOperationsTest.php @@ -0,0 +1,100 @@ +performer = 'Mitsuko Uchida'; + $concert->venue = 'Carnegie Hall'; + $concert->performanceDate = Carbon::create(2024, 4, 1, 20, 0, 0, 'EST'); + $concert->save(); + // end model insert one + + // begin inserted id + $insertedId = $concert->id; + // end inserted id + + $this->assertNotNull($concert); + $this->assertNotNull($insertedId); + + $result = Concert::first(); + $this->assertInstanceOf(Concert::class, $result); + } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function testModelInsertMassAssign(): void + { + require_once __DIR__ . '/Concert.php'; + + Concert::truncate(); + + // begin model insert one mass assign + $insertResult = Concert::create([ + 'performer' => 'The Rolling Stones', + 'venue' => 'Soldier Field', + 'performanceDate' => Carbon::create(2024, 6, 30, 20, 0, 0, 'CDT'), + ]); + // end model insert one mass assign + + $this->assertNotNull($insertResult); + + $result = Concert::first(); + $this->assertInstanceOf(Concert::class, $result); + } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function testModelInsertMany(): void + { + require_once __DIR__ . '/Concert.php'; + + Concert::truncate(); + + // begin model insert many + $data = [ + [ + 'performer' => 'Brad Mehldau', + 'venue' => 'Philharmonie de Paris', + 'performanceDate' => new UTCDateTime(Carbon::create(2025, 2, 12, 20, 0, 0, 'CET')), + ], + [ + 'performer' => 'Billy Joel', + 'venue' => 'Madison Square Garden', + 'performanceDate' => new UTCDateTime(Carbon::create(2025, 2, 12, 20, 0, 0, 'CET')), + ], + ]; + + Concert::insert($data); + // end model insert many + + $results = Concert::get(); + + $this->assertEquals(2, count($results)); + } +} diff --git a/docs/index.txt b/docs/index.txt index febdb9371..c9c45d2dd 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -15,7 +15,7 @@ Laravel MongoDB /quick-start Release Notes - /retrieve + /fundamentals /eloquent-models /query-builder /user-authentication @@ -53,7 +53,8 @@ Fundamentals To learn how to perform the following tasks by using the {+odm-short+}, see the following content: -- :ref:`laravel-fundamentals-retrieve` +- :ref:`laravel-fundamentals-read-ops` +- :ref:`laravel-fundamentals-write-ops` - :ref:`laravel-eloquent-models` - :ref:`laravel-query-builder` - :ref:`laravel-user-authentication`