diff --git a/docs/feature-compatibility.txt b/docs/feature-compatibility.txt new file mode 100644 index 000000000..b4f0406f3 --- /dev/null +++ b/docs/feature-compatibility.txt @@ -0,0 +1,307 @@ +.. _laravel-feature-compat: + +============================= +Laravel Feature Compatibility +============================= + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: php framework, odm, support + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +This guide describes the Laravel features that are supported by +the {+odm-long+}. This page discusses Laravel version 11.x feature +availability in {+odm-short+}. + +The following sections contain tables that describe whether individual +features are available in {+odm-short+}. + +Database Features +----------------- + +.. list-table:: + :header-rows: 1 + + * - Eloquent Feature + - Availability + + * - Configuration + - ✓ + + * - Read/Write Connections + - Use :manual:`read preference ` instead. + + * - Multiple Database Connections + - ✓ + + * - Listening for Query Events + - ✓ + + * - Monitoring Cumulative Query Time + - ✓ + + * - Transactions + - ✓ See :ref:`laravel-transactions`. + + * - Command Line Interface (CLI) + - Use the :mdb-shell:`MongoDB Shell <>` (``mongosh``). + + * - Database Inspection + - *Unsupported* + + * - Database Monitoring + - *Unsupported* + +Query Features +-------------- + +The following Eloquent methods are not supported in {+odm-short+}: + +- ``toSql()`` +- ``toRawSql()`` +- ``whereColumn()`` +- ``orWhereColumn()`` +- ``whereFulltext()`` +- ``groupByRaw()`` +- ``orderByRaw()`` +- ``inRandomOrder()`` +- ``union()`` +- ``unionAll()`` +- ``havingRaw()`` +- ``having()`` +- ``havingBetween()`` +- ``orHavingRaw()`` +- ``whereIntegerInRaw()`` +- ``orWhereIntegerInRaw()`` +- ``whereIntegerNotInRaw()`` +- ``orWhereIntegerNotInRaw()`` + +.. list-table:: + :header-rows: 1 + + * - Eloquent Feature + - Availability + + * - Running Queries + - ✓ + + * - Chunking Results + - ✓ + + * - Aggregates + - ✓ + + * - Select Statements + - ✓ + + * - Raw Expressions + - *Unsupported* + + * - Joins + - *Unsupported* + + * - Unions + - *Unsupported* + + * - `Basic Where Clauses `__ + - ✓ + + * - `Additional Where Clauses `__ + - ✓ + + * - Logical Grouping + - ✓ + + * - `Advanced Where Clauses `__ + - ✓ + + * - `Subquery Where Clauses `__ + - *Unsupported* + + * - Ordering + - ✓ + + * - Random Ordering + - *Unsupported* + + * - Grouping + - Partially supported, use :ref:`Aggregation Builders `. + + * - Limit and Offset + - ✓ + + * - Conditional Clauses + - ✓ + + * - Insert Statements + - ✓ + + * - Auto-Incrementing IDs + - *Unsupported as MongoDB uses ObjectIDs* + + * - Upserts + - *Unsupported* + + * - Update Statements + - ✓ + + * - Updating JSON Columns + - *Unsupported* + + * - Increment and Decrement Values + - ✓ + + * - Debugging + - ✓ + +Pagination Features +------------------- + +{+odm-short+} supports all Laravel pagination features. + + +Migration Features +------------------ + +{+odm-short+} supports all Laravel migration features, but the +implementation is specific to MongoDB's schemaless model. + +Seeding Features +---------------- + +{+odm-short+} supports all Laravel seeding features. + +Eloquent Features +----------------- + +.. list-table:: + :header-rows: 1 + + * - Eloquent Feature + - Availability + + * - Models + - ✓ + + * - UUID and ULID Keys + - ✓ + + * - Timestamps + - ✓ + + * - Retrieving Models + - ✓ + + * - Advanced Subqueries + - *Unsupported* + + * - Retrieving or Creating Models + - ✓ + + * - Retrieving Aggregates + - *Partially supported* + + * - Inserting and Updating Models + - ✓ + + * - Upserts + - *Unsupported, but you can use the createOneOrFirst() method* + + * - Deleting Models + - ✓ + + * - Soft Deleting + - ✓ + + * - Pruning Models + - ✓ + +.. tip:: + + To learn more, see the :ref:`laravel-eloquent-model-class` guide. + +Eloquent Relationship Features +------------------------------ + +.. list-table:: + :header-rows: 1 + + * - Eloquent Feature + - Availability + + * - Defining Relationships + - ✓ + + * - Many-to-Many Relationships + - ✓ + + * - Polymorphic Relationships + - ✓ + + * - Dynamic Relationships + - ✓ + + * - Querying Relations + - ✓ + + * - Aggregating Related Models + - *Unsupported* + + * - Inserting and Updating Related Models + - ✓ + +.. tip:: + + To learn more, see the :ref:`laravel-eloquent-model-relationships` guide. + +Eloquent Collection Features +---------------------------- + +{+odm-short+} supports all Eloquent collection features. + +Eloquent Mutator Features +------------------------- + +.. list-table:: + :header-rows: 1 + + * - Eloquent Feature + - Availability + + * - Casts + - ✓ + + * - Array and JSON Casting + - ✓ You can store objects and arrays in MongoDB without serializing to JSON. + + * - Date Casting + - ✓ + + * - Enum Casting + - ✓ + + * - Encrypted Casting + - ✓ + + * - Custom Casts + - ✓ + +.. tip:: + + To learn more, see the :ref:`laravel-eloquent-model-class` guide. + +Eloquent Model Factory Features +------------------------------- + +{+odm-short+} supports all Eloquent factory features. diff --git a/docs/includes/usage-examples/Movie.php b/docs/includes/usage-examples/Movie.php new file mode 100644 index 000000000..728a066de --- /dev/null +++ b/docs/includes/usage-examples/Movie.php @@ -0,0 +1,12 @@ + 'Carol', + 'imdb' => [ + 'rating' => 7.2, + 'votes' => 125000, + ], + ], + ]); + + // begin-update-one + $updates = Movie::where('title', 'Carol') + ->orderBy('_id') + ->first() + ->update([ + 'imdb' => [ + 'rating' => 7.3, + 'votes' => 142000, + ], + ]); + + echo 'Updated documents: ' . $updates; + // end-update-one + + $this->assertTrue($updates); + $this->expectOutputString('Updated documents: 1'); + } +} diff --git a/docs/index.txt b/docs/index.txt index febdb9371..af09ee013 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -14,6 +14,7 @@ Laravel MongoDB :maxdepth: 1 /quick-start + /usage-examples Release Notes /retrieve /eloquent-models @@ -22,6 +23,7 @@ Laravel MongoDB /queues /transactions /issues-and-help + /feature-compatibility /compatibility /upgrade @@ -47,10 +49,16 @@ Learn how to add {+odm-short+} to a Laravel web application, connect to MongoDB hosted on MongoDB Atlas, and begin working with data in the :ref:`laravel-quick-start` section. +Usage Examples +-------------- + +See fully runnable code examples and explanations of common +MongoDB operations in the :ref:`laravel-usage-examples` section. + Fundamentals ------------ -To learn how to perform the following tasks by using the {+odm-short+}, +To learn how to perform the following tasks by using {+odm-short+}, see the following content: - :ref:`laravel-fundamentals-retrieve` diff --git a/docs/query-builder.txt b/docs/query-builder.txt index 18f03a2e1..55b5762e4 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -172,6 +172,8 @@ Distinct can be combined with **where**: $spamComments = Comment::where('body', 'like', '%spam%')->get(); +.. _laravel-query-builder-aggregates: + **Aggregation** **Aggregations are only available for MongoDB versions greater than 2.2.x** diff --git a/docs/quick-start/view-data.txt b/docs/quick-start/view-data.txt index 52c0e5dc4..9f086c774 100644 --- a/docs/quick-start/view-data.txt +++ b/docs/quick-start/view-data.txt @@ -1,4 +1,4 @@ -.. laravel-quick-start-view-data: +.. _laravel-quick-start-view-data: ================= View MongoDB Data diff --git a/docs/usage-examples.txt b/docs/usage-examples.txt new file mode 100644 index 000000000..08dda77ea --- /dev/null +++ b/docs/usage-examples.txt @@ -0,0 +1,74 @@ +.. _laravel-usage-examples: + +============== +Usage Examples +============== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: set up, runnable + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +Usage examples show runnable code examples to demonstrate frequently used MongoDB +operations. Each usage example includes the following components: + +- Explanation of the MongoDB operation +- Example code that you can run from an application controller +- Output displayed by the print statement + +How to Use the Usage Examples +----------------------------- + +To learn how to add a usage example to your Laravel application and view the expected output, +see the following sections: + +- :ref:`before-start` +- :ref:`run-usage-examples` + +.. _before-start: + +Before You Get Started +~~~~~~~~~~~~~~~~~~~~~~ + +You can run the usage examples from your own Laravel application or from the +``{+quickstart-app-name+}`` application created in the :ref:`laravel-quick-start` guide. + +The usage examples are designed to run operations on a MongoDB deployment that contains +the MongoDB Atlas sample datasets. Before running the usage examples, ensure that you load +the sample data into the MongoDB cluster to which your application connects. Otherwise, the +operation output might not match the text included in the ``{+code-output-label+}`` tab of +the usage example page. + +.. tip:: + + For instructions on loading the sample data into a MongoDB cluster, see + :atlas:`Load Sample Data ` in the Atlas documentation. + +.. _run-usage-examples: + +Run the Usage Example +~~~~~~~~~~~~~~~~~~~~~ + +Each usage example page includes sample code that demonstrates a MongoDB operation and prints +a result. To run the operation, you can copy the sample code to a controller endpoint in your +Laravel application. + +To view the expected output of the operation, you can add a web route to your application that +calls the controller function and returns the result to a web interface. + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /usage-examples/updateOne \ No newline at end of file diff --git a/docs/usage-examples/updateOne.txt b/docs/usage-examples/updateOne.txt new file mode 100644 index 000000000..f60bd3bad --- /dev/null +++ b/docs/usage-examples/updateOne.txt @@ -0,0 +1,67 @@ +.. _laravel-update-one-usage: + +================= +Update a Document +================= + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: update one, modify, code example + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +You can update a document in a collection by retrieving a single document and calling +the ``update()`` method on an Eloquent model or a query builder. + +Pass a query filter to the ``where()`` method, sort the matching documents, and call the +``first()`` method to retrieve only the first document. Then, update this matching document +by passing your intended document changes to the ``update()`` method. + +Example +------- + +This usage example performs the following actions: + +- Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the + ``sample_mflix`` database. +- Updates a document from the ``movies`` collection that matches a query filter. + +The example calls the following methods on the ``Movie`` model: + +- ``where()``: matches documents in which the value of the ``title`` field is ``'Carol'``. +- ``orderBy()``: sorts matched documents by their ascending ``_id`` values. +- ``first()``: retrieves only the first matching document. +- ``update()``: updates the value of the ``imdb.rating`` nested field to from ``6.9`` to + ``7.3``. This method also updates the ``imdb.votes`` nested field from ``493`` to ``142000``. + +.. io-code-block:: + :copyable: true + + .. input:: ../includes/usage-examples/UpdateOneTest.php + :start-after: begin-update-one + :end-before: end-update-one + :language: php + :dedent: + + .. output:: + :language: console + :visible: false + + Updated documents: 1 + +For instructions on editing your Laravel application to run the usage example, see the +:ref:`Usage Example landing page `. + +.. tip:: + + To learn more about updating data with {+odm-short+}, see the `Updates + `__ section of the + Laravel documentation. + diff --git a/phpunit.xml.dist b/phpunit.xml.dist index b1aa3a8eb..5431164d8 100644 --- a/phpunit.xml.dist +++ b/phpunit.xml.dist @@ -12,6 +12,9 @@ tests/ + + docs/includes/ +