From 2322a787534038c8225ee443a5e34828d1f2bf6b Mon Sep 17 00:00:00 2001 From: divine <48183131+divine@users.noreply.github.com> Date: Tue, 1 Feb 2022 03:42:44 +0300 Subject: [PATCH 001/446] chore: update changelog --- CHANGELOG.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 225ddec6f..20a696143 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,8 +3,19 @@ All notable changes to this project will be documented in this file. ## [Unreleased] +## [3.8.4] - 2021-05-27 + ### Fixed -- Sync passthru methods [#2194](https://github.com/jenssegers/laravel-mongodb/pull/2194) by [@simonschaufi](https://github.com/simonschaufi) +- Fix getRelationQuery breaking changes [#2263](https://github.com/jenssegers/laravel-mongodb/pull/2263) by [@divine](https://github.com/divine) +- Apply fixes produced by php-cs-fixer [#2250](https://github.com/jenssegers/laravel-mongodb/pull/2250) by [@divine](https://github.com/divine) + +### Changed +- Add doesntExist to passthru [#2194](https://github.com/jenssegers/laravel-mongodb/pull/2194) by [@simonschaufi](https://github.com/simonschaufi) +- Add Model query whereDate support [#2251](https://github.com/jenssegers/laravel-mongodb/pull/2251) by [@yexk](https://github.com/yexk) +- Add transaction free deleteAndRelease() method [#2229](https://github.com/jenssegers/laravel-mongodb/pull/2229) by [@sodoardi](https://github.com/sodoardi) +- Add setDatabase to Jenssegers\Mongodb\Connection [#2236](https://github.com/jenssegers/laravel-mongodb/pull/2236) by [@ThomasWestrelin](https://github.com/ThomasWestrelin) +- Check dates against DateTimeInterface instead of DateTime [#2239](https://github.com/jenssegers/laravel-mongodb/pull/2239) by [@jeromegamez](https://github.com/jeromegamez) +- Move from psr-0 to psr-4 [#2247](https://github.com/jenssegers/laravel-mongodb/pull/2247) by [@divine](https://github.com/divine) ## [3.8.3] - 2021-02-21 @@ -28,4 +39,4 @@ All notable changes to this project will be documented in this file. ## [3.8.0] - 2020-09-03 ### Added -- Laravel 8 support & updated versions of all dependencies [#2108](https://github.com/jenssegers/laravel-mongodb/pull/2108) by [@divine](https://github.com/divine). \ No newline at end of file +- Laravel 8 support & updated versions of all dependencies [#2108](https://github.com/jenssegers/laravel-mongodb/pull/2108) by [@divine](https://github.com/divine). From 39f940ddc11b24159819b4de5a4fe8f172ede6fb Mon Sep 17 00:00:00 2001 From: divine <48183131+divine@users.noreply.github.com> Date: Tue, 1 Feb 2022 03:43:56 +0300 Subject: [PATCH 002/446] chore: add missing dots to readme. --- CHANGELOG.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 20a696143..a43b9acd7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,27 +6,27 @@ All notable changes to this project will be documented in this file. ## [3.8.4] - 2021-05-27 ### Fixed -- Fix getRelationQuery breaking changes [#2263](https://github.com/jenssegers/laravel-mongodb/pull/2263) by [@divine](https://github.com/divine) -- Apply fixes produced by php-cs-fixer [#2250](https://github.com/jenssegers/laravel-mongodb/pull/2250) by [@divine](https://github.com/divine) +- Fix getRelationQuery breaking changes [#2263](https://github.com/jenssegers/laravel-mongodb/pull/2263) by [@divine](https://github.com/divine). +- Apply fixes produced by php-cs-fixer [#2250](https://github.com/jenssegers/laravel-mongodb/pull/2250) by [@divine](https://github.com/divine). ### Changed -- Add doesntExist to passthru [#2194](https://github.com/jenssegers/laravel-mongodb/pull/2194) by [@simonschaufi](https://github.com/simonschaufi) -- Add Model query whereDate support [#2251](https://github.com/jenssegers/laravel-mongodb/pull/2251) by [@yexk](https://github.com/yexk) -- Add transaction free deleteAndRelease() method [#2229](https://github.com/jenssegers/laravel-mongodb/pull/2229) by [@sodoardi](https://github.com/sodoardi) -- Add setDatabase to Jenssegers\Mongodb\Connection [#2236](https://github.com/jenssegers/laravel-mongodb/pull/2236) by [@ThomasWestrelin](https://github.com/ThomasWestrelin) -- Check dates against DateTimeInterface instead of DateTime [#2239](https://github.com/jenssegers/laravel-mongodb/pull/2239) by [@jeromegamez](https://github.com/jeromegamez) -- Move from psr-0 to psr-4 [#2247](https://github.com/jenssegers/laravel-mongodb/pull/2247) by [@divine](https://github.com/divine) +- Add doesntExist to passthru [#2194](https://github.com/jenssegers/laravel-mongodb/pull/2194) by [@simonschaufi](https://github.com/simonschaufi). +- Add Model query whereDate support [#2251](https://github.com/jenssegers/laravel-mongodb/pull/2251) by [@yexk](https://github.com/yexk). +- Add transaction free deleteAndRelease() method [#2229](https://github.com/jenssegers/laravel-mongodb/pull/2229) by [@sodoardi](https://github.com/sodoardi). +- Add setDatabase to Jenssegers\Mongodb\Connection [#2236](https://github.com/jenssegers/laravel-mongodb/pull/2236) by [@ThomasWestrelin](https://github.com/ThomasWestrelin). +- Check dates against DateTimeInterface instead of DateTime [#2239](https://github.com/jenssegers/laravel-mongodb/pull/2239) by [@jeromegamez](https://github.com/jeromegamez). +- Move from psr-0 to psr-4 [#2247](https://github.com/jenssegers/laravel-mongodb/pull/2247) by [@divine](https://github.com/divine). ## [3.8.3] - 2021-02-21 ### Changed -- Fix query builder regression [#2204](https://github.com/jenssegers/laravel-mongodb/pull/2204) by [@divine](https://github.com/divine) +- Fix query builder regression [#2204](https://github.com/jenssegers/laravel-mongodb/pull/2204) by [@divine](https://github.com/divine). ## [3.8.2] - 2020-12-18 ### Changed -- MongodbQueueServiceProvider does not use the DB Facade anymore [#2149](https://github.com/jenssegers/laravel-mongodb/pull/2149) by [@curosmj](https://github.com/curosmj) -- Add escape regex chars to DB Presence Verifier [#1992](https://github.com/jenssegers/laravel-mongodb/pull/1992) by [@andrei-gafton-rtgt](https://github.com/andrei-gafton-rtgt) +- MongodbQueueServiceProvider does not use the DB Facade anymore [#2149](https://github.com/jenssegers/laravel-mongodb/pull/2149) by [@curosmj](https://github.com/curosmj). +- Add escape regex chars to DB Presence Verifier [#1992](https://github.com/jenssegers/laravel-mongodb/pull/1992) by [@andrei-gafton-rtgt](https://github.com/andrei-gafton-rtgt). ## [3.8.1] - 2020-10-23 From d02a46c47364b7f2dc80b84901876b5ea3b92ef8 Mon Sep 17 00:00:00 2001 From: divine <48183131+divine@users.noreply.github.com> Date: Sun, 6 Feb 2022 05:40:20 +0300 Subject: [PATCH 003/446] feat: initial laravel 9 compatibility --- .github/workflows/build-ci.yml | 23 +++++++---------------- CHANGELOG.md | 3 +++ README.md | 1 + composer.json | 20 +++++++++++--------- src/Query/Builder.php | 2 +- 5 files changed, 23 insertions(+), 26 deletions(-) diff --git a/.github/workflows/build-ci.yml b/.github/workflows/build-ci.yml index 023def9be..b79741f77 100644 --- a/.github/workflows/build-ci.yml +++ b/.github/workflows/build-ci.yml @@ -35,19 +35,14 @@ jobs: strategy: matrix: include: - - { os: ubuntu-latest, php: 7.2, mongodb: 3.6, experimental: true } - - { os: ubuntu-latest, php: 7.2, mongodb: '4.0', experimental: true } - - { os: ubuntu-latest, php: 7.2, mongodb: 4.2, experimental: true } - - { os: ubuntu-latest, php: 7.2, mongodb: 4.4, experimental: true } - - { os: ubuntu-latest, php: 7.3, mongodb: 3.6, experimental: false } - - { os: ubuntu-latest, php: 7.3, mongodb: '4.0', experimental: false } - - { os: ubuntu-latest, php: 7.3, mongodb: 4.2, experimental: false } - - { os: ubuntu-latest, php: 7.3, mongodb: 4.4, experimental: false } - - { os: ubuntu-latest, php: 7.4, mongodb: 3.6, experimental: false } - - { os: ubuntu-latest, php: 7.4, mongodb: '4.0', experimental: false } - - { os: ubuntu-latest, php: 7.4, mongodb: 4.2, experimental: false } - - { os: ubuntu-latest, php: 7.4, mongodb: 4.4, experimental: false } + - { os: ubuntu-latest, php: 8.0, mongodb: '4.0', experimental: false } + - { os: ubuntu-latest, php: 8.0, mongodb: 4.2, experimental: false } - { os: ubuntu-latest, php: 8.0, mongodb: 4.4, experimental: false } + - { os: ubuntu-latest, php: 8.0, mongodb: '5.0', experimental: false } + - { os: ubuntu-latest, php: 8.1, mongodb: '4.0', experimental: false } + - { os: ubuntu-latest, php: 8.1, mongodb: 4.2, experimental: false } + - { os: ubuntu-latest, php: 8.1, mongodb: 4.4, experimental: false } + - { os: ubuntu-latest, php: 8.1, mongodb: '5.0', experimental: false } services: mongo: image: mongo:${{ matrix.mongodb }} @@ -78,22 +73,18 @@ jobs: env: DEBUG: ${{secrets.DEBUG}} - name: Download Composer cache dependencies from cache - if: (!startsWith(matrix.php, '7.2')) id: composer-cache run: echo "::set-output name=dir::$(composer config cache-files-dir)" - name: Cache Composer dependencies - if: (!startsWith(matrix.php, '7.2')) uses: actions/cache@v1 with: path: ${{ steps.composer-cache.outputs.dir }} key: ${{ matrix.os }}-composer-${{ hashFiles('**/composer.json') }} restore-keys: ${{ matrix.os }}-composer- - name: Install dependencies - if: (!startsWith(matrix.php, '7.2')) run: | composer install --no-interaction - name: Run tests - if: (!startsWith(matrix.php, '7.2')) run: | ./vendor/bin/phpunit --coverage-clover coverage.xml env: diff --git a/CHANGELOG.md b/CHANGELOG.md index a43b9acd7..fe0f4dd87 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,9 @@ All notable changes to this project will be documented in this file. ## [Unreleased] +### Added +- Compatibility with Laravel 9.x [#](https://github.com/jenssegers/laravel-mongodb/pull/) by [@divine](https://github.com/divine). + ## [3.8.4] - 2021-05-27 ### Fixed diff --git a/README.md b/README.md index 189d45384..8ede587ec 100644 --- a/README.md +++ b/README.md @@ -58,6 +58,7 @@ Make sure you have the MongoDB PHP driver installed. You can find installation i Laravel | Package | Maintained :---------|:---------------|:---------- + 9.x | 3.9.x | :white_check_mark: 8.x | 3.8.x | :white_check_mark: 7.x | 3.7.x | :x: 6.x | 3.6.x | :white_check_mark: diff --git a/composer.json b/composer.json index 5522a67a6..ddc7f7047 100644 --- a/composer.json +++ b/composer.json @@ -19,17 +19,17 @@ ], "license": "MIT", "require": { - "illuminate/support": "^8.0", - "illuminate/container": "^8.0", - "illuminate/database": "^8.0", - "illuminate/events": "^8.0", - "mongodb/mongodb": "^1.6" + "illuminate/support": "9.x-dev", + "illuminate/container": "9.x-dev", + "illuminate/database": "9.x-dev", + "illuminate/events": "9.x-dev", + "mongodb/mongodb": "^1.11" }, "require-dev": { - "phpunit/phpunit": "^9.0", - "orchestra/testbench": "^6.0", + "phpunit/phpunit": "^9.5.8", + "orchestra/testbench": "7.x-dev", "mockery/mockery": "^1.3.1", - "doctrine/dbal": "^2.6" + "doctrine/dbal": "^2.13.3|^3.1.4" }, "autoload": { "psr-4": { @@ -54,5 +54,7 @@ "Jenssegers\\Mongodb\\MongodbQueueServiceProvider" ] } - } + }, + "minimum-stability": "dev", + "prefer-stable": true } diff --git a/src/Query/Builder.php b/src/Query/Builder.php index de3265cb6..27f64d847 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -526,7 +526,7 @@ public function whereAll($column, array $values, $boolean = 'and', $not = false) /** * @inheritdoc */ - public function whereBetween($column, array $values, $boolean = 'and', $not = false) + public function whereBetween($column, iterable $values, $boolean = 'and', $not = false) { $type = 'between'; From 9c2b001d1b9a6075a86e89f0442ba2e66eddb3e0 Mon Sep 17 00:00:00 2001 From: divine <48183131+divine@users.noreply.github.com> Date: Wed, 9 Feb 2022 03:59:33 +0300 Subject: [PATCH 004/446] feat: use stable laravel release --- composer.json | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/composer.json b/composer.json index ddc7f7047..12a5b7eeb 100644 --- a/composer.json +++ b/composer.json @@ -19,15 +19,15 @@ ], "license": "MIT", "require": { - "illuminate/support": "9.x-dev", - "illuminate/container": "9.x-dev", - "illuminate/database": "9.x-dev", - "illuminate/events": "9.x-dev", + "illuminate/support": "^9.0", + "illuminate/container": "^9.0", + "illuminate/database": "^9.0", + "illuminate/events": "^9.0", "mongodb/mongodb": "^1.11" }, "require-dev": { "phpunit/phpunit": "^9.5.8", - "orchestra/testbench": "7.x-dev", + "orchestra/testbench": "^7.0", "mockery/mockery": "^1.3.1", "doctrine/dbal": "^2.13.3|^3.1.4" }, @@ -54,7 +54,5 @@ "Jenssegers\\Mongodb\\MongodbQueueServiceProvider" ] } - }, - "minimum-stability": "dev", - "prefer-stable": true + } } From 42c1ff29dae5e48d842998bd816c310733eb2f54 Mon Sep 17 00:00:00 2001 From: divine <48183131+divine@users.noreply.github.com> Date: Wed, 9 Feb 2022 04:04:43 +0300 Subject: [PATCH 005/446] feat: update php-cs-fixer & docker php version --- .github/workflows/build-ci.yml | 4 +-- .gitignore | 4 +-- .php_cs.dist => .php-cs-fixer.dist.php | 35 ++++++++++++++++++-------- CHANGELOG.md | 2 +- Dockerfile | 2 +- 5 files changed, 30 insertions(+), 17 deletions(-) rename .php_cs.dist => .php-cs-fixer.dist.php (89%) diff --git a/.github/workflows/build-ci.yml b/.github/workflows/build-ci.yml index b79741f77..2affc132c 100644 --- a/.github/workflows/build-ci.yml +++ b/.github/workflows/build-ci.yml @@ -10,11 +10,11 @@ jobs: php-cs-fixer: runs-on: ubuntu-latest env: - PHP_CS_FIXER_VERSION: v2.18.7 + PHP_CS_FIXER_VERSION: v3.6.0 strategy: matrix: php: - - '7.4' + - '8.0' steps: - name: Checkout uses: actions/checkout@v2 diff --git a/.gitignore b/.gitignore index 691162d09..8a586f33b 100644 --- a/.gitignore +++ b/.gitignore @@ -4,8 +4,8 @@ .DS_Store .idea/ .phpunit.result.cache -/.php_cs -/.php_cs.cache +/.php-cs-fixer.php +/.php-cs-fixer.cache /vendor composer.lock composer.phar diff --git a/.php_cs.dist b/.php-cs-fixer.dist.php similarity index 89% rename from .php_cs.dist rename to .php-cs-fixer.dist.php index 81b74cffb..20c262e3a 100644 --- a/.php_cs.dist +++ b/.php-cs-fixer.dist.php @@ -25,7 +25,7 @@ ], ], 'cast_spaces' => true, - 'class_definition' => true, + 'class_definition' => false, 'clean_namespace' => true, 'compact_nullable_typehint' => true, 'concat_space' => [ @@ -46,16 +46,22 @@ 'heredoc_to_nowdoc' => true, 'include' => true, 'indentation_type' => true, + 'integer_literal_case' => true, + 'braces' => false, 'lowercase_cast' => true, - 'lowercase_constants' => true, + 'constant_case' => [ + 'case' => 'lower', + ], 'lowercase_keywords' => true, 'lowercase_static_reference' => true, 'magic_constant_casing' => true, 'magic_method_casing' => true, - 'method_argument_space' => true, + 'method_argument_space' => [ + 'on_multiline' => 'ignore', + ], 'class_attributes_separation' => [ 'elements' => [ - 'method', + 'method' => 'one', ], ], 'visibility_required' => [ @@ -74,7 +80,6 @@ 'tokens' => [ 'throw', 'use', - 'use_trait', 'extra', ], ], @@ -87,6 +92,7 @@ 'multiline_whitespace_before_semicolons' => true, 'no_short_bool_cast' => true, 'no_singleline_whitespace_before_semicolons' => true, + 'no_space_around_double_colon' => true, 'no_spaces_after_function_name' => true, 'no_spaces_around_offset' => [ 'positions' => [ @@ -120,7 +126,9 @@ 'phpdoc_summary' => true, 'phpdoc_trim' => true, 'phpdoc_no_alias_tag' => [ - 'type' => 'var', + 'replacements' => [ + 'type' => 'var', + ], ], 'phpdoc_types' => true, 'phpdoc_var_without_name' => true, @@ -130,7 +138,6 @@ 'no_mixed_echo_print' => [ 'use' => 'echo', ], - 'braces' => true, 'return_type_declaration' => [ 'space_before' => 'none', ], @@ -153,22 +160,28 @@ 'switch_case_space' => true, 'switch_continue_to_break' => true, 'ternary_operator_spaces' => true, - 'trailing_comma_in_multiline_array' => true, + 'trailing_comma_in_multiline' => [ + 'elements' => [ + 'arrays', + ], + ], 'trim_array_spaces' => true, 'unary_operator_spaces' => true, + 'types_spaces' => [ + 'space' => 'none', + ], 'line_ending' => true, 'whitespace_after_comma_in_array' => true, 'no_alias_functions' => true, 'no_unreachable_default_argument_value' => true, - 'psr4' => true, + 'psr_autoloading' => true, 'self_accessor' => true, ]; $finder = PhpCsFixer\Finder::create() ->in(__DIR__); -$config = new PhpCsFixer\Config(); -return $config +return (new PhpCsFixer\Config()) ->setRiskyAllowed(true) ->setRules($rules) ->setFinder($finder); diff --git a/CHANGELOG.md b/CHANGELOG.md index fe0f4dd87..291694453 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,7 @@ All notable changes to this project will be documented in this file. ## [Unreleased] ### Added -- Compatibility with Laravel 9.x [#](https://github.com/jenssegers/laravel-mongodb/pull/) by [@divine](https://github.com/divine). +- Compatibility with Laravel 9.x [#2344](https://github.com/jenssegers/laravel-mongodb/pull/2344) by [@divine](https://github.com/divine). ## [3.8.4] - 2021-05-27 diff --git a/Dockerfile b/Dockerfile index e8b6b4d2e..aa4fdb95a 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,4 +1,4 @@ -ARG PHP_VERSION=7.4 +ARG PHP_VERSION=8.0 ARG COMPOSER_VERSION=2.0 FROM composer:${COMPOSER_VERSION} From 40846ab4989dd4790c8a266c5f3e7010361265ed Mon Sep 17 00:00:00 2001 From: divine <48183131+divine@users.noreply.github.com> Date: Wed, 9 Feb 2022 04:22:39 +0300 Subject: [PATCH 006/446] fix: imrprove php-doc comments --- src/Auth/PasswordResetServiceProvider.php | 1 + src/Collection.php | 5 ++++- src/Connection.php | 16 ++++++++++++++++ src/Eloquent/Builder.php | 1 + src/Eloquent/EmbedsRelations.php | 2 ++ src/Eloquent/HybridRelations.php | 8 ++++++++ src/Eloquent/Model.php | 14 ++++++++++++++ src/Helpers/QueriesRelationships.php | 4 ++++ src/Query/Builder.php | 21 +++++++++++++++++++++ src/Queue/Failed/MongoFailedJobProvider.php | 4 ++++ src/Queue/MongoConnector.php | 3 +++ src/Queue/MongoJob.php | 1 + src/Queue/MongoQueue.php | 5 +++++ src/Relations/BelongsTo.php | 3 +++ src/Relations/BelongsToMany.php | 8 ++++++++ src/Relations/EmbedsMany.php | 12 ++++++++++++ src/Relations/EmbedsOne.php | 7 +++++++ src/Relations/EmbedsOneOrMany.php | 21 +++++++++++++++++++++ src/Relations/HasMany.php | 3 +++ src/Relations/HasOne.php | 3 +++ src/Relations/MorphTo.php | 2 ++ src/Schema/Blueprint.php | 13 ++++++++++++- src/Schema/Builder.php | 4 ++++ src/Validation/DatabasePresenceVerifier.php | 1 + tests/TestCase.php | 3 +++ tests/models/Birthday.php | 1 + tests/models/Book.php | 1 + tests/models/Item.php | 1 + tests/models/Soft.php | 1 + tests/models/User.php | 1 + 30 files changed, 168 insertions(+), 2 deletions(-) diff --git a/src/Auth/PasswordResetServiceProvider.php b/src/Auth/PasswordResetServiceProvider.php index 6e678d2ec..ba4e32e62 100644 --- a/src/Auth/PasswordResetServiceProvider.php +++ b/src/Auth/PasswordResetServiceProvider.php @@ -8,6 +8,7 @@ class PasswordResetServiceProvider extends BasePasswordResetServiceProvider { /** * Register the token repository implementation. + * * @return void */ protected function registerTokenRepository() diff --git a/src/Collection.php b/src/Collection.php index feaa6f55d..8acf6afe5 100644 --- a/src/Collection.php +++ b/src/Collection.php @@ -10,12 +10,14 @@ class Collection { /** * The connection instance. + * * @var Connection */ protected $connection; /** - * The MongoCollection instance.. + * The MongoCollection instance. + * * @var MongoCollection */ protected $collection; @@ -32,6 +34,7 @@ public function __construct(Connection $connection, MongoCollection $collection) /** * Handle dynamic method calls. + * * @param string $method * @param array $parameters * @return mixed diff --git a/src/Connection.php b/src/Connection.php index c8e7b6bad..57d9d3e37 100644 --- a/src/Connection.php +++ b/src/Connection.php @@ -11,18 +11,21 @@ class Connection extends BaseConnection { /** * The MongoDB database handler. + * * @var \MongoDB\Database */ protected $db; /** * The MongoDB connection handler. + * * @var \MongoDB\Client */ protected $connection; /** * Create a new database connection instance. + * * @param array $config */ public function __construct(array $config) @@ -53,6 +56,7 @@ public function __construct(array $config) /** * Begin a fluent query against a database collection. + * * @param string $collection * @return Query\Builder */ @@ -65,6 +69,7 @@ public function collection($collection) /** * Begin a fluent query against a database collection. + * * @param string $table * @param string|null $as * @return Query\Builder @@ -76,6 +81,7 @@ public function table($table, $as = null) /** * Get a MongoDB collection. + * * @param string $name * @return Collection */ @@ -94,6 +100,7 @@ public function getSchemaBuilder() /** * Get the MongoDB database object. + * * @return \MongoDB\Database */ public function getMongoDB() @@ -103,6 +110,7 @@ public function getMongoDB() /** * return MongoDB object. + * * @return \MongoDB\Client */ public function getMongoClient() @@ -120,6 +128,7 @@ public function getDatabaseName() /** * Get the name of the default database based on db config or try to detect it from dsn. + * * @param string $dsn * @param array $config * @return string @@ -140,6 +149,7 @@ protected function getDefaultDatabaseName($dsn, $config) /** * Create a new MongoDB connection. + * * @param string $dsn * @param array $config * @param array $options @@ -175,6 +185,7 @@ public function disconnect() /** * Determine if the given configuration array has a dsn string. + * * @param array $config * @return bool */ @@ -185,6 +196,7 @@ protected function hasDsnString(array $config) /** * Get the DSN string form configuration. + * * @param array $config * @return string */ @@ -195,6 +207,7 @@ protected function getDsnString(array $config) /** * Get the DSN string for a host / port configuration. + * * @param array $config * @return string */ @@ -218,6 +231,7 @@ protected function getHostDsn(array $config) /** * Create a DSN string from a configuration. + * * @param array $config * @return string */ @@ -270,6 +284,7 @@ protected function getDefaultSchemaGrammar() /** * Set database. + * * @param \MongoDB\Database $db */ public function setDatabase(\MongoDB\Database $db) @@ -279,6 +294,7 @@ public function setDatabase(\MongoDB\Database $db) /** * Dynamically pass methods to the connection. + * * @param string $method * @param array $parameters * @return mixed diff --git a/src/Eloquent/Builder.php b/src/Eloquent/Builder.php index f77e87c2d..398f3893b 100644 --- a/src/Eloquent/Builder.php +++ b/src/Eloquent/Builder.php @@ -13,6 +13,7 @@ class Builder extends EloquentBuilder /** * The methods that should be returned from query builder. + * * @var array */ protected $passthru = [ diff --git a/src/Eloquent/EmbedsRelations.php b/src/Eloquent/EmbedsRelations.php index f7cac6c53..9e5f77d92 100644 --- a/src/Eloquent/EmbedsRelations.php +++ b/src/Eloquent/EmbedsRelations.php @@ -10,6 +10,7 @@ trait EmbedsRelations { /** * Define an embedded one-to-many relationship. + * * @param string $related * @param string $localKey * @param string $foreignKey @@ -44,6 +45,7 @@ protected function embedsMany($related, $localKey = null, $foreignKey = null, $r /** * Define an embedded one-to-many relationship. + * * @param string $related * @param string $localKey * @param string $foreignKey diff --git a/src/Eloquent/HybridRelations.php b/src/Eloquent/HybridRelations.php index e6c5d3352..d3dcb9919 100644 --- a/src/Eloquent/HybridRelations.php +++ b/src/Eloquent/HybridRelations.php @@ -16,6 +16,7 @@ trait HybridRelations { /** * Define a one-to-one relationship. + * * @param string $related * @param string $foreignKey * @param string $localKey @@ -39,6 +40,7 @@ public function hasOne($related, $foreignKey = null, $localKey = null) /** * Define a polymorphic one-to-one relationship. + * * @param string $related * @param string $name * @param string $type @@ -64,6 +66,7 @@ public function morphOne($related, $name, $type = null, $id = null, $localKey = /** * Define a one-to-many relationship. + * * @param string $related * @param string $foreignKey * @param string $localKey @@ -87,6 +90,7 @@ public function hasMany($related, $foreignKey = null, $localKey = null) /** * Define a polymorphic one-to-many relationship. + * * @param string $related * @param string $name * @param string $type @@ -117,6 +121,7 @@ public function morphMany($related, $name, $type = null, $id = null, $localKey = /** * Define an inverse one-to-one or many relationship. + * * @param string $related * @param string $foreignKey * @param string $otherKey @@ -160,6 +165,7 @@ public function belongsTo($related, $foreignKey = null, $otherKey = null, $relat /** * Define a polymorphic, inverse one-to-one or many relationship. + * * @param string $name * @param string $type * @param string $id @@ -204,6 +210,7 @@ public function morphTo($name = null, $type = null, $id = null, $ownerKey = null /** * Define a many-to-many relationship. + * * @param string $related * @param string $collection * @param string $foreignKey @@ -277,6 +284,7 @@ public function belongsToMany( /** * Get the relationship name of the belongs to many. + * * @return string */ protected function guessBelongsToManyRelation() diff --git a/src/Eloquent/Model.php b/src/Eloquent/Model.php index 3553e02ab..226bc357d 100644 --- a/src/Eloquent/Model.php +++ b/src/Eloquent/Model.php @@ -21,30 +21,35 @@ abstract class Model extends BaseModel /** * The collection associated with the model. + * * @var string */ protected $collection; /** * The primary key for the model. + * * @var string */ protected $primaryKey = '_id'; /** * The primary key type. + * * @var string */ protected $keyType = 'string'; /** * The parent relation instance. + * * @var Relation */ protected $parentRelation; /** * Custom accessor for the model's id. + * * @param mixed $value * @return mixed */ @@ -269,6 +274,7 @@ public function originalIsEquivalent($key) /** * Remove one or more fields. + * * @param mixed $columns * @return int */ @@ -314,6 +320,7 @@ public function push() /** * Remove one or more values from an array. + * * @param string $column * @param mixed $values * @return mixed @@ -332,6 +339,7 @@ public function pull($column, $values) /** * Append one or more values to the underlying attribute value and sync with original. + * * @param string $column * @param array $values * @param bool $unique @@ -356,6 +364,7 @@ protected function pushAttributeValues($column, array $values, $unique = false) /** * Remove one or more values to the underlying attribute value and sync with original. + * * @param string $column * @param array $values */ @@ -388,6 +397,7 @@ public function getForeignKey() /** * Set the parent relation. + * * @param \Illuminate\Database\Eloquent\Relations\Relation $relation */ public function setParentRelation(Relation $relation) @@ -397,6 +407,7 @@ public function setParentRelation(Relation $relation) /** * Get the parent relation. + * * @return \Illuminate\Database\Eloquent\Relations\Relation */ public function getParentRelation() @@ -432,6 +443,7 @@ protected function removeTableFromKey($key) /** * Get the queueable relationships for the entity. + * * @return array */ public function getQueueableRelations() @@ -461,6 +473,7 @@ public function getQueueableRelations() /** * Get loaded relations for the instance without parent. + * * @return array */ protected function getRelationsWithoutParent() @@ -477,6 +490,7 @@ protected function getRelationsWithoutParent() /** * Checks if column exists on a table. As this is a document model, just return true. This also * prevents calls to non-existent function Grammar::compileColumnListing(). + * * @param string $key * @return bool */ diff --git a/src/Helpers/QueriesRelationships.php b/src/Helpers/QueriesRelationships.php index ee130ce79..1f7310b99 100644 --- a/src/Helpers/QueriesRelationships.php +++ b/src/Helpers/QueriesRelationships.php @@ -15,12 +15,14 @@ trait QueriesRelationships { /** * Add a relationship count / exists condition to the query. + * * @param Relation|string $relation * @param string $operator * @param int $count * @param string $boolean * @param Closure|null $callback * @return Builder|static + * @throws Exception */ public function has($relation, $operator = '>=', $count = 1, $boolean = 'and', Closure $callback = null) { @@ -72,6 +74,7 @@ protected function isAcrossConnections(Relation $relation) /** * Compare across databases. + * * @param Relation $relation * @param string $operator * @param int $count @@ -150,6 +153,7 @@ protected function getConstrainedRelatedIds($relations, $operator, $count) /** * Returns key we are constraining this parent model's query with. + * * @param Relation $relation * @return string * @throws Exception diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 27f64d847..f83bce3e2 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -24,42 +24,49 @@ class Builder extends BaseBuilder { /** * The database collection. + * * @var \MongoDB\Collection */ protected $collection; /** * The column projections. + * * @var array */ public $projections; /** * The cursor timeout value. + * * @var int */ public $timeout; /** * The cursor hint value. + * * @var int */ public $hint; /** * Custom options to add to the query. + * * @var array */ public $options = []; /** * Indicate if we are executing a pagination query. + * * @var bool */ public $paginating = false; /** * All of the available clause operators. + * * @var array */ public $operators = [ @@ -107,6 +114,7 @@ class Builder extends BaseBuilder /** * Operator conversion. + * * @var array */ protected $conversion = [ @@ -131,6 +139,7 @@ public function __construct(Connection $connection, Processor $processor) /** * Set the projections. + * * @param array $columns * @return $this */ @@ -155,6 +164,7 @@ public function timeout($seconds) /** * Set the cursor hint. + * * @param mixed $index * @return $this */ @@ -205,6 +215,7 @@ public function cursor($columns = []) /** * Execute the query as a fresh "select" statement. + * * @param array $columns * @param bool $returnLazy * @return array|static[]|Collection|LazyCollection @@ -415,6 +426,7 @@ public function getFresh($columns = [], $returnLazy = false) /** * Generate the unique cache key for the current query. + * * @return string */ public function generateCacheKey() @@ -508,6 +520,7 @@ public function orderBy($column, $direction = 'asc') /** * Add a "where all" clause to the query. + * * @param string $column * @param array $values * @param string $boolean @@ -714,6 +727,7 @@ public function truncate(): bool /** * Get an array with the values of a given column. + * * @param string $column * @param string $key * @return array @@ -745,6 +759,7 @@ public function raw($expression = null) /** * Append one or more values to an array. + * * @param mixed $column * @param mixed $value * @param bool $unique @@ -771,6 +786,7 @@ public function push($column, $value = null, $unique = false) /** * Remove one or more values from an array. + * * @param mixed $column * @param mixed $value * @return int @@ -794,6 +810,7 @@ public function pull($column, $value = null) /** * Remove one or more fields. + * * @param mixed $columns * @return int */ @@ -824,6 +841,7 @@ public function newQuery() /** * Perform an update query. + * * @param array $query * @param array $options * @return int @@ -846,6 +864,7 @@ protected function performUpdate($query, array $options = []) /** * Convert a key to ObjectID if needed. + * * @param mixed $id * @return mixed */ @@ -883,6 +902,7 @@ public function where($column, $operator = null, $value = null, $boolean = 'and' /** * Compile the where array. + * * @return array */ protected function compileWheres() @@ -1216,6 +1236,7 @@ protected function compileWhereRaw(array $where) /** * Set custom options for the query. + * * @param array $options * @return $this */ diff --git a/src/Queue/Failed/MongoFailedJobProvider.php b/src/Queue/Failed/MongoFailedJobProvider.php index e130cbeab..1ac69d780 100644 --- a/src/Queue/Failed/MongoFailedJobProvider.php +++ b/src/Queue/Failed/MongoFailedJobProvider.php @@ -9,6 +9,7 @@ class MongoFailedJobProvider extends DatabaseFailedJobProvider { /** * Log a failed job into storage. + * * @param string $connection * @param string $queue * @param string $payload @@ -26,6 +27,7 @@ public function log($connection, $queue, $payload, $exception) /** * Get a list of all of the failed jobs. + * * @return object[] */ public function all() @@ -43,6 +45,7 @@ public function all() /** * Get a single failed job. + * * @param mixed $id * @return object */ @@ -61,6 +64,7 @@ public function find($id) /** * Delete a single failed job from storage. + * * @param mixed $id * @return bool */ diff --git a/src/Queue/MongoConnector.php b/src/Queue/MongoConnector.php index 91cea8c35..f453ba0a4 100644 --- a/src/Queue/MongoConnector.php +++ b/src/Queue/MongoConnector.php @@ -10,12 +10,14 @@ class MongoConnector implements ConnectorInterface { /** * Database connections. + * * @var \Illuminate\Database\ConnectionResolverInterface */ protected $connections; /** * Create a new connector instance. + * * @param \Illuminate\Database\ConnectionResolverInterface $connections */ public function __construct(ConnectionResolverInterface $connections) @@ -25,6 +27,7 @@ public function __construct(ConnectionResolverInterface $connections) /** * Establish a queue connection. + * * @param array $config * @return \Illuminate\Contracts\Queue\Queue */ diff --git a/src/Queue/MongoJob.php b/src/Queue/MongoJob.php index 336515f09..f1a61cf46 100644 --- a/src/Queue/MongoJob.php +++ b/src/Queue/MongoJob.php @@ -8,6 +8,7 @@ class MongoJob extends DatabaseJob { /** * Indicates if the job has been reserved. + * * @return bool */ public function isReserved() diff --git a/src/Queue/MongoQueue.php b/src/Queue/MongoQueue.php index f1568b4b4..2dde89bd7 100644 --- a/src/Queue/MongoQueue.php +++ b/src/Queue/MongoQueue.php @@ -11,12 +11,14 @@ class MongoQueue extends DatabaseQueue { /** * The expiration time of a job. + * * @var int|null */ protected $retryAfter = 60; /** * The connection name for the queue. + * * @var string */ protected $connectionName; @@ -56,6 +58,7 @@ public function pop($queue = null) * This race condition can result in random jobs being run more then * once. To solve this we use findOneAndUpdate to lock the next jobs * record while flagging it as reserved at the same time. + * * @param string|null $queue * @return \StdClass|null */ @@ -91,6 +94,7 @@ protected function getNextAvailableJobAndReserve($queue) /** * Release the jobs that have been reserved for too long. + * * @param string $queue * @return void */ @@ -111,6 +115,7 @@ protected function releaseJobsThatHaveBeenReservedTooLong($queue) /** * Release the given job ID from reservation. + * * @param string $id * @param int $attempts * @return void diff --git a/src/Relations/BelongsTo.php b/src/Relations/BelongsTo.php index b47e856fa..adaa13110 100644 --- a/src/Relations/BelongsTo.php +++ b/src/Relations/BelongsTo.php @@ -9,6 +9,7 @@ class BelongsTo extends \Illuminate\Database\Eloquent\Relations\BelongsTo { /** * Get the key for comparing against the parent key in "has" query. + * * @return string */ public function getHasCompareKey() @@ -52,6 +53,7 @@ public function getRelationExistenceQuery(Builder $query, Builder $parentQuery, /** * Get the owner key with backwards compatible support. + * * @return string */ public function getOwnerKey() @@ -61,6 +63,7 @@ public function getOwnerKey() /** * Get the name of the "where in" method for eager loading. + * * @param \Illuminate\Database\Eloquent\Model $model * @param string $key * @return string diff --git a/src/Relations/BelongsToMany.php b/src/Relations/BelongsToMany.php index 915cc95e2..2352adc50 100644 --- a/src/Relations/BelongsToMany.php +++ b/src/Relations/BelongsToMany.php @@ -13,6 +13,7 @@ class BelongsToMany extends EloquentBelongsToMany { /** * Get the key for comparing against the parent key in "has" query. + * * @return string */ public function getHasCompareKey() @@ -38,6 +39,7 @@ protected function hydratePivotRelation(array $models) /** * Set the select clause for the relation query. + * * @param array $columns * @return array */ @@ -66,6 +68,7 @@ public function addConstraints() /** * Set the where clause for the relation query. + * * @return $this */ protected function setWhere() @@ -272,6 +275,7 @@ public function newPivotQuery() /** * Create a new query builder for the related model. + * * @return \Illuminate\Database\Query\Builder */ public function newRelatedQuery() @@ -281,6 +285,7 @@ public function newRelatedQuery() /** * Get the fully qualified foreign key for the relation. + * * @return string */ public function getForeignKey() @@ -307,6 +312,7 @@ public function getQualifiedRelatedPivotKeyName() /** * Format the sync list so that it is keyed by ID. (Legacy Support) * The original function has been renamed to formatRecordsList since Laravel 5.3. + * * @param array $records * @return array * @deprecated @@ -326,6 +332,7 @@ protected function formatSyncList(array $records) /** * Get the related key with backwards compatible support. + * * @return string */ public function getRelatedKey() @@ -335,6 +342,7 @@ public function getRelatedKey() /** * Get the name of the "where in" method for eager loading. + * * @param \Illuminate\Database\Eloquent\Model $model * @param string $key * @return string diff --git a/src/Relations/EmbedsMany.php b/src/Relations/EmbedsMany.php index d5d8e0d48..88a63d0b4 100644 --- a/src/Relations/EmbedsMany.php +++ b/src/Relations/EmbedsMany.php @@ -33,6 +33,7 @@ public function getResults() /** * Save a new model and attach it to the parent model. + * * @param Model $model * @return Model|bool */ @@ -63,6 +64,7 @@ public function performInsert(Model $model) /** * Save an existing model and attach it to the parent model. + * * @param Model $model * @return Model|bool */ @@ -94,6 +96,7 @@ public function performUpdate(Model $model) /** * Delete an existing model and detach it from the parent model. + * * @param Model $model * @return int */ @@ -120,6 +123,7 @@ public function performDelete(Model $model) /** * Associate the model instance to the given parent, without saving it to the database. + * * @param Model $model * @return Model */ @@ -134,6 +138,7 @@ public function associate(Model $model) /** * Dissociate the model instance from the given parent, without saving it to the database. + * * @param mixed $ids * @return int */ @@ -162,6 +167,7 @@ public function dissociate($ids = []) /** * Destroy the embedded models for the given IDs. + * * @param mixed $ids * @return int */ @@ -186,6 +192,7 @@ public function destroy($ids = []) /** * Delete all embedded models. + * * @return int */ public function delete() @@ -202,6 +209,7 @@ public function delete() /** * Destroy alias. + * * @param mixed $ids * @return int */ @@ -212,6 +220,7 @@ public function detach($ids = []) /** * Save alias. + * * @param Model $model * @return Model */ @@ -222,6 +231,7 @@ public function attach(Model $model) /** * Associate a new model instance to the given parent, without saving it to the database. + * * @param Model $model * @return Model */ @@ -242,6 +252,7 @@ protected function associateNew($model) /** * Associate an existing model instance to the given parent, without saving it to the database. + * * @param Model $model * @return Model */ @@ -332,6 +343,7 @@ public function __call($method, $parameters) /** * Get the name of the "where in" method for eager loading. + * * @param \Illuminate\Database\Eloquent\Model $model * @param string $key * @return string diff --git a/src/Relations/EmbedsOne.php b/src/Relations/EmbedsOne.php index b57a2231a..ba2a41dfc 100644 --- a/src/Relations/EmbedsOne.php +++ b/src/Relations/EmbedsOne.php @@ -32,6 +32,7 @@ public function getEager() /** * Save a new model and attach it to the parent model. + * * @param Model $model * @return Model|bool */ @@ -61,6 +62,7 @@ public function performInsert(Model $model) /** * Save an existing model and attach it to the parent model. + * * @param Model $model * @return Model|bool */ @@ -86,6 +88,7 @@ public function performUpdate(Model $model) /** * Delete an existing model and detach it from the parent model. + * * @return int */ public function performDelete() @@ -110,6 +113,7 @@ public function performDelete() /** * Attach the model to its parent. + * * @param Model $model * @return Model */ @@ -120,6 +124,7 @@ public function associate(Model $model) /** * Detach the model from its parent. + * * @return Model */ public function dissociate() @@ -129,6 +134,7 @@ public function dissociate() /** * Delete all embedded models. + * * @return int */ public function delete() @@ -138,6 +144,7 @@ public function delete() /** * Get the name of the "where in" method for eager loading. + * * @param \Illuminate\Database\Eloquent\Model $model * @param string $key * @return string diff --git a/src/Relations/EmbedsOneOrMany.php b/src/Relations/EmbedsOneOrMany.php index 5e1e9d58b..2e5215377 100644 --- a/src/Relations/EmbedsOneOrMany.php +++ b/src/Relations/EmbedsOneOrMany.php @@ -12,24 +12,28 @@ abstract class EmbedsOneOrMany extends Relation { /** * The local key of the parent model. + * * @var string */ protected $localKey; /** * The foreign key of the parent model. + * * @var string */ protected $foreignKey; /** * The "name" of the relationship. + * * @var string */ protected $relation; /** * Create a new embeds many relationship instance. + * * @param Builder $query * @param Model $parent * @param Model $related @@ -90,6 +94,7 @@ public function match(array $models, Collection $results, $relation) /** * Shorthand to get the results of the relationship. + * * @param array $columns * @return Collection */ @@ -100,6 +105,7 @@ public function get($columns = ['*']) /** * Get the number of embedded models. + * * @return int */ public function count() @@ -109,6 +115,7 @@ public function count() /** * Attach a model instance to the parent model. + * * @param Model $model * @return Model|bool */ @@ -121,6 +128,7 @@ public function save(Model $model) /** * Attach a collection of models to the parent instance. + * * @param Collection|array $models * @return Collection|array */ @@ -135,6 +143,7 @@ public function saveMany($models) /** * Create a new instance of the related model. + * * @param array $attributes * @return Model */ @@ -154,6 +163,7 @@ public function create(array $attributes = []) /** * Create an array of new instances of the related model. + * * @param array $records * @return array */ @@ -170,6 +180,7 @@ public function createMany(array $records) /** * Transform single ID, single Model or array of Models into an array of IDs. + * * @param mixed $ids * @return array */ @@ -224,6 +235,7 @@ protected function setEmbedded($records) /** * Get the foreign key value for the relation. + * * @param mixed $id * @return mixed */ @@ -239,6 +251,7 @@ protected function getForeignKeyValue($id) /** * Convert an array of records to a Collection. + * * @param array $records * @return Collection */ @@ -259,6 +272,7 @@ protected function toCollection(array $records = []) /** * Create a related model instanced. + * * @param array $attributes * @return Model */ @@ -287,6 +301,7 @@ protected function toModel($attributes = []) /** * Get the relation instance of the parent. + * * @return Relation */ protected function getParentRelation() @@ -316,6 +331,7 @@ public function getBaseQuery() /** * Check if this relation is nested in another relation. + * * @return bool */ protected function isNested() @@ -325,6 +341,7 @@ protected function isNested() /** * Get the fully qualified local key name. + * * @param string $glue * @return string */ @@ -351,6 +368,7 @@ public function getQualifiedParentKeyName() /** * Get the primary key value of the parent. + * * @return string */ protected function getParentKey() @@ -360,6 +378,7 @@ protected function getParentKey() /** * Return update values. + * * @param $array * @param string $prepend * @return array @@ -377,6 +396,7 @@ public static function getUpdateValues($array, $prepend = '') /** * Get the foreign key for the relationship. + * * @return string */ public function getQualifiedForeignKeyName() @@ -386,6 +406,7 @@ public function getQualifiedForeignKeyName() /** * Get the name of the "where in" method for eager loading. + * * @param \Illuminate\Database\Eloquent\Model $model * @param string $key * @return string diff --git a/src/Relations/HasMany.php b/src/Relations/HasMany.php index 933a87b54..3069b9b6a 100644 --- a/src/Relations/HasMany.php +++ b/src/Relations/HasMany.php @@ -10,6 +10,7 @@ class HasMany extends EloquentHasMany { /** * Get the plain foreign key. + * * @return string */ public function getForeignKeyName() @@ -19,6 +20,7 @@ public function getForeignKeyName() /** * Get the key for comparing against the parent key in "has" query. + * * @return string */ public function getHasCompareKey() @@ -38,6 +40,7 @@ public function getRelationExistenceQuery(Builder $query, Builder $parentQuery, /** * Get the name of the "where in" method for eager loading. + * * @param \Illuminate\Database\Eloquent\Model $model * @param string $key * @return string diff --git a/src/Relations/HasOne.php b/src/Relations/HasOne.php index f2a5a9b33..77f97a0e2 100644 --- a/src/Relations/HasOne.php +++ b/src/Relations/HasOne.php @@ -10,6 +10,7 @@ class HasOne extends EloquentHasOne { /** * Get the key for comparing against the parent key in "has" query. + * * @return string */ public function getForeignKeyName() @@ -19,6 +20,7 @@ public function getForeignKeyName() /** * Get the key for comparing against the parent key in "has" query. + * * @return string */ public function getHasCompareKey() @@ -38,6 +40,7 @@ public function getRelationExistenceQuery(Builder $query, Builder $parentQuery, /** * Get the name of the "where in" method for eager loading. + * * @param \Illuminate\Database\Eloquent\Model $model * @param string $key * @return string diff --git a/src/Relations/MorphTo.php b/src/Relations/MorphTo.php index 5938f9eeb..426595185 100644 --- a/src/Relations/MorphTo.php +++ b/src/Relations/MorphTo.php @@ -36,6 +36,7 @@ protected function getResultsByType($type) /** * Get the owner key with backwards compatible support. + * * @return string */ public function getOwnerKey() @@ -45,6 +46,7 @@ public function getOwnerKey() /** * Get the name of the "where in" method for eager loading. + * * @param \Illuminate\Database\Eloquent\Model $model * @param string $key * @return string diff --git a/src/Schema/Blueprint.php b/src/Schema/Blueprint.php index ad26b4ddb..557373cbc 100644 --- a/src/Schema/Blueprint.php +++ b/src/Schema/Blueprint.php @@ -8,6 +8,7 @@ class Blueprint extends \Illuminate\Database\Schema\Blueprint { /** * The MongoConnection object for this blueprint. + * * @var \Jenssegers\Mongodb\Connection */ protected $connection; @@ -15,11 +16,13 @@ class Blueprint extends \Illuminate\Database\Schema\Blueprint /** * The MongoCollection object for this blueprint. * @var \Jenssegers\Mongodb\Collection|\MongoDB\Collection + * */ protected $collection; /** * Fluent columns. + * * @var array */ protected $columns = []; @@ -167,6 +170,7 @@ public function unique($columns = null, $name = null, $algorithm = null, $option /** * Specify a non blocking index for the collection. + * * @param string|array $columns * @return Blueprint */ @@ -181,6 +185,7 @@ public function background($columns = null) /** * Specify a sparse index for the collection. + * * @param string|array $columns * @param array $options * @return Blueprint @@ -198,6 +203,7 @@ public function sparse($columns = null, $options = []) /** * Specify a geospatial index for the collection. + * * @param string|array $columns * @param string $index * @param array $options @@ -221,8 +227,9 @@ public function geospatial($columns = null, $index = '2d', $options = []) } /** - * Specify the number of seconds after wich a document should be considered expired based, + * Specify the number of seconds after which a document should be considered expired based, * on the given single-field index containing a date. + * * @param string|array $columns * @param int $seconds * @return Blueprint @@ -238,6 +245,7 @@ public function expire($columns, $seconds) /** * Indicate that the collection needs to be created. + * * @param array $options * @return void */ @@ -271,6 +279,7 @@ public function addColumn($type, $name, array $parameters = []) /** * Specify a sparse and unique index for the collection. + * * @param string|array $columns * @param array $options * @return Blueprint @@ -289,6 +298,7 @@ public function sparse_and_unique($columns = null, $options = []) /** * Allow fluent columns. + * * @param string|array $columns * @return string|array */ @@ -305,6 +315,7 @@ protected function fluent($columns = null) /** * Allows the use of unsupported schema methods. + * * @param $method * @param $args * @return Blueprint diff --git a/src/Schema/Builder.php b/src/Schema/Builder.php index 36aaf9be7..e681b3e41 100644 --- a/src/Schema/Builder.php +++ b/src/Schema/Builder.php @@ -24,6 +24,7 @@ public function hasColumns($table, array $columns) /** * Determine if the given collection exists. + * * @param string $name * @return bool */ @@ -50,6 +51,7 @@ public function hasTable($collection) /** * Modify a collection on the schema. + * * @param string $collection * @param Closure $callback * @return bool @@ -127,6 +129,7 @@ protected function createBlueprint($collection, Closure $callback = null) /** * Get collection. + * * @param string $name * @return bool|\MongoDB\Model\CollectionInfo */ @@ -145,6 +148,7 @@ public function getCollection($name) /** * Get all of the collections names for the database. + * * @return array */ protected function getAllCollections() diff --git a/src/Validation/DatabasePresenceVerifier.php b/src/Validation/DatabasePresenceVerifier.php index 6753db3d9..cb8703944 100644 --- a/src/Validation/DatabasePresenceVerifier.php +++ b/src/Validation/DatabasePresenceVerifier.php @@ -6,6 +6,7 @@ class DatabasePresenceVerifier extends \Illuminate\Validation\DatabasePresenceVe { /** * Count the number of objects in a collection having the given value. + * * @param string $collection * @param string $column * @param string $value diff --git a/tests/TestCase.php b/tests/TestCase.php index 20970656a..cf379a652 100644 --- a/tests/TestCase.php +++ b/tests/TestCase.php @@ -8,6 +8,7 @@ class TestCase extends Orchestra\Testbench\TestCase { /** * Get application providers. + * * @param \Illuminate\Foundation\Application $app * @return array */ @@ -22,6 +23,7 @@ protected function getApplicationProviders($app) /** * Get package providers. + * * @param \Illuminate\Foundation\Application $app * @return array */ @@ -37,6 +39,7 @@ protected function getPackageProviders($app) /** * Define environment setup. + * * @param Illuminate\Foundation\Application $app * @return void */ diff --git a/tests/models/Birthday.php b/tests/models/Birthday.php index c30ebb746..3e725e495 100644 --- a/tests/models/Birthday.php +++ b/tests/models/Birthday.php @@ -6,6 +6,7 @@ /** * Class Birthday. + * * @property string $name * @property string $birthday * @property string $day diff --git a/tests/models/Book.php b/tests/models/Book.php index 17100f0c6..e247abbfb 100644 --- a/tests/models/Book.php +++ b/tests/models/Book.php @@ -7,6 +7,7 @@ /** * Class Book. + * * @property string $title * @property string $author * @property array $chapters diff --git a/tests/models/Item.php b/tests/models/Item.php index 32d6ceb41..4a29aa05a 100644 --- a/tests/models/Item.php +++ b/tests/models/Item.php @@ -8,6 +8,7 @@ /** * Class Item. + * * @property \Carbon\Carbon $created_at */ class Item extends Eloquent diff --git a/tests/models/Soft.php b/tests/models/Soft.php index 6e8e37f36..c4571e6b0 100644 --- a/tests/models/Soft.php +++ b/tests/models/Soft.php @@ -7,6 +7,7 @@ /** * Class Soft. + * * @property \Carbon\Carbon $deleted_at */ class Soft extends Eloquent diff --git a/tests/models/User.php b/tests/models/User.php index 359f6d9fa..ff96b89e4 100644 --- a/tests/models/User.php +++ b/tests/models/User.php @@ -12,6 +12,7 @@ /** * Class User. + * * @property string $_id * @property string $name * @property string $email From 8b4c6dc5b61c41d86848122ec0e2922a8fb6bc22 Mon Sep 17 00:00:00 2001 From: divine <48183131+divine@users.noreply.github.com> Date: Wed, 9 Feb 2022 04:26:20 +0300 Subject: [PATCH 007/446] fix: apply php-cs-fixer results --- src/Schema/Blueprint.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Schema/Blueprint.php b/src/Schema/Blueprint.php index 557373cbc..7e7fb6786 100644 --- a/src/Schema/Blueprint.php +++ b/src/Schema/Blueprint.php @@ -15,8 +15,8 @@ class Blueprint extends \Illuminate\Database\Schema\Blueprint /** * The MongoCollection object for this blueprint. - * @var \Jenssegers\Mongodb\Collection|\MongoDB\Collection * + * @var \Jenssegers\Mongodb\Collection|\MongoDB\Collection */ protected $collection; From 20b9d0e6ea7bb46280e75c415bf88ebdca279700 Mon Sep 17 00:00:00 2001 From: divine <48183131+divine@users.noreply.github.com> Date: Wed, 9 Feb 2022 04:30:38 +0300 Subject: [PATCH 008/446] fix: small php-doc comment --- src/Validation/DatabasePresenceVerifier.php | 1 + 1 file changed, 1 insertion(+) diff --git a/src/Validation/DatabasePresenceVerifier.php b/src/Validation/DatabasePresenceVerifier.php index cb8703944..9a969bb74 100644 --- a/src/Validation/DatabasePresenceVerifier.php +++ b/src/Validation/DatabasePresenceVerifier.php @@ -32,6 +32,7 @@ public function getCount($collection, $column, $value, $excludeId = null, $idCol /** * Count the number of objects in a collection with the given values. + * * @param string $collection * @param string $column * @param array $values From b6a76f9c453a275b0af7a7fbfa0e0e7a1264b933 Mon Sep 17 00:00:00 2001 From: divine <48183131+divine@users.noreply.github.com> Date: Wed, 9 Feb 2022 05:03:48 +0300 Subject: [PATCH 009/446] fix: apply php-cs-fixer result --- src/Validation/DatabasePresenceVerifier.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Validation/DatabasePresenceVerifier.php b/src/Validation/DatabasePresenceVerifier.php index 9a969bb74..6c38a04b2 100644 --- a/src/Validation/DatabasePresenceVerifier.php +++ b/src/Validation/DatabasePresenceVerifier.php @@ -32,7 +32,7 @@ public function getCount($collection, $column, $value, $excludeId = null, $idCol /** * Count the number of objects in a collection with the given values. - * + * * @param string $collection * @param string $column * @param array $values From 8d601b2c59dbced485f31959d1c73b55b0bedbfc Mon Sep 17 00:00:00 2001 From: Rob Brain Date: Wed, 2 Mar 2022 03:45:43 +0700 Subject: [PATCH 010/446] Check if failed log storage is disabled in Queue Service Provider (#2357) * fix: check if failed log storage is disabled in Queue Service Provider Co-authored-by: divine <48183131+divine@users.noreply.github.com> --- src/MongodbQueueServiceProvider.php | 41 ++++++++++++++++++++++------- tests/TestCase.php | 1 + tests/config/queue.php | 1 + 3 files changed, 34 insertions(+), 9 deletions(-) diff --git a/src/MongodbQueueServiceProvider.php b/src/MongodbQueueServiceProvider.php index a0f8e0361..7edfdb97f 100644 --- a/src/MongodbQueueServiceProvider.php +++ b/src/MongodbQueueServiceProvider.php @@ -2,23 +2,46 @@ namespace Jenssegers\Mongodb; +use Illuminate\Queue\Failed\NullFailedJobProvider; use Illuminate\Queue\QueueServiceProvider; use Jenssegers\Mongodb\Queue\Failed\MongoFailedJobProvider; class MongodbQueueServiceProvider extends QueueServiceProvider { /** - * @inheritdoc + * Register the failed job services. + * + * @return void */ protected function registerFailedJobServices() { - // Add compatible queue failer if mongodb is configured. - if ($this->app['db']->connection(config('queue.failed.database'))->getDriverName() == 'mongodb') { - $this->app->singleton('queue.failer', function ($app) { - return new MongoFailedJobProvider($app['db'], config('queue.failed.database'), config('queue.failed.table')); - }); - } else { - parent::registerFailedJobServices(); - } + $this->app->singleton('queue.failer', function ($app) { + $config = $app['config']['queue.failed']; + + if (array_key_exists('driver', $config) && + (is_null($config['driver']) || $config['driver'] === 'null')) { + return new NullFailedJobProvider; + } + + if (isset($config['driver']) && $config['driver'] === 'mongodb') { + return $this->mongoFailedJobProvider($config); + } elseif (isset($config['driver']) && $config['driver'] === 'dynamodb') { + return $this->dynamoFailedJobProvider($config); + } elseif (isset($config['driver']) && $config['driver'] === 'database-uuids') { + return $this->databaseUuidFailedJobProvider($config); + } elseif (isset($config['table'])) { + return $this->databaseFailedJobProvider($config); + } else { + return new NullFailedJobProvider; + } + }); + } + + /** + * Create a new MongoDB failed job provider. + */ + protected function mongoFailedJobProvider(array $config): MongoFailedJobProvider + { + return new MongoFailedJobProvider($this->app['db'], $config['database'], $config['table']); } } diff --git a/tests/TestCase.php b/tests/TestCase.php index cf379a652..584ff82de 100644 --- a/tests/TestCase.php +++ b/tests/TestCase.php @@ -71,5 +71,6 @@ protected function getEnvironmentSetUp($app) 'expire' => 60, ]); $app['config']->set('queue.failed.database', 'mongodb2'); + $app['config']->set('queue.failed.driver', 'mongodb'); } } diff --git a/tests/config/queue.php b/tests/config/queue.php index 20ef36703..7d52487fa 100644 --- a/tests/config/queue.php +++ b/tests/config/queue.php @@ -17,6 +17,7 @@ 'failed' => [ 'database' => env('MONGO_DATABASE'), + 'driver' => 'mongodb', 'table' => 'failed_jobs', ], From f4c448fea0d40c7c0e08b0619990603fe3af33b5 Mon Sep 17 00:00:00 2001 From: Divine <48183131+divine@users.noreply.github.com> Date: Mon, 7 Mar 2022 23:07:22 +0300 Subject: [PATCH 011/446] feat: backport support for cursor pagination (#2362) Backport #2358 to L9 Co-Authored-By: Jeroen van de Weerd --- CHANGELOG.md | 5 +++++ src/Eloquent/Builder.php | 23 +++++++++++++++++++++++ tests/QueryTest.php | 23 +++++++++++++++++++++++ 3 files changed, 51 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 291694453..37f2300f2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,11 @@ All notable changes to this project will be documented in this file. ## [Unreleased] +### Added +- Backport support for cursor pagination [#2358](https://github.com/jenssegers/laravel-mongodb/pull/2358) by [@Jeroenwv](https://github.com/Jeroenwv). + +## [3.9.0] - 2022-02-17 + ### Added - Compatibility with Laravel 9.x [#2344](https://github.com/jenssegers/laravel-mongodb/pull/2344) by [@divine](https://github.com/divine). diff --git a/src/Eloquent/Builder.php b/src/Eloquent/Builder.php index 398f3893b..bfa3d634a 100644 --- a/src/Eloquent/Builder.php +++ b/src/Eloquent/Builder.php @@ -217,4 +217,27 @@ public function getConnection() { return $this->query->getConnection(); } + + /** + * @inheritdoc + */ + protected function ensureOrderForCursorPagination($shouldReverse = false) + { + if (empty($this->query->orders)) { + $this->enforceOrderBy(); + } + + if ($shouldReverse) { + $this->query->orders = collect($this->query->orders)->map(function ($direction) { + return $direction === 1 ? -1 : 1; + })->toArray(); + } + + return collect($this->query->orders)->map(function ($direction, $column) { + return [ + 'column' => $column, + 'direction' => $direction === 1 ? 'asc' : 'desc', + ]; + })->values(); + } } diff --git a/tests/QueryTest.php b/tests/QueryTest.php index cc22df587..b2716e178 100644 --- a/tests/QueryTest.php +++ b/tests/QueryTest.php @@ -383,6 +383,29 @@ public function testPaginate(): void $this->assertEquals(1, $results->currentPage()); } + public function testCursorPaginate(): void + { + $results = User::cursorPaginate(2); + $this->assertEquals(2, $results->count()); + $this->assertNotNull($results->first()->title); + $this->assertNotNull($results->nextCursor()); + $this->assertTrue($results->onFirstPage()); + + $results = User::cursorPaginate(2, ['name', 'age']); + $this->assertEquals(2, $results->count()); + $this->assertNull($results->first()->title); + + $results = User::orderBy('age', 'desc')->cursorPaginate(2, ['name', 'age']); + $this->assertEquals(2, $results->count()); + $this->assertEquals(37, $results->first()->age); + $this->assertNull($results->first()->title); + + $results = User::whereNotNull('age')->orderBy('age', 'asc')->cursorPaginate(2, ['name', 'age']); + $this->assertEquals(2, $results->count()); + $this->assertEquals(13, $results->first()->age); + $this->assertNull($results->first()->title); + } + public function testUpdate(): void { $this->assertEquals(1, User::where(['name' => 'John Doe'])->update(['name' => 'Jim Morrison'])); From fc67e04d834baacc67f15c700113a4d94c578c05 Mon Sep 17 00:00:00 2001 From: divine <48183131+divine@users.noreply.github.com> Date: Fri, 11 Mar 2022 04:14:08 +0300 Subject: [PATCH 012/446] chore: update changelog and prepare release --- CHANGELOG.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 37f2300f2..a5f02194d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,9 +3,14 @@ All notable changes to this project will be documented in this file. ## [Unreleased] +## [3.9.1] - 2022-03-11 + ### Added - Backport support for cursor pagination [#2358](https://github.com/jenssegers/laravel-mongodb/pull/2358) by [@Jeroenwv](https://github.com/Jeroenwv). +### Fixed +- Check if queue service is disabled [#2357](https://github.com/jenssegers/laravel-mongodb/pull/2357) by [@robjbrain](https://github.com/robjbrain). + ## [3.9.0] - 2022-02-17 ### Added From 5d292a2b8a250678206e3c4ec5c4920fef2c526b Mon Sep 17 00:00:00 2001 From: Pavel Borunov <8665691+mrneatly@users.noreply.github.com> Date: Sat, 28 May 2022 09:57:03 +0300 Subject: [PATCH 013/446] Respect new Laravel accessors's approach Fix getting a value from a one-word `\Illuminate\Database\Eloquent\Casts\Attribute`-returning accessors --- src/Eloquent/Model.php | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/Eloquent/Model.php b/src/Eloquent/Model.php index 226bc357d..ac11b9ae0 100644 --- a/src/Eloquent/Model.php +++ b/src/Eloquent/Model.php @@ -155,8 +155,12 @@ public function getAttribute($key) } // This checks for embedded relation support. - if (method_exists($this, $key) && ! method_exists(self::class, $key)) { - return $this->getRelationValue($key); + if ( + method_exists($this, $key) + && ! method_exists(self::class, $key) + && ! $this->hasAttributeGetMutator($key) + ) { + return $this->getRelationValue($key); } return parent::getAttribute($key); From f6c96783d423e45b5b950f2dee28cfdcae44d127 Mon Sep 17 00:00:00 2001 From: Antti Peisa Date: Sat, 16 Jul 2022 12:50:09 +0300 Subject: [PATCH 014/446] support stringable objects when sorting --- src/Query/Builder.php | 2 +- tests/QueryTest.php | 29 +++++++++++++++++++++++++++++ 2 files changed, 30 insertions(+), 1 deletion(-) diff --git a/src/Query/Builder.php b/src/Query/Builder.php index f83bce3e2..3c60a071f 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -512,7 +512,7 @@ public function orderBy($column, $direction = 'asc') if ($column == 'natural') { $this->orders['$natural'] = $direction; } else { - $this->orders[$column] = $direction; + $this->orders[(string) $column] = $direction; } return $this; diff --git a/tests/QueryTest.php b/tests/QueryTest.php index b2716e178..db5c81787 100644 --- a/tests/QueryTest.php +++ b/tests/QueryTest.php @@ -239,6 +239,17 @@ public function testOrder(): void $this->assertEquals(35, $user->age); } + public function testStringableOrder(): void + { + $age = new stringableObject("age"); + + $user = User::whereNotNull('age')->orderBy($age, 'asc')->first(); + $this->assertEquals(13, $user->age); + + $user = User::whereNotNull('age')->orderBy($age, 'desc')->first(); + $this->assertEquals(37, $user->age); + } + public function testGroupBy(): void { $users = User::groupBy('title')->get(); @@ -470,3 +481,21 @@ public function testMultipleSortOrder(): void $this->assertEquals('Brett Boe', $subset[2]->name); } } + +/** + * Mockup class to test stringable objects + */ +class stringableObject implements Stringable { + + private $string; + + public function __construct($string) + { + $this->string = $string; + } + + public function __toString() + { + return $this->string; + } +} From 496f8a0ba7a04637ba6b3c52edb6feef6ffc3581 Mon Sep 17 00:00:00 2001 From: Antti Peisa Date: Sat, 16 Jul 2022 12:52:29 +0300 Subject: [PATCH 015/446] style code fixes --- tests/QueryTest.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/QueryTest.php b/tests/QueryTest.php index db5c81787..beaf3f408 100644 --- a/tests/QueryTest.php +++ b/tests/QueryTest.php @@ -241,7 +241,7 @@ public function testOrder(): void public function testStringableOrder(): void { - $age = new stringableObject("age"); + $age = new stringableObject('age'); $user = User::whereNotNull('age')->orderBy($age, 'asc')->first(); $this->assertEquals(13, $user->age); @@ -483,7 +483,7 @@ public function testMultipleSortOrder(): void } /** - * Mockup class to test stringable objects + * Mockup class to test stringable objects. */ class stringableObject implements Stringable { From 50221ef37edd448605d7b9686402aeb220b902a5 Mon Sep 17 00:00:00 2001 From: Antti Peisa Date: Sat, 16 Jul 2022 12:53:31 +0300 Subject: [PATCH 016/446] style code fixes pt. 2 --- tests/QueryTest.php | 1 - 1 file changed, 1 deletion(-) diff --git a/tests/QueryTest.php b/tests/QueryTest.php index beaf3f408..45151ea1e 100644 --- a/tests/QueryTest.php +++ b/tests/QueryTest.php @@ -486,7 +486,6 @@ public function testMultipleSortOrder(): void * Mockup class to test stringable objects. */ class stringableObject implements Stringable { - private $string; public function __construct($string) From ed86610b85245653f8aa83f6deab7b71da92039a Mon Sep 17 00:00:00 2001 From: Antti Peisa Date: Sat, 16 Jul 2022 12:55:21 +0300 Subject: [PATCH 017/446] make the stringable object type safe --- tests/QueryTest.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/QueryTest.php b/tests/QueryTest.php index 45151ea1e..b790c723b 100644 --- a/tests/QueryTest.php +++ b/tests/QueryTest.php @@ -486,9 +486,9 @@ public function testMultipleSortOrder(): void * Mockup class to test stringable objects. */ class stringableObject implements Stringable { - private $string; + private String $string; - public function __construct($string) + public function __construct(String $string) { $this->string = $string; } From 3a87b28aaaa352bcdffc3e106733f64caab3c5dd Mon Sep 17 00:00:00 2001 From: Antti Peisa Date: Sat, 16 Jul 2022 13:02:38 +0300 Subject: [PATCH 018/446] style code fixes pt. 3 --- tests/QueryTest.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/QueryTest.php b/tests/QueryTest.php index b790c723b..378da9d1d 100644 --- a/tests/QueryTest.php +++ b/tests/QueryTest.php @@ -486,9 +486,9 @@ public function testMultipleSortOrder(): void * Mockup class to test stringable objects. */ class stringableObject implements Stringable { - private String $string; + private string $string; - public function __construct(String $string) + public function __construct(string $string) { $this->string = $string; } From f7895bcfd5e57dbc22c9119efdda5850ba15292d Mon Sep 17 00:00:00 2001 From: Antti Peisa Date: Mon, 25 Jul 2022 13:58:59 +0300 Subject: [PATCH 019/446] Update tests/QueryTest.php Co-authored-by: Divine <48183131+divine@users.noreply.github.com> --- tests/QueryTest.php | 17 ----------------- 1 file changed, 17 deletions(-) diff --git a/tests/QueryTest.php b/tests/QueryTest.php index 378da9d1d..d4b1eef3f 100644 --- a/tests/QueryTest.php +++ b/tests/QueryTest.php @@ -481,20 +481,3 @@ public function testMultipleSortOrder(): void $this->assertEquals('Brett Boe', $subset[2]->name); } } - -/** - * Mockup class to test stringable objects. - */ -class stringableObject implements Stringable { - private string $string; - - public function __construct(string $string) - { - $this->string = $string; - } - - public function __toString() - { - return $this->string; - } -} From f670c5fe5ac8a6775d97e11632dc3e1de01aa054 Mon Sep 17 00:00:00 2001 From: Antti Peisa Date: Mon, 25 Jul 2022 13:59:05 +0300 Subject: [PATCH 020/446] Update tests/QueryTest.php Co-authored-by: Divine <48183131+divine@users.noreply.github.com> --- tests/QueryTest.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/QueryTest.php b/tests/QueryTest.php index d4b1eef3f..c85cd2a21 100644 --- a/tests/QueryTest.php +++ b/tests/QueryTest.php @@ -241,7 +241,7 @@ public function testOrder(): void public function testStringableOrder(): void { - $age = new stringableObject('age'); + $age = str('age'); $user = User::whereNotNull('age')->orderBy($age, 'asc')->first(); $this->assertEquals(13, $user->age); From ce693a8cfbea811fe506d540528cda3714e41e99 Mon Sep 17 00:00:00 2001 From: Rosemary Orchard Date: Thu, 25 Aug 2022 14:17:58 +0100 Subject: [PATCH 021/446] Fix formatting --- src/Eloquent/Model.php | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/Eloquent/Model.php b/src/Eloquent/Model.php index ac11b9ae0..0cb303262 100644 --- a/src/Eloquent/Model.php +++ b/src/Eloquent/Model.php @@ -156,11 +156,11 @@ public function getAttribute($key) // This checks for embedded relation support. if ( - method_exists($this, $key) - && ! method_exists(self::class, $key) - && ! $this->hasAttributeGetMutator($key) - ) { - return $this->getRelationValue($key); + method_exists($this, $key) + && !method_exists(self::class, $key) + && !$this->hasAttributeGetMutator($key) + ) { + return $this->getRelationValue($key); } return parent::getAttribute($key); From 79fad0e9e7bb772ea658e41cc5993370d19a7a39 Mon Sep 17 00:00:00 2001 From: Rosemary Orchard Date: Thu, 25 Aug 2022 14:22:46 +0100 Subject: [PATCH 022/446] More CS-Fixer formatting, unrelated to the PR --- src/Eloquent/Model.php | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/src/Eloquent/Model.php b/src/Eloquent/Model.php index 0cb303262..cf2b3c01b 100644 --- a/src/Eloquent/Model.php +++ b/src/Eloquent/Model.php @@ -57,15 +57,15 @@ public function getIdAttribute($value = null) { // If we don't have a value for 'id', we will use the Mongo '_id' value. // This allows us to work with models in a more sql-like way. - if (! $value && array_key_exists('_id', $this->attributes)) { + if (!$value && array_key_exists('_id', $this->attributes)) { $value = $this->attributes['_id']; } // Convert ObjectID to string. if ($value instanceof ObjectID) { - return (string) $value; + return (string)$value; } elseif ($value instanceof Binary) { - return (string) $value->getData(); + return (string)$value->getData(); } return $value; @@ -90,7 +90,7 @@ public function fromDateTime($value) } // Let Eloquent convert the value to a DateTime instance. - if (! $value instanceof DateTimeInterface) { + if (!$value instanceof DateTimeInterface) { $value = parent::asDateTime($value); } @@ -145,7 +145,7 @@ public function getTable() */ public function getAttribute($key) { - if (! $key) { + if (!$key) { return; } @@ -216,16 +216,16 @@ public function attributesToArray() // nicely when your models are converted to JSON. foreach ($attributes as $key => &$value) { if ($value instanceof ObjectID) { - $value = (string) $value; + $value = (string)$value; } elseif ($value instanceof Binary) { - $value = (string) $value->getData(); + $value = (string)$value->getData(); } } // Convert dot-notation dates. foreach ($this->getDates() as $key) { if (Str::contains($key, '.') && Arr::has($attributes, $key)) { - Arr::set($attributes, $key, (string) $this->asDateTime(Arr::get($attributes, $key))); + Arr::set($attributes, $key, (string)$this->asDateTime(Arr::get($attributes, $key))); } } @@ -245,7 +245,7 @@ public function getCasts() */ public function originalIsEquivalent($key) { - if (! array_key_exists($key, $this->original)) { + if (!array_key_exists($key, $this->original)) { return false; } @@ -273,7 +273,7 @@ public function originalIsEquivalent($key) } return is_numeric($attribute) && is_numeric($original) - && strcmp((string) $attribute, (string) $original) === 0; + && strcmp((string)$attribute, (string)$original) === 0; } /** @@ -354,7 +354,7 @@ protected function pushAttributeValues($column, array $values, $unique = false) foreach ($values as $value) { // Don't add duplicate values when we only want unique values. - if ($unique && (! is_array($current) || in_array($value, $current))) { + if ($unique && (!is_array($current) || in_array($value, $current))) { continue; } @@ -396,7 +396,7 @@ protected function pullAttributeValues($column, array $values) */ public function getForeignKey() { - return Str::snake(class_basename($this)).'_'.ltrim($this->primaryKey, '_'); + return Str::snake(class_basename($this)) . '_' . ltrim($this->primaryKey, '_'); } /** @@ -461,13 +461,13 @@ public function getQueueableRelations() if ($relation instanceof QueueableCollection) { foreach ($relation->getQueueableRelations() as $collectionValue) { - $relations[] = $key.'.'.$collectionValue; + $relations[] = $key . '.' . $collectionValue; } } if ($relation instanceof QueueableEntity) { foreach ($relation->getQueueableRelations() as $entityKey => $entityValue) { - $relations[] = $key.'.'.$entityValue; + $relations[] = $key . '.' . $entityValue; } } } From e5a8272816b29587c7022276d9ad9ed40cd178e0 Mon Sep 17 00:00:00 2001 From: Rosemary Orchard Date: Thu, 25 Aug 2022 14:25:57 +0100 Subject: [PATCH 023/446] PSR2?! --- src/Eloquent/Model.php | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/src/Eloquent/Model.php b/src/Eloquent/Model.php index cf2b3c01b..5836cf83d 100644 --- a/src/Eloquent/Model.php +++ b/src/Eloquent/Model.php @@ -57,15 +57,15 @@ public function getIdAttribute($value = null) { // If we don't have a value for 'id', we will use the Mongo '_id' value. // This allows us to work with models in a more sql-like way. - if (!$value && array_key_exists('_id', $this->attributes)) { + if (! $value && array_key_exists('_id', $this->attributes)) { $value = $this->attributes['_id']; } // Convert ObjectID to string. if ($value instanceof ObjectID) { - return (string)$value; + return (string) $value; } elseif ($value instanceof Binary) { - return (string)$value->getData(); + return (string) $value->getData(); } return $value; @@ -90,7 +90,7 @@ public function fromDateTime($value) } // Let Eloquent convert the value to a DateTime instance. - if (!$value instanceof DateTimeInterface) { + if (! $value instanceof DateTimeInterface) { $value = parent::asDateTime($value); } @@ -145,7 +145,7 @@ public function getTable() */ public function getAttribute($key) { - if (!$key) { + if (! $key) { return; } @@ -157,8 +157,8 @@ public function getAttribute($key) // This checks for embedded relation support. if ( method_exists($this, $key) - && !method_exists(self::class, $key) - && !$this->hasAttributeGetMutator($key) + && ! method_exists(self::class, $key) + && ! $this->hasAttributeGetMutator($key) ) { return $this->getRelationValue($key); } @@ -216,16 +216,16 @@ public function attributesToArray() // nicely when your models are converted to JSON. foreach ($attributes as $key => &$value) { if ($value instanceof ObjectID) { - $value = (string)$value; + $value = (string) $value; } elseif ($value instanceof Binary) { - $value = (string)$value->getData(); + $value = (string) $value->getData(); } } // Convert dot-notation dates. foreach ($this->getDates() as $key) { if (Str::contains($key, '.') && Arr::has($attributes, $key)) { - Arr::set($attributes, $key, (string)$this->asDateTime(Arr::get($attributes, $key))); + Arr::set($attributes, $key, (string) $this->asDateTime(Arr::get($attributes, $key))); } } @@ -245,7 +245,7 @@ public function getCasts() */ public function originalIsEquivalent($key) { - if (!array_key_exists($key, $this->original)) { + if (! array_key_exists($key, $this->original)) { return false; } @@ -273,7 +273,7 @@ public function originalIsEquivalent($key) } return is_numeric($attribute) && is_numeric($original) - && strcmp((string)$attribute, (string)$original) === 0; + && strcmp((string) $attribute, (string) $original) === 0; } /** @@ -354,7 +354,7 @@ protected function pushAttributeValues($column, array $values, $unique = false) foreach ($values as $value) { // Don't add duplicate values when we only want unique values. - if ($unique && (!is_array($current) || in_array($value, $current))) { + if ($unique && (! is_array($current) || in_array($value, $current))) { continue; } @@ -396,7 +396,7 @@ protected function pullAttributeValues($column, array $values) */ public function getForeignKey() { - return Str::snake(class_basename($this)) . '_' . ltrim($this->primaryKey, '_'); + return Str::snake(class_basename($this)).'_'.ltrim($this->primaryKey, '_'); } /** @@ -461,13 +461,13 @@ public function getQueueableRelations() if ($relation instanceof QueueableCollection) { foreach ($relation->getQueueableRelations() as $collectionValue) { - $relations[] = $key . '.' . $collectionValue; + $relations[] = $key.'.'.$collectionValue; } } if ($relation instanceof QueueableEntity) { foreach ($relation->getQueueableRelations() as $entityKey => $entityValue) { - $relations[] = $key . '.' . $entityValue; + $relations[] = $key.'.'.$entityValue; } } } From 6b11977468929e744bd07d9eba827b513e49fd04 Mon Sep 17 00:00:00 2001 From: Rosemary Orchard Date: Thu, 25 Aug 2022 14:17:58 +0100 Subject: [PATCH 024/446] Fix formatting More CS-Fixer formatting, unrelated to the PR PSR2?! --- src/Eloquent/Model.php | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/Eloquent/Model.php b/src/Eloquent/Model.php index ac11b9ae0..5836cf83d 100644 --- a/src/Eloquent/Model.php +++ b/src/Eloquent/Model.php @@ -156,11 +156,11 @@ public function getAttribute($key) // This checks for embedded relation support. if ( - method_exists($this, $key) - && ! method_exists(self::class, $key) - && ! $this->hasAttributeGetMutator($key) - ) { - return $this->getRelationValue($key); + method_exists($this, $key) + && ! method_exists(self::class, $key) + && ! $this->hasAttributeGetMutator($key) + ) { + return $this->getRelationValue($key); } return parent::getAttribute($key); From c27924cff38c264db95dd7317daef3addfd154e1 Mon Sep 17 00:00:00 2001 From: Rosemary Orchard Date: Thu, 25 Aug 2022 17:11:29 +0100 Subject: [PATCH 025/446] Add tests for the mutator --- tests/ModelTest.php | 18 ++++++++++++++++++ tests/models/User.php | 16 +++++++++++++++- 2 files changed, 33 insertions(+), 1 deletion(-) diff --git a/tests/ModelTest.php b/tests/ModelTest.php index 75723c1cb..9e8f60fea 100644 --- a/tests/ModelTest.php +++ b/tests/ModelTest.php @@ -6,6 +6,7 @@ use Illuminate\Database\Eloquent\Collection as EloquentCollection; use Illuminate\Database\Eloquent\ModelNotFoundException; use Illuminate\Support\Facades\Date; +use Illuminate\Support\Str; use Jenssegers\Mongodb\Collection; use Jenssegers\Mongodb\Connection; use Jenssegers\Mongodb\Eloquent\Model; @@ -678,6 +679,23 @@ public function testDotNotation(): void $this->assertEquals('Strasbourg', $user['address.city']); } + public function testAttributeMutator(): void + { + $username = 'JaneDoe'; + $usernameSlug = Str::slug($username); + $user = User::create([ + 'name' => 'Jane Doe', + 'username' => $username, + ]); + + $this->assertNotEquals($username, $user->getAttribute('username')); + $this->assertNotEquals($username, $user['username']); + $this->assertNotEquals($username, $user->username); + $this->assertEquals($usernameSlug, $user->getAttribute('username')); + $this->assertEquals($usernameSlug, $user['username']); + $this->assertEquals($usernameSlug, $user->username); + } + public function testMultipleLevelDotNotation(): void { /** @var Book $book */ diff --git a/tests/models/User.php b/tests/models/User.php index ff96b89e4..b394ea6e7 100644 --- a/tests/models/User.php +++ b/tests/models/User.php @@ -6,7 +6,9 @@ use Illuminate\Auth\Passwords\CanResetPassword; use Illuminate\Contracts\Auth\Authenticatable as AuthenticatableContract; use Illuminate\Contracts\Auth\CanResetPassword as CanResetPasswordContract; +use Illuminate\Database\Eloquent\Casts\Attribute; use Illuminate\Notifications\Notifiable; +use Illuminate\Support\Str; use Jenssegers\Mongodb\Eloquent\HybridRelations; use Jenssegers\Mongodb\Eloquent\Model as Eloquent; @@ -21,10 +23,14 @@ * @property \Carbon\Carbon $birthday * @property \Carbon\Carbon $created_at * @property \Carbon\Carbon $updated_at + * @property string $username */ class User extends Eloquent implements AuthenticatableContract, CanResetPasswordContract { - use Authenticatable, CanResetPassword, HybridRelations, Notifiable; + use Authenticatable; + use CanResetPassword; + use HybridRelations; + use Notifiable; protected $connection = 'mongodb'; protected $dates = ['birthday', 'entry.date']; @@ -84,4 +90,12 @@ protected function serializeDate(DateTimeInterface $date) { return $date->format('l jS \of F Y h:i:s A'); } + + protected function username(): Attribute + { + return Attribute::make( + get: fn ($value) => $value, + set: fn ($value) => Str::slug($value) + ); + } } From 61cc6ed41b9b436f83be53089e5b485faafe46fc Mon Sep 17 00:00:00 2001 From: Stas Date: Thu, 1 Sep 2022 16:20:31 +0300 Subject: [PATCH 026/446] Add info about new release 3.9.2 (#2440) * Add info about new release 3.9.2 * chore: update changelog Co-authored-by: Divine <48183131+divine@users.noreply.github.com> --- CHANGELOG.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index a5f02194d..b1018c1cb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,14 @@ All notable changes to this project will be documented in this file. ## [Unreleased] +## [3.9.2] - 2022-09-01 + +### Addded +- Add single word name mutators [#2438](https://github.com/jenssegers/laravel-mongodb/pull/2438) by [@RosemaryOrchard](https://github.com/RosemaryOrchard) & [@mrneatly](https://github.com/mrneatly). + +### Fixed +- Fix stringable sort [#2420](https://github.com/jenssegers/laravel-mongodb/pull/2420) by [@apeisa](https://github.com/apeisa). + ## [3.9.1] - 2022-03-11 ### Added From 42e010075a62dd57756c460664c9c1c9803ffde8 Mon Sep 17 00:00:00 2001 From: abofazl rasoli <75317352+abolfazl-rasoli@users.noreply.github.com> Date: Fri, 4 Nov 2022 16:18:52 +0330 Subject: [PATCH 027/446] chore: test firstOrCreate method for the model (#2399) --- tests/ModelTest.php | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/tests/ModelTest.php b/tests/ModelTest.php index 9e8f60fea..22e06baee 100644 --- a/tests/ModelTest.php +++ b/tests/ModelTest.php @@ -768,4 +768,23 @@ public function testGuardedModel() $model->fill(['level1' => $dataValues]); $this->assertEquals($dataValues, $model->getAttribute('level1')); } + + public function testFirstOrCreate(): void + { + $name = 'Jane Poe'; + + /** @var User $user */ + $user = User::where('name', $name)->first(); + $this->assertNull($user); + + /** @var User $user */ + $user = User::firstOrCreate(compact('name')); + $this->assertInstanceOf(Model::class, $user); + $this->assertTrue($user->exists); + $this->assertEquals($name, $user->name); + + /** @var User $check */ + $check = User::where('name', $name)->first(); + $this->assertEquals($user->_id, $check->_id); + } } From dbde5127ab763a737df6cfcb63ff58206d810144 Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Thu, 10 Nov 2022 13:55:56 +0100 Subject: [PATCH 028/446] Pass timeout in milliseconds (#2461) --- src/Query/Builder.php | 2 +- tests/QueryBuilderTest.php | 40 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 41 insertions(+), 1 deletion(-) diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 3c60a071f..6412ab603 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -380,7 +380,7 @@ public function getFresh($columns = [], $returnLazy = false) // Apply order, offset, limit and projection if ($this->timeout) { - $options['maxTimeMS'] = $this->timeout; + $options['maxTimeMS'] = $this->timeout * 1000; } if ($this->orders) { $options['sort'] = $this->orders; diff --git a/tests/QueryBuilderTest.php b/tests/QueryBuilderTest.php index 11b7404f9..c169071d0 100644 --- a/tests/QueryBuilderTest.php +++ b/tests/QueryBuilderTest.php @@ -5,12 +5,17 @@ use Illuminate\Support\Facades\Date; use Illuminate\Support\Facades\DB; use Illuminate\Support\LazyCollection; +use Illuminate\Testing\Assert; use Jenssegers\Mongodb\Collection; use Jenssegers\Mongodb\Query\Builder; use MongoDB\BSON\ObjectId; use MongoDB\BSON\Regex; use MongoDB\BSON\UTCDateTime; use MongoDB\Driver\Cursor; +use MongoDB\Driver\Monitoring\CommandFailedEvent; +use MongoDB\Driver\Monitoring\CommandStartedEvent; +use MongoDB\Driver\Monitoring\CommandSubscriber; +use MongoDB\Driver\Monitoring\CommandSucceededEvent; class QueryBuilderTest extends TestCase { @@ -129,6 +134,41 @@ public function testFind() $this->assertEquals('John Doe', $user['name']); } + public function testFindWithTimeout() + { + $id = DB::collection('users')->insertGetId(['name' => 'John Doe']); + + $subscriber = new class implements CommandSubscriber + { + public function commandStarted(CommandStartedEvent $event) + { + if ($event->getCommandName() !== 'find') { + return; + } + + Assert::assertObjectHasAttribute('maxTimeMS', $event->getCommand()); + + // Expect the timeout to be converted to milliseconds + Assert::assertSame(1000, $event->getCommand()->maxTimeMS); + } + + public function commandFailed(CommandFailedEvent $event) + { + } + + public function commandSucceeded(CommandSucceededEvent $event) + { + } + }; + + DB::getMongoClient()->getManager()->addSubscriber($subscriber); + try { + DB::collection('users')->timeout(1)->find($id); + } finally { + DB::getMongoClient()->getManager()->removeSubscriber($subscriber); + } + } + public function testFindNull() { $user = DB::collection('users')->find(null); From 560e05e7d80a5765f2b85ae02a490a17fb3ee6db Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Mon, 14 Nov 2022 12:46:55 +0100 Subject: [PATCH 029/446] Chore: add types where safe (#2464) * Use direct method calls over call_user_func_array * Add return types where safely possible * Fix styleCI issues --- src/Collection.php | 12 ++-- src/Connection.php | 58 ++++++++++--------- src/Eloquent/Model.php | 24 ++++---- src/Query/Builder.php | 106 ++++++++++++++++++----------------- src/Relations/EmbedsMany.php | 34 +++++------ 5 files changed, 119 insertions(+), 115 deletions(-) diff --git a/src/Collection.php b/src/Collection.php index 8acf6afe5..3980e8de6 100644 --- a/src/Collection.php +++ b/src/Collection.php @@ -23,8 +23,8 @@ class Collection protected $collection; /** - * @param Connection $connection - * @param MongoCollection $collection + * @param Connection $connection + * @param MongoCollection $collection */ public function __construct(Connection $connection, MongoCollection $collection) { @@ -35,14 +35,14 @@ public function __construct(Connection $connection, MongoCollection $collection) /** * Handle dynamic method calls. * - * @param string $method - * @param array $parameters + * @param string $method + * @param array $parameters * @return mixed */ - public function __call($method, $parameters) + public function __call(string $method, array $parameters) { $start = microtime(true); - $result = call_user_func_array([$this->collection, $method], $parameters); + $result = $this->collection->$method(...$parameters); // Once we have run the query we will calculate the time that it took to run and // then log the query, bindings, and execution time so we will report them on diff --git a/src/Connection.php b/src/Connection.php index 57d9d3e37..b65b40ca3 100644 --- a/src/Connection.php +++ b/src/Connection.php @@ -6,27 +6,28 @@ use Illuminate\Support\Arr; use InvalidArgumentException; use MongoDB\Client; +use MongoDB\Database; class Connection extends BaseConnection { /** * The MongoDB database handler. * - * @var \MongoDB\Database + * @var Database */ protected $db; /** * The MongoDB connection handler. * - * @var \MongoDB\Client + * @var Client */ protected $connection; /** * Create a new database connection instance. * - * @param array $config + * @param array $config */ public function __construct(array $config) { @@ -57,7 +58,7 @@ public function __construct(array $config) /** * Begin a fluent query against a database collection. * - * @param string $collection + * @param string $collection * @return Query\Builder */ public function collection($collection) @@ -70,8 +71,8 @@ public function collection($collection) /** * Begin a fluent query against a database collection. * - * @param string $table - * @param string|null $as + * @param string $table + * @param string|null $as * @return Query\Builder */ public function table($table, $as = null) @@ -82,7 +83,7 @@ public function table($table, $as = null) /** * Get a MongoDB collection. * - * @param string $name + * @param string $name * @return Collection */ public function getCollection($name) @@ -101,7 +102,7 @@ public function getSchemaBuilder() /** * Get the MongoDB database object. * - * @return \MongoDB\Database + * @return Database */ public function getMongoDB() { @@ -111,7 +112,7 @@ public function getMongoDB() /** * return MongoDB object. * - * @return \MongoDB\Client + * @return Client */ public function getMongoClient() { @@ -129,12 +130,13 @@ public function getDatabaseName() /** * Get the name of the default database based on db config or try to detect it from dsn. * - * @param string $dsn - * @param array $config + * @param string $dsn + * @param array $config * @return string + * * @throws InvalidArgumentException */ - protected function getDefaultDatabaseName($dsn, $config) + protected function getDefaultDatabaseName(string $dsn, array $config): string { if (empty($config['database'])) { if (preg_match('/^mongodb(?:[+]srv)?:\\/\\/.+\\/([^?&]+)/s', $dsn, $matches)) { @@ -150,12 +152,12 @@ protected function getDefaultDatabaseName($dsn, $config) /** * Create a new MongoDB connection. * - * @param string $dsn - * @param array $config - * @param array $options - * @return \MongoDB\Client + * @param string $dsn + * @param array $config + * @param array $options + * @return Client */ - protected function createConnection($dsn, array $config, array $options) + protected function createConnection($dsn, array $config, array $options): Client { // By default driver options is an empty array. $driverOptions = []; @@ -186,7 +188,7 @@ public function disconnect() /** * Determine if the given configuration array has a dsn string. * - * @param array $config + * @param array $config * @return bool */ protected function hasDsnString(array $config) @@ -197,10 +199,10 @@ protected function hasDsnString(array $config) /** * Get the DSN string form configuration. * - * @param array $config + * @param array $config * @return string */ - protected function getDsnString(array $config) + protected function getDsnString(array $config): string { return $config['dsn']; } @@ -208,10 +210,10 @@ protected function getDsnString(array $config) /** * Get the DSN string for a host / port configuration. * - * @param array $config + * @param array $config * @return string */ - protected function getHostDsn(array $config) + protected function getHostDsn(array $config): string { // Treat host option as array of hosts $hosts = is_array($config['host']) ? $config['host'] : [$config['host']]; @@ -232,10 +234,10 @@ protected function getHostDsn(array $config) /** * Create a DSN string from a configuration. * - * @param array $config + * @param array $config * @return string */ - protected function getDsn(array $config) + protected function getDsn(array $config): string { return $this->hasDsnString($config) ? $this->getDsnString($config) @@ -285,7 +287,7 @@ protected function getDefaultSchemaGrammar() /** * Set database. * - * @param \MongoDB\Database $db + * @param \MongoDB\Database $db */ public function setDatabase(\MongoDB\Database $db) { @@ -295,12 +297,12 @@ public function setDatabase(\MongoDB\Database $db) /** * Dynamically pass methods to the connection. * - * @param string $method - * @param array $parameters + * @param string $method + * @param array $parameters * @return mixed */ public function __call($method, $parameters) { - return call_user_func_array([$this->db, $method], $parameters); + return $this->db->$method(...$parameters); } } diff --git a/src/Eloquent/Model.php b/src/Eloquent/Model.php index 5836cf83d..576d8b36b 100644 --- a/src/Eloquent/Model.php +++ b/src/Eloquent/Model.php @@ -50,7 +50,7 @@ abstract class Model extends BaseModel /** * Custom accessor for the model's id. * - * @param mixed $value + * @param mixed $value * @return mixed */ public function getIdAttribute($value = null) @@ -279,7 +279,7 @@ public function originalIsEquivalent($key) /** * Remove one or more fields. * - * @param mixed $columns + * @param mixed $columns * @return int */ public function drop($columns) @@ -325,8 +325,8 @@ public function push() /** * Remove one or more values from an array. * - * @param string $column - * @param mixed $values + * @param string $column + * @param mixed $values * @return mixed */ public function pull($column, $values) @@ -344,9 +344,9 @@ public function pull($column, $values) /** * Append one or more values to the underlying attribute value and sync with original. * - * @param string $column - * @param array $values - * @param bool $unique + * @param string $column + * @param array $values + * @param bool $unique */ protected function pushAttributeValues($column, array $values, $unique = false) { @@ -369,8 +369,8 @@ protected function pushAttributeValues($column, array $values, $unique = false) /** * Remove one or more values to the underlying attribute value and sync with original. * - * @param string $column - * @param array $values + * @param string $column + * @param array $values */ protected function pullAttributeValues($column, array $values) { @@ -402,7 +402,7 @@ public function getForeignKey() /** * Set the parent relation. * - * @param \Illuminate\Database\Eloquent\Relations\Relation $relation + * @param \Illuminate\Database\Eloquent\Relations\Relation $relation */ public function setParentRelation(Relation $relation) { @@ -495,7 +495,7 @@ protected function getRelationsWithoutParent() * Checks if column exists on a table. As this is a document model, just return true. This also * prevents calls to non-existent function Grammar::compileColumnListing(). * - * @param string $key + * @param string $key * @return bool */ protected function isGuardableColumn($key) @@ -510,7 +510,7 @@ public function __call($method, $parameters) { // Unset method if ($method == 'unset') { - return call_user_func_array([$this, 'drop'], $parameters); + return $this->drop(...$parameters); } return parent::__call($method, $parameters); diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 6412ab603..631e64950 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -140,7 +140,7 @@ public function __construct(Connection $connection, Processor $processor) /** * Set the projections. * - * @param array $columns + * @param array $columns * @return $this */ public function project($columns) @@ -152,7 +152,8 @@ public function project($columns) /** * Set the cursor timeout in seconds. - * @param int $seconds + * + * @param int $seconds * @return $this */ public function timeout($seconds) @@ -165,7 +166,7 @@ public function timeout($seconds) /** * Set the cursor hint. * - * @param mixed $index + * @param mixed $index * @return $this */ public function hint($index) @@ -216,8 +217,8 @@ public function cursor($columns = []) /** * Execute the query as a fresh "select" statement. * - * @param array $columns - * @param bool $returnLazy + * @param array $columns + * @param bool $returnLazy * @return array|static[]|Collection|LazyCollection */ public function getFresh($columns = [], $returnLazy = false) @@ -521,10 +522,10 @@ public function orderBy($column, $direction = 'asc') /** * Add a "where all" clause to the query. * - * @param string $column - * @param array $values - * @param string $boolean - * @param bool $not + * @param string $column + * @param array $values + * @param string $boolean + * @param bool $not * @return $this */ public function whereAll($column, array $values, $boolean = 'and', $not = false) @@ -728,9 +729,10 @@ public function truncate(): bool /** * Get an array with the values of a given column. * - * @param string $column - * @param string $key + * @param string $column + * @param string $key * @return array + * * @deprecated */ public function lists($column, $key = null) @@ -760,9 +762,9 @@ public function raw($expression = null) /** * Append one or more values to an array. * - * @param mixed $column - * @param mixed $value - * @param bool $unique + * @param mixed $column + * @param mixed $value + * @param bool $unique * @return int */ public function push($column, $value = null, $unique = false) @@ -787,8 +789,8 @@ public function push($column, $value = null, $unique = false) /** * Remove one or more values from an array. * - * @param mixed $column - * @param mixed $value + * @param mixed $column + * @param mixed $value * @return int */ public function pull($column, $value = null) @@ -811,7 +813,7 @@ public function pull($column, $value = null) /** * Remove one or more fields. * - * @param mixed $columns + * @param mixed $columns * @return int */ public function drop($columns) @@ -842,8 +844,8 @@ public function newQuery() /** * Perform an update query. * - * @param array $query - * @param array $options + * @param array $query + * @param array $options * @return int */ protected function performUpdate($query, array $options = []) @@ -865,7 +867,7 @@ protected function performUpdate($query, array $options = []) /** * Convert a key to ObjectID if needed. * - * @param mixed $id + * @param mixed $id * @return mixed */ public function convertKey($id) @@ -897,7 +899,7 @@ public function where($column, $operator = null, $value = null, $boolean = 'and' } } - return call_user_func_array('parent::where', $params); + return parent::where(...$params); } /** @@ -905,7 +907,7 @@ public function where($column, $operator = null, $value = null, $boolean = 'and' * * @return array */ - protected function compileWheres() + protected function compileWheres(): array { // The wheres to compile. $wheres = $this->wheres ?: []; @@ -999,10 +1001,10 @@ protected function compileWheres() } /** - * @param array $where + * @param array $where * @return array */ - protected function compileWhereAll(array $where) + protected function compileWhereAll(array $where): array { extract($where); @@ -1010,10 +1012,10 @@ protected function compileWhereAll(array $where) } /** - * @param array $where + * @param array $where * @return array */ - protected function compileWhereBasic(array $where) + protected function compileWhereBasic(array $where): array { extract($where); @@ -1066,10 +1068,10 @@ protected function compileWhereBasic(array $where) } /** - * @param array $where + * @param array $where * @return mixed */ - protected function compileWhereNested(array $where) + protected function compileWhereNested(array $where): mixed { extract($where); @@ -1077,10 +1079,10 @@ protected function compileWhereNested(array $where) } /** - * @param array $where + * @param array $where * @return array */ - protected function compileWhereIn(array $where) + protected function compileWhereIn(array $where): array { extract($where); @@ -1088,10 +1090,10 @@ protected function compileWhereIn(array $where) } /** - * @param array $where + * @param array $where * @return array */ - protected function compileWhereNotIn(array $where) + protected function compileWhereNotIn(array $where): array { extract($where); @@ -1099,10 +1101,10 @@ protected function compileWhereNotIn(array $where) } /** - * @param array $where + * @param array $where * @return array */ - protected function compileWhereNull(array $where) + protected function compileWhereNull(array $where): array { $where['operator'] = '='; $where['value'] = null; @@ -1111,10 +1113,10 @@ protected function compileWhereNull(array $where) } /** - * @param array $where + * @param array $where * @return array */ - protected function compileWhereNotNull(array $where) + protected function compileWhereNotNull(array $where): array { $where['operator'] = '!='; $where['value'] = null; @@ -1123,10 +1125,10 @@ protected function compileWhereNotNull(array $where) } /** - * @param array $where + * @param array $where * @return array */ - protected function compileWhereBetween(array $where) + protected function compileWhereBetween(array $where): array { extract($where); @@ -1156,10 +1158,10 @@ protected function compileWhereBetween(array $where) } /** - * @param array $where + * @param array $where * @return array */ - protected function compileWhereDate(array $where) + protected function compileWhereDate(array $where): array { extract($where); @@ -1170,10 +1172,10 @@ protected function compileWhereDate(array $where) } /** - * @param array $where + * @param array $where * @return array */ - protected function compileWhereMonth(array $where) + protected function compileWhereMonth(array $where): array { extract($where); @@ -1184,10 +1186,10 @@ protected function compileWhereMonth(array $where) } /** - * @param array $where + * @param array $where * @return array */ - protected function compileWhereDay(array $where) + protected function compileWhereDay(array $where): array { extract($where); @@ -1198,10 +1200,10 @@ protected function compileWhereDay(array $where) } /** - * @param array $where + * @param array $where * @return array */ - protected function compileWhereYear(array $where) + protected function compileWhereYear(array $where): array { extract($where); @@ -1212,10 +1214,10 @@ protected function compileWhereYear(array $where) } /** - * @param array $where + * @param array $where * @return array */ - protected function compileWhereTime(array $where) + protected function compileWhereTime(array $where): array { extract($where); @@ -1226,10 +1228,10 @@ protected function compileWhereTime(array $where) } /** - * @param array $where + * @param array $where * @return mixed */ - protected function compileWhereRaw(array $where) + protected function compileWhereRaw(array $where): mixed { return $where['sql']; } @@ -1237,7 +1239,7 @@ protected function compileWhereRaw(array $where) /** * Set custom options for the query. * - * @param array $options + * @param array $options * @return $this */ public function options(array $options) @@ -1253,7 +1255,7 @@ public function options(array $options) public function __call($method, $parameters) { if ($method == 'unset') { - return call_user_func_array([$this, 'drop'], $parameters); + return $this->drop(...$parameters); } return parent::__call($method, $parameters); diff --git a/src/Relations/EmbedsMany.php b/src/Relations/EmbedsMany.php index 88a63d0b4..ba1513255 100644 --- a/src/Relations/EmbedsMany.php +++ b/src/Relations/EmbedsMany.php @@ -34,7 +34,7 @@ public function getResults() /** * Save a new model and attach it to the parent model. * - * @param Model $model + * @param Model $model * @return Model|bool */ public function performInsert(Model $model) @@ -65,7 +65,7 @@ public function performInsert(Model $model) /** * Save an existing model and attach it to the parent model. * - * @param Model $model + * @param Model $model * @return Model|bool */ public function performUpdate(Model $model) @@ -97,7 +97,7 @@ public function performUpdate(Model $model) /** * Delete an existing model and detach it from the parent model. * - * @param Model $model + * @param Model $model * @return int */ public function performDelete(Model $model) @@ -124,7 +124,7 @@ public function performDelete(Model $model) /** * Associate the model instance to the given parent, without saving it to the database. * - * @param Model $model + * @param Model $model * @return Model */ public function associate(Model $model) @@ -139,7 +139,7 @@ public function associate(Model $model) /** * Dissociate the model instance from the given parent, without saving it to the database. * - * @param mixed $ids + * @param mixed $ids * @return int */ public function dissociate($ids = []) @@ -168,7 +168,7 @@ public function dissociate($ids = []) /** * Destroy the embedded models for the given IDs. * - * @param mixed $ids + * @param mixed $ids * @return int */ public function destroy($ids = []) @@ -210,7 +210,7 @@ public function delete() /** * Destroy alias. * - * @param mixed $ids + * @param mixed $ids * @return int */ public function detach($ids = []) @@ -221,7 +221,7 @@ public function detach($ids = []) /** * Save alias. * - * @param Model $model + * @param Model $model * @return Model */ public function attach(Model $model) @@ -232,7 +232,7 @@ public function attach(Model $model) /** * Associate a new model instance to the given parent, without saving it to the database. * - * @param Model $model + * @param Model $model * @return Model */ protected function associateNew($model) @@ -253,7 +253,7 @@ protected function associateNew($model) /** * Associate an existing model instance to the given parent, without saving it to the database. * - * @param Model $model + * @param Model $model * @return Model */ protected function associateExisting($model) @@ -277,10 +277,10 @@ protected function associateExisting($model) } /** - * @param null $perPage - * @param array $columns - * @param string $pageName - * @param null $page + * @param null $perPage + * @param array $columns + * @param string $pageName + * @param null $page * @return \Illuminate\Contracts\Pagination\LengthAwarePaginator */ public function paginate($perPage = null, $columns = ['*'], $pageName = 'page', $page = null) @@ -335,7 +335,7 @@ protected function setEmbedded($models) public function __call($method, $parameters) { if (method_exists(Collection::class, $method)) { - return call_user_func_array([$this->getResults(), $method], $parameters); + return $this->getResults()->$method(...$parameters); } return parent::__call($method, $parameters); @@ -344,8 +344,8 @@ public function __call($method, $parameters) /** * Get the name of the "where in" method for eager loading. * - * @param \Illuminate\Database\Eloquent\Model $model - * @param string $key + * @param \Illuminate\Database\Eloquent\Model $model + * @param string $key * @return string */ protected function whereInMethod(EloquentModel $model, $key) From 0606fc05788a45ec954ea6fcda2e78d910b2e398 Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Mon, 14 Nov 2022 12:51:00 +0100 Subject: [PATCH 030/446] Use single connection using DSN for testing (#2462) * Always use connection string in tests * Document DSN configuration as preferred configuration method * Update wordings * Use matrix config instead of manually specifying builds * Apply StyleCI fixes * Add missing test for code coverage --- .github/workflows/build-ci.yml | 24 +++---- README.md | 41 ++++------- phpunit.xml.dist | 3 +- src/Eloquent/Builder.php | 5 +- src/Eloquent/Model.php | 2 +- tests/ConnectionTest.php | 127 ++++++++++++++++++++++++--------- tests/DsnTest.php | 16 ----- tests/TestCase.php | 8 +-- tests/config/database.php | 22 +----- 9 files changed, 131 insertions(+), 117 deletions(-) delete mode 100644 tests/DsnTest.php diff --git a/.github/workflows/build-ci.yml b/.github/workflows/build-ci.yml index 2affc132c..6f57f015d 100644 --- a/.github/workflows/build-ci.yml +++ b/.github/workflows/build-ci.yml @@ -30,19 +30,19 @@ jobs: build: runs-on: ${{ matrix.os }} - name: PHP v${{ matrix.php }} with Mongo v${{ matrix.mongodb }} - continue-on-error: ${{ matrix.experimental }} + name: PHP v${{ matrix.php }} with MongoDB ${{ matrix.mongodb }} strategy: matrix: - include: - - { os: ubuntu-latest, php: 8.0, mongodb: '4.0', experimental: false } - - { os: ubuntu-latest, php: 8.0, mongodb: 4.2, experimental: false } - - { os: ubuntu-latest, php: 8.0, mongodb: 4.4, experimental: false } - - { os: ubuntu-latest, php: 8.0, mongodb: '5.0', experimental: false } - - { os: ubuntu-latest, php: 8.1, mongodb: '4.0', experimental: false } - - { os: ubuntu-latest, php: 8.1, mongodb: 4.2, experimental: false } - - { os: ubuntu-latest, php: 8.1, mongodb: 4.4, experimental: false } - - { os: ubuntu-latest, php: 8.1, mongodb: '5.0', experimental: false } + os: + - ubuntu-latest + mongodb: + - '4.0' + - '4.2' + - '4.4' + - '5.0' + php: + - '8.0' + - '8.1' services: mongo: image: mongo:${{ matrix.mongodb }} @@ -88,7 +88,7 @@ jobs: run: | ./vendor/bin/phpunit --coverage-clover coverage.xml env: - MONGO_HOST: 0.0.0.0 + MONGODB_URI: 'mongodb://127.0.0.1/' MYSQL_HOST: 0.0.0.0 MYSQL_PORT: 3307 - uses: codecov/codecov-action@v1 diff --git a/README.md b/README.md index 8ede587ec..06531dcb1 100644 --- a/README.md +++ b/README.md @@ -143,47 +143,36 @@ Keep in mind that these traits are not yet supported: Configuration ------------- -You can use MongoDB either as the main database, either as a side database. To do so, add a new `mongodb` connection to `config/database.php`: + +To configure a new MongoDB connection, add a new connection entry to `config/database.php`: ```php 'mongodb' => [ 'driver' => 'mongodb', - 'host' => env('DB_HOST', '127.0.0.1'), - 'port' => env('DB_PORT', 27017), + 'dsn' => env('DB_DSN'), 'database' => env('DB_DATABASE', 'homestead'), - 'username' => env('DB_USERNAME', 'homestead'), - 'password' => env('DB_PASSWORD', 'secret'), - 'options' => [ - // here you can pass more settings to the Mongo Driver Manager - // see https://www.php.net/manual/en/mongodb-driver-manager.construct.php under "Uri Options" for a list of complete parameters that you can use - - 'database' => env('DB_AUTHENTICATION_DATABASE', 'admin'), // required with Mongo 3+ - ], ], ``` -For multiple servers or replica set configurations, set the host to an array and specify each server host: +The `dsn` key contains the connection string used to connect to your MongoDB deployment. The format and available options are documented in the [MongoDB documentation](https://docs.mongodb.com/manual/reference/connection-string/). + +Instead of using a connection string, you can also use the `host` and `port` configuration options to have the connection string created for you. ```php 'mongodb' => [ 'driver' => 'mongodb', - 'host' => ['server1', 'server2', ...], - ... + 'host' => env('DB_HOST', '127.0.0.1'), + 'port' => env('DB_PORT', 27017), + 'database' => env('DB_DATABASE', 'homestead'), + 'username' => env('DB_USERNAME', 'homestead'), + 'password' => env('DB_PASSWORD', 'secret'), 'options' => [ - 'replicaSet' => 'rs0', + 'appname' => 'homestead', ], ], ``` -If you wish to use a connection string instead of full key-value params, you can set it so. Check the documentation on MongoDB's URI format: https://docs.mongodb.com/manual/reference/connection-string/ - -```php -'mongodb' => [ - 'driver' => 'mongodb', - 'dsn' => env('DB_DSN'), - 'database' => env('DB_DATABASE', 'homestead'), -], -``` +The `options` key in the connection configuration corresponds to the [`uriOptions` parameter](https://www.php.net/manual/en/mongodb-driver-manager.construct.php#mongodb-driver-manager.construct-urioptions). Eloquent -------- @@ -223,7 +212,7 @@ class Book extends Model protected $primaryKey = 'id'; } -// Mongo will also create _id, but the 'id' property will be used for primary key actions like find(). +// MongoDB will also create _id, but the 'id' property will be used for primary key actions like find(). Book::create(['id' => 1, 'title' => 'The Fault in Our Stars']); ``` @@ -238,7 +227,7 @@ class Book extends Model } ``` -### Extending the Authenticable base model +### Extending the Authenticatable base model This package includes a MongoDB Authenticatable Eloquent class `Jenssegers\Mongodb\Auth\User` that you can use to replace the default Authenticatable class `Illuminate\Foundation\Auth\User` for your `User` model. ```php diff --git a/phpunit.xml.dist b/phpunit.xml.dist index 4dc18cb41..15601b8dc 100644 --- a/phpunit.xml.dist +++ b/phpunit.xml.dist @@ -35,9 +35,8 @@ - + - diff --git a/src/Eloquent/Builder.php b/src/Eloquent/Builder.php index bfa3d634a..84e93b83f 100644 --- a/src/Eloquent/Builder.php +++ b/src/Eloquent/Builder.php @@ -174,7 +174,7 @@ public function raw($expression = null) $results = iterator_to_array($results, false); return $this->model->hydrate($results); - } // Convert Mongo BSONDocument to a single object. + } // Convert MongoDB BSONDocument to a single object. elseif ($results instanceof BSONDocument) { $results = $results->getArrayCopy(); @@ -192,7 +192,8 @@ public function raw($expression = null) * TODO Remove if https://github.com/laravel/framework/commit/6484744326531829341e1ff886cc9b628b20d73e * wiil be reverted * Issue in laravel frawework https://github.com/laravel/framework/issues/27791. - * @param array $values + * + * @param array $values * @return array */ protected function addUpdatedAtColumn(array $values) diff --git a/src/Eloquent/Model.php b/src/Eloquent/Model.php index 576d8b36b..e123391dc 100644 --- a/src/Eloquent/Model.php +++ b/src/Eloquent/Model.php @@ -55,7 +55,7 @@ abstract class Model extends BaseModel */ public function getIdAttribute($value = null) { - // If we don't have a value for 'id', we will use the Mongo '_id' value. + // If we don't have a value for 'id', we will use the MongoDB '_id' value. // This allows us to work with models in a more sql-like way. if (! $value && array_key_exists('_id', $this->attributes)) { $value = $this->attributes['_id']; diff --git a/tests/ConnectionTest.php b/tests/ConnectionTest.php index ed73010ea..f7b8fda82 100644 --- a/tests/ConnectionTest.php +++ b/tests/ConnectionTest.php @@ -37,11 +37,101 @@ public function testDb() $this->assertInstanceOf(Client::class, $connection->getMongoClient()); } - public function testDsnDb() + public function dataConnectionConfig(): Generator { - $connection = DB::connection('dsn_mongodb_db'); - $this->assertInstanceOf(Database::class, $connection->getMongoDB()); - $this->assertInstanceOf(Client::class, $connection->getMongoClient()); + yield 'Single host' => [ + 'expectedUri' => 'mongodb://some-host', + 'expectedDatabaseName' => 'tests', + 'config' => [ + 'host' => 'some-host', + 'database' => 'tests', + ], + ]; + + yield 'Host and port' => [ + 'expectedUri' => 'mongodb://some-host:12345', + 'expectedDatabaseName' => 'tests', + 'config' => [ + 'host' => 'some-host', + 'port' => 12345, + 'database' => 'tests', + ], + ]; + + yield 'Port in host name takes precedence' => [ + 'expectedUri' => 'mongodb://some-host:12345', + 'expectedDatabaseName' => 'tests', + 'config' => [ + 'host' => 'some-host:12345', + 'port' => 54321, + 'database' => 'tests', + ], + ]; + + yield 'Multiple hosts' => [ + 'expectedUri' => 'mongodb://host-1,host-2', + 'expectedDatabaseName' => 'tests', + 'config' => [ + 'host' => ['host-1', 'host-2'], + 'database' => 'tests', + ], + ]; + + yield 'Multiple hosts with same port' => [ + 'expectedUri' => 'mongodb://host-1:12345,host-2:12345', + 'expectedDatabaseName' => 'tests', + 'config' => [ + 'host' => ['host-1', 'host-2'], + 'port' => 12345, + 'database' => 'tests', + ], + ]; + + yield 'Multiple hosts with port' => [ + 'expectedUri' => 'mongodb://host-1:12345,host-2:54321', + 'expectedDatabaseName' => 'tests', + 'config' => [ + 'host' => ['host-1:12345', 'host-2:54321'], + 'database' => 'tests', + ], + ]; + + yield 'DSN takes precedence over host/port config' => [ + 'expectedUri' => 'mongodb://some-host:12345/auth-database', + 'expectedDatabaseName' => 'tests', + 'config' => [ + 'dsn' => 'mongodb://some-host:12345/auth-database', + 'host' => 'wrong-host', + 'port' => 54321, + 'database' => 'tests', + ], + ]; + + yield 'Database is extracted from DSN if not specified' => [ + 'expectedUri' => 'mongodb://some-host:12345/tests', + 'expectedDatabaseName' => 'tests', + 'config' => [ + 'dsn' => 'mongodb://some-host:12345/tests', + ], + ]; + } + + /** @dataProvider dataConnectionConfig */ + public function testConnectionConfig(string $expectedUri, string $expectedDatabaseName, array $config): void + { + $connection = new Connection($config); + $client = $connection->getMongoClient(); + + $this->assertSame($expectedUri, (string) $client); + $this->assertSame($expectedDatabaseName, $connection->getMongoDB()->getDatabaseName()); + } + + public function testConnectionWithoutConfiguredDatabase(): void + { + $this->expectException(InvalidArgumentException::class); + $this->expectExceptionMessage('Database is not properly configured.'); + + new Connection(['dsn' => 'mongodb://some-host']); } public function testCollection() @@ -89,33 +179,4 @@ public function testDriverName() $driver = DB::connection('mongodb')->getDriverName(); $this->assertEquals('mongodb', $driver); } - - public function testAuth() - { - $host = Config::get('database.connections.mongodb.host'); - Config::set('database.connections.mongodb.username', 'foo'); - Config::set('database.connections.mongodb.password', 'bar'); - Config::set('database.connections.mongodb.options.database', 'custom'); - - $connection = DB::connection('mongodb'); - $this->assertEquals('mongodb://'.$host.'/custom', (string) $connection->getMongoClient()); - } - - public function testCustomHostAndPort() - { - Config::set('database.connections.mongodb.host', 'db1'); - Config::set('database.connections.mongodb.port', 27000); - - $connection = DB::connection('mongodb'); - $this->assertEquals('mongodb://db1:27000', (string) $connection->getMongoClient()); - } - - public function testHostWithPorts() - { - Config::set('database.connections.mongodb.port', 27000); - Config::set('database.connections.mongodb.host', ['db1:27001', 'db2:27002', 'db3:27000']); - - $connection = DB::connection('mongodb'); - $this->assertEquals('mongodb://db1:27001,db2:27002,db3:27000', (string) $connection->getMongoClient()); - } } diff --git a/tests/DsnTest.php b/tests/DsnTest.php deleted file mode 100644 index 85230f852..000000000 --- a/tests/DsnTest.php +++ /dev/null @@ -1,16 +0,0 @@ -assertInstanceOf(\Illuminate\Database\Eloquent\Collection::class, DsnAddress::all()); - } -} - -class DsnAddress extends Address -{ - protected $connection = 'dsn_mongodb'; -} diff --git a/tests/TestCase.php b/tests/TestCase.php index 584ff82de..dbe8c97c0 100644 --- a/tests/TestCase.php +++ b/tests/TestCase.php @@ -9,7 +9,7 @@ class TestCase extends Orchestra\Testbench\TestCase /** * Get application providers. * - * @param \Illuminate\Foundation\Application $app + * @param \Illuminate\Foundation\Application $app * @return array */ protected function getApplicationProviders($app) @@ -24,7 +24,7 @@ protected function getApplicationProviders($app) /** * Get package providers. * - * @param \Illuminate\Foundation\Application $app + * @param \Illuminate\Foundation\Application $app * @return array */ protected function getPackageProviders($app) @@ -40,7 +40,7 @@ protected function getPackageProviders($app) /** * Define environment setup. * - * @param Illuminate\Foundation\Application $app + * @param Illuminate\Foundation\Application $app * @return void */ protected function getEnvironmentSetUp($app) @@ -56,8 +56,6 @@ protected function getEnvironmentSetUp($app) $app['config']->set('database.connections.mysql', $config['connections']['mysql']); $app['config']->set('database.connections.mongodb', $config['connections']['mongodb']); $app['config']->set('database.connections.mongodb2', $config['connections']['mongodb']); - $app['config']->set('database.connections.dsn_mongodb', $config['connections']['dsn_mongodb']); - $app['config']->set('database.connections.dsn_mongodb_db', $config['connections']['dsn_mongodb_db']); $app['config']->set('auth.model', 'User'); $app['config']->set('auth.providers.users.model', 'User'); diff --git a/tests/config/database.php b/tests/config/database.php index 5f45066a8..73f3d8697 100644 --- a/tests/config/database.php +++ b/tests/config/database.php @@ -1,35 +1,18 @@ [ - 'mongodb' => [ 'name' => 'mongodb', 'driver' => 'mongodb', - 'host' => $mongoHost, + 'dsn' => env('MONGODB_URI', 'mongodb://127.0.0.1/'), 'database' => env('MONGO_DATABASE', 'unittest'), ], - 'dsn_mongodb' => [ - 'driver' => 'mongodb', - 'dsn' => "mongodb://$mongoHost:$mongoPort", - 'database' => env('MONGO_DATABASE', 'unittest'), - ], - - 'dsn_mongodb_db' => [ - 'driver' => 'mongodb', - 'dsn' => "mongodb://$mongoHost:$mongoPort/".env('MONGO_DATABASE', 'unittest'), - ], - 'mysql' => [ 'driver' => 'mysql', 'host' => env('MYSQL_HOST', 'mysql'), - 'port' => $mysqlPort, + 'port' => env('MYSQL_PORT') ? (int) env('MYSQL_PORT') : 3306, 'database' => env('MYSQL_DATABASE', 'unittest'), 'username' => env('MYSQL_USERNAME', 'root'), 'password' => env('MYSQL_PASSWORD', ''), @@ -38,5 +21,4 @@ 'prefix' => '', ], ], - ]; From e5e91936b7537354672df27e7cfbeec7fa2fb2d1 Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Sun, 27 Nov 2022 19:32:25 +0100 Subject: [PATCH 031/446] Transaction support (#2465) * Add support for transactions Co-authored-by: klinson Co-authored-by: levon80999 * Start single-member replica set in CI Co-authored-by: levon80999 * Add connection options for faster failures in tests The faster connection and server selection timeouts ensure we don't spend too much time waiting for the inevitable as we're expecting fast connections on CI systems Co-authored-by: levon80999 * Apply readme code review suggestions * Simplify replica set creation in CI * Apply feedback from code review * Update naming of database env variable in tests * Use default argument for server selection (which defaults to primary) * Revert "Simplify replica set creation in CI" This partially reverts commit 203160e6630245d82c511eca8c775cb7cac7ad0b. The simplified call unfortunately breaks tests. * Pass connection instance to transactional closure This is consistent with the behaviour of the original ManagesTransactions concern. * Correctly re-throw exception when callback attempts have been exceeded. * Limit transaction lifetime to 5 seconds This ensures that hung transactions don't block any subsequent operations for an unnecessary period of time. * Add build step to print MongoDB server status * Update src/Concerns/ManagesTransactions.php Co-authored-by: Jeremy Mikola Co-authored-by: klinson Co-authored-by: levon80999 Co-authored-by: Jeremy Mikola --- .github/workflows/build-ci.yml | 16 +- README.md | 47 +++ phpunit.xml.dist | 5 +- src/Concerns/ManagesTransactions.php | 116 +++++++ src/Connection.php | 3 + src/Query/Builder.php | 47 ++- tests/TransactionTest.php | 448 +++++++++++++++++++++++++++ tests/config/database.php | 6 +- tests/config/queue.php | 2 +- 9 files changed, 672 insertions(+), 18 deletions(-) create mode 100644 src/Concerns/ManagesTransactions.php create mode 100644 tests/TransactionTest.php diff --git a/.github/workflows/build-ci.yml b/.github/workflows/build-ci.yml index 6f57f015d..f081e3273 100644 --- a/.github/workflows/build-ci.yml +++ b/.github/workflows/build-ci.yml @@ -44,10 +44,6 @@ jobs: - '8.0' - '8.1' services: - mongo: - image: mongo:${{ matrix.mongodb }} - ports: - - 27017:27017 mysql: image: mysql:5.7 ports: @@ -59,6 +55,16 @@ jobs: steps: - uses: actions/checkout@v2 + - name: Create MongoDB Replica Set + run: | + docker run --name mongodb -p 27017:27017 -e MONGO_INITDB_DATABASE=unittest --detach mongo:${{ matrix.mongodb }} mongod --replSet rs --setParameter transactionLifetimeLimitSeconds=5 + until docker exec --tty mongodb mongo 127.0.0.1:27017 --eval "db.runCommand({ ping: 1 })"; do + sleep 1 + done + sudo docker exec --tty mongodb mongo 127.0.0.1:27017 --eval "rs.initiate({\"_id\":\"rs\",\"members\":[{\"_id\":0,\"host\":\"127.0.0.1:27017\" }]})" + - name: Show MongoDB server status + run: | + docker exec --tty mongodb mongo 127.0.0.1:27017 --eval "db.runCommand({ serverStatus: 1 })" - name: "Installing php" uses: shivammathur/setup-php@v2 with: @@ -88,7 +94,7 @@ jobs: run: | ./vendor/bin/phpunit --coverage-clover coverage.xml env: - MONGODB_URI: 'mongodb://127.0.0.1/' + MONGODB_URI: 'mongodb://127.0.0.1/?replicaSet=rs' MYSQL_HOST: 0.0.0.0 MYSQL_PORT: 3307 - uses: codecov/codecov-action@v1 diff --git a/README.md b/README.md index 06531dcb1..0c07e7288 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,7 @@ This package adds functionalities to the Eloquent model and Query builder for Mo - [Query Builder](#query-builder) - [Basic Usage](#basic-usage-2) - [Available operations](#available-operations) + - [Transactions](#transactions) - [Schema](#schema) - [Basic Usage](#basic-usage-3) - [Geospatial indexes](#geospatial-indexes) @@ -968,6 +969,52 @@ If you are familiar with [Eloquent Queries](http://laravel.com/docs/queries), th ### Available operations To see the available operations, check the [Eloquent](#eloquent) section. +Transactions +------------ +Transactions require MongoDB version ^4.0 as well as deployment of replica set or sharded clusters. You can find more information [in the MongoDB docs](https://docs.mongodb.com/manual/core/transactions/) + +### Basic Usage + +```php +DB::transaction(function () { + User::create(['name' => 'john', 'age' => 19, 'title' => 'admin', 'email' => 'john@example.com']); + DB::collection('users')->where('name', 'john')->update(['age' => 20]); + DB::collection('users')->where('name', 'john')->delete(); +}); +``` + +```php +// begin a transaction +DB::beginTransaction(); +User::create(['name' => 'john', 'age' => 19, 'title' => 'admin', 'email' => 'john@example.com']); +DB::collection('users')->where('name', 'john')->update(['age' => 20]); +DB::collection('users')->where('name', 'john')->delete(); + +// commit changes +DB::commit(); +``` + +To abort a transaction, call the `rollBack` method at any point during the transaction: +```php +DB::beginTransaction(); +User::create(['name' => 'john', 'age' => 19, 'title' => 'admin', 'email' => 'john@example.com']); + +// Abort the transaction, discarding any data created as part of it +DB::rollBack(); +``` + +**NOTE:** Transactions in MongoDB cannot be nested. DB::beginTransaction() function will start new transactions in a new created or existing session and will raise the RuntimeException when transactions already exist. See more in MongoDB official docs [Transactions and Sessions](https://www.mongodb.com/docs/manual/core/transactions/#transactions-and-sessions) +```php +DB::beginTransaction(); +User::create(['name' => 'john', 'age' => 20, 'title' => 'admin']); + +// This call to start a nested transaction will raise a RuntimeException +DB::beginTransaction(); +DB::collection('users')->where('name', 'john')->update(['age' => 20]); +DB::commit(); +DB::rollBack(); +``` + Schema ------ The database driver also has (limited) schema builder support. You can easily manipulate collections and set indexes. diff --git a/phpunit.xml.dist b/phpunit.xml.dist index 15601b8dc..9aebe0c0a 100644 --- a/phpunit.xml.dist +++ b/phpunit.xml.dist @@ -19,6 +19,9 @@ tests/QueryBuilderTest.php tests/QueryTest.php + + tests/TransactionTest.php + tests/ModelTest.php tests/RelationsTest.php @@ -36,7 +39,7 @@ - + diff --git a/src/Concerns/ManagesTransactions.php b/src/Concerns/ManagesTransactions.php new file mode 100644 index 000000000..d3344f919 --- /dev/null +++ b/src/Concerns/ManagesTransactions.php @@ -0,0 +1,116 @@ +session; + } + + private function getSessionOrCreate(): Session + { + if ($this->session === null) { + $this->session = $this->getMongoClient()->startSession(); + } + + return $this->session; + } + + private function getSessionOrThrow(): Session + { + $session = $this->getSession(); + + if ($session === null) { + throw new RuntimeException('There is no active session.'); + } + + return $session; + } + + /** + * Starts a transaction on the active session. An active session will be created if none exists. + */ + public function beginTransaction(array $options = []): void + { + $this->getSessionOrCreate()->startTransaction($options); + $this->transactions = 1; + } + + /** + * Commit transaction in this session. + */ + public function commit(): void + { + $this->getSessionOrThrow()->commitTransaction(); + $this->transactions = 0; + } + + /** + * Abort transaction in this session. + */ + public function rollBack($toLevel = null): void + { + $this->getSessionOrThrow()->abortTransaction(); + $this->transactions = 0; + } + + /** + * Static transaction function realize the with_transaction functionality provided by MongoDB. + * + * @param int $attempts + */ + public function transaction(Closure $callback, $attempts = 1, array $options = []): mixed + { + $attemptsLeft = $attempts; + $callbackResult = null; + $throwable = null; + + $callbackFunction = function (Session $session) use ($callback, &$attemptsLeft, &$callbackResult, &$throwable) { + $attemptsLeft--; + + if ($attemptsLeft < 0) { + $session->abortTransaction(); + + return; + } + + // Catch, store, and re-throw any exception thrown during execution + // of the callable. The last exception is re-thrown if the transaction + // was aborted because the number of callback attempts has been exceeded. + try { + $callbackResult = $callback($this); + } catch (Throwable $throwable) { + throw $throwable; + } + }; + + with_transaction($this->getSessionOrCreate(), $callbackFunction, $options); + + if ($attemptsLeft < 0 && $throwable) { + throw $throwable; + } + + return $callbackResult; + } +} diff --git a/src/Connection.php b/src/Connection.php index b65b40ca3..c78ac95c1 100644 --- a/src/Connection.php +++ b/src/Connection.php @@ -5,11 +5,14 @@ use Illuminate\Database\Connection as BaseConnection; use Illuminate\Support\Arr; use InvalidArgumentException; +use Jenssegers\Mongodb\Concerns\ManagesTransactions; use MongoDB\Client; use MongoDB\Database; class Connection extends BaseConnection { + use ManagesTransactions; + /** * The MongoDB database handler. * diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 631e64950..066412734 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -346,6 +346,8 @@ public function getFresh($columns = [], $returnLazy = false) $options = array_merge($options, $this->options); } + $options = $this->inheritConnectionOptions($options); + // Execute aggregation $results = iterator_to_array($this->collection->aggregate($pipeline, $options)); @@ -356,12 +358,10 @@ public function getFresh($columns = [], $returnLazy = false) // Return distinct results directly $column = isset($this->columns[0]) ? $this->columns[0] : '_id'; + $options = $this->inheritConnectionOptions(); + // Execute distinct - if ($wheres) { - $result = $this->collection->distinct($column, $wheres); - } else { - $result = $this->collection->distinct($column); - } + $result = $this->collection->distinct($column, $wheres ?: [], $options); return new Collection($result); } // Normal query @@ -407,6 +407,8 @@ public function getFresh($columns = [], $returnLazy = false) $options = array_merge($options, $this->options); } + $options = $this->inheritConnectionOptions($options); + // Execute query and get MongoCursor $cursor = $this->collection->find($wheres, $options); @@ -581,8 +583,9 @@ public function insert(array $values) $values = [$values]; } - // Batch insert - $result = $this->collection->insertMany($values); + $options = $this->inheritConnectionOptions(); + + $result = $this->collection->insertMany($values, $options); return 1 == (int) $result->isAcknowledged(); } @@ -592,7 +595,9 @@ public function insert(array $values) */ public function insertGetId(array $values, $sequence = null) { - $result = $this->collection->insertOne($values); + $options = $this->inheritConnectionOptions(); + + $result = $this->collection->insertOne($values, $options); if (1 == (int) $result->isAcknowledged()) { if ($sequence === null) { @@ -614,6 +619,8 @@ public function update(array $values, array $options = []) $values = ['$set' => $values]; } + $options = $this->inheritConnectionOptions($options); + return $this->performUpdate($values, $options); } @@ -635,6 +642,8 @@ public function increment($column, $amount = 1, array $extra = [], array $option $query->orWhereNotNull($column); }); + $options = $this->inheritConnectionOptions($options); + return $this->performUpdate($query, $options); } @@ -696,7 +705,10 @@ public function delete($id = null) } $wheres = $this->compileWheres(); - $result = $this->collection->DeleteMany($wheres); + $options = $this->inheritConnectionOptions(); + + $result = $this->collection->deleteMany($wheres, $options); + if (1 == (int) $result->isAcknowledged()) { return $result->getDeletedCount(); } @@ -721,7 +733,8 @@ public function from($collection, $as = null) */ public function truncate(): bool { - $result = $this->collection->deleteMany([]); + $options = $this->inheritConnectionOptions(); + $result = $this->collection->deleteMany([], $options); return 1 === (int) $result->isAcknowledged(); } @@ -855,6 +868,8 @@ protected function performUpdate($query, array $options = []) $options['multiple'] = true; } + $options = $this->inheritConnectionOptions($options); + $wheres = $this->compileWheres(); $result = $this->collection->UpdateMany($wheres, $query, $options); if (1 == (int) $result->isAcknowledged()) { @@ -1249,6 +1264,18 @@ public function options(array $options) return $this; } + /** + * Apply the connection's session to options if it's not already specified. + */ + private function inheritConnectionOptions(array $options = []): array + { + if (! isset($options['session']) && ($session = $this->connection->getSession())) { + $options['session'] = $session; + } + + return $options; + } + /** * @inheritdoc */ diff --git a/tests/TransactionTest.php b/tests/TransactionTest.php new file mode 100644 index 000000000..52ce422a7 --- /dev/null +++ b/tests/TransactionTest.php @@ -0,0 +1,448 @@ +getPrimaryServerType() === Server::TYPE_STANDALONE) { + $this->markTestSkipped('Transactions are not supported on standalone servers'); + } + + User::truncate(); + } + + public function tearDown(): void + { + User::truncate(); + + parent::tearDown(); + } + + public function testCreateWithCommit(): void + { + DB::beginTransaction(); + /** @var User $klinson */ + $klinson = User::create(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + DB::commit(); + + $this->assertInstanceOf(Model::class, $klinson); + $this->assertTrue($klinson->exists); + $this->assertEquals('klinson', $klinson->name); + + $check = User::find($klinson->_id); + $this->assertInstanceOf(User::class, $check); + $this->assertEquals($klinson->name, $check->name); + } + + public function testCreateRollBack(): void + { + DB::beginTransaction(); + /** @var User $klinson */ + $klinson = User::create(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + DB::rollBack(); + + $this->assertInstanceOf(Model::class, $klinson); + $this->assertTrue($klinson->exists); + $this->assertEquals('klinson', $klinson->name); + + $this->assertFalse(User::where('_id', $klinson->_id)->exists()); + } + + public function testInsertWithCommit(): void + { + DB::beginTransaction(); + DB::collection('users')->insert(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + DB::commit(); + + $this->assertTrue(DB::collection('users')->where('name', 'klinson')->exists()); + } + + public function testInsertWithRollBack(): void + { + DB::beginTransaction(); + DB::collection('users')->insert(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + DB::rollBack(); + + $this->assertFalse(DB::collection('users')->where('name', 'klinson')->exists()); + } + + public function testEloquentCreateWithCommit(): void + { + DB::beginTransaction(); + /** @var User $klinson */ + $klinson = User::getModel(); + $klinson->name = 'klinson'; + $klinson->save(); + DB::commit(); + + $this->assertTrue($klinson->exists); + $this->assertNotNull($klinson->getIdAttribute()); + + $check = User::find($klinson->_id); + $this->assertInstanceOf(User::class, $check); + $this->assertEquals($check->name, $klinson->name); + } + + public function testEloquentCreateWithRollBack(): void + { + DB::beginTransaction(); + /** @var User $klinson */ + $klinson = User::getModel(); + $klinson->name = 'klinson'; + $klinson->save(); + DB::rollBack(); + + $this->assertTrue($klinson->exists); + $this->assertNotNull($klinson->getIdAttribute()); + + $this->assertFalse(User::where('_id', $klinson->_id)->exists()); + } + + public function testInsertGetIdWithCommit(): void + { + DB::beginTransaction(); + $userId = DB::collection('users')->insertGetId(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + DB::commit(); + + $this->assertInstanceOf(ObjectId::class, $userId); + + $user = DB::collection('users')->find((string) $userId); + $this->assertEquals('klinson', $user['name']); + } + + public function testInsertGetIdWithRollBack(): void + { + DB::beginTransaction(); + $userId = DB::collection('users')->insertGetId(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + DB::rollBack(); + + $this->assertInstanceOf(ObjectId::class, $userId); + $this->assertFalse(DB::collection('users')->where('_id', (string) $userId)->exists()); + } + + public function testUpdateWithCommit(): void + { + User::create(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + + DB::beginTransaction(); + $updated = DB::collection('users')->where('name', 'klinson')->update(['age' => 21]); + DB::commit(); + + $this->assertEquals(1, $updated); + $this->assertTrue(DB::collection('users')->where('name', 'klinson')->where('age', 21)->exists()); + } + + public function testUpdateWithRollback(): void + { + User::create(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + + DB::beginTransaction(); + $updated = DB::collection('users')->where('name', 'klinson')->update(['age' => 21]); + DB::rollBack(); + + $this->assertEquals(1, $updated); + $this->assertFalse(DB::collection('users')->where('name', 'klinson')->where('age', 21)->exists()); + } + + public function testEloquentUpdateWithCommit(): void + { + /** @var User $klinson */ + $klinson = User::create(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + /** @var User $alcaeus */ + $alcaeus = User::create(['name' => 'alcaeus', 'age' => 38, 'title' => 'admin']); + + DB::beginTransaction(); + $klinson->age = 21; + $klinson->update(); + + $alcaeus->update(['age' => 39]); + DB::commit(); + + $this->assertEquals(21, $klinson->age); + $this->assertEquals(39, $alcaeus->age); + + $this->assertTrue(User::where('_id', $klinson->_id)->where('age', 21)->exists()); + $this->assertTrue(User::where('_id', $alcaeus->_id)->where('age', 39)->exists()); + } + + public function testEloquentUpdateWithRollBack(): void + { + /** @var User $klinson */ + $klinson = User::create(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + /** @var User $alcaeus */ + $alcaeus = User::create(['name' => 'klinson', 'age' => 38, 'title' => 'admin']); + + DB::beginTransaction(); + $klinson->age = 21; + $klinson->update(); + + $alcaeus->update(['age' => 39]); + DB::rollBack(); + + $this->assertEquals(21, $klinson->age); + $this->assertEquals(39, $alcaeus->age); + + $this->assertFalse(User::where('_id', $klinson->_id)->where('age', 21)->exists()); + $this->assertFalse(User::where('_id', $alcaeus->_id)->where('age', 39)->exists()); + } + + public function testDeleteWithCommit(): void + { + User::create(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + + DB::beginTransaction(); + $deleted = User::where(['name' => 'klinson'])->delete(); + DB::commit(); + + $this->assertEquals(1, $deleted); + $this->assertFalse(User::where(['name' => 'klinson'])->exists()); + } + + public function testDeleteWithRollBack(): void + { + User::create(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + + DB::beginTransaction(); + $deleted = User::where(['name' => 'klinson'])->delete(); + DB::rollBack(); + + $this->assertEquals(1, $deleted); + $this->assertTrue(User::where(['name' => 'klinson'])->exists()); + } + + public function testEloquentDeleteWithCommit(): void + { + /** @var User $klinson */ + $klinson = User::create(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + + DB::beginTransaction(); + $klinson->delete(); + DB::commit(); + + $this->assertFalse(User::where('_id', $klinson->_id)->exists()); + } + + public function testEloquentDeleteWithRollBack(): void + { + /** @var User $klinson */ + $klinson = User::create(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + + DB::beginTransaction(); + $klinson->delete(); + DB::rollBack(); + + $this->assertTrue(User::where('_id', $klinson->_id)->exists()); + } + + public function testIncrementWithCommit(): void + { + User::create(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + + DB::beginTransaction(); + DB::collection('users')->where('name', 'klinson')->increment('age'); + DB::commit(); + + $this->assertTrue(DB::collection('users')->where('name', 'klinson')->where('age', 21)->exists()); + } + + public function testIncrementWithRollBack(): void + { + User::create(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + + DB::beginTransaction(); + DB::collection('users')->where('name', 'klinson')->increment('age'); + DB::rollBack(); + + $this->assertTrue(DB::collection('users')->where('name', 'klinson')->where('age', 20)->exists()); + } + + public function testDecrementWithCommit(): void + { + User::create(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + + DB::beginTransaction(); + DB::collection('users')->where('name', 'klinson')->decrement('age'); + DB::commit(); + + $this->assertTrue(DB::collection('users')->where('name', 'klinson')->where('age', 19)->exists()); + } + + public function testDecrementWithRollBack(): void + { + User::create(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + + DB::beginTransaction(); + DB::collection('users')->where('name', 'klinson')->decrement('age'); + DB::rollBack(); + + $this->assertTrue(DB::collection('users')->where('name', 'klinson')->where('age', 20)->exists()); + } + + public function testQuery() + { + /** rollback test */ + DB::beginTransaction(); + $count = DB::collection('users')->count(); + $this->assertEquals(0, $count); + DB::collection('users')->insert(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + $count = DB::collection('users')->count(); + $this->assertEquals(1, $count); + DB::rollBack(); + + $count = DB::collection('users')->count(); + $this->assertEquals(0, $count); + + /** commit test */ + DB::beginTransaction(); + $count = DB::collection('users')->count(); + $this->assertEquals(0, $count); + DB::collection('users')->insert(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + $count = DB::collection('users')->count(); + $this->assertEquals(1, $count); + DB::commit(); + + $count = DB::collection('users')->count(); + $this->assertEquals(1, $count); + } + + public function testTransaction(): void + { + User::create(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + + // The $connection parameter may be unused, but is implicitly used to + // test that the closure is executed with the connection as an argument. + DB::transaction(function (Connection $connection): void { + User::create(['name' => 'alcaeus', 'age' => 38, 'title' => 'admin']); + User::where(['name' => 'klinson'])->update(['age' => 21]); + }); + + $count = User::count(); + $this->assertEquals(2, $count); + + $this->assertTrue(User::where('alcaeus')->exists()); + $this->assertTrue(User::where(['name' => 'klinson'])->where('age', 21)->exists()); + } + + public function testTransactionRepeatsOnTransientFailure(): void + { + User::create(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + + $timesRun = 0; + + DB::transaction(function () use (&$timesRun): void { + $timesRun++; + + // Run a query to start the transaction on the server + User::create(['name' => 'alcaeus', 'age' => 38, 'title' => 'admin']); + + // Update user outside of the session + if ($timesRun == 1) { + DB::getCollection('users')->updateOne(['name' => 'klinson'], ['$set' => ['age' => 22]]); + } + + // This update will create a write conflict, aborting the transaction + User::where(['name' => 'klinson'])->update(['age' => 21]); + }, 2); + + $this->assertSame(2, $timesRun); + $this->assertTrue(User::where(['name' => 'klinson'])->where('age', 21)->exists()); + } + + public function testTransactionRespectsRepetitionLimit(): void + { + $klinson = User::create(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + + $timesRun = 0; + + try { + DB::transaction(function () use (&$timesRun): void { + $timesRun++; + + // Run a query to start the transaction on the server + User::create(['name' => 'alcaeus', 'age' => 38, 'title' => 'admin']); + + // Update user outside of the session + DB::getCollection('users')->updateOne(['name' => 'klinson'], ['$inc' => ['age' => 2]]); + + // This update will create a write conflict, aborting the transaction + User::where(['name' => 'klinson'])->update(['age' => 21]); + }, 2); + + $this->fail('Expected exception during transaction'); + } catch (BulkWriteException $e) { + $this->assertInstanceOf(BulkWriteException::class, $e); + $this->assertStringContainsString('WriteConflict', $e->getMessage()); + } + + $this->assertSame(2, $timesRun); + + $check = User::find($klinson->_id); + $this->assertInstanceOf(User::class, $check); + + // Age is expected to be 24: the callback is executed twice, incrementing age by 2 every time + $this->assertSame(24, $check->age); + } + + public function testTransactionReturnsCallbackResult(): void + { + $result = DB::transaction(function (): User { + return User::create(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + }); + + $this->assertInstanceOf(User::class, $result); + $this->assertEquals($result->title, 'admin'); + $this->assertSame(1, User::count()); + } + + public function testNestedTransactionsCauseException(): void + { + $this->expectException(RuntimeException::class); + $this->expectExceptionMessage('Transaction already in progress'); + + DB::beginTransaction(); + DB::beginTransaction(); + DB::commit(); + DB::rollBack(); + } + + public function testNestingTransactionInManualTransaction() + { + $this->expectException(RuntimeException::class); + $this->expectExceptionMessage('Transaction already in progress'); + + DB::beginTransaction(); + DB::transaction(function (): void { + }); + DB::rollBack(); + } + + public function testCommitWithoutSession(): void + { + $this->expectException(RuntimeException::class); + $this->expectExceptionMessage('There is no active session.'); + + DB::commit(); + } + + public function testRollBackWithoutSession(): void + { + $this->expectException(RuntimeException::class); + $this->expectExceptionMessage('There is no active session.'); + + DB::rollback(); + } + + private function getPrimaryServerType(): int + { + return DB::getMongoClient()->getManager()->selectServer()->getType(); + } +} diff --git a/tests/config/database.php b/tests/config/database.php index 73f3d8697..498e4e7e0 100644 --- a/tests/config/database.php +++ b/tests/config/database.php @@ -6,7 +6,11 @@ 'name' => 'mongodb', 'driver' => 'mongodb', 'dsn' => env('MONGODB_URI', 'mongodb://127.0.0.1/'), - 'database' => env('MONGO_DATABASE', 'unittest'), + 'database' => env('MONGODB_DATABASE', 'unittest'), + 'options' => [ + 'connectTimeoutMS' => 100, + 'serverSelectionTimeoutMS' => 250, + ], ], 'mysql' => [ diff --git a/tests/config/queue.php b/tests/config/queue.php index 7d52487fa..d287780e9 100644 --- a/tests/config/queue.php +++ b/tests/config/queue.php @@ -16,7 +16,7 @@ ], 'failed' => [ - 'database' => env('MONGO_DATABASE'), + 'database' => env('MONGODB_DATABASE'), 'driver' => 'mongodb', 'table' => 'failed_jobs', ], From 317f70222eccb3ac5b173612ecc7372e904f0836 Mon Sep 17 00:00:00 2001 From: Hikmat Date: Sun, 15 Jan 2023 04:58:12 -0800 Subject: [PATCH 032/446] fix: whereBelongsTo (#2454) * override getQualifiedForeignKeyName() and add tests for whereBelongsTo * delete unneeded query() call * type hint for getQualifiedForeignKeyName() Co-authored-by: Hikmat Hasanov --- src/Relations/BelongsTo.php | 5 +++++ tests/RelationsTest.php | 13 +++++++++++++ 2 files changed, 18 insertions(+) diff --git a/src/Relations/BelongsTo.php b/src/Relations/BelongsTo.php index adaa13110..8a3690c47 100644 --- a/src/Relations/BelongsTo.php +++ b/src/Relations/BelongsTo.php @@ -72,4 +72,9 @@ protected function whereInMethod(EloquentModel $model, $key) { return 'whereIn'; } + + public function getQualifiedForeignKeyName(): string + { + return $this->foreignKey; + } } diff --git a/tests/RelationsTest.php b/tests/RelationsTest.php index 59d0f2757..c702f0e2b 100644 --- a/tests/RelationsTest.php +++ b/tests/RelationsTest.php @@ -534,4 +534,17 @@ public function testDoubleSaveManyToMany(): void $this->assertEquals([$user->_id], $client->user_ids); $this->assertEquals([$client->_id], $user->client_ids); } + + public function testWhereBelongsTo() + { + $user = User::create(['name' => 'John Doe']); + Item::create(['user_id' => $user->_id]); + Item::create(['user_id' => $user->_id]); + Item::create(['user_id' => $user->_id]); + Item::create(['user_id' => null]); + + $items = Item::whereBelongsTo($user)->get(); + + $this->assertCount(3, $items); + } } From 551ec9fe8a80d23cc2ee3d2b768dc602d16df8bf Mon Sep 17 00:00:00 2001 From: Henrique Troiano <63327237+henriquetroiano@users.noreply.github.com> Date: Sun, 15 Jan 2023 20:19:33 -0300 Subject: [PATCH 033/446] Add Geonear instructions to ReadMe. Closes #1878 (#2487) * create aggregate geonear instructions * create aggregate geonear instructions * create aggregate geonear instructions * create aggregate geonear instructions * create aggregate geonear instructions * chore: revert back readme changes * chore: minor readme change Co-authored-by: henriquetroiano Co-authored-by: divine <48183131+divine@users.noreply.github.com> --- README.md | 204 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 128 insertions(+), 76 deletions(-) diff --git a/README.md b/README.md index 0c07e7288..f201b2514 100644 --- a/README.md +++ b/README.md @@ -10,69 +10,70 @@ Laravel MongoDB This package adds functionalities to the Eloquent model and Query builder for MongoDB, using the original Laravel API. *This library extends the original Laravel classes, so it uses exactly the same methods.* - [Laravel MongoDB](#laravel-mongodb) - - [Installation](#installation) - - [Laravel version Compatibility](#laravel-version-compatibility) - - [Laravel](#laravel) - - [Lumen](#lumen) - - [Non-Laravel projects](#non-laravel-projects) - - [Testing](#testing) - - [Database Testing](#database-testing) - - [Configuration](#configuration) - - [Eloquent](#eloquent) - - [Extending the base model](#extending-the-base-model) - - [Extending the Authenticable base model](#extending-the-authenticable-base-model) - - [Soft Deletes](#soft-deletes) - - [Guarding attributes](#guarding-attributes) - - [Dates](#dates) - - [Basic Usage](#basic-usage) - - [MongoDB-specific operators](#mongodb-specific-operators) - - [MongoDB-specific Geo operations](#mongodb-specific-geo-operations) - - [Inserts, updates and deletes](#inserts-updates-and-deletes) - - [MongoDB specific operations](#mongodb-specific-operations) - - [Relationships](#relationships) - - [Basic Usage](#basic-usage-1) - - [belongsToMany and pivots](#belongstomany-and-pivots) - - [EmbedsMany Relationship](#embedsmany-relationship) - - [EmbedsOne Relationship](#embedsone-relationship) - - [Query Builder](#query-builder) - - [Basic Usage](#basic-usage-2) - - [Available operations](#available-operations) - - [Transactions](#transactions) - - [Schema](#schema) - - [Basic Usage](#basic-usage-3) - - [Geospatial indexes](#geospatial-indexes) - - [Extending](#extending) - - [Cross-Database Relationships](#cross-database-relationships) - - [Authentication](#authentication) - - [Queues](#queues) - - [Laravel specific](#laravel-specific) - - [Lumen specific](#lumen-specific) - - [Upgrading](#upgrading) - - [Upgrading from version 2 to 3](#upgrading-from-version-2-to-3) - - [Security contact information](#security-contact-information) + - [Installation](#installation) + - [Laravel version Compatibility](#laravel-version-compatibility) + - [Laravel](#laravel) + - [Lumen](#lumen) + - [Non-Laravel projects](#non-laravel-projects) + - [Testing](#testing) + - [Database Testing](#database-testing) + - [Configuration](#configuration) + - [Eloquent](#eloquent) + - [Extending the base model](#extending-the-base-model) + - [Extending the Authenticable base model](#extending-the-authenticable-base-model) + - [Soft Deletes](#soft-deletes) + - [Guarding attributes](#guarding-attributes) + - [Dates](#dates) + - [Basic Usage](#basic-usage) + - [MongoDB-specific operators](#mongodb-specific-operators) + - [MongoDB-specific Geo operations](#mongodb-specific-geo-operations) + - [Inserts, updates and deletes](#inserts-updates-and-deletes) + - [MongoDB specific operations](#mongodb-specific-operations) + - [Relationships](#relationships) + - [Basic Usage](#basic-usage-1) + - [belongsToMany and pivots](#belongstomany-and-pivots) + - [EmbedsMany Relationship](#embedsmany-relationship) + - [EmbedsOne Relationship](#embedsone-relationship) + - [Query Builder](#query-builder) + - [Basic Usage](#basic-usage-2) + - [Available operations](#available-operations) + - [Transactions](#transactions) + - [Schema](#schema) + - [Basic Usage](#basic-usage-3) + - [Geospatial indexes](#geospatial-indexes) + - [Extending](#extending) + - [Cross-Database Relationships](#cross-database-relationships) + - [Authentication](#authentication) + - [Queues](#queues) + - [Laravel specific](#laravel-specific) + - [Lumen specific](#lumen-specific) + - [Upgrading](#upgrading) + - [Upgrading from version 2 to 3](#upgrading-from-version-2-to-3) + - [Security contact information](#security-contact-information) Installation ------------ + Make sure you have the MongoDB PHP driver installed. You can find installation instructions at http://php.net/manual/en/mongodb.installation.php ### Laravel version Compatibility - Laravel | Package | Maintained -:---------|:---------------|:---------- - 9.x | 3.9.x | :white_check_mark: - 8.x | 3.8.x | :white_check_mark: - 7.x | 3.7.x | :x: - 6.x | 3.6.x | :white_check_mark: - 5.8.x | 3.5.x | :x: - 5.7.x | 3.4.x | :x: - 5.6.x | 3.4.x | :x: - 5.5.x | 3.3.x | :x: - 5.4.x | 3.2.x | :x: - 5.3.x | 3.1.x or 3.2.x | :x: - 5.2.x | 2.3.x or 3.0.x | :x: - 5.1.x | 2.2.x or 3.0.x | :x: - 5.0.x | 2.1.x | :x: - 4.2.x | 2.0.x | :x: +| Laravel | Package | Maintained | +| :------ | :------------- | :----------------- | +| 9.x | 3.9.x | :white_check_mark: | +| 8.x | 3.8.x | :white_check_mark: | +| 7.x | 3.7.x | :x: | +| 6.x | 3.6.x | :x: | +| 5.8.x | 3.5.x | :x: | +| 5.7.x | 3.4.x | :x: | +| 5.6.x | 3.4.x | :x: | +| 5.5.x | 3.3.x | :x: | +| 5.4.x | 3.2.x | :x: | +| 5.3.x | 3.1.x or 3.2.x | :x: | +| 5.2.x | 2.3.x or 3.0.x | :x: | +| 5.1.x | 2.2.x or 3.0.x | :x: | +| 5.0.x | 2.1.x | :x: | +| 4.2.x | 2.0.x | :x: | Install the package via Composer: @@ -139,8 +140,9 @@ use DatabaseMigrations; ``` Keep in mind that these traits are not yet supported: -- `use Database Transactions;` -- `use RefreshDatabase;` + +- `use Database Transactions;` +- `use RefreshDatabase;` Configuration ------------- @@ -179,6 +181,7 @@ Eloquent -------- ### Extending the base model + This package includes a MongoDB enabled Eloquent class that you can use to define models for corresponding collections. ```php @@ -229,6 +232,7 @@ class Book extends Model ``` ### Extending the Authenticatable base model + This package includes a MongoDB Authenticatable Eloquent class `Jenssegers\Mongodb\Auth\User` that you can use to replace the default Authenticatable class `Illuminate\Foundation\Auth\User` for your `User` model. ```php @@ -354,8 +358,8 @@ $users = User::whereNull('age')->get(); ```php $users = User::whereDate('birthday', '2021-5-12')->get(); ``` -The usage is the same as `whereMonth` / `whereDay` / `whereYear` / `whereTime` +The usage is the same as `whereMonth` / `whereDay` / `whereYear` / `whereTime` **Advanced wheres** @@ -584,6 +588,44 @@ $bars = Bar::where('location', 'geoIntersects', [ ], ])->get(); ``` + +**GeoNear** + +You are able to make a `geoNear` query on mongoDB. +You don't need to specify the automatic fields on the model. +The returned instance is a collection. So you're able to make the [Collection](https://laravel.com/docs/9.x/collections) operations. +Just make sure that your model has a `location` field, and a [2ndSphereIndex](https://www.mongodb.com/docs/manual/core/2dsphere). +The data in the `location` field must be saved as [GeoJSON](https://www.mongodb.com/docs/manual/reference/geojson/). +The `location` points must be saved as [WGS84](https://www.mongodb.com/docs/manual/reference/glossary/#std-term-WGS84) reference system for geometry calculation. That means, basically, you need to save `longitude and latitude`, in that order specifically, and to find near with calculated distance, you `need to do the same way`. + +``` +Bar::find("63a0cd574d08564f330ceae2")->update( + [ + 'location' => [ + 'type' => 'Point', + 'coordinates' => [ + -0.1367563, + 51.5100913 + ] + ] + ] +); +$bars = Bar::raw(function ($collection) { + return $collection->aggregate([ + [ + '$geoNear' => [ + "near" => [ "type" => "Point", "coordinates" => [-0.132239, 51.511874] ], + "distanceField" => "dist.calculated", + "minDistance" => 0, + "maxDistance" => 6000, + "includeLocs" => "dist.location", + "spherical" => true, + ] + ] + ]); +}); +``` + ### Inserts, updates and deletes Inserting, updating and deleting records works just like the original Eloquent. Please check [Laravel Docs' Eloquent section](https://laravel.com/docs/6.x/eloquent). @@ -740,14 +782,16 @@ Relationships ### Basic Usage The only available relationships are: - - hasOne - - hasMany - - belongsTo - - belongsToMany + +- hasOne +- hasMany +- belongsTo +- belongsToMany The MongoDB-specific relationships are: - - embedsOne - - embedsMany + +- embedsOne +- embedsMany Here is a small example: @@ -889,7 +933,6 @@ class User extends Model Embedded relations will return a Collection of embedded items instead of a query builder. Check out the available operations here: https://laravel.com/docs/master/collections - ### EmbedsOne Relationship The embedsOne relation is similar to the embedsMany relation, but only embeds a single model. @@ -954,7 +997,6 @@ When using MongoDB connections, you will be able to build fluent queries to perf For your convenience, there is a `collection` alias for `table` as well as some additional MongoDB specific operators/operations. - ```php $books = DB::collection('books')->get(); @@ -967,10 +1009,12 @@ $hungerGames = If you are familiar with [Eloquent Queries](http://laravel.com/docs/queries), there is the same functionality. ### Available operations + To see the available operations, check the [Eloquent](#eloquent) section. Transactions ------------ + Transactions require MongoDB version ^4.0 as well as deployment of replica set or sharded clusters. You can find more information [in the MongoDB docs](https://docs.mongodb.com/manual/core/transactions/) ### Basic Usage @@ -995,6 +1039,7 @@ DB::commit(); ``` To abort a transaction, call the `rollBack` method at any point during the transaction: + ```php DB::beginTransaction(); User::create(['name' => 'john', 'age' => 19, 'title' => 'admin', 'email' => 'john@example.com']); @@ -1004,6 +1049,7 @@ DB::rollBack(); ``` **NOTE:** Transactions in MongoDB cannot be nested. DB::beginTransaction() function will start new transactions in a new created or existing session and will raise the RuntimeException when transactions already exist. See more in MongoDB official docs [Transactions and Sessions](https://www.mongodb.com/docs/manual/core/transactions/#transactions-and-sessions) + ```php DB::beginTransaction(); User::create(['name' => 'john', 'age' => 20, 'title' => 'admin']); @@ -1017,6 +1063,7 @@ DB::rollBack(); Schema ------ + The database driver also has (limited) schema builder support. You can easily manipulate collections and set indexes. ### Basic Usage @@ -1046,17 +1093,19 @@ Schema::create('users', function ($collection) { ``` Inherited operations: -- create and drop -- collection -- hasCollection -- index and dropIndex (compound indexes supported as well) -- unique + +- create and drop +- collection +- hasCollection +- index and dropIndex (compound indexes supported as well) +- unique MongoDB specific operations: -- background -- sparse -- expire -- geospatial + +- background +- sparse +- expire +- geospatial All other (unsupported) operations are implemented as dummy pass-through methods because MongoDB does not use a predefined schema. @@ -1112,6 +1161,7 @@ class User extends Model } } ``` + Within your MongoDB model, you should define the relationship: ```php @@ -1129,6 +1179,7 @@ class Message extends Model ``` ### Authentication + If you want to use Laravel's native Auth functionality, register this included service provider: ```php @@ -1140,6 +1191,7 @@ This service provider will slightly modify the internal DatabaseReminderReposito If you don't use password reminders, you don't have to register this service provider and everything else should work just fine. ### Queues + If you want to use MongoDB as your database backend, change the driver in `config/queue.php`: ```php From 23b6fe9a2f295f9df67faa87bbc13a837cce95bb Mon Sep 17 00:00:00 2001 From: Will Taylor-Jackson Date: Fri, 24 Sep 2021 15:58:17 +0100 Subject: [PATCH 034/446] tests: for snake case morph relation name --- tests/RelationsTest.php | 12 ++++++------ tests/models/Client.php | 2 +- tests/models/Photo.php | 2 +- tests/models/User.php | 2 +- 4 files changed, 9 insertions(+), 9 deletions(-) diff --git a/tests/RelationsTest.php b/tests/RelationsTest.php index c702f0e2b..b1b73e6cc 100644 --- a/tests/RelationsTest.php +++ b/tests/RelationsTest.php @@ -370,21 +370,21 @@ public function testMorph(): void $this->assertEquals($photo->id, $client->photo->id); $photo = Photo::first(); - $this->assertEquals($photo->imageable->name, $user->name); + $this->assertEquals($photo->hasImage->name, $user->name); $user = User::with('photos')->find($user->_id); $relations = $user->getRelations(); $this->assertArrayHasKey('photos', $relations); $this->assertEquals(1, $relations['photos']->count()); - $photos = Photo::with('imageable')->get(); + $photos = Photo::with('hasImage')->get(); $relations = $photos[0]->getRelations(); - $this->assertArrayHasKey('imageable', $relations); - $this->assertInstanceOf(User::class, $photos[0]->imageable); + $this->assertArrayHasKey('hasImage', $relations); + $this->assertInstanceOf(User::class, $photos[0]->hasImage); $relations = $photos[1]->getRelations(); - $this->assertArrayHasKey('imageable', $relations); - $this->assertInstanceOf(Client::class, $photos[1]->imageable); + $this->assertArrayHasKey('hasImage', $relations); + $this->assertInstanceOf(Client::class, $photos[1]->hasImage); } public function testHasManyHas(): void diff --git a/tests/models/Client.php b/tests/models/Client.php index 2c1388a6c..65c5d81a0 100644 --- a/tests/models/Client.php +++ b/tests/models/Client.php @@ -20,7 +20,7 @@ public function users(): BelongsToMany public function photo(): MorphOne { - return $this->morphOne('Photo', 'imageable'); + return $this->morphOne('Photo', 'has_image'); } public function addresses(): HasMany diff --git a/tests/models/Photo.php b/tests/models/Photo.php index 8cb800922..05c06d443 100644 --- a/tests/models/Photo.php +++ b/tests/models/Photo.php @@ -11,7 +11,7 @@ class Photo extends Eloquent protected $collection = 'photos'; protected static $unguarded = true; - public function imageable(): MorphTo + public function hasImage(): MorphTo { return $this->morphTo(); } diff --git a/tests/models/User.php b/tests/models/User.php index b394ea6e7..f9360f545 100644 --- a/tests/models/User.php +++ b/tests/models/User.php @@ -73,7 +73,7 @@ public function groups() public function photos() { - return $this->morphMany('Photo', 'imageable'); + return $this->morphMany('Photo', 'has_image'); } public function addresses() From bd351577eb8ccc5ebb4e48a8464c2564bd73bb33 Mon Sep 17 00:00:00 2001 From: Will Taylor-Jackson Date: Fri, 24 Sep 2021 15:59:59 +0100 Subject: [PATCH 035/446] fix: keep camel cased name except for `getMorphs` --- src/Eloquent/HybridRelations.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Eloquent/HybridRelations.php b/src/Eloquent/HybridRelations.php index d3dcb9919..0818ca3ee 100644 --- a/src/Eloquent/HybridRelations.php +++ b/src/Eloquent/HybridRelations.php @@ -180,10 +180,10 @@ public function morphTo($name = null, $type = null, $id = null, $ownerKey = null if ($name === null) { [$current, $caller] = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2); - $name = Str::snake($caller['function']); + $name = $caller['function']; } - [$type, $id] = $this->getMorphs($name, $type, $id); + [$type, $id] = $this->getMorphs(Str::snake($name), $type, $id); // If the type value is null it is probably safe to assume we're eager loading // the relationship. When that is the case we will pass in a dummy query as From 7807734c40ac72a3fec858f3932393beb6a85caa Mon Sep 17 00:00:00 2001 From: Shift Date: Mon, 30 Jan 2023 23:52:14 +0000 Subject: [PATCH 036/446] Bump dependencies for Laravel 10 --- composer.json | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/composer.json b/composer.json index 12a5b7eeb..e3c58d032 100644 --- a/composer.json +++ b/composer.json @@ -19,17 +19,17 @@ ], "license": "MIT", "require": { - "illuminate/support": "^9.0", - "illuminate/container": "^9.0", - "illuminate/database": "^9.0", - "illuminate/events": "^9.0", - "mongodb/mongodb": "^1.11" + "illuminate/support": "^10.0", + "illuminate/container": "^10.0", + "illuminate/database": "^10.0", + "illuminate/events": "^10.0", + "mongodb/mongodb": "^1.15" }, "require-dev": { - "phpunit/phpunit": "^9.5.8", - "orchestra/testbench": "^7.0", - "mockery/mockery": "^1.3.1", - "doctrine/dbal": "^2.13.3|^3.1.4" + "phpunit/phpunit": "^9.5.10", + "orchestra/testbench": "^8.0", + "mockery/mockery": "^1.4.4", + "doctrine/dbal": "^3.5" }, "autoload": { "psr-4": { From 37236c08b103731d8ae4c70e87531fcececdbd8f Mon Sep 17 00:00:00 2001 From: Divine <48183131+divine@users.noreply.github.com> Date: Tue, 31 Jan 2023 10:36:45 +0300 Subject: [PATCH 037/446] chore: update minimum stability --- composer.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/composer.json b/composer.json index e3c58d032..24fb26658 100644 --- a/composer.json +++ b/composer.json @@ -54,5 +54,6 @@ "Jenssegers\\Mongodb\\MongodbQueueServiceProvider" ] } - } + }, + "minimum-stability": "dev" } From 452a0bbb7f6e15cd3301508bc3e54b433059ac08 Mon Sep 17 00:00:00 2001 From: Divine <48183131+divine@users.noreply.github.com> Date: Tue, 31 Jan 2023 10:39:19 +0300 Subject: [PATCH 038/446] chore: disable php 8.0 in gh builds --- .github/workflows/build-ci.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/build-ci.yml b/.github/workflows/build-ci.yml index f081e3273..905c4d2de 100644 --- a/.github/workflows/build-ci.yml +++ b/.github/workflows/build-ci.yml @@ -41,7 +41,6 @@ jobs: - '4.4' - '5.0' php: - - '8.0' - '8.1' services: mysql: From 2ea1a7c0aee085c382349613d399be79a0bd1f1a Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Tue, 7 Feb 2023 14:02:03 +0100 Subject: [PATCH 039/446] Update handling of dates for Laravel 10 --- README.md | 4 +- src/Eloquent/Model.php | 83 +++++++++++++++++++++++++++++++++++------- tests/ModelTest.php | 3 +- tests/models/Soft.php | 2 +- tests/models/User.php | 5 ++- 5 files changed, 77 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index f201b2514..59a22c12c 100644 --- a/README.md +++ b/README.md @@ -256,8 +256,6 @@ use Jenssegers\Mongodb\Eloquent\SoftDeletes; class User extends Model { use SoftDeletes; - - protected $dates = ['deleted_at']; } ``` @@ -279,7 +277,7 @@ use Jenssegers\Mongodb\Eloquent\Model; class User extends Model { - protected $dates = ['birthday']; + protected $casts = ['birthday' => 'datetime']; } ``` diff --git a/src/Eloquent/Model.php b/src/Eloquent/Model.php index e123391dc..9f8d7f90a 100644 --- a/src/Eloquent/Model.php +++ b/src/Eloquent/Model.php @@ -2,18 +2,23 @@ namespace Jenssegers\Mongodb\Eloquent; +use function array_key_exists; use DateTimeInterface; +use function explode; use Illuminate\Contracts\Queue\QueueableCollection; use Illuminate\Contracts\Queue\QueueableEntity; +use Illuminate\Contracts\Support\Arrayable; use Illuminate\Database\Eloquent\Model as BaseModel; use Illuminate\Database\Eloquent\Relations\Relation; use Illuminate\Support\Arr; use Illuminate\Support\Facades\Date; use Illuminate\Support\Str; +use function in_array; use Jenssegers\Mongodb\Query\Builder as QueryBuilder; use MongoDB\BSON\Binary; use MongoDB\BSON\ObjectID; use MongoDB\BSON\UTCDateTime; +use function uniqid; abstract class Model extends BaseModel { @@ -94,7 +99,7 @@ public function fromDateTime($value) $value = parent::asDateTime($value); } - return new UTCDateTime($value->format('Uv')); + return new UTCDateTime($value); } /** @@ -191,13 +196,14 @@ public function setAttribute($key, $value) $value = $builder->convertKey($value); } // Support keys in dot notation. elseif (Str::contains($key, '.')) { - if (in_array($key, $this->getDates()) && $value) { - $value = $this->fromDateTime($value); - } + // Store to a temporary key, then move data to the actual key + $uniqueKey = uniqid($key); + parent::setAttribute($uniqueKey, $value); - Arr::set($this->attributes, $key, $value); + Arr::set($this->attributes, $key, $this->attributes[$uniqueKey] ?? null); + unset($this->attributes[$uniqueKey]); - return; + return $this; } return parent::setAttribute($key, $value); @@ -222,13 +228,6 @@ public function attributesToArray() } } - // Convert dot-notation dates. - foreach ($this->getDates() as $key) { - if (Str::contains($key, '.') && Arr::has($attributes, $key)) { - Arr::set($attributes, $key, (string) $this->asDateTime(Arr::get($attributes, $key))); - } - } - return $attributes; } @@ -515,4 +514,62 @@ public function __call($method, $parameters) return parent::__call($method, $parameters); } + + /** + * Add the casted attributes to the attributes array. + * + * @param array $attributes + * @param array $mutatedAttributes + * @return array + */ + protected function addCastAttributesToArray(array $attributes, array $mutatedAttributes) + { + foreach ($this->getCasts() as $key => $castType) { + if (! Arr::has($attributes, $key) || Arr::has($mutatedAttributes, $key)) { + continue; + } + + $originalValue = Arr::get($attributes, $key); + + // Here we will cast the attribute. Then, if the cast is a date or datetime cast + // then we will serialize the date for the array. This will convert the dates + // to strings based on the date format specified for these Eloquent models. + $castValue = $this->castAttribute( + $key, $originalValue + ); + + // If the attribute cast was a date or a datetime, we will serialize the date as + // a string. This allows the developers to customize how dates are serialized + // into an array without affecting how they are persisted into the storage. + if ($castValue !== null && in_array($castType, ['date', 'datetime', 'immutable_date', 'immutable_datetime'])) { + $castValue = $this->serializeDate($castValue); + } + + if ($castValue !== null && ($this->isCustomDateTimeCast($castType) || + $this->isImmutableCustomDateTimeCast($castType))) { + $castValue = $castValue->format(explode(':', $castType, 2)[1]); + } + + if ($castValue instanceof DateTimeInterface && + $this->isClassCastable($key)) { + $castValue = $this->serializeDate($castValue); + } + + if ($castValue !== null && $this->isClassSerializable($key)) { + $castValue = $this->serializeClassCastableAttribute($key, $castValue); + } + + if ($this->isEnumCastable($key) && (! $castValue instanceof Arrayable)) { + $castValue = $castValue !== null ? $this->getStorableEnumValue($attributes[$key]) : null; + } + + if ($castValue instanceof Arrayable) { + $castValue = $castValue->toArray(); + } + + Arr::set($attributes, $key, $castValue); + } + + return $attributes; + } } diff --git a/tests/ModelTest.php b/tests/ModelTest.php index 22e06baee..5d94920b9 100644 --- a/tests/ModelTest.php +++ b/tests/ModelTest.php @@ -577,8 +577,7 @@ public function testDates(): void $this->assertInstanceOf(Carbon::class, $user->getAttribute('entry.date')); $data = $user->toArray(); - $this->assertNotInstanceOf(UTCDateTime::class, $data['entry']['date']); - $this->assertEquals((string) $user->getAttribute('entry.date')->format('Y-m-d H:i:s'), $data['entry']['date']); + $this->assertIsString($data['entry']['date']); } public function testCarbonDateMockingWorks() diff --git a/tests/models/Soft.php b/tests/models/Soft.php index c4571e6b0..30711e61d 100644 --- a/tests/models/Soft.php +++ b/tests/models/Soft.php @@ -17,5 +17,5 @@ class Soft extends Eloquent protected $connection = 'mongodb'; protected $collection = 'soft'; protected static $unguarded = true; - protected $dates = ['deleted_at']; + protected $casts = ['deleted_at' => 'datetime']; } diff --git a/tests/models/User.php b/tests/models/User.php index f9360f545..8bf3c9410 100644 --- a/tests/models/User.php +++ b/tests/models/User.php @@ -33,7 +33,10 @@ class User extends Eloquent implements AuthenticatableContract, CanResetPassword use Notifiable; protected $connection = 'mongodb'; - protected $dates = ['birthday', 'entry.date']; + protected $casts = [ + 'birthday' => 'datetime', + 'entry.date' => 'datetime', + ]; protected static $unguarded = true; public function books() From 8bb0199a14035f285a0d6209c20d1e64cb67cc5d Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Tue, 7 Feb 2023 14:02:34 +0100 Subject: [PATCH 040/446] Remove deprecated PHPUnit call --- tests/QueryBuilderTest.php | 2 -- 1 file changed, 2 deletions(-) diff --git a/tests/QueryBuilderTest.php b/tests/QueryBuilderTest.php index c169071d0..235784829 100644 --- a/tests/QueryBuilderTest.php +++ b/tests/QueryBuilderTest.php @@ -146,8 +146,6 @@ public function commandStarted(CommandStartedEvent $event) return; } - Assert::assertObjectHasAttribute('maxTimeMS', $event->getCommand()); - // Expect the timeout to be converted to milliseconds Assert::assertSame(1000, $event->getCommand()->maxTimeMS); } From a141614909d3c3f85668465a0ca9a7e510fb5bf1 Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Thu, 9 Feb 2023 08:29:09 +0100 Subject: [PATCH 041/446] Rename getBaseQuery method to toBase --- src/Relations/EmbedsMany.php | 6 +++--- src/Relations/EmbedsOne.php | 6 +++--- src/Relations/EmbedsOneOrMany.php | 4 ++-- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/src/Relations/EmbedsMany.php b/src/Relations/EmbedsMany.php index ba1513255..9797acaa7 100644 --- a/src/Relations/EmbedsMany.php +++ b/src/Relations/EmbedsMany.php @@ -52,7 +52,7 @@ public function performInsert(Model $model) } // Push the new model to the database. - $result = $this->getBaseQuery()->push($this->localKey, $model->getAttributes(), true); + $result = $this->toBase()->push($this->localKey, $model->getAttributes(), true); // Attach the model to its parent. if ($result) { @@ -83,7 +83,7 @@ public function performUpdate(Model $model) $values = $this->getUpdateValues($model->getDirty(), $this->localKey.'.$.'); // Update document in database. - $result = $this->getBaseQuery()->where($this->localKey.'.'.$model->getKeyName(), $foreignKey) + $result = $this->toBase()->where($this->localKey.'.'.$model->getKeyName(), $foreignKey) ->update($values); // Attach the model to its parent. @@ -112,7 +112,7 @@ public function performDelete(Model $model) // Get the correct foreign key value. $foreignKey = $this->getForeignKeyValue($model); - $result = $this->getBaseQuery()->pull($this->localKey, [$model->getKeyName() => $foreignKey]); + $result = $this->toBase()->pull($this->localKey, [$model->getKeyName() => $foreignKey]); if ($result) { $this->dissociate($model); diff --git a/src/Relations/EmbedsOne.php b/src/Relations/EmbedsOne.php index ba2a41dfc..f50454080 100644 --- a/src/Relations/EmbedsOne.php +++ b/src/Relations/EmbedsOne.php @@ -50,7 +50,7 @@ public function performInsert(Model $model) return $this->parent->save() ? $model : false; } - $result = $this->getBaseQuery()->update([$this->localKey => $model->getAttributes()]); + $result = $this->toBase()->update([$this->localKey => $model->getAttributes()]); // Attach the model to its parent. if ($result) { @@ -76,7 +76,7 @@ public function performUpdate(Model $model) $values = $this->getUpdateValues($model->getDirty(), $this->localKey.'.'); - $result = $this->getBaseQuery()->update($values); + $result = $this->toBase()->update($values); // Attach the model to its parent. if ($result) { @@ -101,7 +101,7 @@ public function performDelete() } // Overwrite the local key with an empty array. - $result = $this->getBaseQuery()->update([$this->localKey => null]); + $result = $this->toBase()->update([$this->localKey => null]); // Detach the model from its parent. if ($result) { diff --git a/src/Relations/EmbedsOneOrMany.php b/src/Relations/EmbedsOneOrMany.php index 2e5215377..4cb71d595 100644 --- a/src/Relations/EmbedsOneOrMany.php +++ b/src/Relations/EmbedsOneOrMany.php @@ -246,7 +246,7 @@ protected function getForeignKeyValue($id) } // Convert the id to MongoId if necessary. - return $this->getBaseQuery()->convertKey($id); + return $this->toBase()->convertKey($id); } /** @@ -322,7 +322,7 @@ public function getQuery() /** * @inheritdoc */ - public function getBaseQuery() + public function toBase() { // Because we are sharing this relation instance to models, we need // to make sure we use separate query instances. From e5f3571ad0b162b5b92160e50eec0d5a98353fee Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Thu, 9 Feb 2023 08:30:16 +0100 Subject: [PATCH 042/446] Remove dependency on doctrine/dbal --- composer.json | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/composer.json b/composer.json index 24fb26658..b2dba6529 100644 --- a/composer.json +++ b/composer.json @@ -28,8 +28,7 @@ "require-dev": { "phpunit/phpunit": "^9.5.10", "orchestra/testbench": "^8.0", - "mockery/mockery": "^1.4.4", - "doctrine/dbal": "^3.5" + "mockery/mockery": "^1.4.4" }, "autoload": { "psr-4": { From 02df6cbd5aae85679d2f2f80020eaf6b2114ecdf Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Thu, 9 Feb 2023 08:34:10 +0100 Subject: [PATCH 043/446] Update tested PHP versions --- .github/workflows/build-ci.yml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/.github/workflows/build-ci.yml b/.github/workflows/build-ci.yml index 905c4d2de..c3e22c23f 100644 --- a/.github/workflows/build-ci.yml +++ b/.github/workflows/build-ci.yml @@ -14,10 +14,10 @@ jobs: strategy: matrix: php: - - '8.0' + - '8.1' steps: - name: Checkout - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Setup PHP uses: shivammathur/setup-php@v2 with: @@ -42,6 +42,7 @@ jobs: - '5.0' php: - '8.1' + - '8.2' services: mysql: image: mysql:5.7 @@ -53,7 +54,7 @@ jobs: MYSQL_ROOT_PASSWORD: steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: Create MongoDB Replica Set run: | docker run --name mongodb -p 27017:27017 -e MONGO_INITDB_DATABASE=unittest --detach mongo:${{ matrix.mongodb }} mongod --replSet rs --setParameter transactionLifetimeLimitSeconds=5 From ba66a4ef8757095127ce9fc27b1686eb07d34575 Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Thu, 9 Feb 2023 09:47:26 +0100 Subject: [PATCH 044/446] Fix auth test for Laravel 10 --- src/Auth/PasswordBrokerManager.php | 3 +- src/Auth/PasswordResetServiceProvider.php | 23 ------------ tests/AuthTest.php | 46 +++++++++++------------ 3 files changed, 25 insertions(+), 47 deletions(-) diff --git a/src/Auth/PasswordBrokerManager.php b/src/Auth/PasswordBrokerManager.php index 281f8af75..bfb87874b 100644 --- a/src/Auth/PasswordBrokerManager.php +++ b/src/Auth/PasswordBrokerManager.php @@ -16,7 +16,8 @@ protected function createTokenRepository(array $config) $this->app['hash'], $config['table'], $this->app['config']['app.key'], - $config['expire'] + $config['expire'], + $config['throttle'] ?? 0 ); } } diff --git a/src/Auth/PasswordResetServiceProvider.php b/src/Auth/PasswordResetServiceProvider.php index ba4e32e62..74e5953c0 100644 --- a/src/Auth/PasswordResetServiceProvider.php +++ b/src/Auth/PasswordResetServiceProvider.php @@ -6,29 +6,6 @@ class PasswordResetServiceProvider extends BasePasswordResetServiceProvider { - /** - * Register the token repository implementation. - * - * @return void - */ - protected function registerTokenRepository() - { - $this->app->singleton('auth.password.tokens', function ($app) { - $connection = $app['db']->connection(); - - // The database token repository is an implementation of the token repository - // interface, and is responsible for the actual storing of auth tokens and - // their e-mail addresses. We will inject this table and hash key to it. - $table = $app['config']['auth.password.table']; - - $key = $app['config']['app.key']; - - $expire = $app['config']->get('auth.password.expire', 60); - - return new DatabaseTokenRepository($connection, $table, $key, $expire); - }); - } - /** * @inheritdoc */ diff --git a/tests/AuthTest.php b/tests/AuthTest.php index 912cc9061..86261696e 100644 --- a/tests/AuthTest.php +++ b/tests/AuthTest.php @@ -1,7 +1,6 @@ truncate(); + DB::collection('password_reset_tokens')->truncate(); } public function testAuthAttempt() { User::create([ 'name' => 'John Doe', - 'email' => 'john@doe.com', + 'email' => 'john.doe@example.com', 'password' => Hash::make('foobar'), ]); - $this->assertTrue(Auth::attempt(['email' => 'john@doe.com', 'password' => 'foobar'], true)); + $this->assertTrue(Auth::attempt(['email' => 'john.doe@example.com', 'password' => 'foobar'], true)); $this->assertTrue(Auth::check()); } public function testRemindOld() { - if (Application::VERSION >= '5.2') { - $this->expectNotToPerformAssertions(); - - return; - } - - $mailer = Mockery::mock('Illuminate\Mail\Mailer'); - $tokens = $this->app->make('auth.password.tokens'); - $users = $this->app['auth']->driver()->getProvider(); - - $broker = new PasswordBroker($tokens, $users, $mailer, ''); + $broker = $this->app->make('auth.password.broker'); $user = User::create([ 'name' => 'John Doe', - 'email' => 'john@doe.com', + 'email' => 'john.doe@example.com', 'password' => Hash::make('foobar'), ]); - $mailer->shouldReceive('send')->once(); - $broker->sendResetLink(['email' => 'john@doe.com']); + $token = null; + + $this->assertSame( + PasswordBroker::RESET_LINK_SENT, + $broker->sendResetLink( + ['email' => 'john.doe@example.com'], + function ($actualUser, $actualToken) use ($user, &$token) { + $this->assertEquals($user->_id, $actualUser->_id); + // Store token for later use + $token = $actualToken; + } + ) + ); - $this->assertEquals(1, DB::collection('password_resets')->count()); - $reminder = DB::collection('password_resets')->first(); - $this->assertEquals('john@doe.com', $reminder['email']); + $this->assertEquals(1, DB::collection('password_reset_tokens')->count()); + $reminder = DB::collection('password_reset_tokens')->first(); + $this->assertEquals('john.doe@example.com', $reminder['email']); $this->assertNotNull($reminder['token']); $this->assertInstanceOf(UTCDateTime::class, $reminder['created_at']); $credentials = [ - 'email' => 'john@doe.com', + 'email' => 'john.doe@example.com', 'password' => 'foobar', 'password_confirmation' => 'foobar', - 'token' => $reminder['token'], + 'token' => $token, ]; $response = $broker->reset($credentials, function ($user, $password) { From 4da2a9225a01b243bfbc90f25b675555643b2954 Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Thu, 9 Feb 2023 10:39:10 +0100 Subject: [PATCH 045/446] Fix styleCI issues --- src/Relations/EmbedsOne.php | 10 ++++---- src/Relations/EmbedsOneOrMany.php | 38 +++++++++++++++---------------- 2 files changed, 24 insertions(+), 24 deletions(-) diff --git a/src/Relations/EmbedsOne.php b/src/Relations/EmbedsOne.php index f50454080..8bd573b3e 100644 --- a/src/Relations/EmbedsOne.php +++ b/src/Relations/EmbedsOne.php @@ -33,7 +33,7 @@ public function getEager() /** * Save a new model and attach it to the parent model. * - * @param Model $model + * @param Model $model * @return Model|bool */ public function performInsert(Model $model) @@ -63,7 +63,7 @@ public function performInsert(Model $model) /** * Save an existing model and attach it to the parent model. * - * @param Model $model + * @param Model $model * @return Model|bool */ public function performUpdate(Model $model) @@ -114,7 +114,7 @@ public function performDelete() /** * Attach the model to its parent. * - * @param Model $model + * @param Model $model * @return Model */ public function associate(Model $model) @@ -145,8 +145,8 @@ public function delete() /** * Get the name of the "where in" method for eager loading. * - * @param \Illuminate\Database\Eloquent\Model $model - * @param string $key + * @param \Illuminate\Database\Eloquent\Model $model + * @param string $key * @return string */ protected function whereInMethod(EloquentModel $model, $key) diff --git a/src/Relations/EmbedsOneOrMany.php b/src/Relations/EmbedsOneOrMany.php index 4cb71d595..dedae591b 100644 --- a/src/Relations/EmbedsOneOrMany.php +++ b/src/Relations/EmbedsOneOrMany.php @@ -34,12 +34,12 @@ abstract class EmbedsOneOrMany extends Relation /** * Create a new embeds many relationship instance. * - * @param Builder $query - * @param Model $parent - * @param Model $related - * @param string $localKey - * @param string $foreignKey - * @param string $relation + * @param Builder $query + * @param Model $parent + * @param Model $related + * @param string $localKey + * @param string $foreignKey + * @param string $relation */ public function __construct(Builder $query, Model $parent, Model $related, $localKey, $foreignKey, $relation) { @@ -95,7 +95,7 @@ public function match(array $models, Collection $results, $relation) /** * Shorthand to get the results of the relationship. * - * @param array $columns + * @param array $columns * @return Collection */ public function get($columns = ['*']) @@ -116,7 +116,7 @@ public function count() /** * Attach a model instance to the parent model. * - * @param Model $model + * @param Model $model * @return Model|bool */ public function save(Model $model) @@ -129,7 +129,7 @@ public function save(Model $model) /** * Attach a collection of models to the parent instance. * - * @param Collection|array $models + * @param Collection|array $models * @return Collection|array */ public function saveMany($models) @@ -144,7 +144,7 @@ public function saveMany($models) /** * Create a new instance of the related model. * - * @param array $attributes + * @param array $attributes * @return Model */ public function create(array $attributes = []) @@ -164,7 +164,7 @@ public function create(array $attributes = []) /** * Create an array of new instances of the related model. * - * @param array $records + * @param array $records * @return array */ public function createMany(array $records) @@ -181,7 +181,7 @@ public function createMany(array $records) /** * Transform single ID, single Model or array of Models into an array of IDs. * - * @param mixed $ids + * @param mixed $ids * @return array */ protected function getIdsArrayFrom($ids) @@ -236,7 +236,7 @@ protected function setEmbedded($records) /** * Get the foreign key value for the relation. * - * @param mixed $id + * @param mixed $id * @return mixed */ protected function getForeignKeyValue($id) @@ -252,7 +252,7 @@ protected function getForeignKeyValue($id) /** * Convert an array of records to a Collection. * - * @param array $records + * @param array $records * @return Collection */ protected function toCollection(array $records = []) @@ -273,7 +273,7 @@ protected function toCollection(array $records = []) /** * Create a related model instanced. * - * @param array $attributes + * @param array $attributes * @return Model */ protected function toModel($attributes = []) @@ -342,7 +342,7 @@ protected function isNested() /** * Get the fully qualified local key name. * - * @param string $glue + * @param string $glue * @return string */ protected function getPathHierarchy($glue = '.') @@ -380,7 +380,7 @@ protected function getParentKey() * Return update values. * * @param $array - * @param string $prepend + * @param string $prepend * @return array */ public static function getUpdateValues($array, $prepend = '') @@ -407,8 +407,8 @@ public function getQualifiedForeignKeyName() /** * Get the name of the "where in" method for eager loading. * - * @param \Illuminate\Database\Eloquent\Model $model - * @param string $key + * @param \Illuminate\Database\Eloquent\Model $model + * @param string $key * @return string */ protected function whereInMethod(EloquentModel $model, $key) From 226a7098c31e282dd33b539d2d9003fc4d40a7cd Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Thu, 9 Feb 2023 10:40:03 +0100 Subject: [PATCH 046/446] Add missing return types --- src/Eloquent/Model.php | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/src/Eloquent/Model.php b/src/Eloquent/Model.php index 9f8d7f90a..e12f68f82 100644 --- a/src/Eloquent/Model.php +++ b/src/Eloquent/Model.php @@ -187,7 +187,7 @@ protected function getAttributeFromArray($key) /** * @inheritdoc */ - public function setAttribute($key, $value) + public function setAttribute($key, $value): static { // Convert _id to ObjectID. if ($key == '_id' && is_string($value)) { @@ -516,13 +516,9 @@ public function __call($method, $parameters) } /** - * Add the casted attributes to the attributes array. - * - * @param array $attributes - * @param array $mutatedAttributes - * @return array + * @inheritdoc */ - protected function addCastAttributesToArray(array $attributes, array $mutatedAttributes) + protected function addCastAttributesToArray(array $attributes, array $mutatedAttributes): array { foreach ($this->getCasts() as $key => $castType) { if (! Arr::has($attributes, $key) || Arr::has($mutatedAttributes, $key)) { From 0b03010682e5041ea80177a3db2d6509da92a9a5 Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Fri, 10 Feb 2023 14:18:35 +0100 Subject: [PATCH 047/446] Report package version when establishing connection (#2507) --- src/Connection.php | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/src/Connection.php b/src/Connection.php index c78ac95c1..3a3d235ed 100644 --- a/src/Connection.php +++ b/src/Connection.php @@ -2,17 +2,22 @@ namespace Jenssegers\Mongodb; +use function class_exists; +use Composer\InstalledVersions; use Illuminate\Database\Connection as BaseConnection; use Illuminate\Support\Arr; use InvalidArgumentException; use Jenssegers\Mongodb\Concerns\ManagesTransactions; use MongoDB\Client; use MongoDB\Database; +use Throwable; class Connection extends BaseConnection { use ManagesTransactions; + private static ?string $version = null; + /** * The MongoDB database handler. * @@ -169,6 +174,11 @@ protected function createConnection($dsn, array $config, array $options): Client $driverOptions = $config['driver_options']; } + $driverOptions['driver'] = [ + 'name' => 'laravel-mongodb', + 'version' => self::getVersion(), + ]; + // Check if the credentials are not already set in the options if (! isset($options['username']) && ! empty($config['username'])) { $options['username'] = $config['username']; @@ -308,4 +318,22 @@ public function __call($method, $parameters) { return $this->db->$method(...$parameters); } + + private static function getVersion(): string + { + return self::$version ?? self::lookupVersion(); + } + + private static function lookupVersion(): string + { + if (class_exists(InstalledVersions::class)) { + try { + return self::$version = InstalledVersions::getPrettyVersion('jenssegers/laravel-mongodb'); + } catch (Throwable $t) { + // Ignore exceptions and return unknown version + } + } + + return self::$version = 'unknown'; + } } From 74d85f8194109dde4a121adcb0467b0f22223a6a Mon Sep 17 00:00:00 2001 From: Divine <48183131+divine@users.noreply.github.com> Date: Sun, 19 Feb 2023 19:31:27 +0300 Subject: [PATCH 048/446] chore: improve docker tests --- Dockerfile | 10 ++++++++-- docker-compose.yml | 14 ++++++++------ phpunit.xml.dist | 2 +- 3 files changed, 17 insertions(+), 9 deletions(-) diff --git a/Dockerfile b/Dockerfile index aa4fdb95a..d1b4c5921 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,5 +1,5 @@ -ARG PHP_VERSION=8.0 -ARG COMPOSER_VERSION=2.0 +ARG PHP_VERSION=8.1 +ARG COMPOSER_VERSION=2.5.4 FROM composer:${COMPOSER_VERSION} FROM php:${PHP_VERSION}-cli @@ -13,3 +13,9 @@ RUN apt-get update && \ COPY --from=composer /usr/bin/composer /usr/local/bin/composer WORKDIR /code + +COPY . . + +RUN composer install + +CMD ["./vendor/bin/phpunit"] diff --git a/docker-compose.yml b/docker-compose.yml index ec612f1fe..80993863e 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -3,6 +3,8 @@ version: '3' services: tests: container_name: tests + #platform: linux/arm64 + tty: true build: context: . dockerfile: Dockerfile @@ -15,9 +17,10 @@ services: mysql: container_name: mysql - image: mysql:5.7 + #platform: linux/arm64 + image: mysql:8.0 ports: - - 3306:3306 + - "3306:3306" environment: MYSQL_ROOT_PASSWORD: MYSQL_DATABASE: unittest @@ -27,8 +30,7 @@ services: mongodb: container_name: mongodb - image: mongo + #platform: linux/arm64 + image: mongo:latest ports: - - 27017:27017 - logging: - driver: none + - "27017:27017" diff --git a/phpunit.xml.dist b/phpunit.xml.dist index 9aebe0c0a..120898c08 100644 --- a/phpunit.xml.dist +++ b/phpunit.xml.dist @@ -38,7 +38,7 @@ - + From 9392c5bb218845047cc696b27e38f78487268c16 Mon Sep 17 00:00:00 2001 From: Divine <48183131+divine@users.noreply.github.com> Date: Sun, 19 Feb 2023 19:34:56 +0300 Subject: [PATCH 049/446] chore: docker remove logging driver --- docker-compose.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/docker-compose.yml b/docker-compose.yml index 80993863e..1c833bf7e 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -25,8 +25,6 @@ services: MYSQL_ROOT_PASSWORD: MYSQL_DATABASE: unittest MYSQL_ALLOW_EMPTY_PASSWORD: 'yes' - logging: - driver: none mongodb: container_name: mongodb From 83d5d3493ff37d639c4584ff20e98717b126df7c Mon Sep 17 00:00:00 2001 From: Divine <48183131+divine@users.noreply.github.com> Date: Sun, 19 Feb 2023 19:41:31 +0300 Subject: [PATCH 050/446] chore: docker improve cache --- Dockerfile | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/Dockerfile b/Dockerfile index d1b4c5921..99f5bd076 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,8 +1,5 @@ -ARG PHP_VERSION=8.1 -ARG COMPOSER_VERSION=2.5.4 - -FROM composer:${COMPOSER_VERSION} -FROM php:${PHP_VERSION}-cli +FROM composer:2.5.4 +FROM php:8.1-cli RUN apt-get update && \ apt-get install -y autoconf pkg-config libssl-dev git libzip-dev zlib1g-dev && \ @@ -14,8 +11,10 @@ COPY --from=composer /usr/bin/composer /usr/local/bin/composer WORKDIR /code -COPY . . +COPY composer.* ./ RUN composer install +COPY ./ ./ + CMD ["./vendor/bin/phpunit"] From ab2142c176e6b01cc10f65cea6d03b6660ae5844 Mon Sep 17 00:00:00 2001 From: Divine <48183131+divine@users.noreply.github.com> Date: Sun, 19 Feb 2023 19:44:08 +0300 Subject: [PATCH 051/446] chore: docker remove platform --- docker-compose.yml | 3 --- 1 file changed, 3 deletions(-) diff --git a/docker-compose.yml b/docker-compose.yml index 1c833bf7e..dab907abe 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -3,7 +3,6 @@ version: '3' services: tests: container_name: tests - #platform: linux/arm64 tty: true build: context: . @@ -17,7 +16,6 @@ services: mysql: container_name: mysql - #platform: linux/arm64 image: mysql:8.0 ports: - "3306:3306" @@ -28,7 +26,6 @@ services: mongodb: container_name: mongodb - #platform: linux/arm64 image: mongo:latest ports: - "27017:27017" From b224af5a5642bdb67531dcad5f177debea0a8fe4 Mon Sep 17 00:00:00 2001 From: Divine <48183131+divine@users.noreply.github.com> Date: Sun, 19 Feb 2023 19:47:47 +0300 Subject: [PATCH 052/446] Revert "chore: docker improve cache" This reverts commit 83d5d3493ff37d639c4584ff20e98717b126df7c. --- Dockerfile | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/Dockerfile b/Dockerfile index 99f5bd076..d1b4c5921 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,5 +1,8 @@ -FROM composer:2.5.4 -FROM php:8.1-cli +ARG PHP_VERSION=8.1 +ARG COMPOSER_VERSION=2.5.4 + +FROM composer:${COMPOSER_VERSION} +FROM php:${PHP_VERSION}-cli RUN apt-get update && \ apt-get install -y autoconf pkg-config libssl-dev git libzip-dev zlib1g-dev && \ @@ -11,10 +14,8 @@ COPY --from=composer /usr/bin/composer /usr/local/bin/composer WORKDIR /code -COPY composer.* ./ +COPY . . RUN composer install -COPY ./ ./ - CMD ["./vendor/bin/phpunit"] From 35247a0d3290e73d5d4c7d927da206665879947c Mon Sep 17 00:00:00 2001 From: Divine <48183131+divine@users.noreply.github.com> Date: Sun, 19 Feb 2023 20:04:46 +0300 Subject: [PATCH 053/446] chore: docker test move composer version --- Dockerfile | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Dockerfile b/Dockerfile index d1b4c5921..8ebf8ed7b 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,7 +1,6 @@ ARG PHP_VERSION=8.1 ARG COMPOSER_VERSION=2.5.4 -FROM composer:${COMPOSER_VERSION} FROM php:${PHP_VERSION}-cli RUN apt-get update && \ @@ -10,7 +9,7 @@ RUN apt-get update && \ pecl install xdebug && docker-php-ext-enable xdebug && \ docker-php-ext-install -j$(nproc) pdo_mysql zip -COPY --from=composer /usr/bin/composer /usr/local/bin/composer +COPY --from=composer:${COMPOSER_VERSION} /usr/bin/composer /usr/local/bin/composer WORKDIR /code From c380ce37109d9d673b6e8d74b18699b854004dd1 Mon Sep 17 00:00:00 2001 From: Divine <48183131+divine@users.noreply.github.com> Date: Sun, 19 Feb 2023 21:36:44 +0300 Subject: [PATCH 054/446] chore: docker copy cached --- Dockerfile | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/Dockerfile b/Dockerfile index 8ebf8ed7b..bd7e03a14 100644 --- a/Dockerfile +++ b/Dockerfile @@ -13,7 +13,11 @@ COPY --from=composer:${COMPOSER_VERSION} /usr/bin/composer /usr/local/bin/compos WORKDIR /code -COPY . . +COPY composer.* ./ + +RUN composer install + +COPY ./ ./ RUN composer install From 4901b5758e4b38ad60b43afcd6764cedc0c034ee Mon Sep 17 00:00:00 2001 From: Abbas mkhzomi Date: Wed, 22 Feb 2023 18:10:52 +0330 Subject: [PATCH 055/446] chore: update README.md (#2512) * Update README.md --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 59a22c12c..6a6752575 100644 --- a/README.md +++ b/README.md @@ -38,8 +38,9 @@ This package adds functionalities to the Eloquent model and Query builder for Mo - [Basic Usage](#basic-usage-2) - [Available operations](#available-operations) - [Transactions](#transactions) - - [Schema](#schema) - [Basic Usage](#basic-usage-3) + - [Schema](#schema) + - [Basic Usage](#basic-usage-4) - [Geospatial indexes](#geospatial-indexes) - [Extending](#extending) - [Cross-Database Relationships](#cross-database-relationships) @@ -1107,7 +1108,7 @@ MongoDB specific operations: All other (unsupported) operations are implemented as dummy pass-through methods because MongoDB does not use a predefined schema. -Read more about the schema builder on [Laravel Docs](https://laravel.com/docs/6.0/migrations#tables) +Read more about the schema builder on [Laravel Docs](https://laravel.com/docs/10.x/migrations#tables) ### Geospatial indexes From 7669dc2e91c05c853aab56beb1ce4819fc430253 Mon Sep 17 00:00:00 2001 From: Saulius Kazokas <9000854+saulens22@users.noreply.github.com> Date: Wed, 22 Feb 2023 16:50:55 +0200 Subject: [PATCH 056/446] Fix: remove incompatible return type (#2517) * Fix: remove incompatible return type * fix: remove return type for addCastAttributesToArray --------- Co-authored-by: Divine <48183131+divine@users.noreply.github.com> --- src/Eloquent/Model.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Eloquent/Model.php b/src/Eloquent/Model.php index e12f68f82..faab9a980 100644 --- a/src/Eloquent/Model.php +++ b/src/Eloquent/Model.php @@ -187,7 +187,7 @@ protected function getAttributeFromArray($key) /** * @inheritdoc */ - public function setAttribute($key, $value): static + public function setAttribute($key, $value) { // Convert _id to ObjectID. if ($key == '_id' && is_string($value)) { @@ -518,7 +518,7 @@ public function __call($method, $parameters) /** * @inheritdoc */ - protected function addCastAttributesToArray(array $attributes, array $mutatedAttributes): array + protected function addCastAttributesToArray(array $attributes, array $mutatedAttributes) { foreach ($this->getCasts() as $key => $castType) { if (! Arr::has($attributes, $key) || Arr::has($mutatedAttributes, $key)) { From 23c396ccddd009f106b8f9992cfa03db5fe4ddbd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Gamez?= Date: Tue, 14 Mar 2023 14:12:48 +0100 Subject: [PATCH 057/446] Fix Enums not being cast when calling `Model::toArray()` (#2522) --- src/Eloquent/Model.php | 2 +- tests/ModelTest.php | 15 +++++++++++++++ tests/models/MemberStatus.php | 6 ++++++ tests/models/User.php | 2 ++ 4 files changed, 24 insertions(+), 1 deletion(-) create mode 100644 tests/models/MemberStatus.php diff --git a/src/Eloquent/Model.php b/src/Eloquent/Model.php index faab9a980..2d938b745 100644 --- a/src/Eloquent/Model.php +++ b/src/Eloquent/Model.php @@ -556,7 +556,7 @@ protected function addCastAttributesToArray(array $attributes, array $mutatedAtt } if ($this->isEnumCastable($key) && (! $castValue instanceof Arrayable)) { - $castValue = $castValue !== null ? $this->getStorableEnumValue($attributes[$key]) : null; + $castValue = $castValue !== null ? $this->getStorableEnumValue($castValue) : null; } if ($castValue instanceof Arrayable) { diff --git a/tests/ModelTest.php b/tests/ModelTest.php index 5d94920b9..e4eeefbb4 100644 --- a/tests/ModelTest.php +++ b/tests/ModelTest.php @@ -786,4 +786,19 @@ public function testFirstOrCreate(): void $check = User::where('name', $name)->first(); $this->assertEquals($user->_id, $check->_id); } + + public function testEnumCast(): void + { + $name = 'John Member'; + + $user = new User(); + $user->name = $name; + $user->member_status = MemberStatus::Member; + $user->save(); + + /** @var User $check */ + $check = User::where('name', $name)->first(); + $this->assertSame(MemberStatus::Member->value, $check->getRawOriginal('member_status')); + $this->assertSame(MemberStatus::Member, $check->member_status); + } } diff --git a/tests/models/MemberStatus.php b/tests/models/MemberStatus.php new file mode 100644 index 000000000..0c702218e --- /dev/null +++ b/tests/models/MemberStatus.php @@ -0,0 +1,6 @@ + 'datetime', 'entry.date' => 'datetime', + 'member_status' => MemberStatus::class, ]; protected static $unguarded = true; From 1303b5fb05d1c8f06d29c55b79e3e5468c946f45 Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Thu, 16 Mar 2023 10:02:04 +0100 Subject: [PATCH 058/446] Remove duplicate use statement (#2525) --- src/Relations/BelongsToMany.php | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/Relations/BelongsToMany.php b/src/Relations/BelongsToMany.php index 2352adc50..824a45093 100644 --- a/src/Relations/BelongsToMany.php +++ b/src/Relations/BelongsToMany.php @@ -5,7 +5,6 @@ use Illuminate\Database\Eloquent\Builder; use Illuminate\Database\Eloquent\Collection; use Illuminate\Database\Eloquent\Model; -use Illuminate\Database\Eloquent\Model as EloquentModel; use Illuminate\Database\Eloquent\Relations\BelongsToMany as EloquentBelongsToMany; use Illuminate\Support\Arr; @@ -347,7 +346,7 @@ public function getRelatedKey() * @param string $key * @return string */ - protected function whereInMethod(EloquentModel $model, $key) + protected function whereInMethod(Model $model, $key) { return 'whereIn'; } From 4a10b4c86173c06edf90de35bfcc504c581c21fe Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Thu, 29 Jun 2023 10:33:52 +0200 Subject: [PATCH 059/446] PHPORM-39: Add namespace for tests directory (#2) * Skip MySQL tests if database is not available * Introduce tests namespace --- composer.json | 8 ++--- tests/AuthTest.php | 6 ++++ tests/CollectionTest.php | 2 ++ tests/ConnectionTest.php | 4 +++ tests/EmbeddedRelationsTest.php | 14 ++++++++- tests/GeospatialTest.php | 5 ++++ tests/HybridRelationsTest.php | 18 +++++++++++ tests/ModelTest.php | 10 +++++++ tests/{models => Models}/Address.php | 4 ++- tests/{models => Models}/Birthday.php | 2 ++ tests/{models => Models}/Book.php | 6 ++-- tests/{models => Models}/Client.php | 8 +++-- tests/{models => Models}/Group.php | 4 ++- tests/{models => Models}/Guarded.php | 2 ++ tests/{models => Models}/Item.php | 4 ++- tests/{models => Models}/Location.php | 2 ++ tests/{models => Models}/MemberStatus.php | 2 ++ tests/{models => Models}/MysqlBook.php | 7 +++-- tests/{models => Models}/MysqlRole.php | 9 ++++-- tests/{models => Models}/MysqlUser.php | 12 +++++--- tests/{models => Models}/Photo.php | 2 ++ tests/{models => Models}/Role.php | 6 ++-- tests/{models => Models}/Scoped.php | 2 ++ tests/{models => Models}/Soft.php | 2 ++ tests/{models => Models}/User.php | 23 +++++++------- tests/QueryBuilderTest.php | 6 ++++ tests/QueryTest.php | 6 ++++ tests/QueueTest.php | 7 ++++- tests/RelationsTest.php | 12 +++++++- tests/SchemaTest.php | 4 +++ tests/{seeds => Seeder}/DatabaseSeeder.php | 4 ++- tests/{seeds => Seeder}/UserTableSeeder.php | 2 ++ tests/SeederTest.php | 9 +++++- tests/TestCase.php | 33 +++++++++++++-------- tests/TransactionTest.php | 4 +++ tests/ValidationTest.php | 5 ++++ 36 files changed, 205 insertions(+), 51 deletions(-) rename tests/{models => Models}/Address.php (76%) rename tests/{models => Models}/Birthday.php (91%) rename tests/{models => Models}/Book.php (76%) rename tests/{models => Models}/Client.php (70%) rename tests/{models => Models}/Group.php (70%) rename tests/{models => Models}/Guarded.php (85%) rename tests/{models => Models}/Item.php (85%) rename tests/{models => Models}/Location.php (84%) rename tests/{models => Models}/MemberStatus.php (59%) rename tests/{models => Models}/MysqlBook.php (84%) rename tests/{models => Models}/MysqlRole.php (80%) rename tests/{models => Models}/MysqlUser.php (76%) rename tests/{models => Models}/Photo.php (89%) rename tests/{models => Models}/Role.php (73%) rename tests/{models => Models}/Scoped.php (91%) rename tests/{models => Models}/Soft.php (90%) rename tests/{models => Models}/User.php (75%) rename tests/{seeds => Seeder}/DatabaseSeeder.php (68%) rename tests/{seeds => Seeder}/UserTableSeeder.php (86%) diff --git a/composer.json b/composer.json index b2dba6529..fbc082a83 100644 --- a/composer.json +++ b/composer.json @@ -36,11 +36,9 @@ } }, "autoload-dev": { - "classmap": [ - "tests/TestCase.php", - "tests/models", - "tests/seeds" - ] + "psr-4": { + "Jenssegers\\Mongodb\\Tests\\": "tests/" + } }, "suggest": { "jenssegers/mongodb-session": "Add MongoDB session support to Laravel-MongoDB", diff --git a/tests/AuthTest.php b/tests/AuthTest.php index 86261696e..702257035 100644 --- a/tests/AuthTest.php +++ b/tests/AuthTest.php @@ -1,6 +1,12 @@ 'John Doe']); - /** @var \Address $address */ + /** @var Address $address */ $address = $user->addresses()->create(['city' => 'New York']); $father = $user->father()->create(['name' => 'Mark Doe']); diff --git a/tests/GeospatialTest.php b/tests/GeospatialTest.php index c86e155af..1d492d38e 100644 --- a/tests/GeospatialTest.php +++ b/tests/GeospatialTest.php @@ -2,6 +2,11 @@ declare(strict_types=1); +namespace Jenssegers\Mongodb\Tests; + +use Illuminate\Support\Facades\Schema; +use Jenssegers\Mongodb\Tests\Models\Location; + class GeospatialTest extends TestCase { public function setUp(): void diff --git a/tests/HybridRelationsTest.php b/tests/HybridRelationsTest.php index 7b4e7cdad..aa3a402b7 100644 --- a/tests/HybridRelationsTest.php +++ b/tests/HybridRelationsTest.php @@ -2,7 +2,18 @@ declare(strict_types=1); +namespace Jenssegers\Mongodb\Tests; + +use Illuminate\Database\Connection; use Illuminate\Database\MySqlConnection; +use Illuminate\Support\Facades\DB; +use Jenssegers\Mongodb\Tests\Models\Book; +use Jenssegers\Mongodb\Tests\Models\MysqlBook; +use Jenssegers\Mongodb\Tests\Models\MysqlRole; +use Jenssegers\Mongodb\Tests\Models\MysqlUser; +use Jenssegers\Mongodb\Tests\Models\Role; +use Jenssegers\Mongodb\Tests\Models\User; +use PDOException; class HybridRelationsTest extends TestCase { @@ -10,6 +21,13 @@ public function setUp(): void { parent::setUp(); + /** @var Connection */ + try { + DB::connection('mysql')->select('SELECT 1'); + } catch (PDOException) { + $this->markTestSkipped('MySQL connection is not available.'); + } + MysqlUser::executeSchema(); MysqlBook::executeSchema(); MysqlRole::executeSchema(); diff --git a/tests/ModelTest.php b/tests/ModelTest.php index e4eeefbb4..21523c7f4 100644 --- a/tests/ModelTest.php +++ b/tests/ModelTest.php @@ -2,7 +2,11 @@ declare(strict_types=1); +namespace Jenssegers\Mongodb\Tests; + use Carbon\Carbon; +use DateTime; +use DateTimeImmutable; use Illuminate\Database\Eloquent\Collection as EloquentCollection; use Illuminate\Database\Eloquent\ModelNotFoundException; use Illuminate\Support\Facades\Date; @@ -10,6 +14,12 @@ use Jenssegers\Mongodb\Collection; use Jenssegers\Mongodb\Connection; use Jenssegers\Mongodb\Eloquent\Model; +use Jenssegers\Mongodb\Tests\Models\Book; +use Jenssegers\Mongodb\Tests\Models\Guarded; +use Jenssegers\Mongodb\Tests\Models\Item; +use Jenssegers\Mongodb\Tests\Models\MemberStatus; +use Jenssegers\Mongodb\Tests\Models\Soft; +use Jenssegers\Mongodb\Tests\Models\User; use MongoDB\BSON\ObjectID; use MongoDB\BSON\UTCDateTime; diff --git a/tests/models/Address.php b/tests/Models/Address.php similarity index 76% rename from tests/models/Address.php rename to tests/Models/Address.php index 5e12ddbb7..1050eb0e8 100644 --- a/tests/models/Address.php +++ b/tests/Models/Address.php @@ -2,6 +2,8 @@ declare(strict_types=1); +namespace Jenssegers\Mongodb\Tests\Models; + use Jenssegers\Mongodb\Eloquent\Model as Eloquent; use Jenssegers\Mongodb\Relations\EmbedsMany; @@ -12,6 +14,6 @@ class Address extends Eloquent public function addresses(): EmbedsMany { - return $this->embedsMany('Address'); + return $this->embedsMany(self::class); } } diff --git a/tests/models/Birthday.php b/tests/Models/Birthday.php similarity index 91% rename from tests/models/Birthday.php rename to tests/Models/Birthday.php index 3e725e495..2afca41e0 100644 --- a/tests/models/Birthday.php +++ b/tests/Models/Birthday.php @@ -2,6 +2,8 @@ declare(strict_types=1); +namespace Jenssegers\Mongodb\Tests\Models; + use Jenssegers\Mongodb\Eloquent\Model as Eloquent; /** diff --git a/tests/models/Book.php b/tests/Models/Book.php similarity index 76% rename from tests/models/Book.php rename to tests/Models/Book.php index e247abbfb..74eb8ee09 100644 --- a/tests/models/Book.php +++ b/tests/Models/Book.php @@ -2,6 +2,8 @@ declare(strict_types=1); +namespace Jenssegers\Mongodb\Tests\Models; + use Illuminate\Database\Eloquent\Relations\BelongsTo; use Jenssegers\Mongodb\Eloquent\Model as Eloquent; @@ -21,11 +23,11 @@ class Book extends Eloquent public function author(): BelongsTo { - return $this->belongsTo('User', 'author_id'); + return $this->belongsTo(User::class, 'author_id'); } public function mysqlAuthor(): BelongsTo { - return $this->belongsTo('MysqlUser', 'author_id'); + return $this->belongsTo(MysqlUser::class, 'author_id'); } } diff --git a/tests/models/Client.php b/tests/Models/Client.php similarity index 70% rename from tests/models/Client.php rename to tests/Models/Client.php index 65c5d81a0..0ccc5451f 100644 --- a/tests/models/Client.php +++ b/tests/Models/Client.php @@ -2,6 +2,8 @@ declare(strict_types=1); +namespace Jenssegers\Mongodb\Tests\Models; + use Illuminate\Database\Eloquent\Relations\BelongsToMany; use Illuminate\Database\Eloquent\Relations\HasMany; use Illuminate\Database\Eloquent\Relations\MorphOne; @@ -15,16 +17,16 @@ class Client extends Eloquent public function users(): BelongsToMany { - return $this->belongsToMany('User'); + return $this->belongsToMany(User::class); } public function photo(): MorphOne { - return $this->morphOne('Photo', 'has_image'); + return $this->morphOne(Photo::class, 'has_image'); } public function addresses(): HasMany { - return $this->hasMany('Address', 'data.client_id', 'data.client_id'); + return $this->hasMany(Address::class, 'data.client_id', 'data.client_id'); } } diff --git a/tests/models/Group.php b/tests/Models/Group.php similarity index 70% rename from tests/models/Group.php rename to tests/Models/Group.php index bf4edd9bc..8631dbfc8 100644 --- a/tests/models/Group.php +++ b/tests/Models/Group.php @@ -2,6 +2,8 @@ declare(strict_types=1); +namespace Jenssegers\Mongodb\Tests\Models; + use Illuminate\Database\Eloquent\Relations\BelongsToMany; use Jenssegers\Mongodb\Eloquent\Model as Eloquent; @@ -13,6 +15,6 @@ class Group extends Eloquent public function users(): BelongsToMany { - return $this->belongsToMany('User', 'users', 'groups', 'users', '_id', '_id', 'users'); + return $this->belongsToMany(User::class, 'users', 'groups', 'users', '_id', '_id', 'users'); } } diff --git a/tests/models/Guarded.php b/tests/Models/Guarded.php similarity index 85% rename from tests/models/Guarded.php rename to tests/Models/Guarded.php index 8438867e9..8b838b1f4 100644 --- a/tests/models/Guarded.php +++ b/tests/Models/Guarded.php @@ -2,6 +2,8 @@ declare(strict_types=1); +namespace Jenssegers\Mongodb\Tests\Models; + use Jenssegers\Mongodb\Eloquent\Model as Eloquent; class Guarded extends Eloquent diff --git a/tests/models/Item.php b/tests/Models/Item.php similarity index 85% rename from tests/models/Item.php rename to tests/Models/Item.php index 4a29aa05a..eb9d5b882 100644 --- a/tests/models/Item.php +++ b/tests/Models/Item.php @@ -2,6 +2,8 @@ declare(strict_types=1); +namespace Jenssegers\Mongodb\Tests\Models; + use Illuminate\Database\Eloquent\Relations\BelongsTo; use Jenssegers\Mongodb\Eloquent\Builder; use Jenssegers\Mongodb\Eloquent\Model as Eloquent; @@ -19,7 +21,7 @@ class Item extends Eloquent public function user(): BelongsTo { - return $this->belongsTo('User'); + return $this->belongsTo(User::class); } public function scopeSharp(Builder $query) diff --git a/tests/models/Location.php b/tests/Models/Location.php similarity index 84% rename from tests/models/Location.php rename to tests/Models/Location.php index 9ecaff37a..c1fbc94cd 100644 --- a/tests/models/Location.php +++ b/tests/Models/Location.php @@ -2,6 +2,8 @@ declare(strict_types=1); +namespace Jenssegers\Mongodb\Tests\Models; + use Jenssegers\Mongodb\Eloquent\Model as Eloquent; class Location extends Eloquent diff --git a/tests/models/MemberStatus.php b/tests/Models/MemberStatus.php similarity index 59% rename from tests/models/MemberStatus.php rename to tests/Models/MemberStatus.php index 0c702218e..5dde2263e 100644 --- a/tests/models/MemberStatus.php +++ b/tests/Models/MemberStatus.php @@ -1,5 +1,7 @@ belongsTo('User', 'author_id'); + return $this->belongsTo(User::class, 'author_id'); } /** diff --git a/tests/models/MysqlRole.php b/tests/Models/MysqlRole.php similarity index 80% rename from tests/models/MysqlRole.php rename to tests/Models/MysqlRole.php index a8a490d76..7637f31f0 100644 --- a/tests/models/MysqlRole.php +++ b/tests/Models/MysqlRole.php @@ -2,12 +2,15 @@ declare(strict_types=1); +namespace Jenssegers\Mongodb\Tests\Models; + +use Illuminate\Database\Eloquent\Model as EloquentModel; use Illuminate\Database\Eloquent\Relations\BelongsTo; use Illuminate\Database\Schema\Blueprint; use Illuminate\Support\Facades\Schema; use Jenssegers\Mongodb\Eloquent\HybridRelations; -class MysqlRole extends Eloquent +class MysqlRole extends EloquentModel { use HybridRelations; @@ -17,12 +20,12 @@ class MysqlRole extends Eloquent public function user(): BelongsTo { - return $this->belongsTo('User'); + return $this->belongsTo(User::class); } public function mysqlUser(): BelongsTo { - return $this->belongsTo('MysqlUser'); + return $this->belongsTo(MysqlUser::class); } /** diff --git a/tests/models/MysqlUser.php b/tests/Models/MysqlUser.php similarity index 76% rename from tests/models/MysqlUser.php rename to tests/Models/MysqlUser.php index 8c1393fd5..35929faa5 100644 --- a/tests/models/MysqlUser.php +++ b/tests/Models/MysqlUser.php @@ -2,13 +2,17 @@ declare(strict_types=1); +namespace Jenssegers\Mongodb\Tests\Models; + +use Illuminate\Database\Eloquent\Model as EloquentModel; use Illuminate\Database\Eloquent\Relations\HasMany; use Illuminate\Database\Eloquent\Relations\HasOne; use Illuminate\Database\Schema\Blueprint; +use Illuminate\Database\Schema\MySqlBuilder; use Illuminate\Support\Facades\Schema; use Jenssegers\Mongodb\Eloquent\HybridRelations; -class MysqlUser extends Eloquent +class MysqlUser extends EloquentModel { use HybridRelations; @@ -18,12 +22,12 @@ class MysqlUser extends Eloquent public function books(): HasMany { - return $this->hasMany('Book', 'author_id'); + return $this->hasMany(Book::class, 'author_id'); } public function role(): HasOne { - return $this->hasOne('Role'); + return $this->hasOne(Role::class); } public function mysqlBooks(): HasMany @@ -36,7 +40,7 @@ public function mysqlBooks(): HasMany */ public static function executeSchema(): void { - /** @var \Illuminate\Database\Schema\MySqlBuilder $schema */ + /** @var MySqlBuilder $schema */ $schema = Schema::connection('mysql'); if (! $schema->hasTable('users')) { diff --git a/tests/models/Photo.php b/tests/Models/Photo.php similarity index 89% rename from tests/models/Photo.php rename to tests/Models/Photo.php index 05c06d443..068f3c56c 100644 --- a/tests/models/Photo.php +++ b/tests/Models/Photo.php @@ -2,6 +2,8 @@ declare(strict_types=1); +namespace Jenssegers\Mongodb\Tests\Models; + use Illuminate\Database\Eloquent\Relations\MorphTo; use Jenssegers\Mongodb\Eloquent\Model as Eloquent; diff --git a/tests/models/Role.php b/tests/Models/Role.php similarity index 73% rename from tests/models/Role.php rename to tests/Models/Role.php index 6c8684ecf..6c7eea3d5 100644 --- a/tests/models/Role.php +++ b/tests/Models/Role.php @@ -2,6 +2,8 @@ declare(strict_types=1); +namespace Jenssegers\Mongodb\Tests\Models; + use Illuminate\Database\Eloquent\Relations\BelongsTo; use Jenssegers\Mongodb\Eloquent\Model as Eloquent; @@ -13,11 +15,11 @@ class Role extends Eloquent public function user(): BelongsTo { - return $this->belongsTo('User'); + return $this->belongsTo(User::class); } public function mysqlUser(): BelongsTo { - return $this->belongsTo('MysqlUser'); + return $this->belongsTo(MysqlUser::class); } } diff --git a/tests/models/Scoped.php b/tests/Models/Scoped.php similarity index 91% rename from tests/models/Scoped.php rename to tests/Models/Scoped.php index f94246414..09138753a 100644 --- a/tests/models/Scoped.php +++ b/tests/Models/Scoped.php @@ -2,6 +2,8 @@ declare(strict_types=1); +namespace Jenssegers\Mongodb\Tests\Models; + use Jenssegers\Mongodb\Eloquent\Builder; use Jenssegers\Mongodb\Eloquent\Model as Eloquent; diff --git a/tests/models/Soft.php b/tests/Models/Soft.php similarity index 90% rename from tests/models/Soft.php rename to tests/Models/Soft.php index 30711e61d..6315ac0c0 100644 --- a/tests/models/Soft.php +++ b/tests/Models/Soft.php @@ -2,6 +2,8 @@ declare(strict_types=1); +namespace Jenssegers\Mongodb\Tests\Models; + use Jenssegers\Mongodb\Eloquent\Model as Eloquent; use Jenssegers\Mongodb\Eloquent\SoftDeletes; diff --git a/tests/models/User.php b/tests/Models/User.php similarity index 75% rename from tests/models/User.php rename to tests/Models/User.php index d32d1f8b4..f559af470 100644 --- a/tests/models/User.php +++ b/tests/Models/User.php @@ -2,6 +2,9 @@ declare(strict_types=1); +namespace Jenssegers\Mongodb\Tests\Models; + +use DateTimeInterface; use Illuminate\Auth\Authenticatable; use Illuminate\Auth\Passwords\CanResetPassword; use Illuminate\Contracts\Auth\Authenticatable as AuthenticatableContract; @@ -43,52 +46,52 @@ class User extends Eloquent implements AuthenticatableContract, CanResetPassword public function books() { - return $this->hasMany('Book', 'author_id'); + return $this->hasMany(Book::class, 'author_id'); } public function mysqlBooks() { - return $this->hasMany('MysqlBook', 'author_id'); + return $this->hasMany(MysqlBook::class, 'author_id'); } public function items() { - return $this->hasMany('Item'); + return $this->hasMany(Item::class); } public function role() { - return $this->hasOne('Role'); + return $this->hasOne(Role::class); } public function mysqlRole() { - return $this->hasOne('MysqlRole'); + return $this->hasOne(MysqlRole::class); } public function clients() { - return $this->belongsToMany('Client'); + return $this->belongsToMany(Client::class); } public function groups() { - return $this->belongsToMany('Group', 'groups', 'users', 'groups', '_id', '_id', 'groups'); + return $this->belongsToMany(Group::class, 'groups', 'users', 'groups', '_id', '_id', 'groups'); } public function photos() { - return $this->morphMany('Photo', 'has_image'); + return $this->morphMany(Photo::class, 'has_image'); } public function addresses() { - return $this->embedsMany('Address'); + return $this->embedsMany(Address::class); } public function father() { - return $this->embedsOne('User'); + return $this->embedsOne(self::class); } protected function serializeDate(DateTimeInterface $date) diff --git a/tests/QueryBuilderTest.php b/tests/QueryBuilderTest.php index 235784829..9cb3af405 100644 --- a/tests/QueryBuilderTest.php +++ b/tests/QueryBuilderTest.php @@ -2,12 +2,18 @@ declare(strict_types=1); +namespace Jenssegers\Mongodb\Tests; + +use DateTime; +use DateTimeImmutable; use Illuminate\Support\Facades\Date; use Illuminate\Support\Facades\DB; use Illuminate\Support\LazyCollection; use Illuminate\Testing\Assert; use Jenssegers\Mongodb\Collection; use Jenssegers\Mongodb\Query\Builder; +use Jenssegers\Mongodb\Tests\Models\Item; +use Jenssegers\Mongodb\Tests\Models\User; use MongoDB\BSON\ObjectId; use MongoDB\BSON\Regex; use MongoDB\BSON\UTCDateTime; diff --git a/tests/QueryTest.php b/tests/QueryTest.php index c85cd2a21..4179748d0 100644 --- a/tests/QueryTest.php +++ b/tests/QueryTest.php @@ -2,6 +2,12 @@ declare(strict_types=1); +namespace Jenssegers\Mongodb\Tests; + +use Jenssegers\Mongodb\Tests\Models\Birthday; +use Jenssegers\Mongodb\Tests\Models\Scoped; +use Jenssegers\Mongodb\Tests\Models\User; + class QueryTest extends TestCase { protected static $started = false; diff --git a/tests/QueueTest.php b/tests/QueueTest.php index a0bcbc17d..601d712ae 100644 --- a/tests/QueueTest.php +++ b/tests/QueueTest.php @@ -2,10 +2,15 @@ declare(strict_types=1); +namespace Jenssegers\Mongodb\Tests; + use Carbon\Carbon; +use Illuminate\Support\Facades\Config; +use Illuminate\Support\Facades\Queue; use Illuminate\Support\Str; use Jenssegers\Mongodb\Queue\Failed\MongoFailedJobProvider; use Jenssegers\Mongodb\Queue\MongoQueue; +use Mockery; class QueueTest extends TestCase { @@ -31,7 +36,7 @@ public function testQueueJobLifeCycle(): void // Get and reserve the test job (next available) $job = Queue::pop('test'); - $this->assertInstanceOf(Jenssegers\Mongodb\Queue\MongoJob::class, $job); + $this->assertInstanceOf(\Jenssegers\Mongodb\Queue\MongoJob::class, $job); $this->assertEquals(1, $job->isReserved()); $this->assertEquals(json_encode([ 'uuid' => $uuid, diff --git a/tests/RelationsTest.php b/tests/RelationsTest.php index b1b73e6cc..66c27583f 100644 --- a/tests/RelationsTest.php +++ b/tests/RelationsTest.php @@ -2,7 +2,18 @@ declare(strict_types=1); +namespace Jenssegers\Mongodb\Tests; + use Illuminate\Database\Eloquent\Collection; +use Jenssegers\Mongodb\Tests\Models\Address; +use Jenssegers\Mongodb\Tests\Models\Book; +use Jenssegers\Mongodb\Tests\Models\Client; +use Jenssegers\Mongodb\Tests\Models\Group; +use Jenssegers\Mongodb\Tests\Models\Item; +use Jenssegers\Mongodb\Tests\Models\Photo; +use Jenssegers\Mongodb\Tests\Models\Role; +use Jenssegers\Mongodb\Tests\Models\User; +use Mockery; class RelationsTest extends TestCase { @@ -16,7 +27,6 @@ public function tearDown(): void Book::truncate(); Item::truncate(); Role::truncate(); - Client::truncate(); Group::truncate(); Photo::truncate(); } diff --git a/tests/SchemaTest.php b/tests/SchemaTest.php index fdad70e22..4e820e58a 100644 --- a/tests/SchemaTest.php +++ b/tests/SchemaTest.php @@ -2,6 +2,10 @@ declare(strict_types=1); +namespace Jenssegers\Mongodb\Tests; + +use Illuminate\Support\Facades\DB; +use Illuminate\Support\Facades\Schema; use Jenssegers\Mongodb\Schema\Blueprint; class SchemaTest extends TestCase diff --git a/tests/seeds/DatabaseSeeder.php b/tests/Seeder/DatabaseSeeder.php similarity index 68% rename from tests/seeds/DatabaseSeeder.php rename to tests/Seeder/DatabaseSeeder.php index dbd6172f4..a5d7c940f 100644 --- a/tests/seeds/DatabaseSeeder.php +++ b/tests/Seeder/DatabaseSeeder.php @@ -1,5 +1,7 @@ call('UserTableSeeder'); + $this->call(UserTableSeeder::class); } } diff --git a/tests/seeds/UserTableSeeder.php b/tests/Seeder/UserTableSeeder.php similarity index 86% rename from tests/seeds/UserTableSeeder.php rename to tests/Seeder/UserTableSeeder.php index 9f053bedc..95f1331e3 100644 --- a/tests/seeds/UserTableSeeder.php +++ b/tests/Seeder/UserTableSeeder.php @@ -1,5 +1,7 @@ DatabaseSeeder::class]); $user = User::where('name', 'John Doe')->first(); $this->assertTrue($user->seed); diff --git a/tests/TestCase.php b/tests/TestCase.php index dbe8c97c0..51121d528 100644 --- a/tests/TestCase.php +++ b/tests/TestCase.php @@ -2,21 +2,30 @@ declare(strict_types=1); -use Illuminate\Auth\Passwords\PasswordResetServiceProvider; +namespace Jenssegers\Mongodb\Tests; -class TestCase extends Orchestra\Testbench\TestCase +use Illuminate\Auth\Passwords\PasswordResetServiceProvider as BasePasswordResetServiceProviderAlias; +use Illuminate\Foundation\Application; +use Jenssegers\Mongodb\Auth\PasswordResetServiceProvider; +use Jenssegers\Mongodb\MongodbQueueServiceProvider; +use Jenssegers\Mongodb\MongodbServiceProvider; +use Jenssegers\Mongodb\Tests\Models\User; +use Jenssegers\Mongodb\Validation\ValidationServiceProvider; +use Orchestra\Testbench\TestCase as OrchestraTestCase; + +class TestCase extends OrchestraTestCase { /** * Get application providers. * - * @param \Illuminate\Foundation\Application $app + * @param Application $app * @return array */ protected function getApplicationProviders($app) { $providers = parent::getApplicationProviders($app); - unset($providers[array_search(PasswordResetServiceProvider::class, $providers)]); + unset($providers[array_search(BasePasswordResetServiceProviderAlias::class, $providers)]); return $providers; } @@ -24,23 +33,23 @@ protected function getApplicationProviders($app) /** * Get package providers. * - * @param \Illuminate\Foundation\Application $app + * @param Application $app * @return array */ protected function getPackageProviders($app) { return [ - Jenssegers\Mongodb\MongodbServiceProvider::class, - Jenssegers\Mongodb\MongodbQueueServiceProvider::class, - Jenssegers\Mongodb\Auth\PasswordResetServiceProvider::class, - Jenssegers\Mongodb\Validation\ValidationServiceProvider::class, + MongodbServiceProvider::class, + MongodbQueueServiceProvider::class, + PasswordResetServiceProvider::class, + ValidationServiceProvider::class, ]; } /** * Define environment setup. * - * @param Illuminate\Foundation\Application $app + * @param Application $app * @return void */ protected function getEnvironmentSetUp($app) @@ -57,8 +66,8 @@ protected function getEnvironmentSetUp($app) $app['config']->set('database.connections.mongodb', $config['connections']['mongodb']); $app['config']->set('database.connections.mongodb2', $config['connections']['mongodb']); - $app['config']->set('auth.model', 'User'); - $app['config']->set('auth.providers.users.model', 'User'); + $app['config']->set('auth.model', User::class); + $app['config']->set('auth.providers.users.model', User::class); $app['config']->set('cache.driver', 'array'); $app['config']->set('queue.default', 'database'); diff --git a/tests/TransactionTest.php b/tests/TransactionTest.php index 52ce422a7..46fbf2e2a 100644 --- a/tests/TransactionTest.php +++ b/tests/TransactionTest.php @@ -1,11 +1,15 @@ Date: Thu, 29 Jun 2023 12:58:51 +0200 Subject: [PATCH 060/446] Add classes to cast ObjectId and UUID instances (#1) --- src/Eloquent/Casts/BinaryUuid.php | 63 +++++++++++++++++++++++++++++++ src/Eloquent/Casts/ObjectId.php | 46 ++++++++++++++++++++++ tests/Casts/BinaryUuidTest.php | 48 +++++++++++++++++++++++ tests/Casts/ObjectIdTest.php | 50 ++++++++++++++++++++++++ tests/Models/CastBinaryUuid.php | 17 +++++++++ tests/Models/CastObjectId.php | 17 +++++++++ 6 files changed, 241 insertions(+) create mode 100644 src/Eloquent/Casts/BinaryUuid.php create mode 100644 src/Eloquent/Casts/ObjectId.php create mode 100644 tests/Casts/BinaryUuidTest.php create mode 100644 tests/Casts/ObjectIdTest.php create mode 100644 tests/Models/CastBinaryUuid.php create mode 100644 tests/Models/CastObjectId.php diff --git a/src/Eloquent/Casts/BinaryUuid.php b/src/Eloquent/Casts/BinaryUuid.php new file mode 100644 index 000000000..1ca9d407a --- /dev/null +++ b/src/Eloquent/Casts/BinaryUuid.php @@ -0,0 +1,63 @@ +getType() !== Binary::TYPE_UUID) { + return $value; + } + + $base16Uuid = bin2hex($value->getData()); + + return sprintf( + '%s-%s-%s-%s-%s', + substr($base16Uuid, 0, 8), + substr($base16Uuid, 8, 4), + substr($base16Uuid, 12, 4), + substr($base16Uuid, 16, 4), + substr($base16Uuid, 20, 12), + ); + } + + /** + * Prepare the given value for storage. + * + * @param Model $model + * @param string $key + * @param mixed $value + * @param array $attributes + * @return mixed + */ + public function set($model, string $key, $value, array $attributes) + { + if ($value instanceof Binary) { + return $value; + } + + if (is_string($value) && strlen($value) === 16) { + return new Binary($value, Binary::TYPE_UUID); + } + + return new Binary(hex2bin(str_replace('-', '', $value)), Binary::TYPE_UUID); + } +} diff --git a/src/Eloquent/Casts/ObjectId.php b/src/Eloquent/Casts/ObjectId.php new file mode 100644 index 000000000..bf34bea2f --- /dev/null +++ b/src/Eloquent/Casts/ObjectId.php @@ -0,0 +1,46 @@ + $saveUuid]); + + $model = CastBinaryUuid::firstWhere('uuid', $queryUuid); + $this->assertNotNull($model); + $this->assertSame($expectedUuid, $model->uuid); + } + + public static function provideBinaryUuidCast(): Generator + { + $uuid = '0c103357-3806-48c9-a84b-867dcb625cfb'; + $binaryUuid = new Binary(hex2bin('0c103357380648c9a84b867dcb625cfb'), Binary::TYPE_UUID); + + yield 'Save Binary, Query Binary' => [$uuid, $binaryUuid, $binaryUuid]; + yield 'Save string, Query Binary' => [$uuid, $uuid, $binaryUuid]; + } + + public function testQueryByStringDoesNotCast(): void + { + $uuid = '0c103357-3806-48c9-a84b-867dcb625cfb'; + + CastBinaryUuid::create(['uuid' => $uuid]); + + $model = CastBinaryUuid::firstWhere('uuid', $uuid); + $this->assertNull($model); + } +} diff --git a/tests/Casts/ObjectIdTest.php b/tests/Casts/ObjectIdTest.php new file mode 100644 index 000000000..d9f385543 --- /dev/null +++ b/tests/Casts/ObjectIdTest.php @@ -0,0 +1,50 @@ + $saveObjectId]); + + $model = CastObjectId::firstWhere('oid', $queryObjectId); + $this->assertNotNull($model); + $this->assertSame($stringObjectId, $model->oid); + } + + public static function provideObjectIdCast(): Generator + { + $objectId = new ObjectId(); + $stringObjectId = (string) $objectId; + + yield 'Save ObjectId, Query ObjectId' => [$objectId, $objectId]; + yield 'Save string, Query ObjectId' => [$stringObjectId, $objectId]; + } + + public function testQueryByStringDoesNotCast(): void + { + $objectId = new ObjectId(); + $stringObjectId = (string) $objectId; + + CastObjectId::create(['oid' => $objectId]); + + $model = CastObjectId::firstWhere('oid', $stringObjectId); + $this->assertNull($model); + } +} diff --git a/tests/Models/CastBinaryUuid.php b/tests/Models/CastBinaryUuid.php new file mode 100644 index 000000000..cb8aa5537 --- /dev/null +++ b/tests/Models/CastBinaryUuid.php @@ -0,0 +1,17 @@ + BinaryUuid::class, + ]; +} diff --git a/tests/Models/CastObjectId.php b/tests/Models/CastObjectId.php new file mode 100644 index 000000000..0c82cb9f8 --- /dev/null +++ b/tests/Models/CastObjectId.php @@ -0,0 +1,17 @@ + ObjectId::class, + ]; +} From 19cf7a2ee2c0f2c69459952c4207ee8279b818d3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 11 Jul 2023 17:19:19 +0200 Subject: [PATCH 061/446] PHPORM-44: Throw an exception when Query\Builder::push() is used incorrectly (#5) --- src/Query/Builder.php | 5 ++++- tests/QueryBuilderTest.php | 8 ++++++++ 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 066412734..1f707e9b3 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -786,9 +786,12 @@ public function push($column, $value = null, $unique = false) $operator = $unique ? '$addToSet' : '$push'; // Check if we are pushing multiple values. - $batch = (is_array($value) && array_keys($value) === range(0, count($value) - 1)); + $batch = is_array($value) && array_is_list($value); if (is_array($column)) { + if ($value !== null) { + throw new \InvalidArgumentException(sprintf('2nd argument of %s() must be "null" when 1st argument is an array. Got "%s" instead.', __METHOD__, get_debug_type($value))); + } $query = [$operator => $column]; } elseif ($batch) { $query = [$operator => [$column => ['$each' => $value]]]; diff --git a/tests/QueryBuilderTest.php b/tests/QueryBuilderTest.php index 9cb3af405..92c1bbe75 100644 --- a/tests/QueryBuilderTest.php +++ b/tests/QueryBuilderTest.php @@ -345,6 +345,14 @@ public function testPush() $this->assertCount(3, $user['messages']); } + public function testPushRefuses2ndArgumentWhen1stIsAnArray() + { + $this->expectException(\InvalidArgumentException::class); + $this->expectExceptionMessage('2nd argument of Jenssegers\Mongodb\Query\Builder::push() must be "null" when 1st argument is an array. Got "string" instead.'); + + DB::collection('users')->push(['tags' => 'tag1'], 'tag2'); + } + public function testPull() { $message1 = ['from' => 'Jane', 'body' => 'Hi John']; From ae3e0d5f72c24edcb2a78d321910397f4134e90f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 12 Jul 2023 13:56:04 +0200 Subject: [PATCH 062/446] PHPORM-45 Add Query\Builder::toMql() to simplify comprehensive query tests (#6) * PHPORM-45 Add Query\Builder::toMql() to simplify comprehensive query tests * Move Query/Builder unit tests to a dedicated test class --- composer.json | 1 + src/Query/Builder.php | 132 +++++++++++++++++++----------------- tests/Query/BuilderTest.php | 85 +++++++++++++++++++++++ tests/QueryBuilderTest.php | 5 +- 4 files changed, 158 insertions(+), 65 deletions(-) create mode 100644 tests/Query/BuilderTest.php diff --git a/composer.json b/composer.json index fbc082a83..58bfb3c65 100644 --- a/composer.json +++ b/composer.json @@ -19,6 +19,7 @@ ], "license": "MIT", "require": { + "ext-mongodb": "^1.15", "illuminate/support": "^10.0", "illuminate/container": "^10.0", "illuminate/database": "^10.0", diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 1f707e9b3..893de033d 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -15,6 +15,7 @@ use MongoDB\BSON\ObjectID; use MongoDB\BSON\Regex; use MongoDB\BSON\UTCDateTime; +use MongoDB\Driver\Cursor; use RuntimeException; /** @@ -215,27 +216,21 @@ public function cursor($columns = []) } /** - * Execute the query as a fresh "select" statement. + * Return the MongoDB query to be run in the form of an element array like ['method' => [arguments]]. * - * @param array $columns - * @param bool $returnLazy - * @return array|static[]|Collection|LazyCollection + * Example: ['find' => [['name' => 'John Doe'], ['projection' => ['birthday' => 1]]]] + * + * @return array */ - public function getFresh($columns = [], $returnLazy = false) + public function toMql(): array { - // If no columns have been specified for the select statement, we will set them - // here to either the passed columns, or the standard default of retrieving - // all of the columns on the table using the "wildcard" column character. - if ($this->columns === null) { - $this->columns = $columns; - } + $columns = $this->columns ?? []; // Drop all columns if * is present, MongoDB does not work this way. - if (in_array('*', $this->columns)) { - $this->columns = []; + if (in_array('*', $columns)) { + $columns = []; } - // Compile wheres $wheres = $this->compileWheres(); // Use MongoDB's aggregation framework when using grouping or aggregation functions. @@ -254,7 +249,7 @@ public function getFresh($columns = [], $returnLazy = false) } // Do the same for other columns that are selected. - foreach ($this->columns as $column) { + foreach ($columns as $column) { $key = str_replace('.', '_', $column); $group[$key] = ['$last' => '$'.$column]; @@ -274,26 +269,10 @@ public function getFresh($columns = [], $returnLazy = false) $column = implode('.', $splitColumns); } - // Null coalense only > 7.2 - $aggregations = blank($this->aggregate['columns']) ? [] : $this->aggregate['columns']; if (in_array('*', $aggregations) && $function == 'count') { - // When ORM is paginating, count doesnt need a aggregation, just a cursor operation - // elseif added to use this only in pagination - // https://docs.mongodb.com/manual/reference/method/cursor.count/ - // count method returns int - - $totalResults = $this->collection->count($wheres); - // Preserving format expected by framework - $results = [ - [ - '_id' => null, - 'aggregate' => $totalResults, - ], - ]; - - return new Collection($results); + return ['count' => [$wheres, []]]; } elseif ($function == 'count') { // Translate count into sum. $group['aggregate'] = ['$sum' => 1]; @@ -348,34 +327,23 @@ public function getFresh($columns = [], $returnLazy = false) $options = $this->inheritConnectionOptions($options); - // Execute aggregation - $results = iterator_to_array($this->collection->aggregate($pipeline, $options)); - - // Return results - return new Collection($results); + return ['aggregate' => [$pipeline, $options]]; } // Distinct query elseif ($this->distinct) { // Return distinct results directly - $column = isset($this->columns[0]) ? $this->columns[0] : '_id'; + $column = isset($columns[0]) ? $columns[0] : '_id'; $options = $this->inheritConnectionOptions(); - // Execute distinct - $result = $this->collection->distinct($column, $wheres ?: [], $options); - - return new Collection($result); + return ['distinct' => [$column, $wheres ?: [], $options]]; } // Normal query else { - $columns = []; - // Convert select columns to simple projections. - foreach ($this->columns as $column) { - $columns[$column] = true; - } + $projection = array_fill_keys($columns, true); // Add custom projections. if ($this->projections) { - $columns = array_merge($columns, $this->projections); + $projection = array_merge($projection, $this->projections); } $options = []; @@ -395,8 +363,8 @@ public function getFresh($columns = [], $returnLazy = false) if ($this->hint) { $options['hint'] = $this->hint; } - if ($columns) { - $options['projection'] = $columns; + if ($projection) { + $options['projection'] = $projection; } // Fix for legacy support, converts the results to arrays instead of objects. @@ -409,22 +377,62 @@ public function getFresh($columns = [], $returnLazy = false) $options = $this->inheritConnectionOptions($options); - // Execute query and get MongoCursor - $cursor = $this->collection->find($wheres, $options); + return ['find' => [$wheres, $options]]; + } + } - if ($returnLazy) { - return LazyCollection::make(function () use ($cursor) { - foreach ($cursor as $item) { - yield $item; - } - }); - } + /** + * Execute the query as a fresh "select" statement. + * + * @param array $columns + * @param bool $returnLazy + * @return array|static[]|Collection|LazyCollection + */ + public function getFresh($columns = [], $returnLazy = false) + { + // If no columns have been specified for the select statement, we will set them + // here to either the passed columns, or the standard default of retrieving + // all of the columns on the table using the "wildcard" column character. + if ($this->columns === null) { + $this->columns = $columns; + } + + // Drop all columns if * is present, MongoDB does not work this way. + if (in_array('*', $this->columns)) { + $this->columns = []; + } + + $command = $this->toMql($columns); + assert(count($command) >= 1, 'At least one method call is required to execute a query'); + + $result = $this->collection; + foreach ($command as $method => $arguments) { + $result = call_user_func_array([$result, $method], $arguments); + } + + // countDocuments method returns int, wrap it to the format expected by the framework + if (is_int($result)) { + $result = [ + [ + '_id' => null, + 'aggregate' => $result, + ], + ]; + } - // Return results as an array with numeric keys - $results = iterator_to_array($cursor, false); + if ($returnLazy) { + return LazyCollection::make(function () use ($result) { + foreach ($result as $item) { + yield $item; + } + }); + } - return new Collection($results); + if ($result instanceof Cursor) { + $result = $result->toArray(); } + + return new Collection($result); } /** diff --git a/tests/Query/BuilderTest.php b/tests/Query/BuilderTest.php new file mode 100644 index 000000000..17ce184b5 --- /dev/null +++ b/tests/Query/BuilderTest.php @@ -0,0 +1,85 @@ +assertInstanceOf(Builder::class, $builder); + $mql = $builder->toMql(); + + // Operations that return a Cursor expect a "typeMap" option. + if (isset($expected['find'][1])) { + $expected['find'][1]['typeMap'] = ['root' => 'array', 'document' => 'array']; + } + if (isset($expected['aggregate'][1])) { + $expected['aggregate'][1]['typeMap'] = ['root' => 'array', 'document' => 'array']; + } + + // Compare with assertEquals because the query can contain BSON objects. + $this->assertEquals($expected, $mql, var_export($mql, true)); + } + + public static function provideQueryBuilderToMql(): iterable + { + /** + * Builder::aggregate() and Builder::count() cannot be tested because they return the result, + * without modifying the builder. + */ + $date = new DateTimeImmutable('2016-07-12 15:30:00'); + + yield 'find' => [ + ['find' => [['foo' => 'bar'], []]], + fn (Builder $builder) => $builder->where('foo', 'bar'), + ]; + + yield 'find > date' => [ + ['find' => [['foo' => ['$gt' => new UTCDateTime($date)]], []]], + fn (Builder $builder) => $builder->where('foo', '>', $date), + ]; + + yield 'find in array' => [ + ['find' => [['foo' => ['$in' => ['bar', 'baz']]], []]], + fn (Builder $builder) => $builder->whereIn('foo', ['bar', 'baz']), + ]; + + yield 'find limit offset select' => [ + ['find' => [[], ['limit' => 10, 'skip' => 5, 'projection' => ['foo' => 1, 'bar' => 1]]]], + fn (Builder $builder) => $builder->limit(10)->offset(5)->select('foo', 'bar'), + ]; + + yield 'distinct' => [ + ['distinct' => ['foo', [], []]], + fn (Builder $builder) => $builder->distinct('foo'), + ]; + + yield 'groupBy' => [ + ['aggregate' => [[['$group' => ['_id' => ['foo' => '$foo'], 'foo' => ['$last' => '$foo']]]], []]], + fn (Builder $builder) => $builder->groupBy('foo'), + ]; + } + + private static function getBuilder(): Builder + { + $connection = m::mock(Connection::class); + $processor = m::mock(Processor::class); + $connection->shouldReceive('getSession')->andReturn(null); + + return new Builder($connection, $processor); + } +} diff --git a/tests/QueryBuilderTest.php b/tests/QueryBuilderTest.php index 92c1bbe75..d2356d2f3 100644 --- a/tests/QueryBuilderTest.php +++ b/tests/QueryBuilderTest.php @@ -144,8 +144,7 @@ public function testFindWithTimeout() { $id = DB::collection('users')->insertGetId(['name' => 'John Doe']); - $subscriber = new class implements CommandSubscriber - { + $subscriber = new class implements CommandSubscriber { public function commandStarted(CommandStartedEvent $event) { if ($event->getCommandName() !== 'find') { @@ -830,7 +829,7 @@ public function testValue() public function testHintOptions() { DB::collection('items')->insert([ - ['name' => 'fork', 'tags' => ['sharp', 'pointy']], + ['name' => 'fork', 'tags' => ['sharp', 'pointy']], ['name' => 'spork', 'tags' => ['sharp', 'pointy', 'round', 'bowl']], ['name' => 'spoon', 'tags' => ['round', 'bowl']], ]); From 933073df63be4e9566f48f82991fae319bd51d54 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 12 Jul 2023 13:59:05 +0200 Subject: [PATCH 063/446] Create UTCDateTime from DateTimeInterface objects (#8) --- src/Auth/DatabaseTokenRepository.php | 2 +- src/Eloquent/Model.php | 2 +- src/Query/Builder.php | 8 ++++---- tests/QueryBuilderTest.php | 16 ++++++++-------- 4 files changed, 14 insertions(+), 14 deletions(-) diff --git a/src/Auth/DatabaseTokenRepository.php b/src/Auth/DatabaseTokenRepository.php index cf0f89ea1..4574cf615 100644 --- a/src/Auth/DatabaseTokenRepository.php +++ b/src/Auth/DatabaseTokenRepository.php @@ -18,7 +18,7 @@ protected function getPayload($email, $token) return [ 'email' => $email, 'token' => $this->hasher->make($token), - 'created_at' => new UTCDateTime(Date::now()->format('Uv')), + 'created_at' => new UTCDateTime(Date::now()), ]; } diff --git a/src/Eloquent/Model.php b/src/Eloquent/Model.php index 2d938b745..2d985f627 100644 --- a/src/Eloquent/Model.php +++ b/src/Eloquent/Model.php @@ -134,7 +134,7 @@ public function getDateFormat() */ public function freshTimestamp() { - return new UTCDateTime(Date::now()->format('Uv')); + return new UTCDateTime(Date::now()); } /** diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 893de033d..22d933fea 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -882,7 +882,7 @@ protected function performUpdate($query, array $options = []) $options = $this->inheritConnectionOptions($options); $wheres = $this->compileWheres(); - $result = $this->collection->UpdateMany($wheres, $query, $options); + $result = $this->collection->updateMany($wheres, $query, $options); if (1 == (int) $result->isAcknowledged()) { return $result->getModifiedCount() ? $result->getModifiedCount() : $result->getUpsertedCount(); } @@ -981,18 +981,18 @@ protected function compileWheres(): array if (is_array($where['value'])) { array_walk_recursive($where['value'], function (&$item, $key) { if ($item instanceof DateTimeInterface) { - $item = new UTCDateTime($item->format('Uv')); + $item = new UTCDateTime($item); } }); } else { if ($where['value'] instanceof DateTimeInterface) { - $where['value'] = new UTCDateTime($where['value']->format('Uv')); + $where['value'] = new UTCDateTime($where['value']); } } } elseif (isset($where['values'])) { array_walk_recursive($where['values'], function (&$item, $key) { if ($item instanceof DateTimeInterface) { - $item = new UTCDateTime($item->format('Uv')); + $item = new UTCDateTime($item); } }); } diff --git a/tests/QueryBuilderTest.php b/tests/QueryBuilderTest.php index d2356d2f3..5dbc67cc2 100644 --- a/tests/QueryBuilderTest.php +++ b/tests/QueryBuilderTest.php @@ -600,19 +600,19 @@ public function testUpdateSubdocument() public function testDates() { DB::collection('users')->insert([ - ['name' => 'John Doe', 'birthday' => new UTCDateTime(Date::parse('1980-01-01 00:00:00')->format('Uv'))], - ['name' => 'Robert Roe', 'birthday' => new UTCDateTime(Date::parse('1982-01-01 00:00:00')->format('Uv'))], - ['name' => 'Mark Moe', 'birthday' => new UTCDateTime(Date::parse('1983-01-01 00:00:00.1')->format('Uv'))], - ['name' => 'Frank White', 'birthday' => new UTCDateTime(Date::parse('1960-01-01 12:12:12.1')->format('Uv'))], + ['name' => 'John Doe', 'birthday' => new UTCDateTime(Date::parse('1980-01-01 00:00:00'))], + ['name' => 'Robert Roe', 'birthday' => new UTCDateTime(Date::parse('1982-01-01 00:00:00'))], + ['name' => 'Mark Moe', 'birthday' => new UTCDateTime(Date::parse('1983-01-01 00:00:00.1'))], + ['name' => 'Frank White', 'birthday' => new UTCDateTime(Date::parse('1960-01-01 12:12:12.1'))], ]); $user = DB::collection('users') - ->where('birthday', new UTCDateTime(Date::parse('1980-01-01 00:00:00')->format('Uv'))) + ->where('birthday', new UTCDateTime(Date::parse('1980-01-01 00:00:00'))) ->first(); $this->assertEquals('John Doe', $user['name']); $user = DB::collection('users') - ->where('birthday', new UTCDateTime(Date::parse('1960-01-01 12:12:12.1')->format('Uv'))) + ->where('birthday', new UTCDateTime(Date::parse('1960-01-01 12:12:12.1'))) ->first(); $this->assertEquals('Frank White', $user['name']); @@ -629,8 +629,8 @@ public function testDates() public function testImmutableDates() { DB::collection('users')->insert([ - ['name' => 'John Doe', 'birthday' => new UTCDateTime(Date::parse('1980-01-01 00:00:00')->format('Uv'))], - ['name' => 'Robert Roe', 'birthday' => new UTCDateTime(Date::parse('1982-01-01 00:00:00')->format('Uv'))], + ['name' => 'John Doe', 'birthday' => new UTCDateTime(Date::parse('1980-01-01 00:00:00'))], + ['name' => 'Robert Roe', 'birthday' => new UTCDateTime(Date::parse('1982-01-01 00:00:00'))], ]); $users = DB::collection('users')->where('birthday', '=', new DateTimeImmutable('1980-01-01 00:00:00'))->get(); From edd08715a0dd64bab9fd1194e70fface09e02900 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 12 Jul 2023 14:54:16 +0200 Subject: [PATCH 064/446] PHPORM-46 Throw an exception when Query\Builder::orderBy() is used with invalid direction (#7) * Convert only strings, let the driver fail for int values * Add more tests on Builder::orderBy --- src/Query/Builder.php | 7 +++- tests/Query/BuilderTest.php | 82 +++++++++++++++++++++++++++++++++++++ 2 files changed, 88 insertions(+), 1 deletion(-) diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 22d933fea..78aabffeb 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -513,11 +513,16 @@ public function distinct($column = false) /** * @inheritdoc + * @param int|string|array $direction */ public function orderBy($column, $direction = 'asc') { if (is_string($direction)) { - $direction = (strtolower($direction) == 'asc' ? 1 : -1); + $direction = match ($direction) { + 'asc', 'ASC' => 1, + 'desc', 'DESC' => -1, + default => throw new \InvalidArgumentException('Order direction must be "asc" or "desc".'), + }; } if ($column == 'natural') { diff --git a/tests/Query/BuilderTest.php b/tests/Query/BuilderTest.php index 17ce184b5..b06a89f8e 100644 --- a/tests/Query/BuilderTest.php +++ b/tests/Query/BuilderTest.php @@ -5,6 +5,7 @@ namespace Jenssegers\Mongodb\Tests\Query; use DateTimeImmutable; +use Illuminate\Tests\Database\DatabaseQueryBuilderTest; use Jenssegers\Mongodb\Connection; use Jenssegers\Mongodb\Query\Builder; use Jenssegers\Mongodb\Query\Processor; @@ -63,6 +64,66 @@ public static function provideQueryBuilderToMql(): iterable fn (Builder $builder) => $builder->limit(10)->offset(5)->select('foo', 'bar'), ]; + /** @see DatabaseQueryBuilderTest::testOrderBys() */ + yield 'orderBy multiple columns' => [ + ['find' => [[], ['sort' => ['email' => 1, 'age' => -1]]]], + fn (Builder $builder) => $builder + ->orderBy('email') + ->orderBy('age', 'desc'), + ]; + + yield 'orders = null' => [ + ['find' => [[], []]], + function (Builder $builder) { + $builder->orders = null; + + return $builder; + }, + ]; + + yield 'orders = []' => [ + ['find' => [[], []]], + function (Builder $builder) { + $builder->orders = []; + + return $builder; + }, + ]; + + yield 'multiple orders with direction' => [ + ['find' => [[], ['sort' => ['email' => -1, 'age' => 1]]]], + fn (Builder $builder) => $builder + ->orderBy('email', -1) + ->orderBy('age', 1), + ]; + + yield 'orderByDesc' => [ + ['find' => [[], ['sort' => ['email' => -1]]]], + fn (Builder $builder) => $builder->orderByDesc('email'), + ]; + + /** @see DatabaseQueryBuilderTest::testReorder() */ + yield 'reorder reset' => [ + ['find' => [[], []]], + fn (Builder $builder) => $builder->orderBy('name')->reorder(), + ]; + + yield 'reorder column' => [ + ['find' => [[], ['sort' => ['name' => -1]]]], + fn (Builder $builder) => $builder->orderBy('name')->reorder('name', 'desc'), + ]; + + /** @link https://www.mongodb.com/docs/manual/reference/method/cursor.sort/#text-score-metadata-sort */ + yield 'orderBy array meta' => [ + ['find' => [ + ['$text' => ['$search' => 'operating']], + ['sort' => ['score' => ['$meta' => 'textScore']]], + ]], + fn (Builder $builder) => $builder + ->where('$text', ['$search' => 'operating']) + ->orderBy('score', ['$meta' => 'textScore']), + ]; + yield 'distinct' => [ ['distinct' => ['foo', [], []]], fn (Builder $builder) => $builder->distinct('foo'), @@ -74,6 +135,27 @@ public static function provideQueryBuilderToMql(): iterable ]; } + /** + * @dataProvider provideExceptions + */ + public function testException($class, $message, \Closure $build): void + { + $builder = self::getBuilder(); + + $this->expectException($class); + $this->expectExceptionMessage($message); + $build($builder); + } + + public static function provideExceptions(): iterable + { + yield 'orderBy invalid direction' => [ + \InvalidArgumentException::class, + 'Order direction must be "asc" or "desc"', + fn (Builder $builder) => $builder->orderBy('_id', 'dasc'), + ]; + } + private static function getBuilder(): Builder { $connection = m::mock(Connection::class); From e1a83f47f16054286bc433fc9ccfee078bb40741 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 12 Jul 2023 20:28:49 +0200 Subject: [PATCH 065/446] PHPORM-51 Throw an exception when unsupported query builder method is used (#9) --- src/Query/Builder.php | 66 +++++++++++++++++++++++++++++++++++++ tests/Query/BuilderTest.php | 46 ++++++++++++++++++++++++++ 2 files changed, 112 insertions(+) diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 78aabffeb..0e6a8266f 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -1303,4 +1303,70 @@ public function __call($method, $parameters) return parent::__call($method, $parameters); } + + /** @internal This method is not supported by MongoDB. */ + public function toSql() + { + throw new \BadMethodCallException('This method is not supported by MongoDB. Try "toMql()" instead.'); + } + + /** @internal This method is not supported by MongoDB. */ + public function toRawSql() + { + throw new \BadMethodCallException('This method is not supported by MongoDB. Try "toMql()" instead.'); + } + + /** @internal This method is not supported by MongoDB. */ + public function whereColumn($first, $operator = null, $second = null, $boolean = 'and') + { + throw new \BadMethodCallException('This method is not supported by MongoDB'); + } + + /** @internal This method is not supported by MongoDB. */ + public function whereFullText($columns, $value, array $options = [], $boolean = 'and') + { + throw new \BadMethodCallException('This method is not supported by MongoDB'); + } + + /** @internal This method is not supported by MongoDB. */ + public function groupByRaw($sql, array $bindings = []) + { + throw new \BadMethodCallException('This method is not supported by MongoDB'); + } + + /** @internal This method is not supported by MongoDB. */ + public function orderByRaw($sql, $bindings = []) + { + throw new \BadMethodCallException('This method is not supported by MongoDB'); + } + + /** @internal This method is not supported by MongoDB. */ + public function unionAll($query) + { + throw new \BadMethodCallException('This method is not supported by MongoDB'); + } + + /** @internal This method is not supported by MongoDB. */ + public function union($query, $all = false) + { + throw new \BadMethodCallException('This method is not supported by MongoDB'); + } + + /** @internal This method is not supported by MongoDB. */ + public function having($column, $operator = null, $value = null, $boolean = 'and') + { + throw new \BadMethodCallException('This method is not supported by MongoDB'); + } + + /** @internal This method is not supported by MongoDB. */ + public function havingRaw($sql, array $bindings = [], $boolean = 'and') + { + throw new \BadMethodCallException('This method is not supported by MongoDB'); + } + + /** @internal This method is not supported by MongoDB. */ + public function havingBetween($column, iterable $values, $boolean = 'and', $not = false) + { + throw new \BadMethodCallException('This method is not supported by MongoDB'); + } } diff --git a/tests/Query/BuilderTest.php b/tests/Query/BuilderTest.php index b06a89f8e..f7d12ad4a 100644 --- a/tests/Query/BuilderTest.php +++ b/tests/Query/BuilderTest.php @@ -156,6 +156,52 @@ public static function provideExceptions(): iterable ]; } + /** @dataProvider getEloquentMethodsNotSupported */ + public function testEloquentMethodsNotSupported(\Closure $callback) + { + $builder = self::getBuilder(); + + $this->expectException(\BadMethodCallException::class); + $this->expectExceptionMessage('This method is not supported by MongoDB'); + + $callback($builder); + } + + public static function getEloquentMethodsNotSupported() + { + // Most of this methods can be implemented using aggregation framework + // whereInRaw, whereNotInRaw, orWhereInRaw, orWhereNotInRaw, whereBetweenColumns + + yield 'toSql' => [fn (Builder $builder) => $builder->toSql()]; + yield 'toRawSql' => [fn (Builder $builder) => $builder->toRawSql()]; + + /** @see DatabaseQueryBuilderTest::testBasicWhereColumn() */ + /** @see DatabaseQueryBuilderTest::testArrayWhereColumn() */ + yield 'whereColumn' => [fn (Builder $builder) => $builder->whereColumn('first_name', 'last_name')]; + yield 'orWhereColumn' => [fn (Builder $builder) => $builder->orWhereColumn('first_name', 'last_name')]; + + /** @see DatabaseQueryBuilderTest::testWhereFulltextMySql() */ + yield 'whereFulltext' => [fn (Builder $builder) => $builder->whereFulltext('body', 'Hello World')]; + + /** @see DatabaseQueryBuilderTest::testGroupBys() */ + yield 'groupByRaw' => [fn (Builder $builder) => $builder->groupByRaw('DATE(created_at)')]; + + /** @see DatabaseQueryBuilderTest::testOrderBys() */ + yield 'orderByRaw' => [fn (Builder $builder) => $builder->orderByRaw('"age" ? desc', ['foo'])]; + + /** @see DatabaseQueryBuilderTest::testInRandomOrderMySql */ + yield 'inRandomOrder' => [fn (Builder $builder) => $builder->inRandomOrder()]; + + yield 'union' => [fn (Builder $builder) => $builder->union($builder)]; + yield 'unionAll' => [fn (Builder $builder) => $builder->unionAll($builder)]; + + /** @see DatabaseQueryBuilderTest::testRawHavings */ + yield 'havingRaw' => [fn (Builder $builder) => $builder->havingRaw('user_foo < user_bar')]; + yield 'having' => [fn (Builder $builder) => $builder->having('baz', '=', 1)]; + yield 'havingBetween' => [fn (Builder $builder) => $builder->havingBetween('last_login_date', ['2018-11-16', '2018-12-16'])]; + yield 'orHavingRaw' => [fn (Builder $builder) => $builder->orHavingRaw('user_foo < user_bar')]; + } + private static function getBuilder(): Builder { $connection = m::mock(Connection::class); From cfbff5c940ad26e88c6c6e11aea0349651d37e4f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Thu, 13 Jul 2023 08:41:07 +0200 Subject: [PATCH 066/446] Optimize calls to debug_backtrace (#11) --- src/Eloquent/EmbedsRelations.php | 8 ++------ src/Eloquent/HybridRelations.php | 8 ++------ 2 files changed, 4 insertions(+), 12 deletions(-) diff --git a/src/Eloquent/EmbedsRelations.php b/src/Eloquent/EmbedsRelations.php index 9e5f77d92..95231a542 100644 --- a/src/Eloquent/EmbedsRelations.php +++ b/src/Eloquent/EmbedsRelations.php @@ -23,9 +23,7 @@ protected function embedsMany($related, $localKey = null, $foreignKey = null, $r // the calling method's name and use that as the relationship name as most // of the time this will be what we desire to use for the relationships. if ($relation === null) { - [, $caller] = debug_backtrace(false); - - $relation = $caller['function']; + $relation = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2)[1]['function']; } if ($localKey === null) { @@ -58,9 +56,7 @@ protected function embedsOne($related, $localKey = null, $foreignKey = null, $re // the calling method's name and use that as the relationship name as most // of the time this will be what we desire to use for the relationships. if ($relation === null) { - [, $caller] = debug_backtrace(false); - - $relation = $caller['function']; + $relation = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2)[1]['function']; } if ($localKey === null) { diff --git a/src/Eloquent/HybridRelations.php b/src/Eloquent/HybridRelations.php index 0818ca3ee..398d26f81 100644 --- a/src/Eloquent/HybridRelations.php +++ b/src/Eloquent/HybridRelations.php @@ -134,9 +134,7 @@ public function belongsTo($related, $foreignKey = null, $otherKey = null, $relat // the calling method's name and use that as the relationship name as most // of the time this will be what we desire to use for the relationships. if ($relation === null) { - [$current, $caller] = debug_backtrace(false, 2); - - $relation = $caller['function']; + $relation = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2)[1]['function']; } // Check if it is a relation with an original model. @@ -178,9 +176,7 @@ public function morphTo($name = null, $type = null, $id = null, $ownerKey = null // since that is most likely the name of the polymorphic interface. We can // use that to get both the class and foreign key that will be utilized. if ($name === null) { - [$current, $caller] = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2); - - $name = $caller['function']; + $name = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2)[1]['function']; } [$type, $id] = $this->getMorphs(Str::snake($name), $type, $id); From f90bf78f6b56d02848d39a9c7043e1dcfdd36168 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Thu, 13 Jul 2023 11:33:08 +0200 Subject: [PATCH 067/446] Add header documentation for classes & traits that can be used in applications (#12) * Add header documentation for classes & traits that can be used in applications * Precise mixed types when possible --- src/Collection.php | 3 +++ src/Connection.php | 3 +++ src/Eloquent/Casts/BinaryUuid.php | 2 +- src/Eloquent/EmbedsRelations.php | 3 +++ src/Eloquent/HybridRelations.php | 4 ++++ src/Query/Builder.php | 14 +++++++------- 6 files changed, 21 insertions(+), 8 deletions(-) diff --git a/src/Collection.php b/src/Collection.php index 3980e8de6..ac1c09f74 100644 --- a/src/Collection.php +++ b/src/Collection.php @@ -6,6 +6,9 @@ use MongoDB\BSON\ObjectID; use MongoDB\Collection as MongoCollection; +/** + * @mixin MongoCollection + */ class Collection { /** diff --git a/src/Connection.php b/src/Connection.php index 3a3d235ed..278642081 100644 --- a/src/Connection.php +++ b/src/Connection.php @@ -12,6 +12,9 @@ use MongoDB\Database; use Throwable; +/** + * @mixin Database + */ class Connection extends BaseConnection { use ManagesTransactions; diff --git a/src/Eloquent/Casts/BinaryUuid.php b/src/Eloquent/Casts/BinaryUuid.php index 1ca9d407a..8c8628f76 100644 --- a/src/Eloquent/Casts/BinaryUuid.php +++ b/src/Eloquent/Casts/BinaryUuid.php @@ -46,7 +46,7 @@ public function get($model, string $key, $value, array $attributes) * @param string $key * @param mixed $value * @param array $attributes - * @return mixed + * @return Binary */ public function set($model, string $key, $value, array $attributes) { diff --git a/src/Eloquent/EmbedsRelations.php b/src/Eloquent/EmbedsRelations.php index 95231a542..cd921d603 100644 --- a/src/Eloquent/EmbedsRelations.php +++ b/src/Eloquent/EmbedsRelations.php @@ -6,6 +6,9 @@ use Jenssegers\Mongodb\Relations\EmbedsMany; use Jenssegers\Mongodb\Relations\EmbedsOne; +/** + * Embeds relations for MongoDB models. + */ trait EmbedsRelations { /** diff --git a/src/Eloquent/HybridRelations.php b/src/Eloquent/HybridRelations.php index 398d26f81..bb544f9ae 100644 --- a/src/Eloquent/HybridRelations.php +++ b/src/Eloquent/HybridRelations.php @@ -12,6 +12,10 @@ use Jenssegers\Mongodb\Relations\MorphMany; use Jenssegers\Mongodb\Relations\MorphTo; +/** + * Cross-database relationships between SQL and MongoDB. + * Use this trait in SQL models to define relationships with MongoDB models. + */ trait HybridRelations { /** diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 0e6a8266f..b5141a080 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -788,9 +788,9 @@ public function raw($expression = null) /** * Append one or more values to an array. * - * @param mixed $column - * @param mixed $value - * @param bool $unique + * @param string|array $column + * @param mixed $value + * @param bool $unique * @return int */ public function push($column, $value = null, $unique = false) @@ -818,14 +818,14 @@ public function push($column, $value = null, $unique = false) /** * Remove one or more values from an array. * - * @param mixed $column - * @param mixed $value + * @param string|array $column + * @param mixed $value * @return int */ public function pull($column, $value = null) { // Check if we passed an associative array. - $batch = (is_array($value) && array_keys($value) === range(0, count($value) - 1)); + $batch = is_array($value) && array_is_list($value); // If we are pulling multiple values, we need to use $pullAll. $operator = $batch ? '$pullAll' : '$pull'; @@ -842,7 +842,7 @@ public function pull($column, $value = null) /** * Remove one or more fields. * - * @param mixed $columns + * @param string|string[] $columns * @return int */ public function drop($columns) From f729baad59b4baf3307121df7f60c5cd03a504f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 19 Jul 2023 10:39:18 +0200 Subject: [PATCH 068/446] PHPORM-47 Improve Builder::whereBetween to support CarbonPeriod and reject invalid array (#10) The Query\Builder::whereBetween() method can be used like this: whereBetween('date_field', [min, max]) whereBetween('date_field', collect([min, max])) whereBetween('date_field', CarbonPeriod) Laravel allows other formats: the $values array is flatten and the builder assumes there are at least 2 elements and ignore the others. It's a design that can lead to misunderstandings. I prefer to raise an exception when we have incorrect values, rather than trying to guess what the developer would like to do. Support for CarbonPeriod was fixed in Laravel 10: laravel/framework#46720 because the query builder was taking the 1st 2 values of the iterator instead of the start & end dates. --- src/Query/Builder.php | 27 ++++-- tests/Query/BuilderTest.php | 163 +++++++++++++++++++++++++++++++++++- 2 files changed, 184 insertions(+), 6 deletions(-) diff --git a/src/Query/Builder.php b/src/Query/Builder.php index b5141a080..b6924bb47 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -2,6 +2,7 @@ namespace Jenssegers\Mongodb\Query; +use Carbon\CarbonPeriod; use Closure; use DateTimeInterface; use Illuminate\Database\Query\Builder as BaseBuilder; @@ -554,11 +555,20 @@ public function whereAll($column, array $values, $boolean = 'and', $not = false) /** * @inheritdoc + * @param list{mixed, mixed}|CarbonPeriod $values */ public function whereBetween($column, iterable $values, $boolean = 'and', $not = false) { $type = 'between'; + if ($values instanceof Collection) { + $values = $values->all(); + } + + if (is_array($values) && (! array_is_list($values) || count($values) !== 2)) { + throw new \InvalidArgumentException('Between $values must be a list with exactly two elements: [min, max]'); + } + $this->wheres[] = compact('column', 'type', 'boolean', 'values', 'not'); return $this; @@ -995,11 +1005,18 @@ protected function compileWheres(): array } } } elseif (isset($where['values'])) { - array_walk_recursive($where['values'], function (&$item, $key) { - if ($item instanceof DateTimeInterface) { - $item = new UTCDateTime($item); - } - }); + if (is_array($where['values'])) { + array_walk_recursive($where['values'], function (&$item, $key) { + if ($item instanceof DateTimeInterface) { + $item = new UTCDateTime($item); + } + }); + } elseif ($where['values'] instanceof CarbonPeriod) { + $where['values'] = [ + new UTCDateTime($where['values']->getStartDate()), + new UTCDateTime($where['values']->getEndDate()), + ]; + } } // The next item in a "chain" of wheres devices the boolean of the diff --git a/tests/Query/BuilderTest.php b/tests/Query/BuilderTest.php index f7d12ad4a..f600fa73a 100644 --- a/tests/Query/BuilderTest.php +++ b/tests/Query/BuilderTest.php @@ -5,6 +5,7 @@ namespace Jenssegers\Mongodb\Tests\Query; use DateTimeImmutable; +use Illuminate\Database\Eloquent\Collection; use Illuminate\Tests\Database\DatabaseQueryBuilderTest; use Jenssegers\Mongodb\Connection; use Jenssegers\Mongodb\Query\Builder; @@ -124,13 +125,142 @@ function (Builder $builder) { ->orderBy('score', ['$meta' => 'textScore']), ]; + /** @see DatabaseQueryBuilderTest::testWhereBetweens() */ + yield 'whereBetween array of numbers' => [ + ['find' => [['id' => ['$gte' => 1, '$lte' => 2]], []]], + fn (Builder $builder) => $builder->whereBetween('id', [1, 2]), + ]; + + yield 'whereBetween nested array of numbers' => [ + ['find' => [['id' => ['$gte' => [1], '$lte' => [2, 3]]], []]], + fn (Builder $builder) => $builder->whereBetween('id', [[1], [2, 3]]), + ]; + + $period = now()->toPeriod(now()->addMonth()); + yield 'whereBetween CarbonPeriod' => [ + ['find' => [ + ['created_at' => ['$gte' => new UTCDateTime($period->start), '$lte' => new UTCDateTime($period->end)]], + [], // options + ]], + fn (Builder $builder) => $builder->whereBetween('created_at', $period), + ]; + + yield 'whereBetween collection' => [ + ['find' => [['id' => ['$gte' => 1, '$lte' => 2]], []]], + fn (Builder $builder) => $builder->whereBetween('id', collect([1, 2])), + ]; + + /** @see DatabaseQueryBuilderTest::testOrWhereBetween() */ + yield 'orWhereBetween array of numbers' => [ + ['find' => [ + ['$or' => [ + ['id' => 1], + ['id' => ['$gte' => 3, '$lte' => 5]], + ]], + [], // options + ]], + fn (Builder $builder) => $builder + ->where('id', '=', 1) + ->orWhereBetween('id', [3, 5]), + ]; + + /** @link https://www.mongodb.com/docs/manual/reference/bson-type-comparison-order/#arrays */ + yield 'orWhereBetween nested array of numbers' => [ + ['find' => [ + ['$or' => [ + ['id' => 1], + ['id' => ['$gte' => [4], '$lte' => [6, 8]]], + ]], + [], // options + ]], + fn (Builder $builder) => $builder + ->where('id', '=', 1) + ->orWhereBetween('id', [[4], [6, 8]]), + ]; + + yield 'orWhereBetween collection' => [ + ['find' => [ + ['$or' => [ + ['id' => 1], + ['id' => ['$gte' => 3, '$lte' => 4]], + ]], + [], // options + ]], + fn (Builder $builder) => $builder + ->where('id', '=', 1) + ->orWhereBetween('id', collect([3, 4])), + ]; + + yield 'whereNotBetween array of numbers' => [ + ['find' => [ + ['$or' => [ + ['id' => ['$lte' => 1]], + ['id' => ['$gte' => 2]], + ]], + [], // options + ]], + fn (Builder $builder) => $builder->whereNotBetween('id', [1, 2]), + ]; + + /** @see DatabaseQueryBuilderTest::testOrWhereNotBetween() */ + yield 'orWhereNotBetween array of numbers' => [ + ['find' => [ + ['$or' => [ + ['id' => 1], + ['$or' => [ + ['id' => ['$lte' => 3]], + ['id' => ['$gte' => 5]], + ]], + ]], + [], // options + ]], + fn (Builder $builder) => $builder + ->where('id', '=', 1) + ->orWhereNotBetween('id', [3, 5]), + ]; + + yield 'orWhereNotBetween nested array of numbers' => [ + ['find' => [ + ['$or' => [ + ['id' => 1], + ['$or' => [ + ['id' => ['$lte' => [2, 3]]], + ['id' => ['$gte' => [5]]], + ]], + ]], + [], // options + ]], + fn (Builder $builder) => $builder + ->where('id', '=', 1) + ->orWhereNotBetween('id', [[2, 3], [5]]), + ]; + + yield 'orWhereNotBetween collection' => [ + ['find' => [ + ['$or' => [ + ['id' => 1], + ['$or' => [ + ['id' => ['$lte' => 3]], + ['id' => ['$gte' => 4]], + ]], + ]], + [], // options + ]], + fn (Builder $builder) => $builder + ->where('id', '=', 1) + ->orWhereNotBetween('id', collect([3, 4])), + ]; + yield 'distinct' => [ ['distinct' => ['foo', [], []]], fn (Builder $builder) => $builder->distinct('foo'), ]; yield 'groupBy' => [ - ['aggregate' => [[['$group' => ['_id' => ['foo' => '$foo'], 'foo' => ['$last' => '$foo']]]], []]], + ['aggregate' => [ + [['$group' => ['_id' => ['foo' => '$foo'], 'foo' => ['$last' => '$foo']]]], + [], // options + ]], fn (Builder $builder) => $builder->groupBy('foo'), ]; } @@ -154,6 +284,37 @@ public static function provideExceptions(): iterable 'Order direction must be "asc" or "desc"', fn (Builder $builder) => $builder->orderBy('_id', 'dasc'), ]; + + /** @see DatabaseQueryBuilderTest::testWhereBetweens */ + yield 'whereBetween array too short' => [ + \InvalidArgumentException::class, + 'Between $values must be a list with exactly two elements: [min, max]', + fn (Builder $builder) => $builder->whereBetween('id', [1]), + ]; + + yield 'whereBetween array too short (nested)' => [ + \InvalidArgumentException::class, + 'Between $values must be a list with exactly two elements: [min, max]', + fn (Builder $builder) => $builder->whereBetween('id', [[1, 2]]), + ]; + + yield 'whereBetween array too long' => [ + \InvalidArgumentException::class, + 'Between $values must be a list with exactly two elements: [min, max]', + fn (Builder $builder) => $builder->whereBetween('id', [1, 2, 3]), + ]; + + yield 'whereBetween collection too long' => [ + \InvalidArgumentException::class, + 'Between $values must be a list with exactly two elements: [min, max]', + fn (Builder $builder) => $builder->whereBetween('id', new Collection([1, 2, 3])), + ]; + + yield 'whereBetween array is not a list' => [ + \InvalidArgumentException::class, + 'Between $values must be a list with exactly two elements: [min, max]', + fn (Builder $builder) => $builder->whereBetween('id', ['min' => 1, 'max' => 2]), + ]; } /** @dataProvider getEloquentMethodsNotSupported */ From 78527786d7fe0b295c452aae74d5091c627c607b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 19 Jul 2023 22:12:08 +0200 Subject: [PATCH 069/446] PHPORM-49 Implement `Query\Builder::whereNot` by encapsulating into `$not` (#13) `Query\Builder::whereNot` was simply ignoring the "not" and breaking the built query. --- CHANGELOG.md | 10 +- README.md | 6 ++ src/Query/Builder.php | 19 ++-- tests/Query/BuilderTest.php | 182 ++++++++++++++++++++++++++++++++++++ 4 files changed, 210 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b1018c1cb..04b823816 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,9 +3,17 @@ All notable changes to this project will be documented in this file. ## [Unreleased] +- Add classes to cast ObjectId and UUID instances [#1](https://github.com/GromNaN/laravel-mongodb-private/pull/1) by [@alcaeus](https://github.com/alcaeus). +- Add `Query\Builder::toMql()` to simplify comprehensive query tests [#6](https://github.com/GromNaN/laravel-mongodb-private/pull/6) by [@GromNaN](https://github.com/GromNaN). +- Fix `Query\Builder::whereNot` to use MongoDB [`$not`](https://www.mongodb.com/docs/manual/reference/operator/query/not/) operator [#13](https://github.com/GromNaN/laravel-mongodb-private/pull/13) by [@GromNaN](https://github.com/GromNaN). +- Fix `Query\Builder::whereBetween` to accept `Carbon\Period` object [#10](https://github.com/GromNaN/laravel-mongodb-private/pull/10) by [@GromNaN](https://github.com/GromNaN). +- Throw an exception for unsupported `Query\Builder` methods [#9](https://github.com/GromNaN/laravel-mongodb-private/pull/9) by [@GromNaN](https://github.com/GromNaN). +- Throw an exception when `Query\Builder::orderBy()` is used with invalid direction [#7](https://github.com/GromNaN/laravel-mongodb-private/pull/7) by [@GromNaN](https://github.com/GromNaN). +- Throw an exception when `Query\Builder::push()` is used incorrectly [#5](https://github.com/GromNaN/laravel-mongodb-private/pull/5) by [@GromNaN](https://github.com/GromNaN). + ## [3.9.2] - 2022-09-01 -### Addded +### Added - Add single word name mutators [#2438](https://github.com/jenssegers/laravel-mongodb/pull/2438) by [@RosemaryOrchard](https://github.com/RosemaryOrchard) & [@mrneatly](https://github.com/mrneatly). ### Fixed diff --git a/README.md b/README.md index 6a6752575..71e7768e5 100644 --- a/README.md +++ b/README.md @@ -332,6 +332,12 @@ $users = ->get(); ``` +**NOT statements** + +```php +$users = User::whereNot('age', '>', 18)->get(); +``` + **whereIn** ```php diff --git a/src/Query/Builder.php b/src/Query/Builder.php index b6924bb47..4db2b5a91 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -1019,19 +1019,26 @@ protected function compileWheres(): array } } - // The next item in a "chain" of wheres devices the boolean of the - // first item. So if we see that there are multiple wheres, we will - // use the operator of the next where. - if ($i == 0 && count($wheres) > 1 && $where['boolean'] == 'and') { - $where['boolean'] = $wheres[$i + 1]['boolean']; + // In a sequence of "where" clauses, the logical operator of the + // first "where" is determined by the 2nd "where". + // $where['boolean'] = "and", "or", "and not" or "or not" + if ($i == 0 && count($wheres) > 1 + && str_starts_with($where['boolean'], 'and') + && str_starts_with($wheres[$i + 1]['boolean'], 'or') + ) { + $where['boolean'] = 'or'.(str_ends_with($where['boolean'], 'not') ? ' not' : ''); } // We use different methods to compile different wheres. $method = "compileWhere{$where['type']}"; $result = $this->{$method}($where); + if (str_ends_with($where['boolean'], 'not')) { + $result = ['$not' => $result]; + } + // Wrap the where with an $or operator. - if ($where['boolean'] == 'or') { + if (str_starts_with($where['boolean'], 'or')) { $result = ['$or' => [$result]]; } diff --git a/tests/Query/BuilderTest.php b/tests/Query/BuilderTest.php index f600fa73a..8c8a00c50 100644 --- a/tests/Query/BuilderTest.php +++ b/tests/Query/BuilderTest.php @@ -50,6 +50,17 @@ public static function provideQueryBuilderToMql(): iterable fn (Builder $builder) => $builder->where('foo', 'bar'), ]; + yield 'where with single array of conditions' => [ + ['find' => [ + ['$and' => [ + ['foo' => 1], + ['bar' => 2], + ]], + [], // options + ]], + fn (Builder $builder) => $builder->where(['foo' => 1, 'bar' => 2]), + ]; + yield 'find > date' => [ ['find' => [['foo' => ['$gt' => new UTCDateTime($date)]], []]], fn (Builder $builder) => $builder->where('foo', '>', $date), @@ -65,6 +76,177 @@ public static function provideQueryBuilderToMql(): iterable fn (Builder $builder) => $builder->limit(10)->offset(5)->select('foo', 'bar'), ]; + /** @see DatabaseQueryBuilderTest::testBasicWhereNot() */ + yield 'whereNot (multiple)' => [ + ['find' => [ + ['$and' => [ + ['$not' => ['name' => 'foo']], + ['$not' => ['name' => ['$ne' => 'bar']]], + ]], + [], // options + ]], + fn (Builder $builder) => $builder + ->whereNot('name', 'foo') + ->whereNot('name', '<>', 'bar'), + ]; + + /** @see DatabaseQueryBuilderTest::testBasicOrWheres() */ + yield 'where orWhere' => [ + ['find' => [ + ['$or' => [ + ['id' => 1], + ['email' => 'foo'], + ]], + [], // options + ]], + fn (Builder $builder) => $builder + ->where('id', '=', 1) + ->orWhere('email', '=', 'foo'), + ]; + + /** @see DatabaseQueryBuilderTest::testBasicOrWhereNot() */ + yield 'orWhereNot' => [ + ['find' => [ + ['$or' => [ + ['$not' => ['name' => 'foo']], + ['$not' => ['name' => ['$ne' => 'bar']]], + ]], + [], // options + ]], + fn (Builder $builder) => $builder + ->orWhereNot('name', 'foo') + ->orWhereNot('name', '<>', 'bar'), + ]; + + yield 'whereNot orWhere' => [ + ['find' => [ + ['$or' => [ + ['$not' => ['name' => 'foo']], + ['name' => ['$ne' => 'bar']], + ]], + [], // options + ]], + fn (Builder $builder) => $builder + ->whereNot('name', 'foo') + ->orWhere('name', '<>', 'bar'), + ]; + + /** @see DatabaseQueryBuilderTest::testWhereNot() */ + yield 'whereNot callable' => [ + ['find' => [ + ['$not' => ['name' => 'foo']], + [], // options + ]], + fn (Builder $builder) => $builder + ->whereNot(fn (Builder $q) => $q->where('name', 'foo')), + ]; + + yield 'where whereNot' => [ + ['find' => [ + ['$and' => [ + ['name' => 'bar'], + ['$not' => ['email' => 'foo']], + ]], + [], // options + ]], + fn (Builder $builder) => $builder + ->where('name', '=', 'bar') + ->whereNot(function (Builder $q) { + $q->where('email', '=', 'foo'); + }), + ]; + + yield 'whereNot (nested)' => [ + ['find' => [ + ['$not' => [ + '$and' => [ + ['name' => 'foo'], + ['$not' => ['email' => ['$ne' => 'bar']]], + ], + ]], + [], // options + ]], + fn (Builder $builder) => $builder + ->whereNot(function (Builder $q) { + $q->where('name', '=', 'foo') + ->whereNot('email', '<>', 'bar'); + }), + ]; + + yield 'orWhere orWhereNot' => [ + ['find' => [ + ['$or' => [ + ['name' => 'bar'], + ['$not' => ['email' => 'foo']], + ]], + [], // options + ]], + fn (Builder $builder) => $builder + ->orWhere('name', '=', 'bar') + ->orWhereNot(function (Builder $q) { + $q->where('email', '=', 'foo'); + }), + ]; + + yield 'where orWhereNot' => [ + ['find' => [ + ['$or' => [ + ['name' => 'bar'], + ['$not' => ['email' => 'foo']], + ]], + [], // options + ]], + fn (Builder $builder) => $builder + ->where('name', '=', 'bar') + ->orWhereNot('email', '=', 'foo'), + ]; + + /** @see DatabaseQueryBuilderTest::testWhereNotWithArrayConditions() */ + yield 'whereNot with arrays of single condition' => [ + ['find' => [ + ['$not' => [ + '$and' => [ + ['foo' => 1], + ['bar' => 2], + ], + ]], + [], // options + ]], + fn (Builder $builder) => $builder + ->whereNot([['foo', 1], ['bar', 2]]), + ]; + + yield 'whereNot with single array of conditions' => [ + ['find' => [ + ['$not' => [ + '$and' => [ + ['foo' => 1], + ['bar' => 2], + ], + ]], + [], // options + ]], + fn (Builder $builder) => $builder + ->whereNot(['foo' => 1, 'bar' => 2]), + ]; + + yield 'whereNot with arrays of single condition with operator' => [ + ['find' => [ + ['$not' => [ + '$and' => [ + ['foo' => 1], + ['bar' => ['$lt' => 2]], + ], + ]], + [], // options + ]], + fn (Builder $builder) => $builder + ->whereNot([ + ['foo', 1], + ['bar', '<', 2], + ]), + ]; + /** @see DatabaseQueryBuilderTest::testOrderBys() */ yield 'orderBy multiple columns' => [ ['find' => [[], ['sort' => ['email' => 1, 'age' => -1]]]], From e045fab6c315fe6d17f75669665898ed98b88107 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Thu, 20 Jul 2023 23:48:26 +0200 Subject: [PATCH 070/446] PHPORM-49 Implement `Query\Builder::whereNot` by encapsulating into `$not` (#13) (#15) `Query\Builder::whereNot` was simply ignoring the "not" and breaking the built query. --- CHANGELOG.md | 1 + src/Query/Builder.php | 17 ----------------- tests/Query/BuilderTest.php | 6 ++++++ 3 files changed, 7 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 04b823816..d28e9beae 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ All notable changes to this project will be documented in this file. - Throw an exception for unsupported `Query\Builder` methods [#9](https://github.com/GromNaN/laravel-mongodb-private/pull/9) by [@GromNaN](https://github.com/GromNaN). - Throw an exception when `Query\Builder::orderBy()` is used with invalid direction [#7](https://github.com/GromNaN/laravel-mongodb-private/pull/7) by [@GromNaN](https://github.com/GromNaN). - Throw an exception when `Query\Builder::push()` is used incorrectly [#5](https://github.com/GromNaN/laravel-mongodb-private/pull/5) by [@GromNaN](https://github.com/GromNaN). +- Remove public property `Query\Builder::$paginating` [#15](https://github.com/GromNaN/laravel-mongodb-private/pull/15) by [@GromNaN](https://github.com/GromNaN). ## [3.9.2] - 2022-09-01 diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 4db2b5a91..6321b86de 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -59,13 +59,6 @@ class Builder extends BaseBuilder */ public $options = []; - /** - * Indicate if we are executing a pagination query. - * - * @var bool - */ - public $paginating = false; - /** * All of the available clause operators. * @@ -574,16 +567,6 @@ public function whereBetween($column, iterable $values, $boolean = 'and', $not = return $this; } - /** - * @inheritdoc - */ - public function forPage($page, $perPage = 15) - { - $this->paginating = true; - - return $this->skip(($page - 1) * $perPage)->take($perPage); - } - /** * @inheritdoc */ diff --git a/tests/Query/BuilderTest.php b/tests/Query/BuilderTest.php index 8c8a00c50..7cd6f0584 100644 --- a/tests/Query/BuilderTest.php +++ b/tests/Query/BuilderTest.php @@ -247,6 +247,12 @@ public static function provideQueryBuilderToMql(): iterable ]), ]; + /** @see DatabaseQueryBuilderTest::testForPage() */ + yield 'forPage' => [ + ['find' => [[], ['limit' => 20, 'skip' => 40]]], + fn (Builder $builder) => $builder->forPage(3, 20), + ]; + /** @see DatabaseQueryBuilderTest::testOrderBys() */ yield 'orderBy multiple columns' => [ ['find' => [[], ['sort' => ['email' => 1, 'age' => -1]]]], From 4514964145c70c37e6221be8823f8f73a201c259 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 26 Jul 2023 09:10:43 +0200 Subject: [PATCH 071/446] PHPORM-50 PHPORM-65 Remove call to deprecated Collection::count for countDocuments (#18) https://www.mongodb.com/docs/php-library/current/reference/method/MongoDBCollection-count/ Fix pass options to countDocuments for transaction session --- CHANGELOG.md | 1 + src/Query/Builder.php | 8 +++++--- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d28e9beae..0932cb357 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ All notable changes to this project will be documented in this file. - Throw an exception when `Query\Builder::orderBy()` is used with invalid direction [#7](https://github.com/GromNaN/laravel-mongodb-private/pull/7) by [@GromNaN](https://github.com/GromNaN). - Throw an exception when `Query\Builder::push()` is used incorrectly [#5](https://github.com/GromNaN/laravel-mongodb-private/pull/5) by [@GromNaN](https://github.com/GromNaN). - Remove public property `Query\Builder::$paginating` [#15](https://github.com/GromNaN/laravel-mongodb-private/pull/15) by [@GromNaN](https://github.com/GromNaN). +- Remove call to deprecated `Collection::count` for `countDocuments` [#18](https://github.com/GromNaN/laravel-mongodb-private/pull/18) by [@GromNaN](https://github.com/GromNaN). ## [3.9.2] - 2022-09-01 diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 6321b86de..4c699a863 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -266,7 +266,9 @@ public function toMql(): array $aggregations = blank($this->aggregate['columns']) ? [] : $this->aggregate['columns']; if (in_array('*', $aggregations) && $function == 'count') { - return ['count' => [$wheres, []]]; + $options = $this->inheritConnectionOptions(); + + return ['countDocuments' => [$wheres, $options]]; } elseif ($function == 'count') { // Translate count into sum. $group['aggregate'] = ['$sum' => 1]; @@ -329,7 +331,7 @@ public function toMql(): array $options = $this->inheritConnectionOptions(); - return ['distinct' => [$column, $wheres ?: [], $options]]; + return ['distinct' => [$column, $wheres, $options]]; } // Normal query else { // Convert select columns to simple projections. @@ -396,7 +398,7 @@ public function getFresh($columns = [], $returnLazy = false) $this->columns = []; } - $command = $this->toMql($columns); + $command = $this->toMql(); assert(count($command) >= 1, 'At least one method call is required to execute a query'); $result = $this->collection; From 0fb83af01284cb16def1eda6987432ebbd64bb8f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 26 Jul 2023 09:14:42 +0200 Subject: [PATCH 072/446] PHPORM-67 Accept operators prefixed by $ in Query\Builder::orWhere (#20) --- CHANGELOG.md | 1 + src/Query/Builder.php | 4 ++-- tests/Query/BuilderTest.php | 13 +++++++++++++ 3 files changed, 16 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0932cb357..39e9875f7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,7 @@ All notable changes to this project will be documented in this file. - Throw an exception when `Query\Builder::push()` is used incorrectly [#5](https://github.com/GromNaN/laravel-mongodb-private/pull/5) by [@GromNaN](https://github.com/GromNaN). - Remove public property `Query\Builder::$paginating` [#15](https://github.com/GromNaN/laravel-mongodb-private/pull/15) by [@GromNaN](https://github.com/GromNaN). - Remove call to deprecated `Collection::count` for `countDocuments` [#18](https://github.com/GromNaN/laravel-mongodb-private/pull/18) by [@GromNaN](https://github.com/GromNaN). +- Accept operators prefixed by `$` in `Query\Builder::orWhere` [#20](https://github.com/GromNaN/laravel-mongodb-private/pull/20) by [@GromNaN](https://github.com/GromNaN). ## [3.9.2] - 2022-09-01 diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 4c699a863..4def94573 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -917,10 +917,10 @@ public function where($column, $operator = null, $value = null, $boolean = 'and' $params = func_get_args(); // Remove the leading $ from operators. - if (func_num_args() == 3) { + if (func_num_args() >= 3) { $operator = &$params[1]; - if (Str::startsWith($operator, '$')) { + if (is_string($operator) && str_starts_with($operator, '$')) { $operator = substr($operator, 1); } } diff --git a/tests/Query/BuilderTest.php b/tests/Query/BuilderTest.php index 7cd6f0584..fb5bc2032 100644 --- a/tests/Query/BuilderTest.php +++ b/tests/Query/BuilderTest.php @@ -76,6 +76,19 @@ public static function provideQueryBuilderToMql(): iterable fn (Builder $builder) => $builder->limit(10)->offset(5)->select('foo', 'bar'), ]; + yield 'where accepts $ in operators' => [ + ['find' => [ + ['$or' => [ + ['foo' => ['$type' => 2]], + ['foo' => ['$type' => 4]], + ]], + [], // options + ]], + fn (Builder $builder) => $builder + ->where('foo', '$type', 2) + ->orWhere('foo', '$type', 4), + ]; + /** @see DatabaseQueryBuilderTest::testBasicWhereNot() */ yield 'whereNot (multiple)' => [ ['find' => [ From b9bbcdd91054b58fc4ff19864ce31bc59c2605d9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 26 Jul 2023 09:28:06 +0200 Subject: [PATCH 073/446] PHPORM-33 Add tests on Query\Builder methods (#14) - Add tests on query builder methods that don't need to be fixed. - Throw exception when calling unsupported methods: whereIntegerInRaw, orWhereIntegerInRaw, whereIntegerNotInRaw, orWhereIntegerNotInRaw - Throw an exception when Query\Builder::where is called with only a column name --- src/Query/Builder.php | 28 ++++++ tests/Query/BuilderTest.php | 178 +++++++++++++++++++++++++++++++++++- tests/TransactionTest.php | 2 +- 3 files changed, 205 insertions(+), 3 deletions(-) diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 4def94573..1a0152a95 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -925,6 +925,10 @@ public function where($column, $operator = null, $value = null, $boolean = 'and' } } + if (func_num_args() == 1 && is_string($column)) { + throw new \ArgumentCountError(sprintf('Too few arguments to function %s("%s"), 1 passed and at least 2 expected when the 1st is a string.', __METHOD__, $column)); + } + return parent::where(...$params); } @@ -1378,4 +1382,28 @@ public function havingBetween($column, iterable $values, $boolean = 'and', $not { throw new \BadMethodCallException('This method is not supported by MongoDB'); } + + /** @internal This method is not supported by MongoDB. */ + public function whereIntegerInRaw($column, $values, $boolean = 'and', $not = false) + { + throw new \BadMethodCallException('This method is not supported by MongoDB'); + } + + /** @internal This method is not supported by MongoDB. */ + public function orWhereIntegerInRaw($column, $values) + { + throw new \BadMethodCallException('This method is not supported by MongoDB'); + } + + /** @internal This method is not supported by MongoDB. */ + public function whereIntegerNotInRaw($column, $values, $boolean = 'and') + { + throw new \BadMethodCallException('This method is not supported by MongoDB'); + } + + /** @internal This method is not supported by MongoDB. */ + public function orWhereIntegerNotInRaw($column, $values, $boolean = 'and') + { + throw new \BadMethodCallException('This method is not supported by MongoDB'); + } } diff --git a/tests/Query/BuilderTest.php b/tests/Query/BuilderTest.php index fb5bc2032..8f7d8f851 100644 --- a/tests/Query/BuilderTest.php +++ b/tests/Query/BuilderTest.php @@ -45,7 +45,36 @@ public static function provideQueryBuilderToMql(): iterable */ $date = new DateTimeImmutable('2016-07-12 15:30:00'); - yield 'find' => [ + yield 'select replaces previous select' => [ + ['find' => [[], ['projection' => ['bar' => 1]]]], + fn (Builder $builder) => $builder->select('foo')->select('bar'), + ]; + + yield 'select array' => [ + ['find' => [[], ['projection' => ['foo' => 1, 'bar' => 1]]]], + fn (Builder $builder) => $builder->select(['foo', 'bar']), + ]; + + /** @see DatabaseQueryBuilderTest::testAddingSelects */ + yield 'addSelect' => [ + ['find' => [[], ['projection' => ['foo' => 1, 'bar' => 1, 'baz' => 1, 'boom' => 1]]]], + fn (Builder $builder) => $builder->select('foo') + ->addSelect('bar') + ->addSelect(['baz', 'boom']) + ->addSelect('bar'), + ]; + + yield 'select all' => [ + ['find' => [[], []]], + fn (Builder $builder) => $builder->select('*'), + ]; + + yield 'find all with select' => [ + ['find' => [[], ['projection' => ['foo' => 1, 'bar' => 1]]]], + fn (Builder $builder) => $builder->select('foo', 'bar'), + ]; + + yield 'find equals' => [ ['find' => [['foo' => 'bar'], []]], fn (Builder $builder) => $builder->where('foo', 'bar'), ]; @@ -66,11 +95,55 @@ public static function provideQueryBuilderToMql(): iterable fn (Builder $builder) => $builder->where('foo', '>', $date), ]; - yield 'find in array' => [ + /** @see DatabaseQueryBuilderTest::testBasicWhereIns */ + yield 'whereIn' => [ ['find' => [['foo' => ['$in' => ['bar', 'baz']]], []]], fn (Builder $builder) => $builder->whereIn('foo', ['bar', 'baz']), ]; + // Nested array are not flattened like in the Eloquent builder. MongoDB can compare objects. + $array = [['issue' => 45582], ['id' => 2], [3]]; + yield 'whereIn nested array' => [ + ['find' => [['id' => ['$in' => $array]], []]], + fn (Builder $builder) => $builder->whereIn('id', $array), + ]; + + yield 'orWhereIn' => [ + ['find' => [ + ['$or' => [ + ['id' => 1], + ['id' => ['$in' => [1, 2, 3]]], + ]], + [], // options + ]], + fn (Builder $builder) => $builder->where('id', '=', 1) + ->orWhereIn('id', [1, 2, 3]), + ]; + + /** @see DatabaseQueryBuilderTest::testBasicWhereNotIns */ + yield 'whereNotIn' => [ + ['find' => [['id' => ['$nin' => [1, 2, 3]]], []]], + fn (Builder $builder) => $builder->whereNotIn('id', [1, 2, 3]), + ]; + + yield 'orWhereNotIn' => [ + ['find' => [ + ['$or' => [ + ['id' => 1], + ['id' => ['$nin' => [1, 2, 3]]], + ]], + [], // options + ]], + fn (Builder $builder) => $builder->where('id', '=', 1) + ->orWhereNotIn('id', [1, 2, 3]), + ]; + + /** @see DatabaseQueryBuilderTest::testEmptyWhereIns */ + yield 'whereIn empty array' => [ + ['find' => [['id' => ['$in' => []]], []]], + fn (Builder $builder) => $builder->whereIn('id', []), + ]; + yield 'find limit offset select' => [ ['find' => [[], ['limit' => 10, 'skip' => 5, 'projection' => ['foo' => 1, 'bar' => 1]]]], fn (Builder $builder) => $builder->limit(10)->offset(5)->select('foo', 'bar'), @@ -266,6 +339,43 @@ public static function provideQueryBuilderToMql(): iterable fn (Builder $builder) => $builder->forPage(3, 20), ]; + /** @see DatabaseQueryBuilderTest::testLimitsAndOffsets() */ + yield 'offset limit' => [ + ['find' => [[], ['skip' => 5, 'limit' => 10]]], + fn (Builder $builder) => $builder->offset(5)->limit(10), + ]; + + yield 'offset limit zero (unset)' => [ + ['find' => [[], []]], + fn (Builder $builder) => $builder + ->offset(0)->limit(0), + ]; + + yield 'offset limit zero (reset)' => [ + ['find' => [[], []]], + fn (Builder $builder) => $builder + ->offset(5)->limit(10) + ->offset(0)->limit(0), + ]; + + yield 'offset limit negative (unset)' => [ + ['find' => [[], []]], + fn (Builder $builder) => $builder + ->offset(-5)->limit(-10), + ]; + + yield 'offset limit null (reset)' => [ + ['find' => [[], []]], + fn (Builder $builder) => $builder + ->offset(5)->limit(10) + ->offset(null)->limit(null), + ]; + + yield 'skip take (aliases)' => [ + ['find' => [[], ['skip' => 5, 'limit' => 10]]], + fn (Builder $builder) => $builder->skip(5)->limit(10), + ]; + /** @see DatabaseQueryBuilderTest::testOrderBys() */ yield 'orderBy multiple columns' => [ ['find' => [[], ['sort' => ['email' => 1, 'age' => -1]]]], @@ -452,11 +562,57 @@ function (Builder $builder) { ->orWhereNotBetween('id', collect([3, 4])), ]; + /** @see DatabaseQueryBuilderTest::testBasicSelectDistinct */ yield 'distinct' => [ ['distinct' => ['foo', [], []]], fn (Builder $builder) => $builder->distinct('foo'), ]; + yield 'select distinct' => [ + ['distinct' => ['foo', [], []]], + fn (Builder $builder) => $builder->select('foo', 'bar') + ->distinct(), + ]; + + /** @see DatabaseQueryBuilderTest::testBasicSelectDistinctOnColumns */ + yield 'select distinct on' => [ + ['distinct' => ['foo', [], []]], + fn (Builder $builder) => $builder->distinct('foo') + ->select('foo', 'bar'), + ]; + + /** @see DatabaseQueryBuilderTest::testLatest() */ + yield 'latest' => [ + ['find' => [[], ['sort' => ['created_at' => -1]]]], + fn (Builder $builder) => $builder->latest(), + ]; + + yield 'latest limit' => [ + ['find' => [[], ['sort' => ['created_at' => -1], 'limit' => 1]]], + fn (Builder $builder) => $builder->latest()->limit(1), + ]; + + yield 'latest custom field' => [ + ['find' => [[], ['sort' => ['updated_at' => -1]]]], + fn (Builder $builder) => $builder->latest('updated_at'), + ]; + + /** @see DatabaseQueryBuilderTest::testOldest() */ + yield 'oldest' => [ + ['find' => [[], ['sort' => ['created_at' => 1]]]], + fn (Builder $builder) => $builder->oldest(), + ]; + + yield 'oldest limit' => [ + ['find' => [[], ['sort' => ['created_at' => 1], 'limit' => 1]]], + fn (Builder $builder) => $builder->oldest()->limit(1), + ]; + + yield 'oldest custom field' => [ + ['find' => [[], ['sort' => ['updated_at' => 1]]]], + fn (Builder $builder) => $builder->oldest('updated_at'), + ]; + yield 'groupBy' => [ ['aggregate' => [ [['$group' => ['_id' => ['foo' => '$foo'], 'foo' => ['$last' => '$foo']]]], @@ -516,6 +672,12 @@ public static function provideExceptions(): iterable 'Between $values must be a list with exactly two elements: [min, max]', fn (Builder $builder) => $builder->whereBetween('id', ['min' => 1, 'max' => 2]), ]; + + yield 'find with single string argument' => [ + \ArgumentCountError::class, + 'Too few arguments to function Jenssegers\Mongodb\Query\Builder::where("foo"), 1 passed and at least 2 expected when the 1st is a string', + fn (Builder $builder) => $builder->where('foo'), + ]; } /** @dataProvider getEloquentMethodsNotSupported */ @@ -562,6 +724,18 @@ public static function getEloquentMethodsNotSupported() yield 'having' => [fn (Builder $builder) => $builder->having('baz', '=', 1)]; yield 'havingBetween' => [fn (Builder $builder) => $builder->havingBetween('last_login_date', ['2018-11-16', '2018-12-16'])]; yield 'orHavingRaw' => [fn (Builder $builder) => $builder->orHavingRaw('user_foo < user_bar')]; + + /** @see DatabaseQueryBuilderTest::testWhereIntegerInRaw */ + yield 'whereIntegerInRaw' => [fn (Builder $builder) => $builder->whereIntegerInRaw('id', ['1a', 2])]; + + /** @see DatabaseQueryBuilderTest::testOrWhereIntegerInRaw */ + yield 'orWhereIntegerInRaw' => [fn (Builder $builder) => $builder->orWhereIntegerInRaw('id', ['1a', 2])]; + + /** @see DatabaseQueryBuilderTest::testWhereIntegerNotInRaw */ + yield 'whereIntegerNotInRaw' => [fn (Builder $builder) => $builder->whereIntegerNotInRaw('id', ['1a', 2])]; + + /** @see DatabaseQueryBuilderTest::testOrWhereIntegerNotInRaw */ + yield 'orWhereIntegerNotInRaw' => [fn (Builder $builder) => $builder->orWhereIntegerNotInRaw('id', ['1a', 2])]; } private static function getBuilder(): Builder diff --git a/tests/TransactionTest.php b/tests/TransactionTest.php index 46fbf2e2a..06f1c2150 100644 --- a/tests/TransactionTest.php +++ b/tests/TransactionTest.php @@ -332,7 +332,7 @@ public function testTransaction(): void $count = User::count(); $this->assertEquals(2, $count); - $this->assertTrue(User::where('alcaeus')->exists()); + $this->assertTrue(User::where('name', 'alcaeus')->exists()); $this->assertTrue(User::where(['name' => 'klinson'])->where('age', 21)->exists()); } From 1d74dc3d3df9f7a579b343f3109160762050ca01 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 26 Jul 2023 11:13:34 +0200 Subject: [PATCH 074/446] PHPORM-64 Remove Query\Builder::whereAll (#16) --- CHANGELOG.md | 1 + README.md | 11 +++++++++++ src/Query/Builder.php | 29 ----------------------------- tests/Query/BuilderTest.php | 16 ++++++++++++++++ 4 files changed, 28 insertions(+), 29 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 39e9875f7..18adfc131 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,7 @@ All notable changes to this project will be documented in this file. - Remove public property `Query\Builder::$paginating` [#15](https://github.com/GromNaN/laravel-mongodb-private/pull/15) by [@GromNaN](https://github.com/GromNaN). - Remove call to deprecated `Collection::count` for `countDocuments` [#18](https://github.com/GromNaN/laravel-mongodb-private/pull/18) by [@GromNaN](https://github.com/GromNaN). - Accept operators prefixed by `$` in `Query\Builder::orWhere` [#20](https://github.com/GromNaN/laravel-mongodb-private/pull/20) by [@GromNaN](https://github.com/GromNaN). +- Remove `Query\Builder::whereAll($column, $values)`. Use `Query\Builder::where($column, 'all', $values)` instead. [#16](https://github.com/GromNaN/laravel-mongodb-private/pull/16) by [@GromNaN](https://github.com/GromNaN). ## [3.9.2] - 2022-09-01 diff --git a/README.md b/README.md index 71e7768e5..f00b3a2c7 100644 --- a/README.md +++ b/README.md @@ -483,6 +483,17 @@ Car::where('weight', 300) ### MongoDB-specific operators +In addition to the Laravel Eloquent operators, all available MongoDB query operators can be used with `where`: + +```php +User::where($fieldName, $operator, $value)->get(); +``` + +It generates the following MongoDB filter: +```ts +{ $fieldName: { $operator: $value } } +``` + **Exists** Matches documents that have the specified field. diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 1a0152a95..574bf8f2b 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -530,24 +530,6 @@ public function orderBy($column, $direction = 'asc') return $this; } - /** - * Add a "where all" clause to the query. - * - * @param string $column - * @param array $values - * @param string $boolean - * @param bool $not - * @return $this - */ - public function whereAll($column, array $values, $boolean = 'and', $not = false) - { - $type = 'all'; - - $this->wheres[] = compact('column', 'type', 'boolean', 'values', 'not'); - - return $this; - } - /** * @inheritdoc * @param list{mixed, mixed}|CarbonPeriod $values @@ -1044,17 +1026,6 @@ protected function compileWheres(): array return $compiled; } - /** - * @param array $where - * @return array - */ - protected function compileWhereAll(array $where): array - { - extract($where); - - return [$column => ['$all' => array_values($values)]]; - } - /** * @param array $where * @return array diff --git a/tests/Query/BuilderTest.php b/tests/Query/BuilderTest.php index 8f7d8f851..bc0644909 100644 --- a/tests/Query/BuilderTest.php +++ b/tests/Query/BuilderTest.php @@ -333,6 +333,22 @@ public static function provideQueryBuilderToMql(): iterable ]), ]; + yield 'where all' => [ + ['find' => [['tags' => ['$all' => ['ssl', 'security']]], []]], + fn (Builder $builder) => $builder->where('tags', 'all', ['ssl', 'security']), + ]; + + yield 'where all nested operators' => [ + ['find' => [['tags' => ['$all' => [ + ['$elemMatch' => ['size' => 'M', 'num' => ['$gt' => 50]]], + ['$elemMatch' => ['num' => 100, 'color' => 'green']], + ]]], []]], + fn (Builder $builder) => $builder->where('tags', 'all', [ + ['$elemMatch' => ['size' => 'M', 'num' => ['$gt' => 50]]], + ['$elemMatch' => ['num' => 100, 'color' => 'green']], + ]), + ]; + /** @see DatabaseQueryBuilderTest::testForPage() */ yield 'forPage' => [ ['find' => [[], ['limit' => 20, 'skip' => 40]]], From d5f1bb901f3e3c6777bc604be1af0a8238dc089a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 26 Jul 2023 15:48:40 +0200 Subject: [PATCH 075/446] PHPORM-68 Fix unique validator when the validated value is part of an existing value (#21) --- CHANGELOG.md | 1 + src/Validation/DatabasePresenceVerifier.php | 4 +++- tests/ValidationTest.php | 6 ++++++ 3 files changed, 10 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 18adfc131..9ad3e0ea6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,7 @@ All notable changes to this project will be documented in this file. - Remove call to deprecated `Collection::count` for `countDocuments` [#18](https://github.com/GromNaN/laravel-mongodb-private/pull/18) by [@GromNaN](https://github.com/GromNaN). - Accept operators prefixed by `$` in `Query\Builder::orWhere` [#20](https://github.com/GromNaN/laravel-mongodb-private/pull/20) by [@GromNaN](https://github.com/GromNaN). - Remove `Query\Builder::whereAll($column, $values)`. Use `Query\Builder::where($column, 'all', $values)` instead. [#16](https://github.com/GromNaN/laravel-mongodb-private/pull/16) by [@GromNaN](https://github.com/GromNaN). +- Fix validation of unique values when the validated value is found as part of an existing value. [#21](https://github.com/GromNaN/laravel-mongodb-private/pull/21) by [@GromNaN](https://github.com/GromNaN). ## [3.9.2] - 2022-09-01 diff --git a/src/Validation/DatabasePresenceVerifier.php b/src/Validation/DatabasePresenceVerifier.php index 6c38a04b2..c563a9976 100644 --- a/src/Validation/DatabasePresenceVerifier.php +++ b/src/Validation/DatabasePresenceVerifier.php @@ -2,6 +2,8 @@ namespace Jenssegers\Mongodb\Validation; +use MongoDB\BSON\Regex; + class DatabasePresenceVerifier extends \Illuminate\Validation\DatabasePresenceVerifier { /** @@ -17,7 +19,7 @@ class DatabasePresenceVerifier extends \Illuminate\Validation\DatabasePresenceVe */ public function getCount($collection, $column, $value, $excludeId = null, $idColumn = null, array $extra = []) { - $query = $this->table($collection)->where($column, 'regex', '/'.preg_quote($value).'/i'); + $query = $this->table($collection)->where($column, new Regex('^'.preg_quote($value).'$', '/i')); if ($excludeId !== null && $excludeId != 'NULL') { $query->where($idColumn ?: 'id', '<>', $excludeId); diff --git a/tests/ValidationTest.php b/tests/ValidationTest.php index d4a2fcfdd..5a0459215 100644 --- a/tests/ValidationTest.php +++ b/tests/ValidationTest.php @@ -48,6 +48,12 @@ public function testUnique(): void ); $this->assertFalse($validator->fails()); + $validator = Validator::make( + ['name' => 'John'], // Part of an existing value + ['name' => 'required|unique:users'] + ); + $this->assertFalse($validator->fails()); + User::create(['name' => 'Johnny Cash', 'email' => 'johnny.cash+200@gmail.com']); $validator = Validator::make( From ea89e8631350cd81c8d5bf977efb4c09e60d7807 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Thu, 27 Jul 2023 19:03:49 +0200 Subject: [PATCH 076/446] PHPORM-53 Fix and test `like` and `regex` operators (#17) - Fix support for % and _ in like expression and escaped \% and \_ - Keep ilike and regexp operators as aliases for like and regex - Allow /, # and ~ as regex delimiters - Add functional tests on regexp and not regexp - Add support for not regex --- CHANGELOG.md | 3 +- src/Query/Builder.php | 117 ++++++++++++++++++++---------------- tests/Query/BuilderTest.php | 81 ++++++++++++++++++++++++- tests/QueryTest.php | 21 +++++++ 4 files changed, 167 insertions(+), 55 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9ad3e0ea6..30413ef3b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,7 +3,7 @@ All notable changes to this project will be documented in this file. ## [Unreleased] -- Add classes to cast ObjectId and UUID instances [#1](https://github.com/GromNaN/laravel-mongodb-private/pull/1) by [@alcaeus](https://github.com/alcaeus). +- Add classes to cast `ObjectId` and `UUID` instances [#1](https://github.com/GromNaN/laravel-mongodb-private/pull/1) by [@alcaeus](https://github.com/alcaeus). - Add `Query\Builder::toMql()` to simplify comprehensive query tests [#6](https://github.com/GromNaN/laravel-mongodb-private/pull/6) by [@GromNaN](https://github.com/GromNaN). - Fix `Query\Builder::whereNot` to use MongoDB [`$not`](https://www.mongodb.com/docs/manual/reference/operator/query/not/) operator [#13](https://github.com/GromNaN/laravel-mongodb-private/pull/13) by [@GromNaN](https://github.com/GromNaN). - Fix `Query\Builder::whereBetween` to accept `Carbon\Period` object [#10](https://github.com/GromNaN/laravel-mongodb-private/pull/10) by [@GromNaN](https://github.com/GromNaN). @@ -15,6 +15,7 @@ All notable changes to this project will be documented in this file. - Accept operators prefixed by `$` in `Query\Builder::orWhere` [#20](https://github.com/GromNaN/laravel-mongodb-private/pull/20) by [@GromNaN](https://github.com/GromNaN). - Remove `Query\Builder::whereAll($column, $values)`. Use `Query\Builder::where($column, 'all', $values)` instead. [#16](https://github.com/GromNaN/laravel-mongodb-private/pull/16) by [@GromNaN](https://github.com/GromNaN). - Fix validation of unique values when the validated value is found as part of an existing value. [#21](https://github.com/GromNaN/laravel-mongodb-private/pull/21) by [@GromNaN](https://github.com/GromNaN). +- Support `%` and `_` in `like` expression [#17](https://github.com/GromNaN/laravel-mongodb-private/pull/17) by [@GromNaN](https://github.com/GromNaN). ## [3.9.2] - 2022-09-01 diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 574bf8f2b..dd448ed01 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -24,6 +24,8 @@ */ class Builder extends BaseBuilder { + private const REGEX_DELIMITERS = ['/', '#', '~']; + /** * The database collection. * @@ -91,6 +93,7 @@ class Builder extends BaseBuilder 'all', 'size', 'regex', + 'not regex', 'text', 'slice', 'elemmatch', @@ -113,13 +116,22 @@ class Builder extends BaseBuilder * @var array */ protected $conversion = [ - '=' => '=', - '!=' => '$ne', - '<>' => '$ne', - '<' => '$lt', - '<=' => '$lte', - '>' => '$gt', - '>=' => '$gte', + '!=' => 'ne', + '<>' => 'ne', + '<' => 'lt', + '<=' => 'lte', + '>' => 'gt', + '>=' => 'gte', + 'regexp' => 'regex', + 'not regexp' => 'not regex', + 'ilike' => 'like', + 'elemmatch' => 'elemMatch', + 'geointersects' => 'geoIntersects', + 'geowithin' => 'geoWithin', + 'nearsphere' => 'nearSphere', + 'maxdistance' => 'maxDistance', + 'centersphere' => 'centerSphere', + 'uniquedocs' => 'uniqueDocs', ]; /** @@ -932,20 +944,9 @@ protected function compileWheres(): array if (isset($where['operator'])) { $where['operator'] = strtolower($where['operator']); - // Operator conversions - $convert = [ - 'regexp' => 'regex', - 'elemmatch' => 'elemMatch', - 'geointersects' => 'geoIntersects', - 'geowithin' => 'geoWithin', - 'nearsphere' => 'nearSphere', - 'maxdistance' => 'maxDistance', - 'centersphere' => 'centerSphere', - 'uniquedocs' => 'uniqueDocs', - ]; - - if (array_key_exists($where['operator'], $convert)) { - $where['operator'] = $convert[$where['operator']]; + // Convert aliased operators + if (isset($this->conversion[$where['operator']])) { + $where['operator'] = $this->conversion[$where['operator']]; } } @@ -1036,45 +1037,55 @@ protected function compileWhereBasic(array $where): array // Replace like or not like with a Regex instance. if (in_array($operator, ['like', 'not like'])) { - if ($operator === 'not like') { - $operator = 'not'; - } else { - $operator = '='; - } - - // Convert to regular expression. - $regex = preg_replace('#(^|[^\\\])%#', '$1.*', preg_quote($value)); - - // Convert like to regular expression. - if (! Str::startsWith($value, '%')) { - $regex = '^'.$regex; - } - if (! Str::endsWith($value, '%')) { - $regex .= '$'; - } + $regex = preg_replace( + [ + // Unescaped % are converted to .* + // Group consecutive % + '#(^|[^\\\])%+#', + // Unescaped _ are converted to . + // Use positive lookahead to replace consecutive _ + '#(?<=^|[^\\\\])_#', + // Escaped \% or \_ are unescaped + '#\\\\\\\(%|_)#', + ], + ['$1.*', '$1.', '$1'], + // Escape any regex reserved characters, so they are matched + // All backslashes are converted to \\, which are needed in matching regexes. + preg_quote($value), + ); + $value = new Regex('^'.$regex.'$', 'i'); + + // For inverse like operations, we can just use the $not operator with the Regex + $operator = $operator === 'like' ? '=' : 'not'; + } - $value = new Regex($regex, 'i'); - } // Manipulate regexp operations. - elseif (in_array($operator, ['regexp', 'not regexp', 'regex', 'not regex'])) { + // Manipulate regex operations. + elseif (in_array($operator, ['regex', 'not regex'])) { // Automatically convert regular expression strings to Regex objects. - if (! $value instanceof Regex) { - $e = explode('/', $value); - $flag = end($e); - $regstr = substr($value, 1, -(strlen($flag) + 1)); - $value = new Regex($regstr, $flag); + if (is_string($value)) { + // Detect the delimiter and validate the preg pattern + $delimiter = substr($value, 0, 1); + if (! in_array($delimiter, self::REGEX_DELIMITERS)) { + throw new \LogicException(sprintf('Missing expected starting delimiter in regular expression "%s", supported delimiters are: %s', $value, implode(' ', self::REGEX_DELIMITERS))); + } + $e = explode($delimiter, $value); + // We don't try to detect if the last delimiter is escaped. This would be an invalid regex. + if (count($e) < 3) { + throw new \LogicException(sprintf('Missing expected ending delimiter "%s" in regular expression "%s"', $delimiter, $value)); + } + // Flags are after the last delimiter + $flags = end($e); + // Extract the regex string between the delimiters + $regstr = substr($value, 1, -1 - strlen($flags)); + $value = new Regex($regstr, $flags); } - // For inverse regexp operations, we can just use the $not operator - // and pass it a Regex instence. - if (Str::startsWith($operator, 'not')) { - $operator = 'not'; - } + // For inverse regex operations, we can just use the $not operator with the Regex + $operator = $operator === 'regex' ? '=' : 'not'; } if (! isset($operator) || $operator == '=') { $query = [$column => $value]; - } elseif (array_key_exists($operator, $this->conversion)) { - $query = [$column => [$this->conversion[$operator] => $value]]; } else { $query = [$column => ['$'.$operator => $value]]; } @@ -1133,7 +1144,7 @@ protected function compileWhereNull(array $where): array */ protected function compileWhereNotNull(array $where): array { - $where['operator'] = '!='; + $where['operator'] = 'ne'; $where['value'] = null; return $this->compileWhereBasic($where); diff --git a/tests/Query/BuilderTest.php b/tests/Query/BuilderTest.php index bc0644909..f34642274 100644 --- a/tests/Query/BuilderTest.php +++ b/tests/Query/BuilderTest.php @@ -11,6 +11,7 @@ use Jenssegers\Mongodb\Query\Builder; use Jenssegers\Mongodb\Query\Processor; use Mockery as m; +use MongoDB\BSON\Regex; use MongoDB\BSON\UTCDateTime; use PHPUnit\Framework\TestCase; @@ -578,6 +579,72 @@ function (Builder $builder) { ->orWhereNotBetween('id', collect([3, 4])), ]; + yield 'where like' => [ + ['find' => [['name' => new Regex('^acme$', 'i')], []]], + fn (Builder $builder) => $builder->where('name', 'like', 'acme'), + ]; + + yield 'where ilike' => [ // Alias for like + ['find' => [['name' => new Regex('^acme$', 'i')], []]], + fn (Builder $builder) => $builder->where('name', 'ilike', 'acme'), + ]; + + yield 'where like escape' => [ + ['find' => [['name' => new Regex('^\^ac\.me\$$', 'i')], []]], + fn (Builder $builder) => $builder->where('name', 'like', '^ac.me$'), + ]; + + yield 'where like unescaped \% \_' => [ + ['find' => [['name' => new Regex('^a%cm_e$', 'i')], []]], + fn (Builder $builder) => $builder->where('name', 'like', 'a\%cm\_e'), + ]; + + yield 'where like %' => [ + ['find' => [['name' => new Regex('^.*ac.*me.*$', 'i')], []]], + fn (Builder $builder) => $builder->where('name', 'like', '%ac%%me%'), + ]; + + yield 'where like _' => [ + ['find' => [['name' => new Regex('^.ac..me.$', 'i')], []]], + fn (Builder $builder) => $builder->where('name', 'like', '_ac__me_'), + ]; + + $regex = new Regex('^acme$', 'si'); + yield 'where BSON\Regex' => [ + ['find' => [['name' => $regex], []]], + fn (Builder $builder) => $builder->where('name', 'regex', $regex), + ]; + + yield 'where regexp' => [ // Alias for regex + ['find' => [['name' => $regex], []]], + fn (Builder $builder) => $builder->where('name', 'regex', '/^acme$/si'), + ]; + + yield 'where regex delimiter /' => [ + ['find' => [['name' => $regex], []]], + fn (Builder $builder) => $builder->where('name', 'regex', '/^acme$/si'), + ]; + + yield 'where regex delimiter #' => [ + ['find' => [['name' => $regex], []]], + fn (Builder $builder) => $builder->where('name', 'regex', '#^acme$#si'), + ]; + + yield 'where regex delimiter ~' => [ + ['find' => [['name' => $regex], []]], + fn (Builder $builder) => $builder->where('name', 'regex', '#^acme$#si'), + ]; + + yield 'where regex with escaped characters' => [ + ['find' => [['name' => new Regex('a\.c\/m\+e', '')], []]], + fn (Builder $builder) => $builder->where('name', 'regex', '/a\.c\/m\+e/'), + ]; + + yield 'where not regex' => [ + ['find' => [['name' => ['$not' => $regex]], []]], + fn (Builder $builder) => $builder->where('name', 'not regex', '/^acme$/si'), + ]; + /** @see DatabaseQueryBuilderTest::testBasicSelectDistinct */ yield 'distinct' => [ ['distinct' => ['foo', [], []]], @@ -647,7 +714,7 @@ public function testException($class, $message, \Closure $build): void $this->expectException($class); $this->expectExceptionMessage($message); - $build($builder); + $build($builder)->toMQL(); } public static function provideExceptions(): iterable @@ -694,6 +761,18 @@ public static function provideExceptions(): iterable 'Too few arguments to function Jenssegers\Mongodb\Query\Builder::where("foo"), 1 passed and at least 2 expected when the 1st is a string', fn (Builder $builder) => $builder->where('foo'), ]; + + yield 'where regex not starting with /' => [ + \LogicException::class, + 'Missing expected starting delimiter in regular expression "^ac/me$", supported delimiters are: / # ~', + fn (Builder $builder) => $builder->where('name', 'regex', '^ac/me$'), + ]; + + yield 'where regex not ending with /' => [ + \LogicException::class, + 'Missing expected ending delimiter "/" in regular expression "/foo#bar"', + fn (Builder $builder) => $builder->where('name', 'regex', '/foo#bar'), + ]; } /** @dataProvider getEloquentMethodsNotSupported */ diff --git a/tests/QueryTest.php b/tests/QueryTest.php index 4179748d0..754f204dc 100644 --- a/tests/QueryTest.php +++ b/tests/QueryTest.php @@ -70,6 +70,21 @@ public function testAndWhere(): void $this->assertCount(2, $users); } + public function testRegexp(): void + { + User::create(['name' => 'Simple', 'company' => 'acme']); + User::create(['name' => 'With slash', 'company' => 'oth/er']); + + $users = User::where('company', 'regexp', '/^acme$/')->get(); + $this->assertCount(1, $users); + + $users = User::where('company', 'regexp', '/^ACME$/i')->get(); + $this->assertCount(1, $users); + + $users = User::where('company', 'regexp', '/^oth\/er$/')->get(); + $this->assertCount(1, $users); + } + public function testLike(): void { $users = User::where('name', 'like', '%doe')->get(); @@ -83,6 +98,12 @@ public function testLike(): void $users = User::where('name', 'like', 't%')->get(); $this->assertCount(1, $users); + + $users = User::where('name', 'like', 'j___ doe')->get(); + $this->assertCount(2, $users); + + $users = User::where('name', 'like', '_oh_ _o_')->get(); + $this->assertCount(1, $users); } public function testNotLike(): void From 49ec43c49c661678ba7b8b3a2d75d6172e260e80 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 2 Aug 2023 16:03:05 +0200 Subject: [PATCH 077/446] PHPORM-35 Add various tests on Model `_id` types (#22) * PHPORM-35 Add various tests on Model _id * Add assertion on expected value * Test _id as array and object * Remove tests for arrays and objects as identifiers when keyType is string --------- Co-authored-by: Andreas Braun --- tests/ModelTest.php | 104 ++++++++++++++++++++++++++++++-- tests/Models/IdIsBinaryUuid.php | 17 ++++++ tests/Models/IdIsInt.php | 17 ++++++ tests/Models/IdIsString.php | 16 +++++ 4 files changed, 150 insertions(+), 4 deletions(-) create mode 100644 tests/Models/IdIsBinaryUuid.php create mode 100644 tests/Models/IdIsInt.php create mode 100644 tests/Models/IdIsString.php diff --git a/tests/ModelTest.php b/tests/ModelTest.php index 21523c7f4..1042a07bc 100644 --- a/tests/ModelTest.php +++ b/tests/ModelTest.php @@ -16,10 +16,14 @@ use Jenssegers\Mongodb\Eloquent\Model; use Jenssegers\Mongodb\Tests\Models\Book; use Jenssegers\Mongodb\Tests\Models\Guarded; +use Jenssegers\Mongodb\Tests\Models\IdIsBinaryUuid; +use Jenssegers\Mongodb\Tests\Models\IdIsInt; +use Jenssegers\Mongodb\Tests\Models\IdIsString; use Jenssegers\Mongodb\Tests\Models\Item; use Jenssegers\Mongodb\Tests\Models\MemberStatus; use Jenssegers\Mongodb\Tests\Models\Soft; use Jenssegers\Mongodb\Tests\Models\User; +use MongoDB\BSON\Binary; use MongoDB\BSON\ObjectID; use MongoDB\BSON\UTCDateTime; @@ -325,11 +329,103 @@ public function testSoftDelete(): void $this->assertEquals(2, Soft::count()); } - public function testPrimaryKey(): void + /** + * @dataProvider provideId + */ + public function testPrimaryKey(string $model, $id, $expected, bool $expectedFound): void + { + $model::truncate(); + $expectedType = get_debug_type($expected); + + $document = new $model; + $this->assertEquals('_id', $document->getKeyName()); + + $document->_id = $id; + $document->save(); + $this->assertSame($expectedType, get_debug_type($document->_id)); + $this->assertEquals($expected, $document->_id); + $this->assertSame($expectedType, get_debug_type($document->getKey())); + $this->assertEquals($expected, $document->getKey()); + + $check = $model::find($id); + + if ($expectedFound) { + $this->assertNotNull($check, 'Not found'); + $this->assertSame($expectedType, get_debug_type($check->_id)); + $this->assertEquals($id, $check->_id); + $this->assertSame($expectedType, get_debug_type($check->getKey())); + $this->assertEquals($id, $check->getKey()); + } else { + $this->assertNull($check, 'Found'); + } + } + + public static function provideId(): iterable + { + yield 'int' => [ + 'model' => User::class, + 'id' => 10, + 'expected' => 10, + // Don't expect this to be found, as the int is cast to string for the query + 'expectedFound' => false, + ]; + + yield 'cast as int' => [ + 'model' => IdIsInt::class, + 'id' => 10, + 'expected' => 10, + 'expectedFound' => true, + ]; + + yield 'string' => [ + 'model' => User::class, + 'id' => 'user-10', + 'expected' => 'user-10', + 'expectedFound' => true, + ]; + + yield 'cast as string' => [ + 'model' => IdIsString::class, + 'id' => 'user-10', + 'expected' => 'user-10', + 'expectedFound' => true, + ]; + + $objectId = new ObjectID(); + yield 'ObjectID' => [ + 'model' => User::class, + 'id' => $objectId, + 'expected' => (string) $objectId, + 'expectedFound' => true, + ]; + + $binaryUuid = new Binary(hex2bin('0c103357380648c9a84b867dcb625cfb'), Binary::TYPE_UUID); + yield 'BinaryUuid' => [ + 'model' => User::class, + 'id' => $binaryUuid, + 'expected' => (string) $binaryUuid, + 'expectedFound' => true, + ]; + + yield 'cast as BinaryUuid' => [ + 'model' => IdIsBinaryUuid::class, + 'id' => $binaryUuid, + 'expected' => (string) $binaryUuid, + 'expectedFound' => true, + ]; + + $date = new UTCDateTime(); + yield 'UTCDateTime' => [ + 'model' => User::class, + 'id' => $date, + 'expected' => $date, + // Don't expect this to be found, as the original value is stored as UTCDateTime but then cast to string + 'expectedFound' => false, + ]; + } + + public function testCustomPrimaryKey(): void { - $user = new User; - $this->assertEquals('_id', $user->getKeyName()); - $book = new Book; $this->assertEquals('title', $book->getKeyName()); diff --git a/tests/Models/IdIsBinaryUuid.php b/tests/Models/IdIsBinaryUuid.php new file mode 100644 index 000000000..1d8c59259 --- /dev/null +++ b/tests/Models/IdIsBinaryUuid.php @@ -0,0 +1,17 @@ + BinaryUuid::class, + ]; +} diff --git a/tests/Models/IdIsInt.php b/tests/Models/IdIsInt.php new file mode 100644 index 000000000..d721320c9 --- /dev/null +++ b/tests/Models/IdIsInt.php @@ -0,0 +1,17 @@ + 'int', + ]; +} diff --git a/tests/Models/IdIsString.php b/tests/Models/IdIsString.php new file mode 100644 index 000000000..48a284551 --- /dev/null +++ b/tests/Models/IdIsString.php @@ -0,0 +1,16 @@ + 'string', + ]; +} From e7d4034279a0b2aca0d6924ba30fe89782df94d0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 22 Aug 2023 15:24:08 +0200 Subject: [PATCH 078/446] Explicitly require PHP ^8.1 (#2574) Allows to use PHP 8.1 feature without relying on the transient dependency from laravel 10 --- composer.json | 1 + 1 file changed, 1 insertion(+) diff --git a/composer.json b/composer.json index 58bfb3c65..c628175f8 100644 --- a/composer.json +++ b/composer.json @@ -19,6 +19,7 @@ ], "license": "MIT", "require": { + "php": "^8.1", "ext-mongodb": "^1.15", "illuminate/support": "^10.0", "illuminate/container": "^10.0", From 0604d71264ae9f2b0c8166395bb11a5f6c44538c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 23 Aug 2023 11:18:52 +0200 Subject: [PATCH 079/446] Fix links in changelog (#2575) --- CHANGELOG.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 30413ef3b..c722c9b5b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,19 +3,19 @@ All notable changes to this project will be documented in this file. ## [Unreleased] -- Add classes to cast `ObjectId` and `UUID` instances [#1](https://github.com/GromNaN/laravel-mongodb-private/pull/1) by [@alcaeus](https://github.com/alcaeus). -- Add `Query\Builder::toMql()` to simplify comprehensive query tests [#6](https://github.com/GromNaN/laravel-mongodb-private/pull/6) by [@GromNaN](https://github.com/GromNaN). -- Fix `Query\Builder::whereNot` to use MongoDB [`$not`](https://www.mongodb.com/docs/manual/reference/operator/query/not/) operator [#13](https://github.com/GromNaN/laravel-mongodb-private/pull/13) by [@GromNaN](https://github.com/GromNaN). -- Fix `Query\Builder::whereBetween` to accept `Carbon\Period` object [#10](https://github.com/GromNaN/laravel-mongodb-private/pull/10) by [@GromNaN](https://github.com/GromNaN). -- Throw an exception for unsupported `Query\Builder` methods [#9](https://github.com/GromNaN/laravel-mongodb-private/pull/9) by [@GromNaN](https://github.com/GromNaN). -- Throw an exception when `Query\Builder::orderBy()` is used with invalid direction [#7](https://github.com/GromNaN/laravel-mongodb-private/pull/7) by [@GromNaN](https://github.com/GromNaN). -- Throw an exception when `Query\Builder::push()` is used incorrectly [#5](https://github.com/GromNaN/laravel-mongodb-private/pull/5) by [@GromNaN](https://github.com/GromNaN). -- Remove public property `Query\Builder::$paginating` [#15](https://github.com/GromNaN/laravel-mongodb-private/pull/15) by [@GromNaN](https://github.com/GromNaN). -- Remove call to deprecated `Collection::count` for `countDocuments` [#18](https://github.com/GromNaN/laravel-mongodb-private/pull/18) by [@GromNaN](https://github.com/GromNaN). -- Accept operators prefixed by `$` in `Query\Builder::orWhere` [#20](https://github.com/GromNaN/laravel-mongodb-private/pull/20) by [@GromNaN](https://github.com/GromNaN). -- Remove `Query\Builder::whereAll($column, $values)`. Use `Query\Builder::where($column, 'all', $values)` instead. [#16](https://github.com/GromNaN/laravel-mongodb-private/pull/16) by [@GromNaN](https://github.com/GromNaN). -- Fix validation of unique values when the validated value is found as part of an existing value. [#21](https://github.com/GromNaN/laravel-mongodb-private/pull/21) by [@GromNaN](https://github.com/GromNaN). -- Support `%` and `_` in `like` expression [#17](https://github.com/GromNaN/laravel-mongodb-private/pull/17) by [@GromNaN](https://github.com/GromNaN). +- Add classes to cast `ObjectId` and `UUID` instances [#1](https://github.com/GromNaN/laravel-mongodb/pull/1) by [@alcaeus](https://github.com/alcaeus). +- Add `Query\Builder::toMql()` to simplify comprehensive query tests [#6](https://github.com/GromNaN/laravel-mongodb/pull/6) by [@GromNaN](https://github.com/GromNaN). +- Fix `Query\Builder::whereNot` to use MongoDB [`$not`](https://www.mongodb.com/docs/manual/reference/operator/query/not/) operator [#13](https://github.com/GromNaN/laravel-mongodb/pull/13) by [@GromNaN](https://github.com/GromNaN). +- Fix `Query\Builder::whereBetween` to accept `Carbon\Period` object [#10](https://github.com/GromNaN/laravel-mongodb/pull/10) by [@GromNaN](https://github.com/GromNaN). +- Throw an exception for unsupported `Query\Builder` methods [#9](https://github.com/GromNaN/laravel-mongodb/pull/9) by [@GromNaN](https://github.com/GromNaN). +- Throw an exception when `Query\Builder::orderBy()` is used with invalid direction [#7](https://github.com/GromNaN/laravel-mongodb/pull/7) by [@GromNaN](https://github.com/GromNaN). +- Throw an exception when `Query\Builder::push()` is used incorrectly [#5](https://github.com/GromNaN/laravel-mongodb/pull/5) by [@GromNaN](https://github.com/GromNaN). +- Remove public property `Query\Builder::$paginating` [#15](https://github.com/GromNaN/laravel-mongodb/pull/15) by [@GromNaN](https://github.com/GromNaN). +- Remove call to deprecated `Collection::count` for `countDocuments` [#18](https://github.com/GromNaN/laravel-mongodb/pull/18) by [@GromNaN](https://github.com/GromNaN). +- Accept operators prefixed by `$` in `Query\Builder::orWhere` [#20](https://github.com/GromNaN/laravel-mongodb/pull/20) by [@GromNaN](https://github.com/GromNaN). +- Remove `Query\Builder::whereAll($column, $values)`. Use `Query\Builder::where($column, 'all', $values)` instead. [#16](https://github.com/GromNaN/laravel-mongodb/pull/16) by [@GromNaN](https://github.com/GromNaN). +- Fix validation of unique values when the validated value is found as part of an existing value. [#21](https://github.com/GromNaN/laravel-mongodb/pull/21) by [@GromNaN](https://github.com/GromNaN). +- Support `%` and `_` in `like` expression [#17](https://github.com/GromNaN/laravel-mongodb/pull/17) by [@GromNaN](https://github.com/GromNaN). ## [3.9.2] - 2022-09-01 From 7d3be9ffc03e0ae9306fc2fe00d33e7d409a5c48 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 23 Aug 2023 11:20:30 +0200 Subject: [PATCH 080/446] Remove calls to `Str::contains` and `Arr::get` when not necessary (#2571) * Replace Laravel Str helpers with native PHP8 functions * Remove Arr::get where not necessary --- src/Connection.php | 3 +-- src/Eloquent/Model.php | 6 +++--- src/Query/Builder.php | 5 ++--- src/Queue/MongoConnector.php | 5 ++--- 4 files changed, 8 insertions(+), 11 deletions(-) diff --git a/src/Connection.php b/src/Connection.php index 278642081..d6ed508a4 100644 --- a/src/Connection.php +++ b/src/Connection.php @@ -5,7 +5,6 @@ use function class_exists; use Composer\InstalledVersions; use Illuminate\Database\Connection as BaseConnection; -use Illuminate\Support\Arr; use InvalidArgumentException; use Jenssegers\Mongodb\Concerns\ManagesTransactions; use MongoDB\Client; @@ -48,7 +47,7 @@ public function __construct(array $config) $dsn = $this->getDsn($config); // You can pass options directly to the MongoDB constructor - $options = Arr::get($config, 'options', []); + $options = $config['options'] ?? []; // Create the connection $this->connection = $this->createConnection($dsn, $config, $options); diff --git a/src/Eloquent/Model.php b/src/Eloquent/Model.php index 2d985f627..1c66f7652 100644 --- a/src/Eloquent/Model.php +++ b/src/Eloquent/Model.php @@ -155,7 +155,7 @@ public function getAttribute($key) } // Dot notation support. - if (Str::contains($key, '.') && Arr::has($this->attributes, $key)) { + if (str_contains($key, '.') && Arr::has($this->attributes, $key)) { return $this->getAttributeValue($key); } @@ -177,7 +177,7 @@ public function getAttribute($key) protected function getAttributeFromArray($key) { // Support keys in dot notation. - if (Str::contains($key, '.')) { + if (str_contains($key, '.')) { return Arr::get($this->attributes, $key); } @@ -195,7 +195,7 @@ public function setAttribute($key, $value) $value = $builder->convertKey($value); } // Support keys in dot notation. - elseif (Str::contains($key, '.')) { + elseif (str_contains($key, '.')) { // Store to a temporary key, then move data to the actual key $uniqueKey = uniqid($key); parent::setAttribute($uniqueKey, $value); diff --git a/src/Query/Builder.php b/src/Query/Builder.php index dd448ed01..69bcd8ea0 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -10,7 +10,6 @@ use Illuminate\Support\Arr; use Illuminate\Support\Collection; use Illuminate\Support\LazyCollection; -use Illuminate\Support\Str; use Jenssegers\Mongodb\Connection; use MongoDB\BSON\Binary; use MongoDB\BSON\ObjectID; @@ -617,7 +616,7 @@ public function insertGetId(array $values, $sequence = null) public function update(array $values, array $options = []) { // Use $set as default operator. - if (! Str::startsWith(key($values), '$')) { + if (! str_starts_with(key($values), '$')) { $values = ['$set' => $values]; } @@ -951,7 +950,7 @@ protected function compileWheres(): array } // Convert id's. - if (isset($where['column']) && ($where['column'] == '_id' || Str::endsWith($where['column'], '._id'))) { + if (isset($where['column']) && ($where['column'] == '_id' || str_ends_with($where['column'], '._id'))) { // Multiple values. if (isset($where['values'])) { foreach ($where['values'] as &$value) { diff --git a/src/Queue/MongoConnector.php b/src/Queue/MongoConnector.php index f453ba0a4..8e74e59d0 100644 --- a/src/Queue/MongoConnector.php +++ b/src/Queue/MongoConnector.php @@ -4,7 +4,6 @@ use Illuminate\Database\ConnectionResolverInterface; use Illuminate\Queue\Connectors\ConnectorInterface; -use Illuminate\Support\Arr; class MongoConnector implements ConnectorInterface { @@ -34,10 +33,10 @@ public function __construct(ConnectionResolverInterface $connections) public function connect(array $config) { return new MongoQueue( - $this->connections->connection(Arr::get($config, 'connection')), + $this->connections->connection($config['connection'] ?? null), $config['table'], $config['queue'], - Arr::get($config, 'expire', 60) + $config['expire'] ?? 60 ); } } From b4842886e736f17b833894c7331bda51ecd38c1a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 23 Aug 2023 11:21:59 +0200 Subject: [PATCH 081/446] Remove Eloquent\Builder::chunkById() already having the correct id field in laravel (#2569) --- src/Eloquent/Builder.php | 8 -------- tests/ModelTest.php | 8 ++++---- 2 files changed, 4 insertions(+), 12 deletions(-) diff --git a/src/Eloquent/Builder.php b/src/Eloquent/Builder.php index 84e93b83f..61a9de4b1 100644 --- a/src/Eloquent/Builder.php +++ b/src/Eloquent/Builder.php @@ -153,14 +153,6 @@ public function decrement($column, $amount = 1, array $extra = []) return parent::decrement($column, $amount, $extra); } - /** - * @inheritdoc - */ - public function chunkById($count, callable $callback, $column = '_id', $alias = null) - { - return parent::chunkById($count, $callback, $column, $alias); - } - /** * @inheritdoc */ diff --git a/tests/ModelTest.php b/tests/ModelTest.php index 1042a07bc..1fe71f266 100644 --- a/tests/ModelTest.php +++ b/tests/ModelTest.php @@ -834,12 +834,12 @@ public function testChunkById(): void User::create(['name' => 'spork', 'tags' => ['sharp', 'pointy', 'round', 'bowl']]); User::create(['name' => 'spoon', 'tags' => ['round', 'bowl']]); - $count = 0; - User::chunkById(2, function (EloquentCollection $items) use (&$count) { - $count += count($items); + $names = []; + User::chunkById(2, function (EloquentCollection $items) use (&$names) { + $names = array_merge($names, $items->pluck('name')->all()); }); - $this->assertEquals(3, $count); + $this->assertEquals(['fork', 'spork', 'spoon'], $names); } public function testTruncateModel() From 6c7df455153de9cc952d742180c2d90a004eab06 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 23 Aug 2023 11:27:28 +0200 Subject: [PATCH 082/446] Remove Query\Builder::__constructor overload (#2570) --- CHANGELOG.md | 1 + src/Connection.php | 2 +- src/Eloquent/Builder.php | 4 ++-- src/Eloquent/Model.php | 2 +- src/Query/Builder.php | 24 ++++++++---------------- tests/Query/BuilderTest.php | 4 +++- 6 files changed, 16 insertions(+), 21 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c722c9b5b..60c10feb8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,7 @@ All notable changes to this project will be documented in this file. - Remove `Query\Builder::whereAll($column, $values)`. Use `Query\Builder::where($column, 'all', $values)` instead. [#16](https://github.com/GromNaN/laravel-mongodb/pull/16) by [@GromNaN](https://github.com/GromNaN). - Fix validation of unique values when the validated value is found as part of an existing value. [#21](https://github.com/GromNaN/laravel-mongodb/pull/21) by [@GromNaN](https://github.com/GromNaN). - Support `%` and `_` in `like` expression [#17](https://github.com/GromNaN/laravel-mongodb/pull/17) by [@GromNaN](https://github.com/GromNaN). +- Change signature of `Query\Builder::__constructor` to match the parent class [#26](https://github.com/GromNaN/laravel-mongodb-private/pull/26) by [@GromNaN](https://github.com/GromNaN). ## [3.9.2] - 2022-09-01 diff --git a/src/Connection.php b/src/Connection.php index d6ed508a4..e2b036b4b 100644 --- a/src/Connection.php +++ b/src/Connection.php @@ -73,7 +73,7 @@ public function __construct(array $config) */ public function collection($collection) { - $query = new Query\Builder($this, $this->getPostProcessor()); + $query = new Query\Builder($this, $this->getQueryGrammar(), $this->getPostProcessor()); return $query->from($collection); } diff --git a/src/Eloquent/Builder.php b/src/Eloquent/Builder.php index 61a9de4b1..a0619f3d9 100644 --- a/src/Eloquent/Builder.php +++ b/src/Eloquent/Builder.php @@ -156,10 +156,10 @@ public function decrement($column, $amount = 1, array $extra = []) /** * @inheritdoc */ - public function raw($expression = null) + public function raw($value = null) { // Get raw results from the query builder. - $results = $this->query->raw($expression); + $results = $this->query->raw($value); // Convert MongoCursor results to a collection of models. if ($results instanceof Cursor) { diff --git a/src/Eloquent/Model.php b/src/Eloquent/Model.php index 1c66f7652..ff7f9a175 100644 --- a/src/Eloquent/Model.php +++ b/src/Eloquent/Model.php @@ -433,7 +433,7 @@ protected function newBaseQueryBuilder() { $connection = $this->getConnection(); - return new QueryBuilder($connection, $connection->getPostProcessor()); + return new QueryBuilder($connection, $connection->getQueryGrammar(), $connection->getPostProcessor()); } /** diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 69bcd8ea0..a65edd24a 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -133,16 +133,6 @@ class Builder extends BaseBuilder 'uniquedocs' => 'uniqueDocs', ]; - /** - * @inheritdoc - */ - public function __construct(Connection $connection, Processor $processor) - { - $this->grammar = new Grammar; - $this->connection = $connection; - $this->processor = $processor; - } - /** * Set the projections. * @@ -757,16 +747,16 @@ public function lists($column, $key = null) /** * @inheritdoc */ - public function raw($expression = null) + public function raw($value = null) { // Execute the closure on the mongodb collection - if ($expression instanceof Closure) { - return call_user_func($expression, $this->collection); + if ($value instanceof Closure) { + return call_user_func($value, $this->collection); } // Create an expression for the given value - if ($expression !== null) { - return new Expression($expression); + if ($value !== null) { + return new Expression($value); } // Quick access to the mongodb collection @@ -852,10 +842,12 @@ public function drop($columns) /** * @inheritdoc + * + * @return static */ public function newQuery() { - return new self($this->connection, $this->processor); + return new static($this->connection, $this->grammar, $this->processor); } /** diff --git a/tests/Query/BuilderTest.php b/tests/Query/BuilderTest.php index f34642274..60c05e23f 100644 --- a/tests/Query/BuilderTest.php +++ b/tests/Query/BuilderTest.php @@ -9,6 +9,7 @@ use Illuminate\Tests\Database\DatabaseQueryBuilderTest; use Jenssegers\Mongodb\Connection; use Jenssegers\Mongodb\Query\Builder; +use Jenssegers\Mongodb\Query\Grammar; use Jenssegers\Mongodb\Query\Processor; use Mockery as m; use MongoDB\BSON\Regex; @@ -838,7 +839,8 @@ private static function getBuilder(): Builder $connection = m::mock(Connection::class); $processor = m::mock(Processor::class); $connection->shouldReceive('getSession')->andReturn(null); + $connection->shouldReceive('getQueryGrammar')->andReturn(new Grammar()); - return new Builder($connection, $processor); + return new Builder($connection, null, $processor); } } From af13edaa6ae819b55c1eb7a72723805624d2f49a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 23 Aug 2023 12:38:28 +0200 Subject: [PATCH 083/446] PHPORM-68 Fix partial value un exist validator (#2568) * PHPORM-68 Fix partial value un exist validator * escape values for regex --- src/Validation/DatabasePresenceVerifier.php | 9 +++++-- tests/ValidationTest.php | 26 +++++++++++++++++++++ 2 files changed, 33 insertions(+), 2 deletions(-) diff --git a/src/Validation/DatabasePresenceVerifier.php b/src/Validation/DatabasePresenceVerifier.php index c563a9976..fee8ef610 100644 --- a/src/Validation/DatabasePresenceVerifier.php +++ b/src/Validation/DatabasePresenceVerifier.php @@ -43,8 +43,13 @@ public function getCount($collection, $column, $value, $excludeId = null, $idCol */ public function getMultiCount($collection, $column, array $values, array $extra = []) { - // Generates a regex like '/(a|b|c)/i' which can query multiple values - $regex = '/('.implode('|', $values).')/i'; + // Nothing can match an empty array. Return early to avoid matching an empty string. + if ($values === []) { + return 0; + } + + // Generates a regex like '/^(a|b|c)$/i' which can query multiple values + $regex = new Regex('^('.implode('|', array_map(preg_quote(...), $values)).')$', 'i'); $query = $this->table($collection)->where($column, 'regex', $regex); diff --git a/tests/ValidationTest.php b/tests/ValidationTest.php index 5a0459215..63f074de3 100644 --- a/tests/ValidationTest.php +++ b/tests/ValidationTest.php @@ -103,5 +103,31 @@ public function testExists(): void ['name' => 'required|exists:users'] ); $this->assertFalse($validator->fails()); + + $validator = Validator::make( + ['name' => ['test name', 'john']], // Part of an existing value + ['name' => 'required|exists:users'] + ); + $this->assertTrue($validator->fails()); + + $validator = Validator::make( + ['name' => '(invalid regex{'], + ['name' => 'required|exists:users'] + ); + $this->assertTrue($validator->fails()); + + $validator = Validator::make( + ['name' => ['foo', '(invalid regex{']], + ['name' => 'required|exists:users'] + ); + $this->assertTrue($validator->fails()); + + User::create(['name' => '']); + + $validator = Validator::make( + ['name' => []], + ['name' => 'exists:users'] + ); + $this->assertFalse($validator->fails()); } } From f33041290d9dfc57e80b5ea250d4c7addee657f8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Fri, 25 Aug 2023 14:58:17 +0200 Subject: [PATCH 084/446] PHPORM-60 Fix Query on whereDate, whereDay, whereMonth, whereYear (#2572) * Fix whereDate, whereMonth, whereYear, whereTime to use $expr and respective query rather than using basic comparison * Add and fix tests * Fix whereDate * PHPORM-60 Native support for whereTime * Remove magic extract to use explicit array access to options * Update whereDate * Support various time formats in whereTime --------- Co-authored-by: David --- CHANGELOG.md | 1 + src/Query/Builder.php | 107 +++++++++++++++------ tests/Models/Birthday.php | 9 +- tests/Query/BuilderTest.php | 182 ++++++++++++++++++++++++++++++++++++ tests/QueryTest.php | 73 +++++++++++---- 5 files changed, 324 insertions(+), 48 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 60c10feb8..fc10adb59 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,7 @@ All notable changes to this project will be documented in this file. - Fix validation of unique values when the validated value is found as part of an existing value. [#21](https://github.com/GromNaN/laravel-mongodb/pull/21) by [@GromNaN](https://github.com/GromNaN). - Support `%` and `_` in `like` expression [#17](https://github.com/GromNaN/laravel-mongodb/pull/17) by [@GromNaN](https://github.com/GromNaN). - Change signature of `Query\Builder::__constructor` to match the parent class [#26](https://github.com/GromNaN/laravel-mongodb-private/pull/26) by [@GromNaN](https://github.com/GromNaN). +- Fix Query on `whereDate`, `whereDay`, `whereMonth`, `whereYear`, `whereTime` to use MongoDB operators [#2570](https://github.com/jenssegers/laravel-mongodb/pull/2376) by [@Davpyu](https://github.com/Davpyu) and [@GromNaN](https://github.com/GromNaN). ## [3.9.2] - 2022-09-01 diff --git a/src/Query/Builder.php b/src/Query/Builder.php index a65edd24a..682c70c19 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -8,6 +8,7 @@ use Illuminate\Database\Query\Builder as BaseBuilder; use Illuminate\Database\Query\Expression; use Illuminate\Support\Arr; +use Illuminate\Support\Carbon; use Illuminate\Support\Collection; use Illuminate\Support\LazyCollection; use Jenssegers\Mongodb\Connection; @@ -115,6 +116,7 @@ class Builder extends BaseBuilder * @var array */ protected $conversion = [ + '=' => 'eq', '!=' => 'ne', '<>' => 'ne', '<' => 'lt', @@ -1075,7 +1077,7 @@ protected function compileWhereBasic(array $where): array $operator = $operator === 'regex' ? '=' : 'not'; } - if (! isset($operator) || $operator == '=') { + if (! isset($operator) || $operator === '=' || $operator === 'eq') { $query = [$column => $value]; } else { $query = [$column => ['$'.$operator => $value]]; @@ -1180,12 +1182,35 @@ protected function compileWhereBetween(array $where): array */ protected function compileWhereDate(array $where): array { - extract($where); - - $where['operator'] = $operator; - $where['value'] = $value; + $startOfDay = new UTCDateTime(Carbon::parse($where['value'])->startOfDay()); + $endOfDay = new UTCDateTime(Carbon::parse($where['value'])->endOfDay()); - return $this->compileWhereBasic($where); + return match($where['operator']) { + 'eq', '=' => [ + $where['column'] => [ + '$gte' => $startOfDay, + '$lte' => $endOfDay, + ], + ], + 'ne' => [ + $where['column'] => [ + '$not' => [ + '$gte' => $startOfDay, + '$lte' => $endOfDay, + ], + ], + ], + 'lt', 'gte' => [ + $where['column'] => [ + '$'.$where['operator'] => $startOfDay, + ], + ], + 'gt', 'lte' => [ + $where['column'] => [ + '$'.$where['operator'] => $endOfDay, + ], + ], + }; } /** @@ -1194,12 +1219,16 @@ protected function compileWhereDate(array $where): array */ protected function compileWhereMonth(array $where): array { - extract($where); - - $where['operator'] = $operator; - $where['value'] = $value; - - return $this->compileWhereBasic($where); + return [ + '$expr' => [ + '$'.$where['operator'] => [ + [ + '$month' => '$'.$where['column'], + ], + (int) $where['value'], + ], + ], + ]; } /** @@ -1208,12 +1237,16 @@ protected function compileWhereMonth(array $where): array */ protected function compileWhereDay(array $where): array { - extract($where); - - $where['operator'] = $operator; - $where['value'] = $value; - - return $this->compileWhereBasic($where); + return [ + '$expr' => [ + '$'.$where['operator'] => [ + [ + '$dayOfMonth' => '$'.$where['column'], + ], + (int) $where['value'], + ], + ], + ]; } /** @@ -1222,12 +1255,16 @@ protected function compileWhereDay(array $where): array */ protected function compileWhereYear(array $where): array { - extract($where); - - $where['operator'] = $operator; - $where['value'] = $value; - - return $this->compileWhereBasic($where); + return [ + '$expr' => [ + '$'.$where['operator'] => [ + [ + '$year' => '$'.$where['column'], + ], + (int) $where['value'], + ], + ], + ]; } /** @@ -1236,12 +1273,26 @@ protected function compileWhereYear(array $where): array */ protected function compileWhereTime(array $where): array { - extract($where); + if (! is_string($where['value']) || ! preg_match('/^[0-2][0-9](:[0-6][0-9](:[0-6][0-9])?)?$/', $where['value'], $matches)) { + throw new \InvalidArgumentException(sprintf('Invalid time format, expected HH:MM:SS, HH:MM or HH, got "%s"', is_string($where['value']) ? $where['value'] : get_debug_type($where['value']))); + } - $where['operator'] = $operator; - $where['value'] = $value; + $format = match (count($matches)) { + 1 => '%H', + 2 => '%H:%M', + 3 => '%H:%M:%S', + }; - return $this->compileWhereBasic($where); + return [ + '$expr' => [ + '$'.$where['operator'] => [ + [ + '$dateToString' => ['date' => '$'.$where['column'], 'format' => $format], + ], + $where['value'], + ], + ], + ]; } /** diff --git a/tests/Models/Birthday.php b/tests/Models/Birthday.php index 2afca41e0..712d18d3f 100644 --- a/tests/Models/Birthday.php +++ b/tests/Models/Birthday.php @@ -11,14 +11,15 @@ * * @property string $name * @property string $birthday - * @property string $day - * @property string $month - * @property string $year * @property string $time */ class Birthday extends Eloquent { protected $connection = 'mongodb'; protected $collection = 'birthday'; - protected $fillable = ['name', 'birthday', 'day', 'month', 'year', 'time']; + protected $fillable = ['name', 'birthday']; + + protected $casts = [ + 'birthday' => 'datetime', + ]; } diff --git a/tests/Query/BuilderTest.php b/tests/Query/BuilderTest.php index 60c05e23f..8e76840af 100644 --- a/tests/Query/BuilderTest.php +++ b/tests/Query/BuilderTest.php @@ -646,6 +646,170 @@ function (Builder $builder) { fn (Builder $builder) => $builder->where('name', 'not regex', '/^acme$/si'), ]; + yield 'where date' => [ + ['find' => [['created_at' => [ + '$gte' => new UTCDateTime(new DateTimeImmutable('2018-09-30 00:00:00.000 +00:00')), + '$lte' => new UTCDateTime(new DateTimeImmutable('2018-09-30 23:59:59.999 +00:00')), + ]], []]], + fn (Builder $builder) => $builder->whereDate('created_at', '2018-09-30'), + ]; + + yield 'where date DateTimeImmutable' => [ + ['find' => [['created_at' => [ + '$gte' => new UTCDateTime(new DateTimeImmutable('2018-09-30 00:00:00.000 +00:00')), + '$lte' => new UTCDateTime(new DateTimeImmutable('2018-09-30 23:59:59.999 +00:00')), + ]], []]], + fn (Builder $builder) => $builder->whereDate('created_at', '=', new DateTimeImmutable('2018-09-30 15:00:00 +02:00')), + ]; + + yield 'where date !=' => [ + ['find' => [['created_at' => [ + '$not' => [ + '$gte' => new UTCDateTime(new DateTimeImmutable('2018-09-30 00:00:00.000 +00:00')), + '$lte' => new UTCDateTime(new DateTimeImmutable('2018-09-30 23:59:59.999 +00:00')), + ], + ]], []]], + fn (Builder $builder) => $builder->whereDate('created_at', '!=', '2018-09-30'), + ]; + + yield 'where date <' => [ + ['find' => [['created_at' => [ + '$lt' => new UTCDateTime(new DateTimeImmutable('2018-09-30 00:00:00.000 +00:00')), + ]], []]], + fn (Builder $builder) => $builder->whereDate('created_at', '<', '2018-09-30'), + ]; + + yield 'where date >=' => [ + ['find' => [['created_at' => [ + '$gte' => new UTCDateTime(new DateTimeImmutable('2018-09-30 00:00:00.000 +00:00')), + ]], []]], + fn (Builder $builder) => $builder->whereDate('created_at', '>=', '2018-09-30'), + ]; + + yield 'where date >' => [ + ['find' => [['created_at' => [ + '$gt' => new UTCDateTime(new DateTimeImmutable('2018-09-30 23:59:59.999 +00:00')), + ]], []]], + fn (Builder $builder) => $builder->whereDate('created_at', '>', '2018-09-30'), + ]; + + yield 'where date <=' => [ + ['find' => [['created_at' => [ + '$lte' => new UTCDateTime(new DateTimeImmutable('2018-09-30 23:59:59.999 +00:00')), + ]], []]], + fn (Builder $builder) => $builder->whereDate('created_at', '<=', '2018-09-30'), + ]; + + yield 'where day' => [ + ['find' => [['$expr' => [ + '$eq' => [ + ['$dayOfMonth' => '$created_at'], + 5, + ], + ]], []]], + fn (Builder $builder) => $builder->whereDay('created_at', 5), + ]; + + yield 'where day > string' => [ + ['find' => [['$expr' => [ + '$gt' => [ + ['$dayOfMonth' => '$created_at'], + 5, + ], + ]], []]], + fn (Builder $builder) => $builder->whereDay('created_at', '>', '05'), + ]; + + yield 'where month' => [ + ['find' => [['$expr' => [ + '$eq' => [ + ['$month' => '$created_at'], + 10, + ], + ]], []]], + fn (Builder $builder) => $builder->whereMonth('created_at', 10), + ]; + + yield 'where month > string' => [ + ['find' => [['$expr' => [ + '$gt' => [ + ['$month' => '$created_at'], + 5, + ], + ]], []]], + fn (Builder $builder) => $builder->whereMonth('created_at', '>', '05'), + ]; + + yield 'where year' => [ + ['find' => [['$expr' => [ + '$eq' => [ + ['$year' => '$created_at'], + 2023, + ], + ]], []]], + fn (Builder $builder) => $builder->whereYear('created_at', 2023), + ]; + + yield 'where year > string' => [ + ['find' => [['$expr' => [ + '$gt' => [ + ['$year' => '$created_at'], + 2023, + ], + ]], []]], + fn (Builder $builder) => $builder->whereYear('created_at', '>', '2023'), + ]; + + yield 'where time HH:MM:SS' => [ + ['find' => [['$expr' => [ + '$eq' => [ + ['$dateToString' => ['date' => '$created_at', 'format' => '%H:%M:%S']], + '10:11:12', + ], + ]], []]], + fn (Builder $builder) => $builder->whereTime('created_at', '10:11:12'), + ]; + + yield 'where time HH:MM' => [ + ['find' => [['$expr' => [ + '$eq' => [ + ['$dateToString' => ['date' => '$created_at', 'format' => '%H:%M']], + '10:11', + ], + ]], []]], + fn (Builder $builder) => $builder->whereTime('created_at', '10:11'), + ]; + + yield 'where time HH' => [ + ['find' => [['$expr' => [ + '$eq' => [ + ['$dateToString' => ['date' => '$created_at', 'format' => '%H']], + '10', + ], + ]], []]], + fn (Builder $builder) => $builder->whereTime('created_at', '10'), + ]; + + yield 'where time DateTime' => [ + ['find' => [['$expr' => [ + '$eq' => [ + ['$dateToString' => ['date' => '$created_at', 'format' => '%H:%M:%S']], + '10:11:12', + ], + ]], []]], + fn (Builder $builder) => $builder->whereTime('created_at', new \DateTimeImmutable('2023-08-22 10:11:12')), + ]; + + yield 'where time >' => [ + ['find' => [['$expr' => [ + '$gt' => [ + ['$dateToString' => ['date' => '$created_at', 'format' => '%H:%M:%S']], + '10:11:12', + ], + ]], []]], + fn (Builder $builder) => $builder->whereTime('created_at', '>', '10:11:12'), + ]; + /** @see DatabaseQueryBuilderTest::testBasicSelectDistinct */ yield 'distinct' => [ ['distinct' => ['foo', [], []]], @@ -774,6 +938,24 @@ public static function provideExceptions(): iterable 'Missing expected ending delimiter "/" in regular expression "/foo#bar"', fn (Builder $builder) => $builder->where('name', 'regex', '/foo#bar'), ]; + + yield 'whereTime with invalid time' => [ + \InvalidArgumentException::class, + 'Invalid time format, expected HH:MM:SS, HH:MM or HH, got "10:11:12:13"', + fn (Builder $builder) => $builder->whereTime('created_at', '10:11:12:13'), + ]; + + yield 'whereTime out of range' => [ + \InvalidArgumentException::class, + 'Invalid time format, expected HH:MM:SS, HH:MM or HH, got "23:70"', + fn (Builder $builder) => $builder->whereTime('created_at', '23:70'), + ]; + + yield 'whereTime invalid type' => [ + \InvalidArgumentException::class, + 'Invalid time format, expected HH:MM:SS, HH:MM or HH, got "stdClass"', + fn (Builder $builder) => $builder->whereTime('created_at', new \stdClass()), + ]; } /** @dataProvider getEloquentMethodsNotSupported */ diff --git a/tests/QueryTest.php b/tests/QueryTest.php index 754f204dc..8737a7d68 100644 --- a/tests/QueryTest.php +++ b/tests/QueryTest.php @@ -4,6 +4,7 @@ namespace Jenssegers\Mongodb\Tests; +use DateTimeImmutable; use Jenssegers\Mongodb\Tests\Models\Birthday; use Jenssegers\Mongodb\Tests\Models\Scoped; use Jenssegers\Mongodb\Tests\Models\User; @@ -24,12 +25,13 @@ public function setUp(): void User::create(['name' => 'Tommy Toe', 'age' => 33, 'title' => 'user']); User::create(['name' => 'Yvonne Yoe', 'age' => 35, 'title' => 'admin']); User::create(['name' => 'Error', 'age' => null, 'title' => null]); - Birthday::create(['name' => 'Mark Moe', 'birthday' => '2020-04-10', 'day' => '10', 'month' => '04', 'year' => '2020', 'time' => '10:53:11']); - Birthday::create(['name' => 'Jane Doe', 'birthday' => '2021-05-12', 'day' => '12', 'month' => '05', 'year' => '2021', 'time' => '10:53:12']); - Birthday::create(['name' => 'Harry Hoe', 'birthday' => '2021-05-11', 'day' => '11', 'month' => '05', 'year' => '2021', 'time' => '10:53:13']); - Birthday::create(['name' => 'Robert Doe', 'birthday' => '2021-05-12', 'day' => '12', 'month' => '05', 'year' => '2021', 'time' => '10:53:14']); - Birthday::create(['name' => 'Mark Moe', 'birthday' => '2021-05-12', 'day' => '12', 'month' => '05', 'year' => '2021', 'time' => '10:53:15']); - Birthday::create(['name' => 'Mark Moe', 'birthday' => '2022-05-12', 'day' => '12', 'month' => '05', 'year' => '2022', 'time' => '10:53:16']); + Birthday::create(['name' => 'Mark Moe', 'birthday' => new DateTimeImmutable('2020-04-10 10:53:11')]); + Birthday::create(['name' => 'Jane Doe', 'birthday' => new DateTimeImmutable('2021-05-12 10:53:12')]); + Birthday::create(['name' => 'Harry Hoe', 'birthday' => new DateTimeImmutable('2021-05-11 10:53:13')]); + Birthday::create(['name' => 'Robert Doe', 'birthday' => new DateTimeImmutable('2021-05-12 10:53:14')]); + Birthday::create(['name' => 'Mark Moe', 'birthday' => new DateTimeImmutable('2021-05-12 10:53:15')]); + Birthday::create(['name' => 'Mark Moe', 'birthday' => new DateTimeImmutable('2022-05-12 10:53:16')]); + Birthday::create(['name' => 'Boo']); } public function tearDown(): void @@ -204,45 +206,84 @@ public function testWhereDate(): void $birthdayCount = Birthday::whereDate('birthday', '2021-05-11')->get(); $this->assertCount(1, $birthdayCount); + + $birthdayCount = Birthday::whereDate('birthday', '>', '2021-05-11')->get(); + $this->assertCount(4, $birthdayCount); + + $birthdayCount = Birthday::whereDate('birthday', '>=', '2021-05-11')->get(); + $this->assertCount(5, $birthdayCount); + + $birthdayCount = Birthday::whereDate('birthday', '<', '2021-05-11')->get(); + $this->assertCount(1, $birthdayCount); + + $birthdayCount = Birthday::whereDate('birthday', '<=', '2021-05-11')->get(); + $this->assertCount(2, $birthdayCount); + + $birthdayCount = Birthday::whereDate('birthday', '<>', '2021-05-11')->get(); + $this->assertCount(6, $birthdayCount); } public function testWhereDay(): void { - $day = Birthday::whereDay('day', '12')->get(); + $day = Birthday::whereDay('birthday', '12')->get(); $this->assertCount(4, $day); - $day = Birthday::whereDay('day', '11')->get(); + $day = Birthday::whereDay('birthday', '11')->get(); $this->assertCount(1, $day); } public function testWhereMonth(): void { - $month = Birthday::whereMonth('month', '04')->get(); + $month = Birthday::whereMonth('birthday', '04')->get(); $this->assertCount(1, $month); - $month = Birthday::whereMonth('month', '05')->get(); + $month = Birthday::whereMonth('birthday', '05')->get(); + $this->assertCount(5, $month); + + $month = Birthday::whereMonth('birthday', '>=', '5')->get(); $this->assertCount(5, $month); + + $month = Birthday::whereMonth('birthday', '<', '10')->get(); + $this->assertCount(7, $month); + + $month = Birthday::whereMonth('birthday', '<>', '5')->get(); + $this->assertCount(2, $month); } public function testWhereYear(): void { - $year = Birthday::whereYear('year', '2021')->get(); + $year = Birthday::whereYear('birthday', '2021')->get(); $this->assertCount(4, $year); - $year = Birthday::whereYear('year', '2022')->get(); + $year = Birthday::whereYear('birthday', '2022')->get(); $this->assertCount(1, $year); - $year = Birthday::whereYear('year', '<', '2021')->get(); - $this->assertCount(1, $year); + $year = Birthday::whereYear('birthday', '<', '2021')->get(); + $this->assertCount(2, $year); + + $year = Birthday::whereYear('birthday', '<>', '2021')->get(); + $this->assertCount(3, $year); } public function testWhereTime(): void { - $time = Birthday::whereTime('time', '10:53:11')->get(); + $time = Birthday::whereTime('birthday', '10:53:11')->get(); $this->assertCount(1, $time); - $time = Birthday::whereTime('time', '>=', '10:53:14')->get(); + $time = Birthday::whereTime('birthday', '10:53')->get(); + $this->assertCount(6, $time); + + $time = Birthday::whereTime('birthday', '10')->get(); + $this->assertCount(6, $time); + + $time = Birthday::whereTime('birthday', '>=', '10:53:14')->get(); $this->assertCount(3, $time); + + $time = Birthday::whereTime('birthday', '!=', '10:53:14')->get(); + $this->assertCount(6, $time); + + $time = Birthday::whereTime('birthday', '<', '10:53:12')->get(); + $this->assertCount(2, $time); } public function testOrder(): void From 929f28414b70868a53f94683775f31be5afda216 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Fri, 25 Aug 2023 16:30:37 +0200 Subject: [PATCH 085/446] Fix tests for MongoDB 7.0 (#2579) Error message have changed Caused by :: Write conflict during plan execution and yielding is disabled. :: Please retry your operation or multi-document transaction. --- .github/workflows/build-ci.yml | 15 +++++++++------ Dockerfile | 13 +++++-------- docker-compose.yml | 16 +++++++++++++--- tests/TransactionTest.php | 1 - 4 files changed, 27 insertions(+), 18 deletions(-) diff --git a/.github/workflows/build-ci.yml b/.github/workflows/build-ci.yml index c3e22c23f..8feea0f6c 100644 --- a/.github/workflows/build-ci.yml +++ b/.github/workflows/build-ci.yml @@ -36,16 +36,16 @@ jobs: os: - ubuntu-latest mongodb: - - '4.0' - - '4.2' - '4.4' - '5.0' + - '6.0' + - '7.0' php: - '8.1' - '8.2' services: mysql: - image: mysql:5.7 + image: mysql:8.0 ports: - 3307:3306 env: @@ -58,13 +58,16 @@ jobs: - name: Create MongoDB Replica Set run: | docker run --name mongodb -p 27017:27017 -e MONGO_INITDB_DATABASE=unittest --detach mongo:${{ matrix.mongodb }} mongod --replSet rs --setParameter transactionLifetimeLimitSeconds=5 - until docker exec --tty mongodb mongo 127.0.0.1:27017 --eval "db.runCommand({ ping: 1 })"; do + + if [ "${{ matrix.mongodb }}" = "4.4" ]; then MONGOSH_BIN="mongo"; else MONGOSH_BIN="mongosh"; fi + until docker exec --tty mongodb $MONGOSH_BIN 127.0.0.1:27017 --eval "db.runCommand({ ping: 1 })"; do sleep 1 done - sudo docker exec --tty mongodb mongo 127.0.0.1:27017 --eval "rs.initiate({\"_id\":\"rs\",\"members\":[{\"_id\":0,\"host\":\"127.0.0.1:27017\" }]})" + sudo docker exec --tty mongodb $MONGOSH_BIN 127.0.0.1:27017 --eval "rs.initiate({\"_id\":\"rs\",\"members\":[{\"_id\":0,\"host\":\"127.0.0.1:27017\" }]})" - name: Show MongoDB server status run: | - docker exec --tty mongodb mongo 127.0.0.1:27017 --eval "db.runCommand({ serverStatus: 1 })" + if [ "${{ matrix.mongodb }}" = "4.4" ]; then MONGOSH_BIN="mongo"; else MONGOSH_BIN="mongosh"; fi + docker exec --tty mongodb $MONGOSH_BIN 127.0.0.1:27017 --eval "db.runCommand({ serverStatus: 1 })" - name: "Installing php" uses: shivammathur/setup-php@v2 with: diff --git a/Dockerfile b/Dockerfile index bd7e03a14..d13553499 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,24 +1,21 @@ ARG PHP_VERSION=8.1 -ARG COMPOSER_VERSION=2.5.4 FROM php:${PHP_VERSION}-cli RUN apt-get update && \ - apt-get install -y autoconf pkg-config libssl-dev git libzip-dev zlib1g-dev && \ + apt-get install -y autoconf pkg-config libssl-dev git unzip libzip-dev zlib1g-dev && \ pecl install mongodb && docker-php-ext-enable mongodb && \ pecl install xdebug && docker-php-ext-enable xdebug && \ docker-php-ext-install -j$(nproc) pdo_mysql zip -COPY --from=composer:${COMPOSER_VERSION} /usr/bin/composer /usr/local/bin/composer +COPY --from=composer:2.5.8 /usr/bin/composer /usr/local/bin/composer WORKDIR /code -COPY composer.* ./ - -RUN composer install - COPY ./ ./ +ENV COMPOSER_ALLOW_SUPERUSER=1 + RUN composer install -CMD ["./vendor/bin/phpunit"] +CMD ["./vendor/bin/phpunit", "--testdox"] diff --git a/docker-compose.yml b/docker-compose.yml index dab907abe..7ae2b00d8 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,4 +1,4 @@ -version: '3' +version: '3.5' services: tests: @@ -10,9 +10,14 @@ services: volumes: - .:/code working_dir: /code + environment: + MONGODB_URI: 'mongodb://mongodb/' + MYSQL_HOST: 'mysql' depends_on: - - mongodb - - mysql + mongodb: + condition: service_healthy + mysql: + condition: service_started mysql: container_name: mysql @@ -29,3 +34,8 @@ services: image: mongo:latest ports: - "27017:27017" + healthcheck: + test: echo 'db.runCommand("ping").ok' | mongosh mongodb:27017 --quiet + interval: 10s + timeout: 10s + retries: 5 diff --git a/tests/TransactionTest.php b/tests/TransactionTest.php index 06f1c2150..e373e2dae 100644 --- a/tests/TransactionTest.php +++ b/tests/TransactionTest.php @@ -384,7 +384,6 @@ public function testTransactionRespectsRepetitionLimit(): void $this->fail('Expected exception during transaction'); } catch (BulkWriteException $e) { $this->assertInstanceOf(BulkWriteException::class, $e); - $this->assertStringContainsString('WriteConflict', $e->getMessage()); } $this->assertSame(2, $timesRun); From e652b0c5f1fdf0ebca30118ee566ed0195cf2c28 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Fri, 25 Aug 2023 16:31:56 +0200 Subject: [PATCH 086/446] PHPORM-75 Defer `Model::unset($field)` to the `save()` (#2578) * PHPORM-75 Defer Model::unset($field) to the save() * Deprecate Model::drop(), use Model::unset() instead * Add assertions on isDirty --- CHANGELOG.md | 1 + src/Eloquent/Model.php | 93 ++++++++++++++++++++++++++++++-------- src/Query/Builder.php | 9 ++-- tests/ModelTest.php | 55 ++++++++++++++++++++++ tests/QueryBuilderTest.php | 32 +++++++++++++ 5 files changed, 168 insertions(+), 22 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fc10adb59..3dbdee597 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,7 @@ All notable changes to this project will be documented in this file. - Support `%` and `_` in `like` expression [#17](https://github.com/GromNaN/laravel-mongodb/pull/17) by [@GromNaN](https://github.com/GromNaN). - Change signature of `Query\Builder::__constructor` to match the parent class [#26](https://github.com/GromNaN/laravel-mongodb-private/pull/26) by [@GromNaN](https://github.com/GromNaN). - Fix Query on `whereDate`, `whereDay`, `whereMonth`, `whereYear`, `whereTime` to use MongoDB operators [#2570](https://github.com/jenssegers/laravel-mongodb/pull/2376) by [@Davpyu](https://github.com/Davpyu) and [@GromNaN](https://github.com/GromNaN). +- `Model::unset()` does not persist the change. Call `Model::save()` to persist the change [#2578](https://github.com/jenssegers/laravel-mongodb/pull/2578) by [@GromNaN](https://github.com/GromNaN). ## [3.9.2] - 2022-09-01 diff --git a/src/Eloquent/Model.php b/src/Eloquent/Model.php index ff7f9a175..4e118c46f 100644 --- a/src/Eloquent/Model.php +++ b/src/Eloquent/Model.php @@ -52,6 +52,13 @@ abstract class Model extends BaseModel */ protected $parentRelation; + /** + * List of field names to unset from the document on save. + * + * @var array{string, true} + */ + private array $unset = []; + /** * Custom accessor for the model's id. * @@ -151,7 +158,12 @@ public function getTable() public function getAttribute($key) { if (! $key) { - return; + return null; + } + + // An unset attribute is null or throw an exception. + if (isset($this->unset[$key])) { + return $this->throwMissingAttributeExceptionIfApplicable($key); } // Dot notation support. @@ -206,6 +218,9 @@ public function setAttribute($key, $value) return $this; } + // Setting an attribute cancels the unset operation. + unset($this->unset[$key]); + return parent::setAttribute($key, $value); } @@ -239,6 +254,21 @@ public function getCasts() return $this->casts; } + /** + * @inheritdoc + */ + public function getDirty() + { + $dirty = parent::getDirty(); + + // The specified value in the $unset expression does not impact the operation. + if (! empty($this->unset)) { + $dirty['$unset'] = $this->unset; + } + + return $dirty; + } + /** * @inheritdoc */ @@ -248,6 +278,11 @@ public function originalIsEquivalent($key) return false; } + // Calling unset on an attribute marks it as "not equivalent". + if (isset($this->unset[$key])) { + return false; + } + $attribute = Arr::get($this->attributes, $key); $original = Arr::get($this->original, $key); @@ -275,13 +310,49 @@ public function originalIsEquivalent($key) && strcmp((string) $attribute, (string) $original) === 0; } + /** + * @inheritdoc + */ + public function offsetUnset($offset): void + { + parent::offsetUnset($offset); + + // Force unsetting even if the attribute is not set. + // End user can optimize DB calls by checking if the attribute is set before unsetting it. + $this->unset[$offset] = true; + } + + /** + * @inheritdoc + */ + public function offsetSet($offset, $value): void + { + parent::offsetSet($offset, $value); + + // Setting an attribute cancels the unset operation. + unset($this->unset[$offset]); + } + /** * Remove one or more fields. * - * @param mixed $columns - * @return int + * @param string|string[] $columns + * @return void + * + * @deprecated Use unset() instead. */ public function drop($columns) + { + $this->unset($columns); + } + + /** + * Remove one or more fields. + * + * @param string|string[] $columns + * @return void + */ + public function unset($columns) { $columns = Arr::wrap($columns); @@ -289,9 +360,6 @@ public function drop($columns) foreach ($columns as $column) { $this->__unset($column); } - - // Perform unset only on current document - return $this->newQuery()->where($this->getKeyName(), $this->getKey())->unset($columns); } /** @@ -502,19 +570,6 @@ protected function isGuardableColumn($key) return true; } - /** - * @inheritdoc - */ - public function __call($method, $parameters) - { - // Unset method - if ($method == 'unset') { - return $this->drop(...$parameters); - } - - return parent::__call($method, $parameters); - } - /** * @inheritdoc */ diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 682c70c19..dce8ee2a4 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -607,9 +607,12 @@ public function insertGetId(array $values, $sequence = null) */ public function update(array $values, array $options = []) { - // Use $set as default operator. - if (! str_starts_with(key($values), '$')) { - $values = ['$set' => $values]; + // Use $set as default operator for field names that are not in an operator + foreach ($values as $key => $value) { + if (! str_starts_with($key, '$')) { + $values['$set'][$key] = $value; + unset($values[$key]); + } } $options = $this->inheritConnectionOptions($options); diff --git a/tests/ModelTest.php b/tests/ModelTest.php index 1fe71f266..75dfaf4bf 100644 --- a/tests/ModelTest.php +++ b/tests/ModelTest.php @@ -473,6 +473,10 @@ public function testUnset(): void $user1->unset('note1'); + $this->assertFalse(isset($user1->note1)); + + $user1->save(); + $this->assertFalse(isset($user1->note1)); $this->assertTrue(isset($user1->note2)); $this->assertTrue(isset($user2->note1)); @@ -488,9 +492,60 @@ public function testUnset(): void $this->assertTrue(isset($user2->note2)); $user2->unset(['note1', 'note2']); + $user2->save(); $this->assertFalse(isset($user2->note1)); $this->assertFalse(isset($user2->note2)); + + // Re-re-fetch to be sure + $user2 = User::find($user2->_id); + + $this->assertFalse(isset($user2->note1)); + $this->assertFalse(isset($user2->note2)); + } + + public function testUnsetAndSet(): void + { + $user = User::create(['name' => 'John Doe', 'note1' => 'ABC', 'note2' => 'DEF']); + + $this->assertTrue($user->originalIsEquivalent('note1')); + + // Unset the value + $user->unset('note1'); + $this->assertFalse(isset($user->note1)); + $this->assertNull($user['note1']); + $this->assertFalse($user->originalIsEquivalent('note1')); + $this->assertTrue($user->isDirty()); + $this->assertSame(['$unset' => ['note1' => true]], $user->getDirty()); + + // Reset the previous value + $user->note1 = 'ABC'; + $this->assertTrue($user->originalIsEquivalent('note1')); + $this->assertFalse($user->isDirty()); + $this->assertSame([], $user->getDirty()); + + // Change the value + $user->note1 = 'GHI'; + $this->assertTrue(isset($user->note1)); + $this->assertSame('GHI', $user['note1']); + $this->assertFalse($user->originalIsEquivalent('note1')); + $this->assertTrue($user->isDirty()); + $this->assertSame(['note1' => 'GHI'], $user->getDirty()); + + // Fetch to be sure the changes are not persisted yet + $userCheck = User::find($user->_id); + $this->assertSame('ABC', $userCheck['note1']); + + // Persist the changes + $user->save(); + + // Re-fetch to be sure + $user = User::find($user->_id); + + $this->assertTrue(isset($user->note1)); + $this->assertSame('GHI', $user->note1); + $this->assertTrue($user->originalIsEquivalent('note1')); + $this->assertFalse($user->isDirty()); } public function testDates(): void diff --git a/tests/QueryBuilderTest.php b/tests/QueryBuilderTest.php index 5dbc67cc2..11817018a 100644 --- a/tests/QueryBuilderTest.php +++ b/tests/QueryBuilderTest.php @@ -203,6 +203,38 @@ public function testUpdate() $this->assertEquals(20, $jane['age']); } + public function testUpdateOperators() + { + DB::collection('users')->insert([ + ['name' => 'Jane Doe', 'age' => 20], + ['name' => 'John Doe', 'age' => 19], + ]); + + DB::collection('users')->where('name', 'John Doe')->update( + [ + '$unset' => ['age' => 1], + 'ageless' => true, + ] + ); + DB::collection('users')->where('name', 'Jane Doe')->update( + [ + '$inc' => ['age' => 1], + '$set' => ['pronoun' => 'she'], + 'ageless' => false, + ] + ); + + $john = DB::collection('users')->where('name', 'John Doe')->first(); + $jane = DB::collection('users')->where('name', 'Jane Doe')->first(); + + $this->assertArrayNotHasKey('age', $john); + $this->assertTrue($john['ageless']); + + $this->assertEquals(21, $jane['age']); + $this->assertEquals('she', $jane['pronoun']); + $this->assertFalse($jane['ageless']); + } + public function testDelete() { DB::collection('users')->insert([ From 58e2e2855116b31a9241f3c340362da145b884cc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 28 Aug 2023 17:36:09 +0200 Subject: [PATCH 087/446] Fix Model::unset with dot field name --- src/Eloquent/Model.php | 15 ++++++--- tests/ModelTest.php | 73 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 83 insertions(+), 5 deletions(-) diff --git a/src/Eloquent/Model.php b/src/Eloquent/Model.php index 4e118c46f..9163145bd 100644 --- a/src/Eloquent/Model.php +++ b/src/Eloquent/Model.php @@ -315,11 +315,16 @@ public function originalIsEquivalent($key) */ public function offsetUnset($offset): void { - parent::offsetUnset($offset); - - // Force unsetting even if the attribute is not set. - // End user can optimize DB calls by checking if the attribute is set before unsetting it. - $this->unset[$offset] = true; + if (str_contains($offset, '.')) { + // Update the field in the subdocument + Arr::forget($this->attributes, $offset); + } else { + parent::offsetUnset($offset); + + // Force unsetting even if the attribute is not set. + // End user can optimize DB calls by checking if the attribute is set before unsetting it. + $this->unset[$offset] = true; + } } /** diff --git a/tests/ModelTest.php b/tests/ModelTest.php index 75dfaf4bf..93fbae438 100644 --- a/tests/ModelTest.php +++ b/tests/ModelTest.php @@ -548,6 +548,79 @@ public function testUnsetAndSet(): void $this->assertFalse($user->isDirty()); } + public function testUnsetDotAttributes(): void + { + $user = User::create(['name' => 'John Doe', 'notes' => ['note1' => 'ABC', 'note2' => 'DEF']]); + + $user->unset('notes.note1'); + + $this->assertFalse(isset($user->notes['note1'])); + $this->assertTrue(isset($user->notes['note2'])); + $this->assertTrue($user->isDirty()); + $dirty = $user->getDirty(); + $this->assertArrayHasKey('notes', $dirty); + $this->assertArrayNotHasKey('$unset', $dirty); + + $user->save(); + + $this->assertFalse(isset($user->notes['note1'])); + $this->assertTrue(isset($user->notes['note2'])); + + // Re-fetch to be sure + $user = User::find($user->_id); + + $this->assertFalse(isset($user->notes['note1'])); + $this->assertTrue(isset($user->notes['note2'])); + + // Unset the parent key + $user->unset('notes'); + + $this->assertFalse(isset($user->notes['note1'])); + $this->assertFalse(isset($user->notes['note2'])); + $this->assertFalse(isset($user->notes)); + + $user->save(); + + $this->assertFalse(isset($user->notes)); + + // Re-fetch to be sure + $user = User::find($user->_id); + + $this->assertFalse(isset($user->notes)); + } + + public function testUnsetDotAttributesAndSet(): void + { + $user = User::create(['name' => 'John Doe', 'notes' => ['note1' => 'ABC', 'note2' => 'DEF']]); + + // notes.note2 is the last attribute of the document + $user->unset('notes.note2'); + $this->assertTrue($user->isDirty()); + $this->assertSame(['note1' => 'ABC'], $user->notes); + + $user->setAttribute('notes.note2', 'DEF'); + $this->assertFalse($user->isDirty()); + $this->assertSame(['note1' => 'ABC', 'note2' => 'DEF'], $user->notes); + + // Unsetting and resetting the 1st attribute of the document will change the order of the attributes + $user->unset('notes.note1'); + $this->assertSame(['note2' => 'DEF'], $user->notes); + $this->assertTrue($user->isDirty()); + + $user->setAttribute('notes.note1', 'ABC'); + $this->assertSame(['note2' => 'DEF', 'note1' => 'ABC'], $user->notes); + $this->assertTrue($user->isDirty()); + $this->assertSame(['notes' => ['note2' => 'DEF', 'note1' => 'ABC']], $user->getDirty()); + + $user->save(); + $this->assertSame(['note2' => 'DEF', 'note1' => 'ABC'], $user->notes); + + // Re-fetch to be sure + $user = User::find($user->_id); + + $this->assertSame(['note2' => 'DEF', 'note1' => 'ABC'], $user->notes); + } + public function testDates(): void { $user = User::create(['name' => 'John Doe', 'birthday' => new DateTime('1965/1/1')]); From 25c73e28d1b0a8491ec61450ccf59465cdbffeaa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 30 Aug 2023 12:16:38 +0200 Subject: [PATCH 088/446] PHPORM-77 Rename project (#2576) * Change namespace MongoDB\Laravel * Rename package mongodb/laravel-mongodb * Update code of conduct according to MongoDB code of conduct. * Change code ownership in License file and composer.json Co-authored-by: Andreas Braun --- .github/FUNDING.yml | 2 - CHANGELOG.md | 4 +- CODE_OF_CONDUCT.md | 86 +-------------- LICENSE.md => LICENSE | 2 +- README.md | 109 ++++++------------- composer.json | 36 +++--- src/Auth/DatabaseTokenRepository.php | 2 +- src/Auth/PasswordBrokerManager.php | 2 +- src/Auth/PasswordResetServiceProvider.php | 2 +- src/Auth/User.php | 4 +- src/Collection.php | 2 +- src/Concerns/ManagesTransactions.php | 2 +- src/Connection.php | 6 +- src/Eloquent/Builder.php | 4 +- src/Eloquent/Casts/BinaryUuid.php | 4 +- src/Eloquent/Casts/ObjectId.php | 4 +- src/Eloquent/EmbedsRelations.php | 10 +- src/Eloquent/HybridRelations.php | 30 ++--- src/Eloquent/Model.php | 4 +- src/Eloquent/SoftDeletes.php | 2 +- src/Helpers/EloquentBuilder.php | 2 +- src/Helpers/QueriesRelationships.php | 4 +- src/MongodbQueueServiceProvider.php | 4 +- src/MongodbServiceProvider.php | 6 +- src/Query/Builder.php | 4 +- src/Query/Grammar.php | 2 +- src/Query/Processor.php | 2 +- src/Queue/Failed/MongoFailedJobProvider.php | 2 +- src/Queue/MongoConnector.php | 2 +- src/Queue/MongoJob.php | 2 +- src/Queue/MongoQueue.php | 4 +- src/Relations/BelongsTo.php | 2 +- src/Relations/BelongsToMany.php | 2 +- src/Relations/EmbedsMany.php | 2 +- src/Relations/EmbedsOne.php | 2 +- src/Relations/EmbedsOneOrMany.php | 4 +- src/Relations/HasMany.php | 2 +- src/Relations/HasOne.php | 2 +- src/Relations/MorphMany.php | 2 +- src/Relations/MorphTo.php | 2 +- src/Schema/Blueprint.php | 6 +- src/Schema/Builder.php | 2 +- src/Schema/Grammar.php | 2 +- src/Validation/DatabasePresenceVerifier.php | 2 +- src/Validation/ValidationServiceProvider.php | 2 +- tests/AuthTest.php | 4 +- tests/Casts/BinaryUuidTest.php | 6 +- tests/Casts/ObjectIdTest.php | 6 +- tests/CollectionTest.php | 6 +- tests/ConnectionTest.php | 10 +- tests/EmbeddedRelationsTest.php | 18 +-- tests/GeospatialTest.php | 4 +- tests/HybridRelationsTest.php | 14 +-- tests/ModelTest.php | 26 ++--- tests/Models/Address.php | 6 +- tests/Models/Birthday.php | 4 +- tests/Models/Book.php | 4 +- tests/Models/CastBinaryUuid.php | 6 +- tests/Models/CastObjectId.php | 6 +- tests/Models/Client.php | 4 +- tests/Models/Group.php | 4 +- tests/Models/Guarded.php | 4 +- tests/Models/IdIsBinaryUuid.php | 6 +- tests/Models/IdIsInt.php | 4 +- tests/Models/IdIsString.php | 4 +- tests/Models/Item.php | 6 +- tests/Models/Location.php | 4 +- tests/Models/MemberStatus.php | 2 +- tests/Models/MysqlBook.php | 4 +- tests/Models/MysqlRole.php | 4 +- tests/Models/MysqlUser.php | 4 +- tests/Models/Photo.php | 4 +- tests/Models/Role.php | 4 +- tests/Models/Scoped.php | 6 +- tests/Models/Soft.php | 6 +- tests/Models/User.php | 6 +- tests/Query/BuilderTest.php | 12 +- tests/QueryBuilderTest.php | 12 +- tests/QueryTest.php | 8 +- tests/QueueTest.php | 8 +- tests/RelationsTest.php | 18 +-- tests/SchemaTest.php | 4 +- tests/Seeder/DatabaseSeeder.php | 2 +- tests/Seeder/UserTableSeeder.php | 2 +- tests/SeederTest.php | 8 +- tests/TestCase.php | 12 +- tests/TransactionTest.php | 8 +- tests/ValidationTest.php | 4 +- 88 files changed, 278 insertions(+), 401 deletions(-) delete mode 100644 .github/FUNDING.yml rename LICENSE.md => LICENSE (97%) diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml deleted file mode 100644 index 6136cca0a..000000000 --- a/.github/FUNDING.yml +++ /dev/null @@ -1,2 +0,0 @@ -github: jenssegers -tidelift: "packagist/jenssegers/mongodb" diff --git a/CHANGELOG.md b/CHANGELOG.md index 3dbdee597..962d4aa03 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,10 @@ # Changelog All notable changes to this project will be documented in this file. -## [Unreleased] +## [4.0.0] - unreleased +- Rename package to `mongodb/laravel-mongodb` +- Change namespace to `MongoDB\Laravel` - Add classes to cast `ObjectId` and `UUID` instances [#1](https://github.com/GromNaN/laravel-mongodb/pull/1) by [@alcaeus](https://github.com/alcaeus). - Add `Query\Builder::toMql()` to simplify comprehensive query tests [#6](https://github.com/GromNaN/laravel-mongodb/pull/6) by [@GromNaN](https://github.com/GromNaN). - Fix `Query\Builder::whereNot` to use MongoDB [`$not`](https://www.mongodb.com/docs/manual/reference/operator/query/not/) operator [#13](https://github.com/GromNaN/laravel-mongodb/pull/13) by [@GromNaN](https://github.com/GromNaN). diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 61f005408..f4552fe59 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,84 +1,6 @@ -# Contributor Covenant Code of Conduct +# MongoDB Code of Conduct -## Our Pledge +The Code of Conduct outlines the expectations for our behavior as members of the MongoDB community. +We value the participation of each member of the MongoDB community and want all participants to have an enjoyable and fulfilling experience. -We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -## Our Standards - -Examples of behavior that contributes to a positive environment for our community include: - -* Demonstrating empathy and kindness toward other people -* Being respectful of differing opinions, viewpoints, and experiences -* Giving and gracefully accepting constructive feedback -* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience -* Focusing on what is best not just for us as individuals, but for the overall community - -Examples of unacceptable behavior include: - -* The use of sexualized language or imagery, and sexual attention or - advances of any kind -* Trolling, insulting or derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or email - address, without their explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Enforcement Responsibilities - -Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. - -Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. - -## Scope - -This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at hello@jenssegers.com. All complaints will be reviewed and investigated promptly and fairly. - -All community leaders are obligated to respect the privacy and security of the reporter of any incident. - -## Enforcement Guidelines - -Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community. - -**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0, -available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. - -Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). - -[homepage]: https://www.contributor-covenant.org - -For answers to common questions about this code of conduct, see the FAQ at -https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations. \ No newline at end of file +Thanks for reading the [MongoDB Code of Conduct](https://www.mongodb.com/community-code-of-conduct). diff --git a/LICENSE.md b/LICENSE similarity index 97% rename from LICENSE.md rename to LICENSE index 948b1b1bd..4962cfa56 100644 --- a/LICENSE.md +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2020 Jens Segers +Copyright (c) 2023 MongoDB, Inc Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index f00b3a2c7..5fc9a203a 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,10 @@ Laravel MongoDB =============== -[![Latest Stable Version](http://img.shields.io/github/release/jenssegers/laravel-mongodb.svg)](https://packagist.org/packages/jenssegers/mongodb) -[![Total Downloads](http://img.shields.io/packagist/dm/jenssegers/mongodb.svg)](https://packagist.org/packages/jenssegers/mongodb) -[![Build Status](https://img.shields.io/github/workflow/status/jenssegers/laravel-mongodb/CI)](https://github.com/jenssegers/laravel-mongodb/actions) -[![codecov](https://codecov.io/gh/jenssegers/laravel-mongodb/branch/master/graph/badge.svg)](https://codecov.io/gh/jenssegers/laravel-mongodb/branch/master) -[![Donate](https://img.shields.io/badge/donate-paypal-blue.svg)](https://www.paypal.me/jenssegers) +[![Latest Stable Version](http://img.shields.io/github/release/mongodb/laravel-mongodb.svg)](https://packagist.org/packages/mongodb/laravel-mongodb) +[![Total Downloads](http://img.shields.io/packagist/dm/mongodb/laravel-mongodb.svg)](https://packagist.org/packages/mongodb/laravel-mongodb) +[![Build Status](https://img.shields.io/github/workflow/status/mongodb/laravel-mongodb/CI)](https://github.com/mongodb/laravel-mongodb/actions) +[![codecov](https://codecov.io/gh/mongodb/laravel-mongodb/branch/master/graph/badge.svg)](https://codecov.io/gh/mongodb/laravel-mongodb/branch/master) This package adds functionalities to the Eloquent model and Query builder for MongoDB, using the original Laravel API. *This library extends the original Laravel classes, so it uses exactly the same methods.* @@ -46,8 +45,6 @@ This package adds functionalities to the Eloquent model and Query builder for Mo - [Cross-Database Relationships](#cross-database-relationships) - [Authentication](#authentication) - [Queues](#queues) - - [Laravel specific](#laravel-specific) - - [Lumen specific](#lumen-specific) - [Upgrading](#upgrading) - [Upgrading from version 2 to 3](#upgrading-from-version-2-to-3) - [Security contact information](#security-contact-information) @@ -79,7 +76,7 @@ Make sure you have the MongoDB PHP driver installed. You can find installation i Install the package via Composer: ```bash -$ composer require jenssegers/mongodb +$ composer require mongodb/laravel-mongodb ``` ### Laravel @@ -87,7 +84,7 @@ $ composer require jenssegers/mongodb In case your Laravel version does NOT autoload the packages, add the service provider to `config/app.php`: ```php -Jenssegers\Mongodb\MongodbServiceProvider::class, +MongoDB\Laravel\MongodbServiceProvider::class, ``` ### Lumen @@ -95,7 +92,7 @@ Jenssegers\Mongodb\MongodbServiceProvider::class, For usage with [Lumen](http://lumen.laravel.com), add the service provider in `bootstrap/app.php`. In this file, you will also need to enable Eloquent. You must however ensure that your call to `$app->withEloquent();` is **below** where you have registered the `MongodbServiceProvider`: ```php -$app->register(Jenssegers\Mongodb\MongodbServiceProvider::class); +$app->register(MongoDB\Laravel\MongodbServiceProvider::class); $app->withEloquent(); ``` @@ -112,7 +109,7 @@ For usage outside Laravel, check out the [Capsule manager](https://github.com/il $capsule->getDatabaseManager()->extend('mongodb', function($config, $name) { $config['name'] = $name; - return new Jenssegers\Mongodb\Connection($config); + return new MongoDB\Laravel\Connection($config); }); ``` @@ -186,7 +183,7 @@ Eloquent This package includes a MongoDB enabled Eloquent class that you can use to define models for corresponding collections. ```php -use Jenssegers\Mongodb\Eloquent\Model; +use MongoDB\Laravel\Eloquent\Model; class Book extends Model { @@ -199,7 +196,7 @@ Just like a normal model, the MongoDB model class will know which collection to To change the collection, pass the `$collection` property: ```php -use Jenssegers\Mongodb\Eloquent\Model; +use MongoDB\Laravel\Eloquent\Model; class Book extends Model { @@ -210,7 +207,7 @@ class Book extends Model **NOTE:** MongoDB documents are automatically stored with a unique ID that is stored in the `_id` property. If you wish to use your own ID, substitute the `$primaryKey` property and set it to your own primary key attribute name. ```php -use Jenssegers\Mongodb\Eloquent\Model; +use MongoDB\Laravel\Eloquent\Model; class Book extends Model { @@ -224,7 +221,7 @@ Book::create(['id' => 1, 'title' => 'The Fault in Our Stars']); Likewise, you may define a `connection` property to override the name of the database connection that should be used when utilizing the model. ```php -use Jenssegers\Mongodb\Eloquent\Model; +use MongoDB\Laravel\Eloquent\Model; class Book extends Model { @@ -234,10 +231,10 @@ class Book extends Model ### Extending the Authenticatable base model -This package includes a MongoDB Authenticatable Eloquent class `Jenssegers\Mongodb\Auth\User` that you can use to replace the default Authenticatable class `Illuminate\Foundation\Auth\User` for your `User` model. +This package includes a MongoDB Authenticatable Eloquent class `MongoDB\Laravel\Auth\User` that you can use to replace the default Authenticatable class `Illuminate\Foundation\Auth\User` for your `User` model. ```php -use Jenssegers\Mongodb\Auth\User as Authenticatable; +use MongoDB\Laravel\Auth\User as Authenticatable; class User extends Authenticatable { @@ -249,10 +246,10 @@ class User extends Authenticatable When soft deleting a model, it is not actually removed from your database. Instead, a deleted_at timestamp is set on the record. -To enable soft deletes for a model, apply the `Jenssegers\Mongodb\Eloquent\SoftDeletes` Trait to the model: +To enable soft deletes for a model, apply the `MongoDB\Laravel\Eloquent\SoftDeletes` Trait to the model: ```php -use Jenssegers\Mongodb\Eloquent\SoftDeletes; +use MongoDB\Laravel\Eloquent\SoftDeletes; class User extends Model { @@ -274,7 +271,7 @@ Keep in mind guarding still works, but you may experience unexpected behavior. Eloquent allows you to work with Carbon or DateTime objects instead of MongoDate objects. Internally, these dates will be converted to MongoDate objects when saved to the database. ```php -use Jenssegers\Mongodb\Eloquent\Model; +use MongoDB\Laravel\Eloquent\Model; class User extends Model { @@ -812,7 +809,7 @@ The MongoDB-specific relationships are: Here is a small example: ```php -use Jenssegers\Mongodb\Eloquent\Model; +use MongoDB\Laravel\Eloquent\Model; class User extends Model { @@ -826,7 +823,7 @@ class User extends Model The inverse relation of `hasMany` is `belongsTo`: ```php -use Jenssegers\Mongodb\Eloquent\Model; +use MongoDB\Laravel\Eloquent\Model; class Item extends Model { @@ -844,7 +841,7 @@ The belongsToMany relation will not use a pivot "table" but will push id's to a If you want to define custom keys for your relation, set it to `null`: ```php -use Jenssegers\Mongodb\Eloquent\Model; +use MongoDB\Laravel\Eloquent\Model; class User extends Model { @@ -864,7 +861,7 @@ If you want to embed models, rather than referencing them, you can use the `embe **REMEMBER**: These relations return Eloquent collections, they don't return query builder objects! ```php -use Jenssegers\Mongodb\Eloquent\Model; +use MongoDB\Laravel\Eloquent\Model; class User extends Model { @@ -936,7 +933,7 @@ $user->save(); Like other relations, embedsMany assumes the local key of the relationship based on the model name. You can override the default local key by passing a second argument to the embedsMany method: ```php -use Jenssegers\Mongodb\Eloquent\Model; +use MongoDB\Laravel\Eloquent\Model; class User extends Model { @@ -954,7 +951,7 @@ Embedded relations will return a Collection of embedded items instead of a query The embedsOne relation is similar to the embedsMany relation, but only embeds a single model. ```php -use Jenssegers\Mongodb\Eloquent\Model; +use MongoDB\Laravel\Eloquent\Model; class Book extends Model { @@ -1156,14 +1153,14 @@ If you're using a hybrid MongoDB and SQL setup, you can define relationships acr The model will automatically return a MongoDB-related or SQL-related relation based on the type of the related model. -If you want this functionality to work both ways, your SQL-models will need to use the `Jenssegers\Mongodb\Eloquent\HybridRelations` trait. +If you want this functionality to work both ways, your SQL-models will need to use the `MongoDB\Laravel\Eloquent\HybridRelations` trait. **This functionality only works for `hasOne`, `hasMany` and `belongsTo`.** The MySQL model should use the `HybridRelations` trait: ```php -use Jenssegers\Mongodb\Eloquent\HybridRelations; +use MongoDB\Laravel\Eloquent\HybridRelations; class User extends Model { @@ -1181,7 +1178,7 @@ class User extends Model Within your MongoDB model, you should define the relationship: ```php -use Jenssegers\Mongodb\Eloquent\Model; +use MongoDB\Laravel\Eloquent\Model; class Message extends Model { @@ -1199,7 +1196,7 @@ class Message extends Model If you want to use Laravel's native Auth functionality, register this included service provider: ```php -Jenssegers\Mongodb\Auth\PasswordResetServiceProvider::class, +MongoDB\Laravel\Auth\PasswordResetServiceProvider::class, ``` This service provider will slightly modify the internal DatabaseReminderRepository to add support for MongoDB based password reminders. @@ -1234,63 +1231,19 @@ If you want to use MongoDB to handle failed jobs, change the database in `config ], ``` -#### Laravel specific - Add the service provider in `config/app.php`: ```php -Jenssegers\Mongodb\MongodbQueueServiceProvider::class, -``` - -#### Lumen specific - -With [Lumen](http://lumen.laravel.com), add the service provider in `bootstrap/app.php`. You must however ensure that you add the following **after** the `MongodbServiceProvider` registration. - -```php -$app->make('queue'); - -$app->register(Jenssegers\Mongodb\MongodbQueueServiceProvider::class); +MongoDB\Laravel\MongodbQueueServiceProvider::class, ``` Upgrading --------- -#### Upgrading from version 2 to 3 - -In this new major release which supports the new MongoDB PHP extension, we also moved the location of the Model class and replaced the MySQL model class with a trait. - -Please change all `Jenssegers\Mongodb\Model` references to `Jenssegers\Mongodb\Eloquent\Model` either at the top of your model files or your registered alias. - -```php -use Jenssegers\Mongodb\Eloquent\Model; - -class User extends Model -{ - // -} -``` +#### Upgrading from version 3 to 4 -If you are using hybrid relations, your MySQL classes should now extend the original Eloquent model class `Illuminate\Database\Eloquent\Model` instead of the removed `Jenssegers\Eloquent\Model`. - -Instead use the new `Jenssegers\Mongodb\Eloquent\HybridRelations` trait. This should make things more clear as there is only one single model class in this package. - -```php -use Jenssegers\Mongodb\Eloquent\HybridRelations; - -class User extends Model -{ - - use HybridRelations; - - protected $connection = 'mysql'; -} -``` - -Embedded relations now return an `Illuminate\Database\Eloquent\Collection` rather than a custom Collection class. If you were using one of the special methods that were available, convert them to Collection operations. - -```php -$books = $user->books()->sortBy('title')->get(); -``` +Change project name in composer.json to `mongodb/laravel` and run `composer update`. +Change namespace from `Jenssegers\Mongodb` to `MongoDB\Laravel` in your models and config. ## Security contact information diff --git a/composer.json b/composer.json index c628175f8..b5c2ddd8d 100644 --- a/composer.json +++ b/composer.json @@ -1,21 +1,24 @@ { - "name": "jenssegers/mongodb", - "description": "A MongoDB based Eloquent model and Query builder for Laravel (Moloquent)", + "name": "mongodb/laravel-mongodb", + "description": "A MongoDB based Eloquent model and Query builder for Laravel", "keywords": [ "laravel", "eloquent", "mongodb", "mongo", "database", - "model", - "moloquent" + "model" ], - "homepage": "https://github.com/jenssegers/laravel-mongodb", + "homepage": "https://github.com/mongodb/laravel-mongodb", + "support": { + "issues": "https://www.mongodb.com/support", + "security": "https://www.mongodb.com/security" + }, "authors": [ - { - "name": "Jens Segers", - "homepage": "https://jenssegers.com" - } + { "name": "Andreas Braun", "email": "andreas.braun@mongodb.com", "role": "Leader" }, + { "name": "Jérôme Tamarelle", "email": "jerome.tamarelle@mongodb.com", "role": "Maintainer" }, + { "name": "Jeremy Mikola", "email": "jmikola@gmail.com", "role": "Maintainer" }, + { "name": "Jens Segers", "homepage": "https://jenssegers.com", "role": "Creator" } ], "license": "MIT", "require": { @@ -32,25 +35,24 @@ "orchestra/testbench": "^8.0", "mockery/mockery": "^1.4.4" }, + "replace": { + "jenssegers/mongodb": "self.version" + }, "autoload": { "psr-4": { - "Jenssegers\\Mongodb\\": "src/" + "MongoDB\\Laravel\\": "src/" } }, "autoload-dev": { "psr-4": { - "Jenssegers\\Mongodb\\Tests\\": "tests/" + "MongoDB\\Laravel\\Tests\\": "tests/" } }, - "suggest": { - "jenssegers/mongodb-session": "Add MongoDB session support to Laravel-MongoDB", - "jenssegers/mongodb-sentry": "Add Sentry support to Laravel-MongoDB" - }, "extra": { "laravel": { "providers": [ - "Jenssegers\\Mongodb\\MongodbServiceProvider", - "Jenssegers\\Mongodb\\MongodbQueueServiceProvider" + "MongoDB\\Laravel\\MongodbServiceProvider", + "MongoDB\\Laravel\\MongodbQueueServiceProvider" ] } }, diff --git a/src/Auth/DatabaseTokenRepository.php b/src/Auth/DatabaseTokenRepository.php index 4574cf615..b2f43c748 100644 --- a/src/Auth/DatabaseTokenRepository.php +++ b/src/Auth/DatabaseTokenRepository.php @@ -1,6 +1,6 @@ [ \ArgumentCountError::class, - 'Too few arguments to function Jenssegers\Mongodb\Query\Builder::where("foo"), 1 passed and at least 2 expected when the 1st is a string', + 'Too few arguments to function MongoDB\Laravel\Query\Builder::where("foo"), 1 passed and at least 2 expected when the 1st is a string', fn (Builder $builder) => $builder->where('foo'), ]; diff --git a/tests/QueryBuilderTest.php b/tests/QueryBuilderTest.php index 11817018a..6c4e14f6e 100644 --- a/tests/QueryBuilderTest.php +++ b/tests/QueryBuilderTest.php @@ -2,7 +2,7 @@ declare(strict_types=1); -namespace Jenssegers\Mongodb\Tests; +namespace MongoDB\Laravel\Tests; use DateTime; use DateTimeImmutable; @@ -10,10 +10,6 @@ use Illuminate\Support\Facades\DB; use Illuminate\Support\LazyCollection; use Illuminate\Testing\Assert; -use Jenssegers\Mongodb\Collection; -use Jenssegers\Mongodb\Query\Builder; -use Jenssegers\Mongodb\Tests\Models\Item; -use Jenssegers\Mongodb\Tests\Models\User; use MongoDB\BSON\ObjectId; use MongoDB\BSON\Regex; use MongoDB\BSON\UTCDateTime; @@ -22,6 +18,10 @@ use MongoDB\Driver\Monitoring\CommandStartedEvent; use MongoDB\Driver\Monitoring\CommandSubscriber; use MongoDB\Driver\Monitoring\CommandSucceededEvent; +use MongoDB\Laravel\Collection; +use MongoDB\Laravel\Query\Builder; +use MongoDB\Laravel\Tests\Models\Item; +use MongoDB\Laravel\Tests\Models\User; class QueryBuilderTest extends TestCase { @@ -379,7 +379,7 @@ public function testPush() public function testPushRefuses2ndArgumentWhen1stIsAnArray() { $this->expectException(\InvalidArgumentException::class); - $this->expectExceptionMessage('2nd argument of Jenssegers\Mongodb\Query\Builder::push() must be "null" when 1st argument is an array. Got "string" instead.'); + $this->expectExceptionMessage('2nd argument of MongoDB\Laravel\Query\Builder::push() must be "null" when 1st argument is an array. Got "string" instead.'); DB::collection('users')->push(['tags' => 'tag1'], 'tag2'); } diff --git a/tests/QueryTest.php b/tests/QueryTest.php index 8737a7d68..03713ffae 100644 --- a/tests/QueryTest.php +++ b/tests/QueryTest.php @@ -2,12 +2,12 @@ declare(strict_types=1); -namespace Jenssegers\Mongodb\Tests; +namespace MongoDB\Laravel\Tests; use DateTimeImmutable; -use Jenssegers\Mongodb\Tests\Models\Birthday; -use Jenssegers\Mongodb\Tests\Models\Scoped; -use Jenssegers\Mongodb\Tests\Models\User; +use MongoDB\Laravel\Tests\Models\Birthday; +use MongoDB\Laravel\Tests\Models\Scoped; +use MongoDB\Laravel\Tests\Models\User; class QueryTest extends TestCase { diff --git a/tests/QueueTest.php b/tests/QueueTest.php index 601d712ae..072835b32 100644 --- a/tests/QueueTest.php +++ b/tests/QueueTest.php @@ -2,15 +2,15 @@ declare(strict_types=1); -namespace Jenssegers\Mongodb\Tests; +namespace MongoDB\Laravel\Tests; use Carbon\Carbon; use Illuminate\Support\Facades\Config; use Illuminate\Support\Facades\Queue; use Illuminate\Support\Str; -use Jenssegers\Mongodb\Queue\Failed\MongoFailedJobProvider; -use Jenssegers\Mongodb\Queue\MongoQueue; use Mockery; +use MongoDB\Laravel\Queue\Failed\MongoFailedJobProvider; +use MongoDB\Laravel\Queue\MongoQueue; class QueueTest extends TestCase { @@ -36,7 +36,7 @@ public function testQueueJobLifeCycle(): void // Get and reserve the test job (next available) $job = Queue::pop('test'); - $this->assertInstanceOf(\Jenssegers\Mongodb\Queue\MongoJob::class, $job); + $this->assertInstanceOf(\MongoDB\Laravel\Queue\MongoJob::class, $job); $this->assertEquals(1, $job->isReserved()); $this->assertEquals(json_encode([ 'uuid' => $uuid, diff --git a/tests/RelationsTest.php b/tests/RelationsTest.php index 66c27583f..f418bf384 100644 --- a/tests/RelationsTest.php +++ b/tests/RelationsTest.php @@ -2,18 +2,18 @@ declare(strict_types=1); -namespace Jenssegers\Mongodb\Tests; +namespace MongoDB\Laravel\Tests; use Illuminate\Database\Eloquent\Collection; -use Jenssegers\Mongodb\Tests\Models\Address; -use Jenssegers\Mongodb\Tests\Models\Book; -use Jenssegers\Mongodb\Tests\Models\Client; -use Jenssegers\Mongodb\Tests\Models\Group; -use Jenssegers\Mongodb\Tests\Models\Item; -use Jenssegers\Mongodb\Tests\Models\Photo; -use Jenssegers\Mongodb\Tests\Models\Role; -use Jenssegers\Mongodb\Tests\Models\User; use Mockery; +use MongoDB\Laravel\Tests\Models\Address; +use MongoDB\Laravel\Tests\Models\Book; +use MongoDB\Laravel\Tests\Models\Client; +use MongoDB\Laravel\Tests\Models\Group; +use MongoDB\Laravel\Tests\Models\Item; +use MongoDB\Laravel\Tests\Models\Photo; +use MongoDB\Laravel\Tests\Models\Role; +use MongoDB\Laravel\Tests\Models\User; class RelationsTest extends TestCase { diff --git a/tests/SchemaTest.php b/tests/SchemaTest.php index 4e820e58a..6befaa942 100644 --- a/tests/SchemaTest.php +++ b/tests/SchemaTest.php @@ -2,11 +2,11 @@ declare(strict_types=1); -namespace Jenssegers\Mongodb\Tests; +namespace MongoDB\Laravel\Tests; use Illuminate\Support\Facades\DB; use Illuminate\Support\Facades\Schema; -use Jenssegers\Mongodb\Schema\Blueprint; +use MongoDB\Laravel\Schema\Blueprint; class SchemaTest extends TestCase { diff --git a/tests/Seeder/DatabaseSeeder.php b/tests/Seeder/DatabaseSeeder.php index a5d7c940f..27e4468ad 100644 --- a/tests/Seeder/DatabaseSeeder.php +++ b/tests/Seeder/DatabaseSeeder.php @@ -1,6 +1,6 @@ Date: Thu, 31 Aug 2023 12:00:33 +0200 Subject: [PATCH 089/446] Remove legacy from readme (#2586) --- README.md | 56 ++++--------------------------------------------------- 1 file changed, 4 insertions(+), 52 deletions(-) diff --git a/README.md b/README.md index 5fc9a203a..d7a505bd1 100644 --- a/README.md +++ b/README.md @@ -8,12 +8,11 @@ Laravel MongoDB This package adds functionalities to the Eloquent model and Query builder for MongoDB, using the original Laravel API. *This library extends the original Laravel classes, so it uses exactly the same methods.* +This package was renamed to `mongodb/laravel-mongodb` because of a transfer of ownership to MongoDB, Inc. +It is compatible with Laravel 10.x. For older versions of Laravel, please refer to the [old versions](https://github.com/mongodb/laravel-mongodb/tree/3.9#laravel-version-compatibility). + - [Laravel MongoDB](#laravel-mongodb) - [Installation](#installation) - - [Laravel version Compatibility](#laravel-version-compatibility) - - [Laravel](#laravel) - - [Lumen](#lumen) - - [Non-Laravel projects](#non-laravel-projects) - [Testing](#testing) - [Database Testing](#database-testing) - [Configuration](#configuration) @@ -52,26 +51,7 @@ This package adds functionalities to the Eloquent model and Query builder for Mo Installation ------------ -Make sure you have the MongoDB PHP driver installed. You can find installation instructions at http://php.net/manual/en/mongodb.installation.php - -### Laravel version Compatibility - -| Laravel | Package | Maintained | -| :------ | :------------- | :----------------- | -| 9.x | 3.9.x | :white_check_mark: | -| 8.x | 3.8.x | :white_check_mark: | -| 7.x | 3.7.x | :x: | -| 6.x | 3.6.x | :x: | -| 5.8.x | 3.5.x | :x: | -| 5.7.x | 3.4.x | :x: | -| 5.6.x | 3.4.x | :x: | -| 5.5.x | 3.3.x | :x: | -| 5.4.x | 3.2.x | :x: | -| 5.3.x | 3.1.x or 3.2.x | :x: | -| 5.2.x | 2.3.x or 3.0.x | :x: | -| 5.1.x | 2.2.x or 3.0.x | :x: | -| 5.0.x | 2.1.x | :x: | -| 4.2.x | 2.0.x | :x: | +Make sure you have the MongoDB PHP driver installed. You can find installation instructions at https://php.net/manual/en/mongodb.installation.php Install the package via Composer: @@ -79,40 +59,12 @@ Install the package via Composer: $ composer require mongodb/laravel-mongodb ``` -### Laravel - In case your Laravel version does NOT autoload the packages, add the service provider to `config/app.php`: ```php MongoDB\Laravel\MongodbServiceProvider::class, ``` -### Lumen - -For usage with [Lumen](http://lumen.laravel.com), add the service provider in `bootstrap/app.php`. In this file, you will also need to enable Eloquent. You must however ensure that your call to `$app->withEloquent();` is **below** where you have registered the `MongodbServiceProvider`: - -```php -$app->register(MongoDB\Laravel\MongodbServiceProvider::class); - -$app->withEloquent(); -``` - -The service provider will register a MongoDB database extension with the original database manager. There is no need to register additional facades or objects. - -When using MongoDB connections, Laravel will automatically provide you with the corresponding MongoDB objects. - -### Non-Laravel projects - -For usage outside Laravel, check out the [Capsule manager](https://github.com/illuminate/database/blob/master/README.md) and add: - -```php -$capsule->getDatabaseManager()->extend('mongodb', function($config, $name) { - $config['name'] = $name; - - return new MongoDB\Laravel\Connection($config); -}); -``` - Testing ------- From 9d36d17cf7c0bd67bdd40614bfc3b1f5b5798a1f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Thu, 31 Aug 2023 20:17:39 +0200 Subject: [PATCH 090/446] Clean phpdoc and arg names for relation traits (#2587) --- src/Eloquent/EmbedsRelations.php | 20 +++--- src/Eloquent/HybridRelations.php | 110 +++++++++++++++++------------- src/Relations/EmbedsMany.php | 4 +- src/Relations/EmbedsOneOrMany.php | 2 +- 4 files changed, 76 insertions(+), 60 deletions(-) diff --git a/src/Eloquent/EmbedsRelations.php b/src/Eloquent/EmbedsRelations.php index 32ceb7fa4..2847de338 100644 --- a/src/Eloquent/EmbedsRelations.php +++ b/src/Eloquent/EmbedsRelations.php @@ -14,11 +14,11 @@ trait EmbedsRelations /** * Define an embedded one-to-many relationship. * - * @param string $related - * @param string $localKey - * @param string $foreignKey - * @param string $relation - * @return \MongoDB\Laravel\Relations\EmbedsMany + * @param class-string $related + * @param string|null $localKey + * @param string|null $foreignKey + * @param string|null $relation + * @return EmbedsMany */ protected function embedsMany($related, $localKey = null, $foreignKey = null, $relation = null) { @@ -47,11 +47,11 @@ protected function embedsMany($related, $localKey = null, $foreignKey = null, $r /** * Define an embedded one-to-many relationship. * - * @param string $related - * @param string $localKey - * @param string $foreignKey - * @param string $relation - * @return \MongoDB\Laravel\Relations\EmbedsOne + * @param class-string $related + * @param string|null $localKey + * @param string|null $foreignKey + * @param string|null $relation + * @return EmbedsOne */ protected function embedsOne($related, $localKey = null, $foreignKey = null, $relation = null) { diff --git a/src/Eloquent/HybridRelations.php b/src/Eloquent/HybridRelations.php index 3d86e7aac..dc735b973 100644 --- a/src/Eloquent/HybridRelations.php +++ b/src/Eloquent/HybridRelations.php @@ -2,8 +2,10 @@ namespace MongoDB\Laravel\Eloquent; +use Illuminate\Database\Eloquent\Concerns\HasRelationships; use Illuminate\Database\Eloquent\Relations\MorphOne; use Illuminate\Support\Str; +use MongoDB\Laravel\Eloquent\Model as MongoDBModel; use MongoDB\Laravel\Helpers\EloquentBuilder; use MongoDB\Laravel\Relations\BelongsTo; use MongoDB\Laravel\Relations\BelongsToMany; @@ -21,15 +23,17 @@ trait HybridRelations /** * Define a one-to-one relationship. * - * @param string $related - * @param string $foreignKey - * @param string $localKey + * @param class-string $related + * @param string|null $foreignKey + * @param string|null $localKey * @return \Illuminate\Database\Eloquent\Relations\HasOne + * + * @see HasRelationships::hasOne() */ public function hasOne($related, $foreignKey = null, $localKey = null) { // Check if it is a relation with an original model. - if (! is_subclass_of($related, \MongoDB\Laravel\Eloquent\Model::class)) { + if (! is_subclass_of($related, MongoDBModel::class)) { return parent::hasOne($related, $foreignKey, $localKey); } @@ -45,17 +49,19 @@ public function hasOne($related, $foreignKey = null, $localKey = null) /** * Define a polymorphic one-to-one relationship. * - * @param string $related + * @param class-string $related * @param string $name - * @param string $type - * @param string $id - * @param string $localKey + * @param string|null $type + * @param string|null $id + * @param string|null $localKey * @return \Illuminate\Database\Eloquent\Relations\MorphOne + * + * @see HasRelationships::morphOne() */ public function morphOne($related, $name, $type = null, $id = null, $localKey = null) { // Check if it is a relation with an original model. - if (! is_subclass_of($related, \MongoDB\Laravel\Eloquent\Model::class)) { + if (! is_subclass_of($related, MongoDBModel::class)) { return parent::morphOne($related, $name, $type, $id, $localKey); } @@ -71,15 +77,17 @@ public function morphOne($related, $name, $type = null, $id = null, $localKey = /** * Define a one-to-many relationship. * - * @param string $related - * @param string $foreignKey - * @param string $localKey + * @param class-string $related + * @param string|null $foreignKey + * @param string|null $localKey * @return \Illuminate\Database\Eloquent\Relations\HasMany + * + * @see HasRelationships::hasMany() */ public function hasMany($related, $foreignKey = null, $localKey = null) { // Check if it is a relation with an original model. - if (! is_subclass_of($related, \MongoDB\Laravel\Eloquent\Model::class)) { + if (! is_subclass_of($related, MongoDBModel::class)) { return parent::hasMany($related, $foreignKey, $localKey); } @@ -95,17 +103,19 @@ public function hasMany($related, $foreignKey = null, $localKey = null) /** * Define a polymorphic one-to-many relationship. * - * @param string $related + * @param class-string $related * @param string $name - * @param string $type - * @param string $id - * @param string $localKey + * @param string|null $type + * @param string|null $id + * @param string|null $localKey * @return \Illuminate\Database\Eloquent\Relations\MorphMany + * + * @see HasRelationships::morphMany() */ public function morphMany($related, $name, $type = null, $id = null, $localKey = null) { // Check if it is a relation with an original model. - if (! is_subclass_of($related, \MongoDB\Laravel\Eloquent\Model::class)) { + if (! is_subclass_of($related, MongoDBModel::class)) { return parent::morphMany($related, $name, $type, $id, $localKey); } @@ -126,13 +136,15 @@ public function morphMany($related, $name, $type = null, $id = null, $localKey = /** * Define an inverse one-to-one or many relationship. * - * @param string $related - * @param string $foreignKey - * @param string $otherKey - * @param string $relation + * @param class-string $related + * @param string|null $foreignKey + * @param string|null $ownerKey + * @param string|null $relation * @return \Illuminate\Database\Eloquent\Relations\BelongsTo + * + * @see HasRelationships::belongsTo() */ - public function belongsTo($related, $foreignKey = null, $otherKey = null, $relation = null) + public function belongsTo($related, $foreignKey = null, $ownerKey = null, $relation = null) { // If no relation name was given, we will use this debug backtrace to extract // the calling method's name and use that as the relationship name as most @@ -142,8 +154,8 @@ public function belongsTo($related, $foreignKey = null, $otherKey = null, $relat } // Check if it is a relation with an original model. - if (! is_subclass_of($related, \MongoDB\Laravel\Eloquent\Model::class)) { - return parent::belongsTo($related, $foreignKey, $otherKey, $relation); + if (! is_subclass_of($related, MongoDBModel::class)) { + return parent::belongsTo($related, $foreignKey, $ownerKey, $relation); } // If no foreign key was supplied, we can use a backtrace to guess the proper @@ -160,19 +172,21 @@ public function belongsTo($related, $foreignKey = null, $otherKey = null, $relat // actually be responsible for retrieving and hydrating every relations. $query = $instance->newQuery(); - $otherKey = $otherKey ?: $instance->getKeyName(); + $ownerKey = $ownerKey ?: $instance->getKeyName(); - return new BelongsTo($query, $this, $foreignKey, $otherKey, $relation); + return new BelongsTo($query, $this, $foreignKey, $ownerKey, $relation); } /** * Define a polymorphic, inverse one-to-one or many relationship. * * @param string $name - * @param string $type - * @param string $id - * @param string $ownerKey + * @param string|null $type + * @param string|null $id + * @param string|null $ownerKey * @return \Illuminate\Database\Eloquent\Relations\MorphTo + * + * @see HasRelationships::morphTo() */ public function morphTo($name = null, $type = null, $id = null, $ownerKey = null) { @@ -211,20 +225,22 @@ public function morphTo($name = null, $type = null, $id = null, $ownerKey = null /** * Define a many-to-many relationship. * - * @param string $related - * @param string $collection - * @param string $foreignKey - * @param string $otherKey - * @param string $parentKey - * @param string $relatedKey - * @param string $relation + * @param class-string $related + * @param string|null $collection + * @param string|null $foreignPivotKey + * @param string|null $relatedPivotKey + * @param string|null $parentKey + * @param string|null $relatedKey + * @param string|null $relation * @return \Illuminate\Database\Eloquent\Relations\BelongsToMany + * + * @see HasRelationships::belongsToMany() */ public function belongsToMany( $related, $collection = null, - $foreignKey = null, - $otherKey = null, + $foreignPivotKey = null, + $relatedPivotKey = null, $parentKey = null, $relatedKey = null, $relation = null @@ -237,12 +253,12 @@ public function belongsToMany( } // Check if it is a relation with an original model. - if (! is_subclass_of($related, \MongoDB\Laravel\Eloquent\Model::class)) { + if (! is_subclass_of($related, MongoDBModel::class)) { return parent::belongsToMany( $related, $collection, - $foreignKey, - $otherKey, + $foreignPivotKey, + $relatedPivotKey, $parentKey, $relatedKey, $relation @@ -252,11 +268,11 @@ public function belongsToMany( // First, we'll need to determine the foreign key and "other key" for the // relationship. Once we have determined the keys we'll make the query // instances as well as the relationship instances we need for this. - $foreignKey = $foreignKey ?: $this->getForeignKey().'s'; + $foreignPivotKey = $foreignPivotKey ?: $this->getForeignKey().'s'; $instance = new $related; - $otherKey = $otherKey ?: $instance->getForeignKey().'s'; + $relatedPivotKey = $relatedPivotKey ?: $instance->getForeignKey().'s'; // If no table name was provided, we can guess it by concatenating the two // models using underscores in alphabetical order. The two model names @@ -274,8 +290,8 @@ public function belongsToMany( $query, $this, $collection, - $foreignKey, - $otherKey, + $foreignPivotKey, + $relatedPivotKey, $parentKey ?: $this->getKeyName(), $relatedKey ?: $instance->getKeyName(), $relation @@ -301,7 +317,7 @@ protected function guessBelongsToManyRelation() */ public function newEloquentBuilder($query) { - if (is_subclass_of($this, \MongoDB\Laravel\Eloquent\Model::class)) { + if ($this instanceof MongoDBModel) { return new Builder($query); } diff --git a/src/Relations/EmbedsMany.php b/src/Relations/EmbedsMany.php index ece7ee7ff..be8d5f737 100644 --- a/src/Relations/EmbedsMany.php +++ b/src/Relations/EmbedsMany.php @@ -277,10 +277,10 @@ protected function associateExisting($model) } /** - * @param null $perPage + * @param int|null $perPage * @param array $columns * @param string $pageName - * @param null $page + * @param int|null $page * @return \Illuminate\Contracts\Pagination\LengthAwarePaginator */ public function paginate($perPage = null, $columns = ['*'], $pageName = 'page', $page = null) diff --git a/src/Relations/EmbedsOneOrMany.php b/src/Relations/EmbedsOneOrMany.php index 356848483..200cdf65e 100644 --- a/src/Relations/EmbedsOneOrMany.php +++ b/src/Relations/EmbedsOneOrMany.php @@ -41,7 +41,7 @@ abstract class EmbedsOneOrMany extends Relation * @param string $foreignKey * @param string $relation */ - public function __construct(Builder $query, Model $parent, Model $related, $localKey, $foreignKey, $relation) + public function __construct(Builder $query, Model $parent, Model $related, string $localKey, string $foreignKey, string $relation) { $this->query = $query; $this->parent = $parent; From ad79fb19faf6be454bc22e54b05346e4829f38db Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Fri, 1 Sep 2023 10:51:56 +0200 Subject: [PATCH 091/446] Support delete one document with the query builder (#2591) * Support delete one document MongoDB PHP Library supports deleting one or all documents only. So we cannot accept other limits than null (unlimited) or 1. The notion of limit: 0 meaning "delete all" is an implementation detail of MongoDB's delete command and not a general concept. * Update changelog after repository move --- CHANGELOG.md | 41 +++++++++++++++++++++-------------------- src/Query/Builder.php | 9 ++++++++- tests/QueryTest.php | 36 ++++++++++++++++++++++++++++++++++++ 3 files changed, 65 insertions(+), 21 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 962d4aa03..fe44cbfb8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,54 +19,55 @@ All notable changes to this project will be documented in this file. - Fix validation of unique values when the validated value is found as part of an existing value. [#21](https://github.com/GromNaN/laravel-mongodb/pull/21) by [@GromNaN](https://github.com/GromNaN). - Support `%` and `_` in `like` expression [#17](https://github.com/GromNaN/laravel-mongodb/pull/17) by [@GromNaN](https://github.com/GromNaN). - Change signature of `Query\Builder::__constructor` to match the parent class [#26](https://github.com/GromNaN/laravel-mongodb-private/pull/26) by [@GromNaN](https://github.com/GromNaN). -- Fix Query on `whereDate`, `whereDay`, `whereMonth`, `whereYear`, `whereTime` to use MongoDB operators [#2570](https://github.com/jenssegers/laravel-mongodb/pull/2376) by [@Davpyu](https://github.com/Davpyu) and [@GromNaN](https://github.com/GromNaN). -- `Model::unset()` does not persist the change. Call `Model::save()` to persist the change [#2578](https://github.com/jenssegers/laravel-mongodb/pull/2578) by [@GromNaN](https://github.com/GromNaN). +- Fix Query on `whereDate`, `whereDay`, `whereMonth`, `whereYear`, `whereTime` to use MongoDB operators [#2570](https://github.com/mongodb/laravel-mongodb/pull/2376) by [@Davpyu](https://github.com/Davpyu) and [@GromNaN](https://github.com/GromNaN). +- `Model::unset()` does not persist the change. Call `Model::save()` to persist the change [#2578](https://github.com/mongodb/laravel-mongodb/pull/2578) by [@GromNaN](https://github.com/GromNaN). +- Support delete one document with `Query\Builder::limit(1)->delete()` [#2591](https://github.com/mongodb/laravel-mongodb/pull/2591) by [@GromNaN](https://github.com/GromNaN) ## [3.9.2] - 2022-09-01 ### Added -- Add single word name mutators [#2438](https://github.com/jenssegers/laravel-mongodb/pull/2438) by [@RosemaryOrchard](https://github.com/RosemaryOrchard) & [@mrneatly](https://github.com/mrneatly). +- Add single word name mutators [#2438](https://github.com/mongodb/laravel-mongodb/pull/2438) by [@RosemaryOrchard](https://github.com/RosemaryOrchard) & [@mrneatly](https://github.com/mrneatly). ### Fixed -- Fix stringable sort [#2420](https://github.com/jenssegers/laravel-mongodb/pull/2420) by [@apeisa](https://github.com/apeisa). +- Fix stringable sort [#2420](https://github.com/mongodb/laravel-mongodb/pull/2420) by [@apeisa](https://github.com/apeisa). ## [3.9.1] - 2022-03-11 ### Added -- Backport support for cursor pagination [#2358](https://github.com/jenssegers/laravel-mongodb/pull/2358) by [@Jeroenwv](https://github.com/Jeroenwv). +- Backport support for cursor pagination [#2358](https://github.com/mongodb/laravel-mongodb/pull/2358) by [@Jeroenwv](https://github.com/Jeroenwv). ### Fixed -- Check if queue service is disabled [#2357](https://github.com/jenssegers/laravel-mongodb/pull/2357) by [@robjbrain](https://github.com/robjbrain). +- Check if queue service is disabled [#2357](https://github.com/mongodb/laravel-mongodb/pull/2357) by [@robjbrain](https://github.com/robjbrain). ## [3.9.0] - 2022-02-17 ### Added -- Compatibility with Laravel 9.x [#2344](https://github.com/jenssegers/laravel-mongodb/pull/2344) by [@divine](https://github.com/divine). +- Compatibility with Laravel 9.x [#2344](https://github.com/mongodb/laravel-mongodb/pull/2344) by [@divine](https://github.com/divine). ## [3.8.4] - 2021-05-27 ### Fixed -- Fix getRelationQuery breaking changes [#2263](https://github.com/jenssegers/laravel-mongodb/pull/2263) by [@divine](https://github.com/divine). -- Apply fixes produced by php-cs-fixer [#2250](https://github.com/jenssegers/laravel-mongodb/pull/2250) by [@divine](https://github.com/divine). +- Fix getRelationQuery breaking changes [#2263](https://github.com/mongodb/laravel-mongodb/pull/2263) by [@divine](https://github.com/divine). +- Apply fixes produced by php-cs-fixer [#2250](https://github.com/mongodb/laravel-mongodb/pull/2250) by [@divine](https://github.com/divine). ### Changed -- Add doesntExist to passthru [#2194](https://github.com/jenssegers/laravel-mongodb/pull/2194) by [@simonschaufi](https://github.com/simonschaufi). -- Add Model query whereDate support [#2251](https://github.com/jenssegers/laravel-mongodb/pull/2251) by [@yexk](https://github.com/yexk). -- Add transaction free deleteAndRelease() method [#2229](https://github.com/jenssegers/laravel-mongodb/pull/2229) by [@sodoardi](https://github.com/sodoardi). -- Add setDatabase to Jenssegers\Mongodb\Connection [#2236](https://github.com/jenssegers/laravel-mongodb/pull/2236) by [@ThomasWestrelin](https://github.com/ThomasWestrelin). -- Check dates against DateTimeInterface instead of DateTime [#2239](https://github.com/jenssegers/laravel-mongodb/pull/2239) by [@jeromegamez](https://github.com/jeromegamez). -- Move from psr-0 to psr-4 [#2247](https://github.com/jenssegers/laravel-mongodb/pull/2247) by [@divine](https://github.com/divine). +- Add doesntExist to passthru [#2194](https://github.com/mongodb/laravel-mongodb/pull/2194) by [@simonschaufi](https://github.com/simonschaufi). +- Add Model query whereDate support [#2251](https://github.com/mongodb/laravel-mongodb/pull/2251) by [@yexk](https://github.com/yexk). +- Add transaction free deleteAndRelease() method [#2229](https://github.com/mongodb/laravel-mongodb/pull/2229) by [@sodoardi](https://github.com/sodoardi). +- Add setDatabase to Jenssegers\Mongodb\Connection [#2236](https://github.com/mongodb/laravel-mongodb/pull/2236) by [@ThomasWestrelin](https://github.com/ThomasWestrelin). +- Check dates against DateTimeInterface instead of DateTime [#2239](https://github.com/mongodb/laravel-mongodb/pull/2239) by [@jeromegamez](https://github.com/jeromegamez). +- Move from psr-0 to psr-4 [#2247](https://github.com/mongodb/laravel-mongodb/pull/2247) by [@divine](https://github.com/divine). ## [3.8.3] - 2021-02-21 ### Changed -- Fix query builder regression [#2204](https://github.com/jenssegers/laravel-mongodb/pull/2204) by [@divine](https://github.com/divine). +- Fix query builder regression [#2204](https://github.com/mongodb/laravel-mongodb/pull/2204) by [@divine](https://github.com/divine). ## [3.8.2] - 2020-12-18 ### Changed -- MongodbQueueServiceProvider does not use the DB Facade anymore [#2149](https://github.com/jenssegers/laravel-mongodb/pull/2149) by [@curosmj](https://github.com/curosmj). -- Add escape regex chars to DB Presence Verifier [#1992](https://github.com/jenssegers/laravel-mongodb/pull/1992) by [@andrei-gafton-rtgt](https://github.com/andrei-gafton-rtgt). +- MongodbQueueServiceProvider does not use the DB Facade anymore [#2149](https://github.com/mongodb/laravel-mongodb/pull/2149) by [@curosmj](https://github.com/curosmj). +- Add escape regex chars to DB Presence Verifier [#1992](https://github.com/mongodb/laravel-mongodb/pull/1992) by [@andrei-gafton-rtgt](https://github.com/andrei-gafton-rtgt). ## [3.8.1] - 2020-10-23 @@ -74,9 +75,9 @@ All notable changes to this project will be documented in this file. - Laravel 8 support by [@divine](https://github.com/divine). ### Changed -- Fix like with numeric values [#2127](https://github.com/jenssegers/laravel-mongodb/pull/2127) by [@hnassr](https://github.com/hnassr). +- Fix like with numeric values [#2127](https://github.com/mongodb/laravel-mongodb/pull/2127) by [@hnassr](https://github.com/hnassr). ## [3.8.0] - 2020-09-03 ### Added -- Laravel 8 support & updated versions of all dependencies [#2108](https://github.com/jenssegers/laravel-mongodb/pull/2108) by [@divine](https://github.com/divine). +- Laravel 8 support & updated versions of all dependencies [#2108](https://github.com/mongodb/laravel-mongodb/pull/2108) by [@divine](https://github.com/divine). diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 50b3ba34f..6a37e1608 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -703,7 +703,14 @@ public function delete($id = null) $wheres = $this->compileWheres(); $options = $this->inheritConnectionOptions(); - $result = $this->collection->deleteMany($wheres, $options); + 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 (1 == (int) $result->isAcknowledged()) { return $result->getDeletedCount(); diff --git a/tests/QueryTest.php b/tests/QueryTest.php index 03713ffae..2a9bd4085 100644 --- a/tests/QueryTest.php +++ b/tests/QueryTest.php @@ -548,4 +548,40 @@ public function testMultipleSortOrder(): void $this->assertEquals('John Doe', $subset[1]->name); $this->assertEquals('Brett Boe', $subset[2]->name); } + + public function testDelete(): void + { + // Check fixtures + $this->assertEquals(3, User::where('title', 'admin')->count()); + + // Delete a single document with filter + User::where('title', 'admin')->limit(1)->delete(); + $this->assertEquals(2, User::where('title', 'admin')->count()); + + // Delete all with filter + User::where('title', 'admin')->delete(); + $this->assertEquals(0, User::where('title', 'admin')->count()); + + // Check remaining fixtures + $this->assertEquals(6, User::count()); + + // Delete a single document + User::limit(1)->delete(); + $this->assertEquals(5, User::count()); + + // Delete all + User::limit(null)->delete(); + $this->assertEquals(0, User::count()); + } + + /** + * @testWith [0] + * [2] + */ + public function testDeleteException(int $limit): void + { + $this->expectException(\LogicException::class); + $this->expectExceptionMessage('Delete limit can be 1 or null (unlimited).'); + User::limit($limit)->delete(); + } } From 51bbdf7a31be1c8f597caf31adca011b2767be41 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 5 Sep 2023 09:31:38 +0200 Subject: [PATCH 092/446] Support ipv6 in host config (#2595) --- src/Connection.php | 14 +++++++++--- tests/ConnectionTest.php | 48 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 59 insertions(+), 3 deletions(-) diff --git a/src/Connection.php b/src/Connection.php index 9b12575f0..99bfbd04a 100644 --- a/src/Connection.php +++ b/src/Connection.php @@ -234,9 +234,17 @@ protected function getHostDsn(array $config): string $hosts = is_array($config['host']) ? $config['host'] : [$config['host']]; foreach ($hosts as &$host) { - // Check if we need to add a port to the host - if (strpos($host, ':') === false && ! empty($config['port'])) { - $host = $host.':'.$config['port']; + // ipv6 + if (filter_var($host, \FILTER_VALIDATE_IP, \FILTER_FLAG_IPV6)) { + $host = '['.$host.']'; + if (! empty($config['port'])) { + $host = $host.':'.$config['port']; + } + } else { + // Check if we need to add a port to the host + if (! str_contains($host, ':') && ! empty($config['port'])) { + $host = $host.':'.$config['port']; + } } } diff --git a/tests/ConnectionTest.php b/tests/ConnectionTest.php index de1c329eb..77a2dce78 100644 --- a/tests/ConnectionTest.php +++ b/tests/ConnectionTest.php @@ -62,6 +62,54 @@ public function dataConnectionConfig(): Generator ], ]; + yield 'IPv4' => [ + 'expectedUri' => 'mongodb://1.2.3.4', + 'expectedDatabaseName' => 'tests', + 'config' => [ + 'host' => '1.2.3.4', + 'database' => 'tests', + ], + ]; + + yield 'IPv4 and port' => [ + 'expectedUri' => 'mongodb://1.2.3.4:1234', + 'expectedDatabaseName' => 'tests', + 'config' => [ + 'host' => '1.2.3.4', + 'port' => 1234, + 'database' => 'tests', + ], + ]; + + yield 'IPv6' => [ + 'expectedUri' => 'mongodb://[2001:db8:3333:4444:5555:6666:7777:8888]', + 'expectedDatabaseName' => 'tests', + 'config' => [ + 'host' => '2001:db8:3333:4444:5555:6666:7777:8888', + 'database' => 'tests', + ], + ]; + + yield 'IPv6 and port' => [ + 'expectedUri' => 'mongodb://[2001:db8:3333:4444:5555:6666:7777:8888]:1234', + 'expectedDatabaseName' => 'tests', + 'config' => [ + 'host' => '2001:db8:3333:4444:5555:6666:7777:8888', + 'port' => 1234, + 'database' => 'tests', + ], + ]; + + yield 'multiple IPv6' => [ + 'expectedUri' => 'mongodb://[::1],[2001:db8::1:0:0:1]', + 'expectedDatabaseName' => 'tests', + 'config' => [ + 'host' => ['::1', '2001:db8::1:0:0:1'], + 'port' => null, + 'database' => 'tests', + ], + ]; + yield 'Port in host name takes precedence' => [ 'expectedUri' => 'mongodb://some-host:12345', 'expectedDatabaseName' => 'tests', From 810d0c96fc29da927f8c96cbb872550cf79ea44e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 5 Sep 2023 09:46:33 +0200 Subject: [PATCH 093/446] Implement MassPrunable without chunks limit (#2598) Custom implementation of MassPrunable is required to prevent using the limit. #2591 added an exception when limited is used because MongoDB Delete operation doesn't support it. - MassPrunable::pruneAll() is called by the command model:prune. - Using the parent trait is required because it's used to detect prunable models. - Prunable feature was introducted in Laravel 8.x by laravel/framework#37889. Users have to be aware that MassPrunable can break relationships as it doesn't call model methods to remove links. --- CHANGELOG.md | 1 + README.md | 22 ++++++++++ src/Eloquent/MassPrunable.php | 28 +++++++++++++ tests/Eloquent/MassPrunableTest.php | 63 +++++++++++++++++++++++++++++ tests/Models/Soft.php | 8 ++++ tests/Models/User.php | 8 ++++ 6 files changed, 130 insertions(+) create mode 100644 src/Eloquent/MassPrunable.php create mode 100644 tests/Eloquent/MassPrunableTest.php diff --git a/CHANGELOG.md b/CHANGELOG.md index fe44cbfb8..3841b715c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,6 +22,7 @@ All notable changes to this project will be documented in this file. - Fix Query on `whereDate`, `whereDay`, `whereMonth`, `whereYear`, `whereTime` to use MongoDB operators [#2570](https://github.com/mongodb/laravel-mongodb/pull/2376) by [@Davpyu](https://github.com/Davpyu) and [@GromNaN](https://github.com/GromNaN). - `Model::unset()` does not persist the change. Call `Model::save()` to persist the change [#2578](https://github.com/mongodb/laravel-mongodb/pull/2578) by [@GromNaN](https://github.com/GromNaN). - Support delete one document with `Query\Builder::limit(1)->delete()` [#2591](https://github.com/mongodb/laravel-mongodb/pull/2591) by [@GromNaN](https://github.com/GromNaN) +- Add trait `MongoDB\Laravel\Eloquent\MassPrunable` to replace the Eloquent trait on MongoDB models [#2598](https://github.com/mongodb/laravel-mongodb/pull/2598) by [@GromNaN](https://github.com/GromNaN) ## [3.9.2] - 2022-09-01 diff --git a/README.md b/README.md index d7a505bd1..e5e599cfd 100644 --- a/README.md +++ b/README.md @@ -44,6 +44,7 @@ It is compatible with Laravel 10.x. For older versions of Laravel, please refer - [Cross-Database Relationships](#cross-database-relationships) - [Authentication](#authentication) - [Queues](#queues) + - [Prunable](#prunable) - [Upgrading](#upgrading) - [Upgrading from version 2 to 3](#upgrading-from-version-2-to-3) - [Security contact information](#security-contact-information) @@ -1189,14 +1190,35 @@ Add the service provider in `config/app.php`: MongoDB\Laravel\MongodbQueueServiceProvider::class, ``` +### Prunable + +`Prunable` and `MassPrunable` traits are Laravel features to automatically remove models from your database. You can use +`Illuminate\Database\Eloquent\Prunable` trait to remove models one by one. If you want to remove models in bulk, you need +to use the `MongoDB\Laravel\Eloquent\MassPrunable` trait instead: it will be more performant but can break links with +other documents as it does not load the models. + + +```php +use MongoDB\Laravel\Eloquent\Model; +use MongoDB\Laravel\Eloquent\MassPrunable; + +class Book extends Model +{ + use MassPrunable; +} +``` + Upgrading --------- #### Upgrading from version 3 to 4 Change project name in composer.json to `mongodb/laravel` and run `composer update`. + Change namespace from `Jenssegers\Mongodb` to `MongoDB\Laravel` in your models and config. +Replace `Illuminate\Database\Eloquent\MassPrunable` with `MongoDB\Laravel\Eloquent\MassPrunable` in your models. + ## Security contact information To report a security vulnerability, follow [these steps](https://tidelift.com/security). diff --git a/src/Eloquent/MassPrunable.php b/src/Eloquent/MassPrunable.php new file mode 100644 index 000000000..df8839d5d --- /dev/null +++ b/src/Eloquent/MassPrunable.php @@ -0,0 +1,28 @@ +prunable(); + $total = in_array(SoftDeletes::class, class_uses_recursive(get_class($this))) + ? $query->forceDelete() + : $query->delete(); + + event(new ModelsPruned(static::class, $total)); + + return $total; + } +} diff --git a/tests/Eloquent/MassPrunableTest.php b/tests/Eloquent/MassPrunableTest.php new file mode 100644 index 000000000..3426a2443 --- /dev/null +++ b/tests/Eloquent/MassPrunableTest.php @@ -0,0 +1,63 @@ +assertTrue($this->isPrunable(User::class)); + + User::insert([ + ['name' => 'John Doe', 'age' => 35], + ['name' => 'Jane Doe', 'age' => 32], + ['name' => 'Tomy Doe', 'age' => 11], + ]); + + $model = new User(); + $total = $model->pruneAll(); + $this->assertEquals(2, $total); + $this->assertEquals(1, User::count()); + } + + public function testPruneSoftDelete(): void + { + $this->assertTrue($this->isPrunable(Soft::class)); + + Soft::insert([ + ['name' => 'John Doe'], + ['name' => 'Jane Doe'], + ]); + + $model = new Soft(); + $total = $model->pruneAll(); + $this->assertEquals(2, $total); + $this->assertEquals(0, Soft::count()); + $this->assertEquals(0, Soft::withTrashed()->count()); + } + + /** + * @see PruneCommand::isPrunable() + */ + protected function isPrunable($model) + { + $uses = class_uses_recursive($model); + + return in_array(Prunable::class, $uses) || in_array(MassPrunable::class, $uses); + } +} diff --git a/tests/Models/Soft.php b/tests/Models/Soft.php index aec3a0bb9..7a5d25704 100644 --- a/tests/Models/Soft.php +++ b/tests/Models/Soft.php @@ -4,6 +4,8 @@ namespace MongoDB\Laravel\Tests\Models; +use MongoDB\Laravel\Eloquent\Builder; +use MongoDB\Laravel\Eloquent\MassPrunable; use MongoDB\Laravel\Eloquent\Model as Eloquent; use MongoDB\Laravel\Eloquent\SoftDeletes; @@ -15,9 +17,15 @@ class Soft extends Eloquent { use SoftDeletes; + use MassPrunable; protected $connection = 'mongodb'; protected $collection = 'soft'; protected static $unguarded = true; protected $casts = ['deleted_at' => 'datetime']; + + public function prunable(): Builder + { + return $this->newQuery(); + } } diff --git a/tests/Models/User.php b/tests/Models/User.php index f1d373fab..57319f84a 100644 --- a/tests/Models/User.php +++ b/tests/Models/User.php @@ -12,7 +12,9 @@ use Illuminate\Database\Eloquent\Casts\Attribute; use Illuminate\Notifications\Notifiable; use Illuminate\Support\Str; +use MongoDB\Laravel\Eloquent\Builder; use MongoDB\Laravel\Eloquent\HybridRelations; +use MongoDB\Laravel\Eloquent\MassPrunable; use MongoDB\Laravel\Eloquent\Model as Eloquent; /** @@ -35,6 +37,7 @@ class User extends Eloquent implements AuthenticatableContract, CanResetPassword use CanResetPassword; use HybridRelations; use Notifiable; + use MassPrunable; protected $connection = 'mongodb'; protected $casts = [ @@ -106,4 +109,9 @@ protected function username(): Attribute set: fn ($value) => Str::slug($value) ); } + + public function prunable(): Builder + { + return $this->where('age', '>', 18); + } } From 86aa9c758ea1449b99e9d19fb674efaec1aa1287 Mon Sep 17 00:00:00 2001 From: wivaku Date: Tue, 5 Sep 2023 11:40:11 +0200 Subject: [PATCH 094/446] make sure $column is string (#2593) Native Eloquent allows $column to be stringable(). Not possible when using as array key. --- src/Query/Builder.php | 12 ++++++-- tests/QueryBuilderTest.php | 61 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 70 insertions(+), 3 deletions(-) diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 6a37e1608..e73ef150a 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -625,7 +625,7 @@ public function update(array $values, array $options = []) */ public function increment($column, $amount = 1, array $extra = [], array $options = []) { - $query = ['$inc' => [$column => $amount]]; + $query = ['$inc' => [(string) $column => $amount]]; if (! empty($extra)) { $query['$set'] = $extra; @@ -797,9 +797,9 @@ public function push($column, $value = null, $unique = false) } $query = [$operator => $column]; } elseif ($batch) { - $query = [$operator => [$column => ['$each' => $value]]]; + $query = [$operator => [(string) $column => ['$each' => $value]]]; } else { - $query = [$operator => [$column => $value]]; + $query = [$operator => [(string) $column => $value]]; } return $this->performUpdate($query); @@ -1004,8 +1004,14 @@ protected function compileWheres(): array $where['boolean'] = 'or'.(str_ends_with($where['boolean'], 'not') ? ' not' : ''); } + // Column name can be a Stringable object. + if (isset($where['column']) && $where['column'] instanceof \Stringable) { + $where['column'] = (string) $where['column']; + } + // We use different methods to compile different wheres. $method = "compileWhere{$where['type']}"; + $result = $this->{$method}($where); if (str_ends_with($where['boolean'], 'not')) { diff --git a/tests/QueryBuilderTest.php b/tests/QueryBuilderTest.php index 6c4e14f6e..eabdaca1c 100644 --- a/tests/QueryBuilderTest.php +++ b/tests/QueryBuilderTest.php @@ -9,6 +9,7 @@ use Illuminate\Support\Facades\Date; use Illuminate\Support\Facades\DB; use Illuminate\Support\LazyCollection; +use Illuminate\Support\Str; use Illuminate\Testing\Assert; use MongoDB\BSON\ObjectId; use MongoDB\BSON\Regex; @@ -895,4 +896,64 @@ public function testCursor() $this->assertEquals($data[$i]['name'], $result['name']); } } + + public function testStringableColumn() + { + DB::collection('users')->insert([ + ['name' => 'Jane Doe', 'age' => 36, 'birthday' => new UTCDateTime(new \DateTime('1987-01-01 00:00:00'))], + ['name' => 'John Doe', 'age' => 28, 'birthday' => new UTCDateTime(new \DateTime('1995-01-01 00:00:00'))], + ]); + + $nameColumn = Str::of('name'); + $this->assertInstanceOf(\Stringable::class, $nameColumn, 'Ensure we are testing the feature with a Stringable instance'); + + $user = DB::collection('users')->where($nameColumn, 'John Doe')->first(); + $this->assertEquals('John Doe', $user['name']); + + // Test this other document to be sure this is not a random success to data order + $user = DB::collection('users')->where($nameColumn, 'Jane Doe')->orderBy('natural')->first(); + $this->assertEquals('Jane Doe', $user['name']); + + // With an operator + $user = DB::collection('users')->where($nameColumn, '!=', 'Jane Doe')->first(); + $this->assertEquals('John Doe', $user['name']); + + // whereIn and whereNotIn + $user = DB::collection('users')->whereIn($nameColumn, ['John Doe'])->first(); + $this->assertEquals('John Doe', $user['name']); + + $user = DB::collection('users')->whereNotIn($nameColumn, ['John Doe'])->first(); + $this->assertEquals('Jane Doe', $user['name']); + + // whereBetween and whereNotBetween + $ageColumn = Str::of('age'); + $user = DB::collection('users')->whereBetween($ageColumn, [30, 40])->first(); + $this->assertEquals('Jane Doe', $user['name']); + + // whereBetween and whereNotBetween + $ageColumn = Str::of('age'); + $user = DB::collection('users')->whereNotBetween($ageColumn, [30, 40])->first(); + $this->assertEquals('John Doe', $user['name']); + + // whereDate + $birthdayColumn = Str::of('birthday'); + $user = DB::collection('users')->whereDate($birthdayColumn, '1995-01-01')->first(); + $this->assertEquals('John Doe', $user['name']); + + $user = DB::collection('users')->whereDate($birthdayColumn, '<', '1990-01-01') + ->orderBy($birthdayColumn, 'desc')->first(); + $this->assertEquals('Jane Doe', $user['name']); + + $user = DB::collection('users')->whereDate($birthdayColumn, '>', '1990-01-01') + ->orderBy($birthdayColumn, 'asc')->first(); + $this->assertEquals('John Doe', $user['name']); + + $user = DB::collection('users')->whereDate($birthdayColumn, '!=', '1987-01-01')->first(); + $this->assertEquals('John Doe', $user['name']); + + // increment + DB::collection('users')->where($ageColumn, 28)->increment($ageColumn, 1); + $user = DB::collection('users')->where($ageColumn, 29)->first(); + $this->assertEquals('John Doe', $user['name']); + } } From 2ea9f7af8e0090b1f29b797660b6c71d8a458b0b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 6 Sep 2023 08:43:06 +0200 Subject: [PATCH 095/446] Add tests on null date casts (#2592) --- tests/ModelTest.php | 193 +++++++++++++------------------------------- 1 file changed, 57 insertions(+), 136 deletions(-) diff --git a/tests/ModelTest.php b/tests/ModelTest.php index 6b3e5eb57..d592228ec 100644 --- a/tests/ModelTest.php +++ b/tests/ModelTest.php @@ -6,7 +6,6 @@ use Carbon\Carbon; use DateTime; -use DateTimeImmutable; use Illuminate\Database\Eloquent\Collection as EloquentCollection; use Illuminate\Database\Eloquent\ModelNotFoundException; use Illuminate\Support\Facades\Date; @@ -657,161 +656,83 @@ public function testDates(): void $item = Item::create(['name' => 'sword']); $json = $item->toArray(); $this->assertEquals($item->created_at->toISOString(), $json['created_at']); + } - /** @var User $user */ - //Test with create and standard property - $user = User::create(['name' => 'Jane Doe', 'birthday' => time()]); - $this->assertInstanceOf(Carbon::class, $user->birthday); - - $user = User::create(['name' => 'Jane Doe', 'birthday' => Date::now()]); - $this->assertInstanceOf(Carbon::class, $user->birthday); - - $user = User::create(['name' => 'Jane Doe', 'birthday' => 'Monday 8th August 2005 03:12:46 PM']); - $this->assertInstanceOf(Carbon::class, $user->birthday); - - $user = User::create(['name' => 'Jane Doe', 'birthday' => 'Monday 8th August 1960 03:12:46 PM']); - $this->assertInstanceOf(Carbon::class, $user->birthday); - - $user = User::create(['name' => 'Jane Doe', 'birthday' => '2005-08-08']); - $this->assertInstanceOf(Carbon::class, $user->birthday); - - $user = User::create(['name' => 'Jane Doe', 'birthday' => '1965-08-08']); - $this->assertInstanceOf(Carbon::class, $user->birthday); - - $user = User::create(['name' => 'Jane Doe', 'birthday' => new DateTime('2010-08-08')]); - $this->assertInstanceOf(Carbon::class, $user->birthday); - - $user = User::create(['name' => 'Jane Doe', 'birthday' => new DateTime('1965-08-08')]); - $this->assertInstanceOf(Carbon::class, $user->birthday); - - $user = User::create(['name' => 'Jane Doe', 'birthday' => new DateTime('2010-08-08 04.08.37')]); - $this->assertInstanceOf(Carbon::class, $user->birthday); - - $user = User::create(['name' => 'Jane Doe', 'birthday' => new DateTime('1965-08-08 04.08.37')]); - $this->assertInstanceOf(Carbon::class, $user->birthday); - - $user = User::create(['name' => 'Jane Doe', 'birthday' => new DateTime('2010-08-08 04.08.37.324')]); - $this->assertInstanceOf(Carbon::class, $user->birthday); + public static function provideDate(): \Generator + { + yield 'int timestamp' => [time()]; + yield 'Carbon date' => [Date::now()]; + yield 'Date in words' => ['Monday 8th August 2005 03:12:46 PM']; + yield 'Date in words before unix epoch' => ['Monday 8th August 1960 03:12:46 PM']; + yield 'Date' => ['2005-08-08']; + yield 'Date before unix epoch' => ['1965-08-08']; + yield 'DateTime date' => [new DateTime('2010-08-08')]; + yield 'DateTime date before unix epoch' => [new DateTime('1965-08-08')]; + yield 'DateTime date and time' => [new DateTime('2010-08-08 04.08.37')]; + yield 'DateTime date and time before unix epoch' => [new DateTime('1965-08-08 04.08.37')]; + yield 'DateTime date, time and ms' => [new DateTime('2010-08-08 04.08.37.324')]; + yield 'DateTime date, time and ms before unix epoch' => [new DateTime('1965-08-08 04.08.37.324')]; + } - $user = User::create(['name' => 'Jane Doe', 'birthday' => new DateTime('1965-08-08 04.08.37.324')]); + /** + * @dataProvider provideDate + */ + public function testDateInputs($date): void + { + /** @var User $user */ + // Test with create and standard property + $user = User::create(['name' => 'Jane Doe', 'birthday' => $date]); $this->assertInstanceOf(Carbon::class, $user->birthday); //Test with setAttribute and standard property - $user->setAttribute('birthday', time()); - $this->assertInstanceOf(Carbon::class, $user->birthday); - - $user->setAttribute('birthday', Date::now()); - $this->assertInstanceOf(Carbon::class, $user->birthday); - - $user->setAttribute('birthday', 'Monday 8th August 2005 03:12:46 PM'); - $this->assertInstanceOf(Carbon::class, $user->birthday); - - $user->setAttribute('birthday', 'Monday 8th August 1960 03:12:46 PM'); - $this->assertInstanceOf(Carbon::class, $user->birthday); - - $user->setAttribute('birthday', '2005-08-08'); - $this->assertInstanceOf(Carbon::class, $user->birthday); - - $user->setAttribute('birthday', '1965-08-08'); - $this->assertInstanceOf(Carbon::class, $user->birthday); - - $user->setAttribute('birthday', new DateTime('2010-08-08')); - $this->assertInstanceOf(Carbon::class, $user->birthday); - - $user->setAttribute('birthday', new DateTime('1965-08-08')); - $this->assertInstanceOf(Carbon::class, $user->birthday); - - $user->setAttribute('birthday', new DateTime('2010-08-08 04.08.37')); - $this->assertInstanceOf(Carbon::class, $user->birthday); - - $user->setAttribute('birthday', new DateTime('1965-08-08 04.08.37')); - $this->assertInstanceOf(Carbon::class, $user->birthday); - - $user->setAttribute('birthday', new DateTime('2010-08-08 04.08.37.324')); - $this->assertInstanceOf(Carbon::class, $user->birthday); + $user->setAttribute('birthday', null); + $this->assertNull($user->birthday); - $user->setAttribute('birthday', new DateTime('1965-08-08 04.08.37.324')); + $user->setAttribute('birthday', $date); $this->assertInstanceOf(Carbon::class, $user->birthday); - $user->setAttribute('birthday', new DateTimeImmutable('1965-08-08 04.08.37.324')); - $this->assertInstanceOf(Carbon::class, $user->birthday); - - //Test with create and array property - $user = User::create(['name' => 'Jane Doe', 'entry' => ['date' => time()]]); - $this->assertInstanceOf(Carbon::class, $user->getAttribute('entry.date')); - - $user = User::create(['name' => 'Jane Doe', 'entry' => ['date' => Date::now()]]); + // Test with create and array property + $user = User::create(['name' => 'Jane Doe', 'entry' => ['date' => $date]]); $this->assertInstanceOf(Carbon::class, $user->getAttribute('entry.date')); - $user = User::create(['name' => 'Jane Doe', 'entry' => ['date' => 'Monday 8th August 2005 03:12:46 PM']]); - $this->assertInstanceOf(Carbon::class, $user->getAttribute('entry.date')); - - $user = User::create(['name' => 'Jane Doe', 'entry' => ['date' => 'Monday 8th August 1960 03:12:46 PM']]); - $this->assertInstanceOf(Carbon::class, $user->getAttribute('entry.date')); - - $user = User::create(['name' => 'Jane Doe', 'entry' => ['date' => '2005-08-08']]); - $this->assertInstanceOf(Carbon::class, $user->getAttribute('entry.date')); - - $user = User::create(['name' => 'Jane Doe', 'entry' => ['date' => '1965-08-08']]); - $this->assertInstanceOf(Carbon::class, $user->getAttribute('entry.date')); - - $user = User::create(['name' => 'Jane Doe', 'entry' => ['date' => new DateTime('2010-08-08')]]); - $this->assertInstanceOf(Carbon::class, $user->getAttribute('entry.date')); - - $user = User::create(['name' => 'Jane Doe', 'entry' => ['date' => new DateTime('1965-08-08')]]); - $this->assertInstanceOf(Carbon::class, $user->getAttribute('entry.date')); - - $user = User::create(['name' => 'Jane Doe', 'entry' => ['date' => new DateTime('2010-08-08 04.08.37')]]); - $this->assertInstanceOf(Carbon::class, $user->getAttribute('entry.date')); - - $user = User::create(['name' => 'Jane Doe', 'entry' => ['date' => new DateTime('1965-08-08 04.08.37')]]); - $this->assertInstanceOf(Carbon::class, $user->getAttribute('entry.date')); - - $user = User::create(['name' => 'Jane Doe', 'entry' => ['date' => new DateTime('2010-08-08 04.08.37.324')]]); - $this->assertInstanceOf(Carbon::class, $user->getAttribute('entry.date')); - - $user = User::create(['name' => 'Jane Doe', 'entry' => ['date' => new DateTime('1965-08-08 04.08.37.324')]]); - $this->assertInstanceOf(Carbon::class, $user->getAttribute('entry.date')); - - //Test with setAttribute and array property - $user->setAttribute('entry.date', time()); - $this->assertInstanceOf(Carbon::class, $user->getAttribute('entry.date')); + // Test with setAttribute and array property + $user->setAttribute('entry.date', null); + $this->assertNull($user->birthday); - $user->setAttribute('entry.date', Date::now()); + $user->setAttribute('entry.date', $date); $this->assertInstanceOf(Carbon::class, $user->getAttribute('entry.date')); - $user->setAttribute('entry.date', 'Monday 8th August 2005 03:12:46 PM'); - $this->assertInstanceOf(Carbon::class, $user->getAttribute('entry.date')); - - $user->setAttribute('entry.date', 'Monday 8th August 1960 03:12:46 PM'); - $this->assertInstanceOf(Carbon::class, $user->getAttribute('entry.date')); - - $user->setAttribute('entry.date', '2005-08-08'); - $this->assertInstanceOf(Carbon::class, $user->getAttribute('entry.date')); - - $user->setAttribute('entry.date', '1965-08-08'); - $this->assertInstanceOf(Carbon::class, $user->getAttribute('entry.date')); + // Test with create and array property + $data = $user->toArray(); + $this->assertIsString($data['entry']['date']); + } - $user->setAttribute('entry.date', new DateTime('2010-08-08')); - $this->assertInstanceOf(Carbon::class, $user->getAttribute('entry.date')); + public function testDateNull(): void + { + $user = User::create(['name' => 'Jane Doe', 'birthday' => null]); + $this->assertNull($user->birthday); - $user->setAttribute('entry.date', new DateTime('1965-08-08')); - $this->assertInstanceOf(Carbon::class, $user->getAttribute('entry.date')); + $user->setAttribute('birthday', new DateTime()); + $user->setAttribute('birthday', null); + $this->assertNull($user->birthday); - $user->setAttribute('entry.date', new DateTime('2010-08-08 04.08.37')); - $this->assertInstanceOf(Carbon::class, $user->getAttribute('entry.date')); + $user->save(); - $user->setAttribute('entry.date', new DateTime('1965-08-08 04.08.37')); - $this->assertInstanceOf(Carbon::class, $user->getAttribute('entry.date')); + // Re-fetch to be sure + $user = User::find($user->_id); + $this->assertNull($user->birthday); - $user->setAttribute('entry.date', new DateTime('2010-08-08 04.08.37.324')); - $this->assertInstanceOf(Carbon::class, $user->getAttribute('entry.date')); + // Nested field with dot notation + $user = User::create(['name' => 'Jane Doe', 'entry' => ['date' => null]]); + $this->assertNull($user->getAttribute('entry.date')); - $user->setAttribute('entry.date', new DateTime('1965-08-08 04.08.37.324')); - $this->assertInstanceOf(Carbon::class, $user->getAttribute('entry.date')); + $user->setAttribute('entry.date', new DateTime()); + $user->setAttribute('entry.date', null); + $this->assertNull($user->getAttribute('entry.date')); - $data = $user->toArray(); - $this->assertIsString($data['entry']['date']); + // Re-fetch to be sure + $user = User::find($user->_id); + $this->assertNull($user->getAttribute('entry.date')); } public function testCarbonDateMockingWorks() From 035d704b2681cb150ad5f3a48c2237977d3af21e Mon Sep 17 00:00:00 2001 From: Matheus Silva Freitas Date: Wed, 6 Sep 2023 04:09:50 -0300 Subject: [PATCH 096/446] Check if $primaryKey is present before execute unset (#2599) Problem: Previously, while executing a dissociate operation on Embed Models in MongoDB, an Exception was thrown that prevented the removal of Models. This happened specifically when a Model in the list lacked a $propertyKey. Solution: Add a validation check to the dissociate operation for Embed Models in MongoDB. With this fix, the application will now verify if a propertyKey is present in each Model in the list before proceeding with the removal. This resolves the issue of an Exception being thrown during the operation. --- src/Relations/EmbedsMany.php | 2 +- tests/EmbeddedRelationsTest.php | 15 +++++++++++++++ 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/src/Relations/EmbedsMany.php b/src/Relations/EmbedsMany.php index be8d5f737..5ef9a2e6e 100644 --- a/src/Relations/EmbedsMany.php +++ b/src/Relations/EmbedsMany.php @@ -152,7 +152,7 @@ public function dissociate($ids = []) // Remove the document from the parent model. foreach ($records as $i => $record) { - if (in_array($record[$primaryKey], $ids)) { + if (array_key_exists($primaryKey, $record) && in_array($record[$primaryKey], $ids)) { unset($records[$i]); } } diff --git a/tests/EmbeddedRelationsTest.php b/tests/EmbeddedRelationsTest.php index e965a0ee7..231fec6dc 100644 --- a/tests/EmbeddedRelationsTest.php +++ b/tests/EmbeddedRelationsTest.php @@ -310,6 +310,21 @@ public function testEmbedsManyDissociate() $freshUser = User::find($user->id); $this->assertEquals(0, $user->addresses->count()); $this->assertEquals(1, $freshUser->addresses->count()); + + $broken_address = Address::make(['name' => 'Broken']); + + $user->update([ + 'addresses' => array_merge( + [$broken_address->toArray()], + $user->addresses()->toArray() + ), + ]); + + $curitiba = $user->addresses()->create(['city' => 'Curitiba']); + $user->addresses()->dissociate($curitiba->id); + + $this->assertEquals(1, $user->addresses->where('name', $broken_address->name)->count()); + $this->assertEquals(1, $user->addresses->count()); } public function testEmbedsManyAliases() From 5394a8d2b8fce5944cfab6cd3a339f6993b13297 Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Wed, 6 Sep 2023 10:57:41 +0200 Subject: [PATCH 097/446] PHPORM-86: Add support links to New Issue page (#2602) --- .github/ISSUE_TEMPLATE/config.yml | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/config.yml diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 000000000..f9b85cd6b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,12 @@ +blank_issues_enabled: false + +contact_links: + - name: Discussions + url: https://github.com/mongodb/laravel-mongodb/discussions/new/choose + about: For questions, discussions, or general technical support from other Laravel users, visit the Discussions page. + - name: MongoDB Developer Community Forums + url: https://developer.mongodb.com/community/forums/ + about: For questions, discussions, or general technical support, visit the MongoDB Community Forums. The MongoDB Community Forums are a centralized place to connect with other MongoDB users, ask questions, and get answers. + - name: Report a Security Vulnerability + url: https://mongodb.com/docs/manual/tutorial/create-a-vulnerability-report + about: If you believe you have discovered a vulnerability in MongoDB products or have experienced a security incident related to MongoDB products, please report the issue to aid in its resolution. From 9bc8999b79279e46bc92a4e1951a0dc70ce2d63a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 6 Sep 2023 14:47:57 +0200 Subject: [PATCH 098/446] Switch to phpcs and upgrade codebase (#2596) To be consistent with other MongoDB PHP projects, we use phpcs to analyze and fix the code style. Summary of changes: - added "declare(strict_types=1);" to all file headers - added "use function" for all functions used in each file (performance gain for functions with specific opcode compilation) - use of short closures - remove `@var` annotations in tests, replaced by `assertInstanceOf` or `assert` - Use early exit when appropriate, but disable the rule - Remove `@param` & `@return` phpdoc when duplicate of native types --- .github/workflows/build-ci.yml | 21 - .github/workflows/coding-standards.yml | 55 ++ .gitignore | 3 +- .php-cs-fixer.dist.php | 187 ----- composer.json | 10 +- phpcs.xml.dist | 38 + src/Auth/DatabaseTokenRepository.php | 19 +- src/Auth/PasswordBrokerManager.php | 8 +- src/Auth/PasswordResetServiceProvider.php | 6 +- src/Auth/User.php | 7 +- src/Collection.php | 27 +- src/Concerns/ManagesTransactions.php | 19 +- src/Connection.php | 120 ++- src/Eloquent/Builder.php | 86 +- src/Eloquent/Casts/BinaryUuid.php | 24 +- src/Eloquent/Casts/ObjectId.php | 16 +- src/Eloquent/EmbedsRelations.php | 25 +- src/Eloquent/HybridRelations.php | 136 +-- src/Eloquent/MassPrunable.php | 8 +- src/Eloquent/Model.php | 192 ++--- src/Eloquent/SoftDeletes.php | 6 +- src/Helpers/EloquentBuilder.php | 2 + src/Helpers/QueriesRelationships.php | 70 +- src/MongodbQueueServiceProvider.php | 25 +- src/MongodbServiceProvider.php | 2 + src/Query/Builder.php | 552 ++++++------- src/Query/Grammar.php | 2 + src/Query/Processor.php | 2 + src/Queue/Failed/MongoFailedJobProvider.php | 28 +- src/Queue/MongoConnector.php | 12 +- src/Queue/MongoJob.php | 7 +- src/Queue/MongoQueue.php | 50 +- src/Relations/BelongsTo.php | 22 +- src/Relations/BelongsToMany.php | 85 +- src/Relations/EmbedsMany.php | 86 +- src/Relations/EmbedsOne.php | 18 +- src/Relations/EmbedsOneOrMany.php | 112 ++- src/Relations/HasMany.php | 12 +- src/Relations/HasOne.php | 12 +- src/Relations/MorphMany.php | 7 +- src/Relations/MorphTo.php | 18 +- src/Schema/Blueprint.php | 92 ++- src/Schema/Builder.php | 73 +- src/Schema/Grammar.php | 2 + src/Validation/DatabasePresenceVerifier.php | 21 +- src/Validation/ValidationServiceProvider.php | 2 + tests/AuthTest.php | 9 +- tests/Casts/BinaryUuidTest.php | 7 +- tests/Casts/ObjectIdTest.php | 6 +- tests/CollectionTest.php | 6 +- tests/ConnectionTest.php | 8 +- tests/Eloquent/MassPrunableTest.php | 7 +- tests/EmbeddedRelationsTest.php | 192 ++--- tests/HybridRelationsTest.php | 22 +- tests/ModelTest.php | 183 ++-- tests/Models/Address.php | 2 +- tests/Models/Birthday.php | 8 +- tests/Models/Book.php | 8 +- tests/Models/CastBinaryUuid.php | 4 +- tests/Models/CastObjectId.php | 4 +- tests/Models/Client.php | 4 +- tests/Models/Group.php | 4 +- tests/Models/Guarded.php | 2 +- tests/Models/IdIsBinaryUuid.php | 4 +- tests/Models/IdIsInt.php | 8 +- tests/Models/IdIsString.php | 6 +- tests/Models/Item.php | 11 +- tests/Models/Location.php | 4 +- tests/Models/MemberStatus.php | 2 + tests/Models/MysqlBook.php | 27 +- tests/Models/MysqlRole.php | 23 +- tests/Models/MysqlUser.php | 22 +- tests/Models/Photo.php | 4 +- tests/Models/Role.php | 4 +- tests/Models/Scoped.php | 2 +- tests/Models/Soft.php | 13 +- tests/Models/User.php | 13 +- tests/Query/BuilderTest.php | 828 ++++++++++++------- tests/QueryBuilderTest.php | 52 +- tests/QueryTest.php | 9 +- tests/QueueTest.php | 48 +- tests/RelationsTest.php | 40 +- tests/Seeder/DatabaseSeeder.php | 2 + tests/Seeder/UserTableSeeder.php | 2 + tests/SeederTest.php | 2 +- tests/TestCase.php | 11 +- tests/TransactionTest.php | 24 +- tests/ValidationTest.php | 34 +- tests/config/database.php | 2 + tests/config/queue.php | 2 + 90 files changed, 2101 insertions(+), 1901 deletions(-) create mode 100644 .github/workflows/coding-standards.yml delete mode 100644 .php-cs-fixer.dist.php create mode 100644 phpcs.xml.dist diff --git a/.github/workflows/build-ci.yml b/.github/workflows/build-ci.yml index 8feea0f6c..ecbf50b50 100644 --- a/.github/workflows/build-ci.yml +++ b/.github/workflows/build-ci.yml @@ -7,27 +7,6 @@ on: pull_request: jobs: - php-cs-fixer: - runs-on: ubuntu-latest - env: - PHP_CS_FIXER_VERSION: v3.6.0 - strategy: - matrix: - php: - - '8.1' - steps: - - name: Checkout - uses: actions/checkout@v3 - - name: Setup PHP - uses: shivammathur/setup-php@v2 - with: - php-version: ${{ matrix.php }} - extensions: curl,mbstring - tools: php-cs-fixer:${{ env.PHP_CS_FIXER_VERSION }} - coverage: none - - name: Run PHP-CS-Fixer Fix, version ${{ env.PHP_CS_FIXER_VERSION }} - run: php-cs-fixer fix --dry-run --diff --ansi - build: runs-on: ${{ matrix.os }} name: PHP v${{ matrix.php }} with MongoDB ${{ matrix.mongodb }} diff --git a/.github/workflows/coding-standards.yml b/.github/workflows/coding-standards.yml new file mode 100644 index 000000000..45daae584 --- /dev/null +++ b/.github/workflows/coding-standards.yml @@ -0,0 +1,55 @@ +name: "Coding Standards" + +on: + push: + branches: + tags: + pull_request: + +env: + PHP_VERSION: "8.2" + DRIVER_VERSION: "stable" + +jobs: + phpcs: + name: "phpcs" + runs-on: "ubuntu-22.04" + + steps: + - name: "Checkout" + uses: "actions/checkout@v3" + + - name: Setup cache environment + id: extcache + uses: shivammathur/cache-extensions@v1 + with: + php-version: ${{ env.PHP_VERSION }} + extensions: "mongodb-${{ env.DRIVER_VERSION }}" + key: "extcache-v1" + + - name: Cache extensions + uses: actions/cache@v3 + with: + path: ${{ steps.extcache.outputs.dir }} + key: ${{ steps.extcache.outputs.key }} + restore-keys: ${{ steps.extcache.outputs.key }} + + - name: "Install PHP" + uses: "shivammathur/setup-php@v2" + with: + coverage: "none" + extensions: "mongodb-${{ env.DRIVER_VERSION }}" + php-version: "${{ env.PHP_VERSION }}" + tools: "cs2pr" + + - name: "Show driver information" + run: "php --ri mongodb" + + - name: "Install dependencies with Composer" + uses: "ramsey/composer-install@2.2.0" + with: + composer-options: "--no-suggest" + + # The -q option is required until phpcs v4 is released + - name: "Run PHP_CodeSniffer" + run: "vendor/bin/phpcs -q --no-colors --report=checkstyle | cs2pr" diff --git a/.gitignore b/.gitignore index 8a586f33b..4a03159de 100644 --- a/.gitignore +++ b/.gitignore @@ -4,8 +4,7 @@ .DS_Store .idea/ .phpunit.result.cache -/.php-cs-fixer.php -/.php-cs-fixer.cache +.phpcs-cache /vendor composer.lock composer.phar diff --git a/.php-cs-fixer.dist.php b/.php-cs-fixer.dist.php deleted file mode 100644 index 20c262e3a..000000000 --- a/.php-cs-fixer.dist.php +++ /dev/null @@ -1,187 +0,0 @@ - true, - 'align_multiline_comment' => [ - 'comment_type' => 'phpdocs_like', - ], - 'ordered_imports' => [ - 'sort_algorithm' => 'alpha', - ], - 'array_indentation' => true, - 'binary_operator_spaces' => [ - 'operators' => [ - '=>' => null, - '=' => 'single_space', - ], - ], - 'blank_line_after_namespace' => true, - 'blank_line_after_opening_tag' => true, - 'blank_line_before_statement' => [ - 'statements' => [ - 'return', - ], - ], - 'cast_spaces' => true, - 'class_definition' => false, - 'clean_namespace' => true, - 'compact_nullable_typehint' => true, - 'concat_space' => [ - 'spacing' => 'none', - ], - 'declare_equal_normalize' => true, - 'no_alias_language_construct_call' => true, - 'elseif' => true, - 'encoding' => true, - 'full_opening_tag' => true, - 'function_declaration' => true, - 'function_typehint_space' => true, - 'single_line_comment_style' => [ - 'comment_types' => [ - 'hash', - ], - ], - 'heredoc_to_nowdoc' => true, - 'include' => true, - 'indentation_type' => true, - 'integer_literal_case' => true, - 'braces' => false, - 'lowercase_cast' => true, - 'constant_case' => [ - 'case' => 'lower', - ], - 'lowercase_keywords' => true, - 'lowercase_static_reference' => true, - 'magic_constant_casing' => true, - 'magic_method_casing' => true, - 'method_argument_space' => [ - 'on_multiline' => 'ignore', - ], - 'class_attributes_separation' => [ - 'elements' => [ - 'method' => 'one', - ], - ], - 'visibility_required' => [ - 'elements' => [ - 'method', - 'property', - ], - ], - 'native_function_casing' => true, - 'native_function_type_declaration_casing' => true, - 'no_alternative_syntax' => true, - 'no_binary_string' => true, - 'no_blank_lines_after_class_opening' => true, - 'no_blank_lines_after_phpdoc' => true, - 'no_extra_blank_lines' => [ - 'tokens' => [ - 'throw', - 'use', - 'extra', - ], - ], - 'no_closing_tag' => true, - 'no_empty_phpdoc' => true, - 'no_empty_statement' => true, - 'no_leading_import_slash' => true, - 'no_leading_namespace_whitespace' => true, - 'no_multiline_whitespace_around_double_arrow' => true, - 'multiline_whitespace_before_semicolons' => true, - 'no_short_bool_cast' => true, - 'no_singleline_whitespace_before_semicolons' => true, - 'no_space_around_double_colon' => true, - 'no_spaces_after_function_name' => true, - 'no_spaces_around_offset' => [ - 'positions' => [ - 'inside', - ], - ], - 'no_spaces_inside_parenthesis' => true, - 'no_trailing_comma_in_list_call' => true, - 'no_trailing_comma_in_singleline_array' => true, - 'no_trailing_whitespace' => true, - 'no_trailing_whitespace_in_comment' => true, - 'no_unneeded_control_parentheses' => true, - 'no_unneeded_curly_braces' => true, - 'no_unset_cast' => true, - 'no_unused_imports' => true, - 'lambda_not_used_import' => true, - 'no_useless_return' => true, - 'no_whitespace_before_comma_in_array' => true, - 'no_whitespace_in_blank_line' => true, - 'normalize_index_brace' => true, - 'not_operator_with_successor_space' => true, - 'object_operator_without_whitespace' => true, - 'phpdoc_indent' => true, - 'phpdoc_inline_tag_normalizer' => true, - 'phpdoc_no_access' => true, - 'phpdoc_no_package' => true, - 'phpdoc_no_useless_inheritdoc' => true, - 'phpdoc_return_self_reference' => true, - 'phpdoc_scalar' => true, - 'phpdoc_single_line_var_spacing' => true, - 'phpdoc_summary' => true, - 'phpdoc_trim' => true, - 'phpdoc_no_alias_tag' => [ - 'replacements' => [ - 'type' => 'var', - ], - ], - 'phpdoc_types' => true, - 'phpdoc_var_without_name' => true, - 'increment_style' => [ - 'style' => 'post', - ], - 'no_mixed_echo_print' => [ - 'use' => 'echo', - ], - 'return_type_declaration' => [ - 'space_before' => 'none', - ], - 'array_syntax' => [ - 'syntax' => 'short', - ], - 'list_syntax' => [ - 'syntax' => 'short', - ], - 'short_scalar_cast' => true, - 'single_blank_line_at_eof' => true, - 'single_blank_line_before_namespace' => true, - 'single_class_element_per_statement' => true, - 'single_import_per_statement' => true, - 'single_line_after_imports' => true, - 'single_quote' => true, - 'space_after_semicolon' => true, - 'standardize_not_equals' => true, - 'switch_case_semicolon_to_colon' => true, - 'switch_case_space' => true, - 'switch_continue_to_break' => true, - 'ternary_operator_spaces' => true, - 'trailing_comma_in_multiline' => [ - 'elements' => [ - 'arrays', - ], - ], - 'trim_array_spaces' => true, - 'unary_operator_spaces' => true, - 'types_spaces' => [ - 'space' => 'none', - ], - 'line_ending' => true, - 'whitespace_after_comma_in_array' => true, - 'no_alias_functions' => true, - 'no_unreachable_default_argument_value' => true, - 'psr_autoloading' => true, - 'self_accessor' => true, -]; - -$finder = PhpCsFixer\Finder::create() - ->in(__DIR__); - -return (new PhpCsFixer\Config()) - ->setRiskyAllowed(true) - ->setRules($rules) - ->setFinder($finder); diff --git a/composer.json b/composer.json index b5c2ddd8d..eb0ac3d9e 100644 --- a/composer.json +++ b/composer.json @@ -33,7 +33,8 @@ "require-dev": { "phpunit/phpunit": "^9.5.10", "orchestra/testbench": "^8.0", - "mockery/mockery": "^1.4.4" + "mockery/mockery": "^1.4.4", + "doctrine/coding-standard": "12.0.x-dev" }, "replace": { "jenssegers/mongodb": "self.version" @@ -56,5 +57,10 @@ ] } }, - "minimum-stability": "dev" + "minimum-stability": "dev", + "config": { + "allow-plugins": { + "dealerdirect/phpcodesniffer-composer-installer": true + } + } } diff --git a/phpcs.xml.dist b/phpcs.xml.dist new file mode 100644 index 000000000..36cc870e9 --- /dev/null +++ b/phpcs.xml.dist @@ -0,0 +1,38 @@ + + + + + + + + + + + + src + tests + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/Auth/DatabaseTokenRepository.php b/src/Auth/DatabaseTokenRepository.php index b2f43c748..83ce9bf6d 100644 --- a/src/Auth/DatabaseTokenRepository.php +++ b/src/Auth/DatabaseTokenRepository.php @@ -1,5 +1,7 @@ convertDateTime($createdAt); @@ -32,9 +33,7 @@ protected function tokenExpired($createdAt) return parent::tokenExpired($createdAt); } - /** - * @inheritdoc - */ + /** @inheritdoc */ protected function tokenRecentlyCreated($createdAt) { $createdAt = $this->convertDateTime($createdAt); @@ -50,7 +49,7 @@ private function convertDateTime($createdAt) $date->setTimezone(new DateTimeZone(date_default_timezone_get())); $createdAt = $date->format('Y-m-d H:i:s'); } elseif (is_array($createdAt) && isset($createdAt['date'])) { - $date = new DateTime($createdAt['date'], new DateTimeZone(isset($createdAt['timezone']) ? $createdAt['timezone'] : 'UTC')); + $date = new DateTime($createdAt['date'], new DateTimeZone($createdAt['timezone'] ?? 'UTC')); $date->setTimezone(new DateTimeZone(date_default_timezone_get())); $createdAt = $date->format('Y-m-d H:i:s'); } diff --git a/src/Auth/PasswordBrokerManager.php b/src/Auth/PasswordBrokerManager.php index 0a2f615e5..157df3d97 100644 --- a/src/Auth/PasswordBrokerManager.php +++ b/src/Auth/PasswordBrokerManager.php @@ -1,14 +1,14 @@ app['config']['app.key'], $config['expire'], - $config['throttle'] ?? 0 + $config['throttle'] ?? 0, ); } } diff --git a/src/Auth/PasswordResetServiceProvider.php b/src/Auth/PasswordResetServiceProvider.php index fc06ab584..a8aa61da4 100644 --- a/src/Auth/PasswordResetServiceProvider.php +++ b/src/Auth/PasswordResetServiceProvider.php @@ -1,14 +1,14 @@ app->singleton('auth.password', function ($app) { diff --git a/src/Auth/User.php b/src/Auth/User.php index d7d3d7c93..d14aa4822 100644 --- a/src/Auth/User.php +++ b/src/Auth/User.php @@ -1,5 +1,7 @@ connection = $connection; @@ -38,13 +41,11 @@ public function __construct(Connection $connection, MongoCollection $collection) /** * Handle dynamic method calls. * - * @param string $method - * @param array $parameters * @return mixed */ public function __call(string $method, array $parameters) { - $start = microtime(true); + $start = microtime(true); $result = $this->collection->$method(...$parameters); // Once we have run the query we will calculate the time that it took to run and @@ -64,13 +65,13 @@ public function __call(string $method, array $parameters) // Convert the query parameters to a json string. foreach ($parameters as $parameter) { try { - $query[] = json_encode($parameter); - } catch (Exception $e) { + $query[] = json_encode($parameter, JSON_THROW_ON_ERROR); + } catch (Exception) { $query[] = '{...}'; } } - $queryString = $this->collection->getCollectionName().'.'.$method.'('.implode(',', $query).')'; + $queryString = $this->collection->getCollectionName() . '.' . $method . '(' . implode(',', $query) . ')'; $this->connection->logQuery($queryString, [], $time); diff --git a/src/Concerns/ManagesTransactions.php b/src/Concerns/ManagesTransactions.php index e4771343a..ac3c1c6f7 100644 --- a/src/Concerns/ManagesTransactions.php +++ b/src/Concerns/ManagesTransactions.php @@ -1,26 +1,25 @@ connection = $this->createConnection($dsn, $config, $options); - // Get default database name - $default_db = $this->getDefaultDatabaseName($dsn, $config); - // Select database - $this->db = $this->connection->selectDatabase($default_db); + $this->db = $this->connection->selectDatabase($this->getDefaultDatabaseName($dsn, $config)); $this->useDefaultPostProcessor(); @@ -68,7 +72,8 @@ public function __construct(array $config) /** * Begin a fluent query against a database collection. * - * @param string $collection + * @param string $collection + * * @return Query\Builder */ public function collection($collection) @@ -81,8 +86,9 @@ public function collection($collection) /** * Begin a fluent query against a database collection. * - * @param string $table - * @param string|null $as + * @param string $table + * @param string|null $as + * * @return Query\Builder */ public function table($table, $as = null) @@ -93,7 +99,8 @@ public function table($table, $as = null) /** * Get a MongoDB collection. * - * @param string $name + * @param string $name + * * @return Collection */ public function getCollection($name) @@ -101,9 +108,7 @@ public function getCollection($name) return new Collection($this, $this->db->selectCollection($name)); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function getSchemaBuilder() { return new Schema\Builder($this); @@ -130,7 +135,7 @@ public function getMongoClient() } /** - * {@inheritdoc} + * {@inheritDoc} */ public function getDatabaseName() { @@ -140,20 +145,16 @@ public function getDatabaseName() /** * Get the name of the default database based on db config or try to detect it from dsn. * - * @param string $dsn - * @param array $config - * @return string - * * @throws InvalidArgumentException */ protected function getDefaultDatabaseName(string $dsn, array $config): string { if (empty($config['database'])) { - if (preg_match('/^mongodb(?:[+]srv)?:\\/\\/.+\\/([^?&]+)/s', $dsn, $matches)) { - $config['database'] = $matches[1]; - } else { + if (! preg_match('/^mongodb(?:[+]srv)?:\\/\\/.+\\/([^?&]+)/s', $dsn, $matches)) { throw new InvalidArgumentException('Database is not properly configured.'); } + + $config['database'] = $matches[1]; } return $config['database']; @@ -161,13 +162,8 @@ protected function getDefaultDatabaseName(string $dsn, array $config): string /** * Create a new MongoDB connection. - * - * @param string $dsn - * @param array $config - * @param array $options - * @return Client */ - protected function createConnection($dsn, array $config, array $options): Client + protected function createConnection(string $dsn, array $config, array $options): Client { // By default driver options is an empty array. $driverOptions = []; @@ -185,6 +181,7 @@ protected function createConnection($dsn, array $config, array $options): Client if (! isset($options['username']) && ! empty($config['username'])) { $options['username'] = $config['username']; } + if (! isset($options['password']) && ! empty($config['password'])) { $options['password'] = $config['password']; } @@ -192,9 +189,7 @@ protected function createConnection($dsn, array $config, array $options): Client return new Client($dsn, $options, $driverOptions); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function disconnect() { unset($this->connection); @@ -202,20 +197,14 @@ public function disconnect() /** * Determine if the given configuration array has a dsn string. - * - * @param array $config - * @return bool */ - protected function hasDsnString(array $config) + protected function hasDsnString(array $config): bool { - return isset($config['dsn']) && ! empty($config['dsn']); + return ! empty($config['dsn']); } /** * Get the DSN string form configuration. - * - * @param array $config - * @return string */ protected function getDsnString(array $config): string { @@ -224,9 +213,6 @@ protected function getDsnString(array $config): string /** * Get the DSN string for a host / port configuration. - * - * @param array $config - * @return string */ protected function getHostDsn(array $config): string { @@ -235,30 +221,27 @@ protected function getHostDsn(array $config): string foreach ($hosts as &$host) { // ipv6 - if (filter_var($host, \FILTER_VALIDATE_IP, \FILTER_FLAG_IPV6)) { - $host = '['.$host.']'; + if (filter_var($host, FILTER_VALIDATE_IP, FILTER_FLAG_IPV6)) { + $host = '[' . $host . ']'; if (! empty($config['port'])) { - $host = $host.':'.$config['port']; + $host .= ':' . $config['port']; } } else { // Check if we need to add a port to the host if (! str_contains($host, ':') && ! empty($config['port'])) { - $host = $host.':'.$config['port']; + $host .= ':' . $config['port']; } } } // Check if we want to authenticate against a specific database. - $auth_database = isset($config['options']) && ! empty($config['options']['database']) ? $config['options']['database'] : null; + $authDatabase = isset($config['options']) && ! empty($config['options']['database']) ? $config['options']['database'] : null; - return 'mongodb://'.implode(',', $hosts).($auth_database ? '/'.$auth_database : ''); + return 'mongodb://' . implode(',', $hosts) . ($authDatabase ? '/' . $authDatabase : ''); } /** * Create a DSN string from a configuration. - * - * @param array $config - * @return string */ protected function getDsn(array $config): string { @@ -267,41 +250,31 @@ protected function getDsn(array $config): string : $this->getHostDsn($config); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function getElapsedTime($start) { return parent::getElapsedTime($start); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function getDriverName() { return 'mongodb'; } - /** - * @inheritdoc - */ + /** @inheritdoc */ protected function getDefaultPostProcessor() { return new Query\Processor(); } - /** - * @inheritdoc - */ + /** @inheritdoc */ protected function getDefaultQueryGrammar() { return new Query\Grammar(); } - /** - * @inheritdoc - */ + /** @inheritdoc */ protected function getDefaultSchemaGrammar() { return new Schema\Grammar(); @@ -309,10 +282,8 @@ protected function getDefaultSchemaGrammar() /** * Set database. - * - * @param \MongoDB\Database $db */ - public function setDatabase(\MongoDB\Database $db) + public function setDatabase(Database $db) { $this->db = $db; } @@ -320,8 +291,9 @@ public function setDatabase(\MongoDB\Database $db) /** * Dynamically pass methods to the connection. * - * @param string $method + * @param string $method * @param array $parameters + * * @return mixed */ public function __call($method, $parameters) @@ -339,7 +311,7 @@ private static function lookupVersion(): string if (class_exists(InstalledVersions::class)) { try { return self::$version = InstalledVersions::getPrettyVersion('mongodb/laravel-mongodb'); - } catch (Throwable $t) { + } catch (Throwable) { // Ignore exceptions and return unknown version } } diff --git a/src/Eloquent/Builder.php b/src/Eloquent/Builder.php index 7951a93a8..4d210c873 100644 --- a/src/Eloquent/Builder.php +++ b/src/Eloquent/Builder.php @@ -1,12 +1,21 @@ model->getParentRelation()) { + $relation = $this->model->getParentRelation(); + if ($relation) { $relation->performUpdate($this->model, $values); return 1; @@ -57,14 +65,13 @@ public function update(array $values, array $options = []) return $this->toBase()->update($this->addUpdatedAtColumn($values), $options); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function insert(array $values) { // Intercept operations on embedded models and delegate logic // to the parent relation instance. - if ($relation = $this->model->getParentRelation()) { + $relation = $this->model->getParentRelation(); + if ($relation) { $relation->performInsert($this->model, $values); return true; @@ -73,14 +80,13 @@ public function insert(array $values) return parent::insert($values); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function insertGetId(array $values, $sequence = null) { // Intercept operations on embedded models and delegate logic // to the parent relation instance. - if ($relation = $this->model->getParentRelation()) { + $relation = $this->model->getParentRelation(); + if ($relation) { $relation->performInsert($this->model, $values); return $this->model->getKey(); @@ -89,14 +95,13 @@ public function insertGetId(array $values, $sequence = null) return parent::insertGetId($values, $sequence); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function delete() { // Intercept operations on embedded models and delegate logic // to the parent relation instance. - if ($relation = $this->model->getParentRelation()) { + $relation = $this->model->getParentRelation(); + if ($relation) { $relation->performDelete($this->model); return $this->model->getKey(); @@ -105,14 +110,13 @@ public function delete() return parent::delete(); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function increment($column, $amount = 1, array $extra = []) { // Intercept operations on embedded models and delegate logic // to the parent relation instance. - if ($relation = $this->model->getParentRelation()) { + $relation = $this->model->getParentRelation(); + if ($relation) { $value = $this->model->{$column}; // When doing increment and decrements, Eloquent will automatically @@ -122,22 +126,19 @@ public function increment($column, $amount = 1, array $extra = []) $this->model->syncOriginalAttribute($column); - $result = $this->model->update([$column => $value]); - - return $result; + return $this->model->update([$column => $value]); } return parent::increment($column, $amount, $extra); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function decrement($column, $amount = 1, array $extra = []) { // Intercept operations on embedded models and delegate logic // to the parent relation instance. - if ($relation = $this->model->getParentRelation()) { + $relation = $this->model->getParentRelation(); + if ($relation) { $value = $this->model->{$column}; // When doing increment and decrements, Eloquent will automatically @@ -153,9 +154,7 @@ public function decrement($column, $amount = 1, array $extra = []) return parent::decrement($column, $amount, $extra); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function raw($value = null) { // Get raw results from the query builder. @@ -166,13 +165,17 @@ public function raw($value = null) $results = iterator_to_array($results, false); return $this->model->hydrate($results); - } // Convert MongoDB BSONDocument to a single object. - elseif ($results instanceof BSONDocument) { + } + + // Convert MongoDB BSONDocument to a single object. + if ($results instanceof BSONDocument) { $results = $results->getArrayCopy(); return $this->model->newFromBuilder((array) $results); - } // The result is a single object. - elseif (is_array($results) && array_key_exists('_id', $results)) { + } + + // The result is a single object. + if (is_array($results) && array_key_exists('_id', $results)) { return $this->model->newFromBuilder((array) $results); } @@ -182,10 +185,9 @@ public function raw($value = null) /** * Add the "updated at" column to an array of values. * TODO Remove if https://github.com/laravel/framework/commit/6484744326531829341e1ff886cc9b628b20d73e - * wiil be reverted - * Issue in laravel frawework https://github.com/laravel/framework/issues/27791. + * will be reverted + * Issue in laravel/frawework https://github.com/laravel/framework/issues/27791. * - * @param array $values * @return array */ protected function addUpdatedAtColumn(array $values) @@ -197,23 +199,19 @@ protected function addUpdatedAtColumn(array $values) $column = $this->model->getUpdatedAtColumn(); $values = array_merge( [$column => $this->model->freshTimestampString()], - $values + $values, ); return $values; } - /** - * @return \Illuminate\Database\ConnectionInterface - */ + /** @return ConnectionInterface */ public function getConnection() { return $this->query->getConnection(); } - /** - * @inheritdoc - */ + /** @inheritdoc */ protected function ensureOrderForCursorPagination($shouldReverse = false) { if (empty($this->query->orders)) { diff --git a/src/Eloquent/Casts/BinaryUuid.php b/src/Eloquent/Casts/BinaryUuid.php index 7549680fe..c7832f125 100644 --- a/src/Eloquent/Casts/BinaryUuid.php +++ b/src/Eloquent/Casts/BinaryUuid.php @@ -1,13 +1,19 @@ newQuery(); - $instance = new $related; + $instance = new $related(); return new EmbedsMany($query, $this, $instance, $localKey, $foreignKey, $relation); } @@ -48,9 +56,10 @@ protected function embedsMany($related, $localKey = null, $foreignKey = null, $r * Define an embedded one-to-many relationship. * * @param class-string $related - * @param string|null $localKey - * @param string|null $foreignKey - * @param string|null $relation + * @param string|null $localKey + * @param string|null $foreignKey + * @param string|null $relation + * * @return EmbedsOne */ protected function embedsOne($related, $localKey = null, $foreignKey = null, $relation = null) @@ -72,7 +81,7 @@ protected function embedsOne($related, $localKey = null, $foreignKey = null, $re $query = $this->newQuery(); - $instance = new $related; + $instance = new $related(); return new EmbedsOne($query, $this, $instance, $localKey, $foreignKey, $relation); } diff --git a/src/Eloquent/HybridRelations.php b/src/Eloquent/HybridRelations.php index dc735b973..9d6aa90e1 100644 --- a/src/Eloquent/HybridRelations.php +++ b/src/Eloquent/HybridRelations.php @@ -1,5 +1,7 @@ getForeignKey(); - $instance = new $related; + $instance = new $related(); $localKey = $localKey ?: $this->getKeyName(); @@ -49,14 +58,15 @@ public function hasOne($related, $foreignKey = null, $localKey = null) /** * Define a polymorphic one-to-one relationship. * + * @see HasRelationships::morphOne() + * * @param class-string $related - * @param string $name - * @param string|null $type - * @param string|null $id - * @param string|null $localKey - * @return \Illuminate\Database\Eloquent\Relations\MorphOne + * @param string $name + * @param string|null $type + * @param string|null $id + * @param string|null $localKey * - * @see HasRelationships::morphOne() + * @return MorphOne */ public function morphOne($related, $name, $type = null, $id = null, $localKey = null) { @@ -65,7 +75,7 @@ public function morphOne($related, $name, $type = null, $id = null, $localKey = return parent::morphOne($related, $name, $type, $id, $localKey); } - $instance = new $related; + $instance = new $related(); [$type, $id] = $this->getMorphs($name, $type, $id); @@ -77,12 +87,13 @@ public function morphOne($related, $name, $type = null, $id = null, $localKey = /** * Define a one-to-many relationship. * + * @see HasRelationships::hasMany() + * * @param class-string $related - * @param string|null $foreignKey - * @param string|null $localKey - * @return \Illuminate\Database\Eloquent\Relations\HasMany + * @param string|null $foreignKey + * @param string|null $localKey * - * @see HasRelationships::hasMany() + * @return \Illuminate\Database\Eloquent\Relations\HasMany */ public function hasMany($related, $foreignKey = null, $localKey = null) { @@ -93,7 +104,7 @@ public function hasMany($related, $foreignKey = null, $localKey = null) $foreignKey = $foreignKey ?: $this->getForeignKey(); - $instance = new $related; + $instance = new $related(); $localKey = $localKey ?: $this->getKeyName(); @@ -103,14 +114,15 @@ public function hasMany($related, $foreignKey = null, $localKey = null) /** * Define a polymorphic one-to-many relationship. * + * @see HasRelationships::morphMany() + * * @param class-string $related - * @param string $name - * @param string|null $type - * @param string|null $id - * @param string|null $localKey - * @return \Illuminate\Database\Eloquent\Relations\MorphMany + * @param string $name + * @param string|null $type + * @param string|null $id + * @param string|null $localKey * - * @see HasRelationships::morphMany() + * @return \Illuminate\Database\Eloquent\Relations\MorphMany */ public function morphMany($related, $name, $type = null, $id = null, $localKey = null) { @@ -119,7 +131,7 @@ public function morphMany($related, $name, $type = null, $id = null, $localKey = return parent::morphMany($related, $name, $type, $id, $localKey); } - $instance = new $related; + $instance = new $related(); // Here we will gather up the morph type and ID for the relationship so that we // can properly query the intermediate table of a relation. Finally, we will @@ -136,13 +148,14 @@ public function morphMany($related, $name, $type = null, $id = null, $localKey = /** * Define an inverse one-to-one or many relationship. * + * @see HasRelationships::belongsTo() + * * @param class-string $related - * @param string|null $foreignKey - * @param string|null $ownerKey - * @param string|null $relation - * @return \Illuminate\Database\Eloquent\Relations\BelongsTo + * @param string|null $foreignKey + * @param string|null $ownerKey + * @param string|null $relation * - * @see HasRelationships::belongsTo() + * @return \Illuminate\Database\Eloquent\Relations\BelongsTo */ public function belongsTo($related, $foreignKey = null, $ownerKey = null, $relation = null) { @@ -162,10 +175,10 @@ public function belongsTo($related, $foreignKey = null, $ownerKey = null, $relat // foreign key name by using the name of the relationship function, which // when combined with an "_id" should conventionally match the columns. if ($foreignKey === null) { - $foreignKey = Str::snake($relation).'_id'; + $foreignKey = Str::snake($relation) . '_id'; } - $instance = new $related; + $instance = new $related(); // Once we have the foreign key names, we'll just create a new Eloquent query // for the related models and returns the relationship instance which will @@ -180,13 +193,14 @@ public function belongsTo($related, $foreignKey = null, $ownerKey = null, $relat /** * Define a polymorphic, inverse one-to-one or many relationship. * - * @param string $name + * @see HasRelationships::morphTo() + * + * @param string $name * @param string|null $type * @param string|null $id * @param string|null $ownerKey - * @return \Illuminate\Database\Eloquent\Relations\MorphTo * - * @see HasRelationships::morphTo() + * @return \Illuminate\Database\Eloquent\Relations\MorphTo */ public function morphTo($name = null, $type = null, $id = null, $ownerKey = null) { @@ -202,9 +216,15 @@ public function morphTo($name = null, $type = null, $id = null, $ownerKey = null // If the type value is null it is probably safe to assume we're eager loading // the relationship. When that is the case we will pass in a dummy query as // there are multiple types in the morph and we can't use single queries. - if (($class = $this->$type) === null) { + $class = $this->$type; + if ($class === null) { return new MorphTo( - $this->newQuery(), $this, $id, $ownerKey, $type, $name + $this->newQuery(), + $this, + $id, + $ownerKey, + $type, + $name, ); } @@ -213,28 +233,34 @@ public function morphTo($name = null, $type = null, $id = null, $ownerKey = null // we will pass in the appropriate values so that it behaves as expected. $class = $this->getActualClassNameForMorph($class); - $instance = new $class; + $instance = new $class(); - $ownerKey = $ownerKey ?? $instance->getKeyName(); + $ownerKey ??= $instance->getKeyName(); return new MorphTo( - $instance->newQuery(), $this, $id, $ownerKey, $type, $name + $instance->newQuery(), + $this, + $id, + $ownerKey, + $type, + $name, ); } /** * Define a many-to-many relationship. * + * @see HasRelationships::belongsToMany() + * * @param class-string $related - * @param string|null $collection - * @param string|null $foreignPivotKey - * @param string|null $relatedPivotKey - * @param string|null $parentKey - * @param string|null $relatedKey - * @param string|null $relation - * @return \Illuminate\Database\Eloquent\Relations\BelongsToMany + * @param string|null $collection + * @param string|null $foreignPivotKey + * @param string|null $relatedPivotKey + * @param string|null $parentKey + * @param string|null $relatedKey + * @param string|null $relation * - * @see HasRelationships::belongsToMany() + * @return \Illuminate\Database\Eloquent\Relations\BelongsToMany */ public function belongsToMany( $related, @@ -243,7 +269,7 @@ public function belongsToMany( $relatedPivotKey = null, $parentKey = null, $relatedKey = null, - $relation = null + $relation = null, ) { // If no relationship name was passed, we will pull backtraces to get the // name of the calling function. We will use that function name as the @@ -261,18 +287,18 @@ public function belongsToMany( $relatedPivotKey, $parentKey, $relatedKey, - $relation + $relation, ); } // First, we'll need to determine the foreign key and "other key" for the // relationship. Once we have determined the keys we'll make the query // instances as well as the relationship instances we need for this. - $foreignPivotKey = $foreignPivotKey ?: $this->getForeignKey().'s'; + $foreignPivotKey = $foreignPivotKey ?: $this->getForeignKey() . 's'; - $instance = new $related; + $instance = new $related(); - $relatedPivotKey = $relatedPivotKey ?: $instance->getForeignKey().'s'; + $relatedPivotKey = $relatedPivotKey ?: $instance->getForeignKey() . 's'; // If no table name was provided, we can guess it by concatenating the two // models using underscores in alphabetical order. The two model names @@ -294,7 +320,7 @@ public function belongsToMany( $relatedPivotKey, $parentKey ?: $this->getKeyName(), $relatedKey ?: $instance->getKeyName(), - $relation + $relation, ); } @@ -312,9 +338,7 @@ protected function guessBelongsToManyRelation() return parent::guessBelongsToManyRelation(); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function newEloquentBuilder($query) { if ($this instanceof MongoDBModel) { diff --git a/src/Eloquent/MassPrunable.php b/src/Eloquent/MassPrunable.php index df8839d5d..98e947842 100644 --- a/src/Eloquent/MassPrunable.php +++ b/src/Eloquent/MassPrunable.php @@ -1,10 +1,16 @@ prunable(); - $total = in_array(SoftDeletes::class, class_uses_recursive(get_class($this))) + $total = in_array(SoftDeletes::class, class_uses_recursive(static::class)) ? $query->forceDelete() : $query->delete(); diff --git a/src/Eloquent/Model.php b/src/Eloquent/Model.php index 45f583501..05a20bb31 100644 --- a/src/Eloquent/Model.php +++ b/src/Eloquent/Model.php @@ -1,10 +1,10 @@ getData(); } return $value; } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function getQualifiedKeyName() { return $this->getKeyName(); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function fromDateTime($value) { // If the value is already a UTCDateTime instance, we don't need to parse it. @@ -109,18 +127,16 @@ public function fromDateTime($value) return new UTCDateTime($value); } - /** - * @inheritdoc - */ + /** @inheritdoc */ protected function asDateTime($value) { // Convert UTCDateTime instances. if ($value instanceof UTCDateTime) { $date = $value->toDateTime(); - $seconds = $date->format('U'); - $milliseconds = abs($date->format('v')); - $timestampMs = sprintf('%d%03d', $seconds, $milliseconds); + $seconds = $date->format('U'); + $milliseconds = abs((int) $date->format('v')); + $timestampMs = sprintf('%d%03d', $seconds, $milliseconds); return Date::createFromTimestampMs($timestampMs); } @@ -128,33 +144,25 @@ protected function asDateTime($value) return parent::asDateTime($value); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function getDateFormat() { return $this->dateFormat ?: 'Y-m-d H:i:s'; } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function freshTimestamp() { return new UTCDateTime(Date::now()); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function getTable() { return $this->collection ?: parent::getTable(); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function getAttribute($key) { if (! $key) { @@ -183,9 +191,7 @@ public function getAttribute($key) return parent::getAttribute($key); } - /** - * @inheritdoc - */ + /** @inheritdoc */ protected function getAttributeFromArray($key) { // Support keys in dot notation. @@ -196,20 +202,21 @@ protected function getAttributeFromArray($key) return parent::getAttributeFromArray($key); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function setAttribute($key, $value) { // Convert _id to ObjectID. - if ($key == '_id' && is_string($value)) { + if ($key === '_id' && is_string($value)) { $builder = $this->newBaseQueryBuilder(); $value = $builder->convertKey($value); - } // Support keys in dot notation. - elseif (str_contains($key, '.')) { + } + + // Support keys in dot notation. + if (str_contains($key, '.')) { // Store to a temporary key, then move data to the actual key $uniqueKey = uniqid($key); + parent::setAttribute($uniqueKey, $value); Arr::set($this->attributes, $key, $this->attributes[$uniqueKey] ?? null); @@ -224,9 +231,7 @@ public function setAttribute($key, $value) return parent::setAttribute($key, $value); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function attributesToArray() { $attributes = parent::attributesToArray(); @@ -246,32 +251,26 @@ public function attributesToArray() return $attributes; } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function getCasts() { return $this->casts; } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function getDirty() { $dirty = parent::getDirty(); // The specified value in the $unset expression does not impact the operation. - if (! empty($this->unset)) { + if ($this->unset !== []) { $dirty['$unset'] = $this->unset; } return $dirty; } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function originalIsEquivalent($key) { if (! array_key_exists($key, $this->original)) { @@ -284,20 +283,22 @@ public function originalIsEquivalent($key) } $attribute = Arr::get($this->attributes, $key); - $original = Arr::get($this->original, $key); + $original = Arr::get($this->original, $key); if ($attribute === $original) { return true; } - if (null === $attribute) { + if ($attribute === null) { return false; } if ($this->isDateAttribute($key)) { $attribute = $attribute instanceof UTCDateTime ? $this->asDateTime($attribute) : $attribute; - $original = $original instanceof UTCDateTime ? $this->asDateTime($original) : $original; + $original = $original instanceof UTCDateTime ? $this->asDateTime($original) : $original; + // Comparison on DateTimeInterface values + // phpcs:disable SlevomatCodingStandard.Operators.DisallowEqualOperators.DisallowedEqualOperator return $attribute == $original; } @@ -310,9 +311,7 @@ public function originalIsEquivalent($key) && strcmp((string) $attribute, (string) $original) === 0; } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function offsetUnset($offset): void { if (str_contains($offset, '.')) { @@ -327,9 +326,7 @@ public function offsetUnset($offset): void } } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function offsetSet($offset, $value): void { parent::offsetSet($offset, $value); @@ -341,10 +338,11 @@ public function offsetSet($offset, $value): void /** * Remove one or more fields. * - * @param string|string[] $columns - * @return void - * * @deprecated Use unset() instead. + * + * @param string|string[] $columns + * + * @return void */ public function drop($columns) { @@ -354,7 +352,8 @@ public function drop($columns) /** * Remove one or more fields. * - * @param string|string[] $columns + * @param string|string[] $columns + * * @return void */ public function unset($columns) @@ -367,12 +366,11 @@ public function unset($columns) } } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function push() { - if ($parameters = func_get_args()) { + $parameters = func_get_args(); + if ($parameters) { $unique = false; if (count($parameters) === 3) { @@ -397,8 +395,9 @@ public function push() /** * Remove one or more values from an array. * - * @param string $column + * @param string $column * @param mixed $values + * * @return mixed */ public function pull($column, $values) @@ -416,9 +415,8 @@ public function pull($column, $values) /** * Append one or more values to the underlying attribute value and sync with original. * - * @param string $column - * @param array $values - * @param bool $unique + * @param string $column + * @param bool $unique */ protected function pushAttributeValues($column, array $values, $unique = false) { @@ -441,8 +439,7 @@ protected function pushAttributeValues($column, array $values, $unique = false) /** * Remove one or more values to the underlying attribute value and sync with original. * - * @param string $column - * @param array $values + * @param string $column */ protected function pullAttributeValues($column, array $values) { @@ -463,18 +460,14 @@ protected function pullAttributeValues($column, array $values) $this->syncOriginalAttribute($column); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function getForeignKey() { - return Str::snake(class_basename($this)).'_'.ltrim($this->primaryKey, '_'); + return Str::snake(class_basename($this)) . '_' . ltrim($this->primaryKey, '_'); } /** * Set the parent relation. - * - * @param \Illuminate\Database\Eloquent\Relations\Relation $relation */ public function setParentRelation(Relation $relation) { @@ -484,24 +477,20 @@ public function setParentRelation(Relation $relation) /** * Get the parent relation. * - * @return \Illuminate\Database\Eloquent\Relations\Relation + * @return Relation */ public function getParentRelation() { return $this->parentRelation; } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function newEloquentBuilder($query) { return new Builder($query); } - /** - * @inheritdoc - */ + /** @inheritdoc */ protected function newBaseQueryBuilder() { $connection = $this->getConnection(); @@ -509,9 +498,7 @@ protected function newBaseQueryBuilder() return new QueryBuilder($connection, $connection->getQueryGrammar(), $connection->getPostProcessor()); } - /** - * @inheritdoc - */ + /** @inheritdoc */ protected function removeTableFromKey($key) { return $key; @@ -533,13 +520,13 @@ public function getQueueableRelations() if ($relation instanceof QueueableCollection) { foreach ($relation->getQueueableRelations() as $collectionValue) { - $relations[] = $key.'.'.$collectionValue; + $relations[] = $key . '.' . $collectionValue; } } if ($relation instanceof QueueableEntity) { foreach ($relation->getQueueableRelations() as $entityKey => $entityValue) { - $relations[] = $key.'.'.$entityValue; + $relations[] = $key . '.' . $entityValue; } } } @@ -556,7 +543,8 @@ protected function getRelationsWithoutParent() { $relations = $this->getRelations(); - if ($parentRelation = $this->getParentRelation()) { + $parentRelation = $this->getParentRelation(); + if ($parentRelation) { unset($relations[$parentRelation->getQualifiedForeignKeyName()]); } @@ -567,7 +555,8 @@ protected function getRelationsWithoutParent() * Checks if column exists on a table. As this is a document model, just return true. This also * prevents calls to non-existent function Grammar::compileColumnListing(). * - * @param string $key + * @param string $key + * * @return bool */ protected function isGuardableColumn($key) @@ -575,9 +564,7 @@ protected function isGuardableColumn($key) return true; } - /** - * @inheritdoc - */ + /** @inheritdoc */ protected function addCastAttributesToArray(array $attributes, array $mutatedAttributes) { foreach ($this->getCasts() as $key => $castType) { @@ -591,7 +578,8 @@ protected function addCastAttributesToArray(array $attributes, array $mutatedAtt // then we will serialize the date for the array. This will convert the dates // to strings based on the date format specified for these Eloquent models. $castValue = $this->castAttribute( - $key, $originalValue + $key, + $originalValue, ); // If the attribute cast was a date or a datetime, we will serialize the date as @@ -601,13 +589,11 @@ protected function addCastAttributesToArray(array $attributes, array $mutatedAtt $castValue = $this->serializeDate($castValue); } - if ($castValue !== null && ($this->isCustomDateTimeCast($castType) || - $this->isImmutableCustomDateTimeCast($castType))) { + if ($castValue !== null && ($this->isCustomDateTimeCast($castType) || $this->isImmutableCustomDateTimeCast($castType))) { $castValue = $castValue->format(explode(':', $castType, 2)[1]); } - if ($castValue instanceof DateTimeInterface && - $this->isClassCastable($key)) { + if ($castValue instanceof DateTimeInterface && $this->isClassCastable($key)) { $castValue = $this->serializeDate($castValue); } diff --git a/src/Eloquent/SoftDeletes.php b/src/Eloquent/SoftDeletes.php index 8263e4c53..135c55dcf 100644 --- a/src/Eloquent/SoftDeletes.php +++ b/src/Eloquent/SoftDeletes.php @@ -1,14 +1,14 @@ getDeletedAtColumn(); diff --git a/src/Helpers/EloquentBuilder.php b/src/Helpers/EloquentBuilder.php index e408b78f8..3140330e5 100644 --- a/src/Helpers/EloquentBuilder.php +++ b/src/Helpers/EloquentBuilder.php @@ -1,5 +1,7 @@ =', $count = 1, $boolean = 'and', Closure $callback = null) + public function has($relation, $operator = '>=', $count = 1, $boolean = 'and', ?Closure $callback = null) { if (is_string($relation)) { if (strpos($relation, '.') !== false) { @@ -48,7 +63,8 @@ public function has($relation, $operator = '>=', $count = 1, $boolean = 'and', C : 'getRelationExistenceCountQuery'; $hasQuery = $relation->{$method}( - $relation->getRelated()->newQuery(), $this + $relation->getRelated()->newQuery(), + $this ); // Next we will call any given callback as an "anonymous" scope so they can get the @@ -59,14 +75,15 @@ public function has($relation, $operator = '>=', $count = 1, $boolean = 'and', C } return $this->addHasWhere( - $hasQuery, $relation, $operator, $count, $boolean + $hasQuery, + $relation, + $operator, + $count, + $boolean, ); } - /** - * @param Relation $relation - * @return bool - */ + /** @return bool */ protected function isAcrossConnections(Relation $relation) { return $relation->getParent()->getConnectionName() !== $relation->getRelated()->getConnectionName(); @@ -75,15 +92,15 @@ protected function isAcrossConnections(Relation $relation) /** * Compare across databases. * - * @param Relation $relation * @param string $operator - * @param int $count + * @param int $count * @param string $boolean - * @param Closure|null $callback + * * @return mixed + * * @throws Exception */ - public function addHybridHas(Relation $relation, $operator = '>=', $count = 1, $boolean = 'and', Closure $callback = null) + public function addHybridHas(Relation $relation, $operator = '>=', $count = 1, $boolean = 'and', ?Closure $callback = null) { $hasQuery = $relation->getQuery(); if ($callback) { @@ -93,7 +110,7 @@ public function addHybridHas(Relation $relation, $operator = '>=', $count = 1, $ // If the operator is <, <= or !=, we will use whereNotIn. $not = in_array($operator, ['<', '<=', '!=']); // If we are comparing to 0, we need an additional $not flip. - if ($count == 0) { + if ($count === 0) { $not = ! $not; } @@ -104,10 +121,7 @@ public function addHybridHas(Relation $relation, $operator = '>=', $count = 1, $ return $this->whereIn($this->getRelatedConstraintKey($relation), $relatedIds, $boolean, $not); } - /** - * @param Relation $relation - * @return string - */ + /** @return string */ protected function getHasCompareKey(Relation $relation) { if (method_exists($relation, 'getHasCompareKey')) { @@ -118,9 +132,10 @@ protected function getHasCompareKey(Relation $relation) } /** - * @param $relations - * @param $operator - * @param $count + * @param Collection $relations + * @param string $operator + * @param int $count + * * @return array */ protected function getConstrainedRelatedIds($relations, $operator, $count) @@ -131,9 +146,10 @@ protected function getConstrainedRelatedIds($relations, $operator, $count) // Remove unwanted related objects based on the operator and count. $relationCount = array_filter($relationCount, function ($counted) use ($count, $operator) { // If we are comparing to 0, we always need all results. - if ($count == 0) { + if ($count === 0) { return true; } + switch ($operator) { case '>=': case '<': @@ -143,7 +159,7 @@ protected function getConstrainedRelatedIds($relations, $operator, $count) return $counted > $count; case '=': case '!=': - return $counted == $count; + return $counted === $count; } }); @@ -154,8 +170,8 @@ protected function getConstrainedRelatedIds($relations, $operator, $count) /** * Returns key we are constraining this parent model's query with. * - * @param Relation $relation * @return string + * * @throws Exception */ protected function getRelatedConstraintKey(Relation $relation) @@ -172,6 +188,6 @@ protected function getRelatedConstraintKey(Relation $relation) return $this->model->getKeyName(); } - throw new Exception(class_basename($relation).' is not supported for hybrid query constraints.'); + throw new Exception(class_basename($relation) . ' is not supported for hybrid query constraints.'); } } diff --git a/src/MongodbQueueServiceProvider.php b/src/MongodbQueueServiceProvider.php index 7ec851d09..7b2066ecb 100644 --- a/src/MongodbQueueServiceProvider.php +++ b/src/MongodbQueueServiceProvider.php @@ -1,11 +1,15 @@ app->singleton('queue.failer', function ($app) { $config = $app['config']['queue.failed']; - if (array_key_exists('driver', $config) && - (is_null($config['driver']) || $config['driver'] === 'null')) { - return new NullFailedJobProvider; + if (array_key_exists('driver', $config) && ($config['driver'] === null || $config['driver'] === 'null')) { + return new NullFailedJobProvider(); } if (isset($config['driver']) && $config['driver'] === 'mongodb') { return $this->mongoFailedJobProvider($config); - } elseif (isset($config['driver']) && $config['driver'] === 'dynamodb') { + } + + if (isset($config['driver']) && $config['driver'] === 'dynamodb') { return $this->dynamoFailedJobProvider($config); - } elseif (isset($config['driver']) && $config['driver'] === 'database-uuids') { + } + + if (isset($config['driver']) && $config['driver'] === 'database-uuids') { return $this->databaseUuidFailedJobProvider($config); - } elseif (isset($config['table'])) { + } + + if (isset($config['table'])) { return $this->databaseFailedJobProvider($config); - } else { - return new NullFailedJobProvider; } + + return new NullFailedJobProvider(); }); } diff --git a/src/MongodbServiceProvider.php b/src/MongodbServiceProvider.php index ece75d2b7..a9ebc1d17 100644 --- a/src/MongodbServiceProvider.php +++ b/src/MongodbServiceProvider.php @@ -1,5 +1,7 @@ where('_id', '=', $this->convertKey($id))->first($columns); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function value($column) { $result = (array) $this->first([$column]); @@ -192,23 +230,20 @@ public function value($column) return Arr::get($result, $column); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function get($columns = []) { return $this->getFresh($columns); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function cursor($columns = []) { $result = $this->getFresh($columns, true); if ($result instanceof LazyCollection) { return $result; } + throw new RuntimeException('Query not compatible with cursor'); } @@ -232,24 +267,24 @@ public function toMql(): array // Use MongoDB's aggregation framework when using grouping or aggregation functions. if ($this->groups || $this->aggregate) { - $group = []; + $group = []; $unwinds = []; // Add grouping columns to the $group part of the aggregation pipeline. if ($this->groups) { foreach ($this->groups as $column) { - $group['_id'][$column] = '$'.$column; + $group['_id'][$column] = '$' . $column; // When grouping, also add the $last operator to each grouped field, // this mimics MySQL's behaviour a bit. - $group[$column] = ['$last' => '$'.$column]; + $group[$column] = ['$last' => '$' . $column]; } // Do the same for other columns that are selected. foreach ($columns as $column) { $key = str_replace('.', '_', $column); - $group[$key] = ['$last' => '$'.$column]; + $group[$key] = ['$last' => '$' . $column]; } } @@ -261,22 +296,25 @@ public function toMql(): array foreach ($this->aggregate['columns'] as $column) { // Add unwind if a subdocument array should be aggregated // column: subarray.price => {$unwind: '$subarray'} - if (count($splitColumns = explode('.*.', $column)) == 2) { + $splitColumns = explode('.*.', $column); + if (count($splitColumns) === 2) { $unwinds[] = $splitColumns[0]; - $column = implode('.', $splitColumns); + $column = implode('.', $splitColumns); } $aggregations = blank($this->aggregate['columns']) ? [] : $this->aggregate['columns']; - if (in_array('*', $aggregations) && $function == 'count') { + if (in_array('*', $aggregations) && $function === 'count') { $options = $this->inheritConnectionOptions(); return ['countDocuments' => [$wheres, $options]]; - } elseif ($function == 'count') { + } + + if ($function === 'count') { // Translate count into sum. $group['aggregate'] = ['$sum' => 1]; } else { - $group['aggregate'] = ['$'.$function => '$'.$column]; + $group['aggregate'] = ['$' . $function => '$' . $column]; } } } @@ -294,7 +332,7 @@ public function toMql(): array // apply unwinds for subdocument array aggregation foreach ($unwinds as $unwind) { - $pipeline[] = ['$unwind' => '$'.$unwind]; + $pipeline[] = ['$unwind' => '$' . $unwind]; } if ($group) { @@ -305,12 +343,15 @@ public function toMql(): array if ($this->orders) { $pipeline[] = ['$sort' => $this->orders]; } + if ($this->offset) { $pipeline[] = ['$skip' => $this->offset]; } + if ($this->limit) { $pipeline[] = ['$limit' => $this->limit]; } + if ($this->projections) { $pipeline[] = ['$project' => $this->projections]; } @@ -327,64 +368,73 @@ public function toMql(): array $options = $this->inheritConnectionOptions($options); return ['aggregate' => [$pipeline, $options]]; - } // Distinct query - elseif ($this->distinct) { + } + + // Distinct query + if ($this->distinct) { // Return distinct results directly - $column = isset($columns[0]) ? $columns[0] : '_id'; + $column = $columns[0] ?? '_id'; $options = $this->inheritConnectionOptions(); return ['distinct' => [$column, $wheres, $options]]; - } // Normal query - else { - // Convert select columns to simple projections. - $projection = array_fill_keys($columns, true); + } - // Add custom projections. - if ($this->projections) { - $projection = array_merge($projection, $this->projections); - } - $options = []; + // Normal query + // Convert select columns to simple projections. + $projection = array_fill_keys($columns, true); - // Apply order, offset, limit and projection - if ($this->timeout) { - $options['maxTimeMS'] = $this->timeout * 1000; - } - if ($this->orders) { - $options['sort'] = $this->orders; - } - if ($this->offset) { - $options['skip'] = $this->offset; - } - if ($this->limit) { - $options['limit'] = $this->limit; - } - if ($this->hint) { - $options['hint'] = $this->hint; - } - if ($projection) { - $options['projection'] = $projection; - } + // Add custom projections. + if ($this->projections) { + $projection = array_merge($projection, $this->projections); + } - // Fix for legacy support, converts the results to arrays instead of objects. - $options['typeMap'] = ['root' => 'array', 'document' => 'array']; + $options = []; - // Add custom query options - if (count($this->options)) { - $options = array_merge($options, $this->options); - } + // Apply order, offset, limit and projection + if ($this->timeout) { + $options['maxTimeMS'] = $this->timeout * 1000; + } - $options = $this->inheritConnectionOptions($options); + if ($this->orders) { + $options['sort'] = $this->orders; + } + + if ($this->offset) { + $options['skip'] = $this->offset; + } + + if ($this->limit) { + $options['limit'] = $this->limit; + } + + if ($this->hint) { + $options['hint'] = $this->hint; + } + + if ($projection) { + $options['projection'] = $projection; + } + + // Fix for legacy support, converts the results to arrays instead of objects. + $options['typeMap'] = ['root' => 'array', 'document' => 'array']; - return ['find' => [$wheres, $options]]; + // Add custom query options + if (count($this->options)) { + $options = array_merge($options, $this->options); } + + $options = $this->inheritConnectionOptions($options); + + return ['find' => [$wheres, $options]]; } /** * Execute the query as a fresh "select" statement. * - * @param array $columns + * @param array $columns * @param bool $returnLazy + * * @return array|static[]|Collection|LazyCollection */ public function getFresh($columns = [], $returnLazy = false) @@ -456,12 +506,13 @@ public function generateCacheKey() return md5(serialize(array_values($key))); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function aggregate($function, $columns = []) { - $this->aggregate = compact('function', 'columns'); + $this->aggregate = [ + 'function' => $function, + 'columns' => $columns, + ]; $previousColumns = $this->columns; @@ -477,8 +528,8 @@ public function aggregate($function, $columns = []) // Once we have executed the query, we will reset the aggregate property so // that more select queries can be executed against the database without // the aggregate value getting in the way when the grammar builds it. - $this->aggregate = null; - $this->columns = $previousColumns; + $this->aggregate = null; + $this->columns = $previousColumns; $this->bindings['select'] = $previousSelectBindings; if (isset($results[0])) { @@ -488,17 +539,13 @@ public function aggregate($function, $columns = []) } } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function exists() { return $this->first() !== null; } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function distinct($column = false) { $this->distinct = true; @@ -511,8 +558,9 @@ public function distinct($column = false) } /** - * @inheritdoc * @param int|string|array $direction + * + * @inheritdoc */ public function orderBy($column, $direction = 'asc') { @@ -520,22 +568,24 @@ public function orderBy($column, $direction = 'asc') $direction = match ($direction) { 'asc', 'ASC' => 1, 'desc', 'DESC' => -1, - default => throw new \InvalidArgumentException('Order direction must be "asc" or "desc".'), + default => throw new InvalidArgumentException('Order direction must be "asc" or "desc".'), }; } - if ($column == 'natural') { + $column = (string) $column; + if ($column === 'natural') { $this->orders['$natural'] = $direction; } else { - $this->orders[(string) $column] = $direction; + $this->orders[$column] = $direction; } return $this; } /** - * @inheritdoc * @param list{mixed, mixed}|CarbonPeriod $values + * + * @inheritdoc */ public function whereBetween($column, iterable $values, $boolean = 'and', $not = false) { @@ -546,17 +596,21 @@ public function whereBetween($column, iterable $values, $boolean = 'and', $not = } if (is_array($values) && (! array_is_list($values) || count($values) !== 2)) { - throw new \InvalidArgumentException('Between $values must be a list with exactly two elements: [min, max]'); + throw new InvalidArgumentException('Between $values must be a list with exactly two elements: [min, max]'); } - $this->wheres[] = compact('column', 'type', 'boolean', 'values', 'not'); + $this->wheres[] = [ + 'column' => $column, + 'type' => $type, + 'boolean' => $boolean, + 'values' => $values, + 'not' => $not, + ]; return $this; } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function insert(array $values) { // Since every insert gets treated like a batch insert, we will have to detect @@ -580,39 +634,38 @@ public function insert(array $values) $result = $this->collection->insertMany($values, $options); - return 1 == (int) $result->isAcknowledged(); + return $result->isAcknowledged(); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function insertGetId(array $values, $sequence = null) { $options = $this->inheritConnectionOptions(); $result = $this->collection->insertOne($values, $options); - if (1 == (int) $result->isAcknowledged()) { - if ($sequence === null) { - $sequence = '_id'; - } + if (! $result->isAcknowledged()) { + return null; + } - // Return id - return $sequence == '_id' ? $result->getInsertedId() : $values[$sequence]; + if ($sequence === null || $sequence === '_id') { + return $result->getInsertedId(); } + + return $values[$sequence]; } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function update(array $values, array $options = []) { // Use $set as default operator for field names that are not in an operator foreach ($values as $key => $value) { - if (! str_starts_with($key, '$')) { - $values['$set'][$key] = $value; - unset($values[$key]); + if (str_starts_with($key, '$')) { + continue; } + + $values['$set'][$key] = $value; + unset($values[$key]); } $options = $this->inheritConnectionOptions($options); @@ -620,9 +673,7 @@ public function update(array $values, array $options = []) return $this->performUpdate($values, $options); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function increment($column, $amount = 1, array $extra = [], array $options = []) { $query = ['$inc' => [(string) $column => $amount]]; @@ -643,39 +694,31 @@ public function increment($column, $amount = 1, array $extra = [], array $option return $this->performUpdate($query, $options); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function decrement($column, $amount = 1, array $extra = [], array $options = []) { return $this->increment($column, -1 * $amount, $extra, $options); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function chunkById($count, callable $callback, $column = '_id', $alias = null) { return parent::chunkById($count, $callback, $column, $alias); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function forPageAfterId($perPage = 15, $lastId = 0, $column = '_id') { return parent::forPageAfterId($perPage, $lastId, $column); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function pluck($column, $key = null) { $results = $this->get($key === null ? [$column] : [$column, $key]); // Convert ObjectID's to strings - if ($key == '_id') { + if (((string) $key) === '_id') { $results = $results->map(function ($item) { $item['_id'] = (string) $item['_id']; @@ -688,9 +731,7 @@ public function pluck($column, $key = null) return new Collection($p); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function delete($id = null) { // If an ID is passed to the method, we will set the where clause to check @@ -700,28 +741,27 @@ public function delete($id = null) $this->where('_id', '=', $id); } - $wheres = $this->compileWheres(); + $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)); + 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 (1 == (int) $result->isAcknowledged()) { + if ($result->isAcknowledged()) { return $result->getDeletedCount(); } return 0; } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function from($collection, $as = null) { if ($collection) { @@ -731,34 +771,30 @@ public function from($collection, $as = null) return parent::from($collection); } - /** - * @inheritdoc - */ public function truncate(): bool { $options = $this->inheritConnectionOptions(); - $result = $this->collection->deleteMany([], $options); + $result = $this->collection->deleteMany([], $options); - return 1 === (int) $result->isAcknowledged(); + return $result->isAcknowledged(); } /** * Get an array with the values of a given column. * - * @param string $column - * @param string $key - * @return array + * @deprecated Use pluck instead. + * + * @param string $column + * @param string $key * - * @deprecated + * @return Collection */ public function lists($column, $key = null) { return $this->pluck($column, $key); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function raw($value = null) { // Execute the closure on the mongodb collection @@ -778,9 +814,10 @@ public function raw($value = null) /** * Append one or more values to an array. * - * @param string|array $column - * @param mixed $value - * @param bool $unique + * @param string|array $column + * @param mixed $value + * @param bool $unique + * * @return int */ public function push($column, $value = null, $unique = false) @@ -793,8 +830,9 @@ public function push($column, $value = null, $unique = false) if (is_array($column)) { if ($value !== null) { - throw new \InvalidArgumentException(sprintf('2nd argument of %s() must be "null" when 1st argument is an array. Got "%s" instead.', __METHOD__, get_debug_type($value))); + throw new InvalidArgumentException(sprintf('2nd argument of %s() must be "null" when 1st argument is an array. Got "%s" instead.', __METHOD__, get_debug_type($value))); } + $query = [$operator => $column]; } elseif ($batch) { $query = [$operator => [(string) $column => ['$each' => $value]]]; @@ -808,8 +846,9 @@ public function push($column, $value = null, $unique = false) /** * Remove one or more values from an array. * - * @param string|array $column - * @param mixed $value + * @param string|array $column + * @param mixed $value + * * @return int */ public function pull($column, $value = null) @@ -832,7 +871,8 @@ public function pull($column, $value = null) /** * Remove one or more fields. * - * @param string|string[] $columns + * @param string|string[] $columns + * * @return int */ public function drop($columns) @@ -853,9 +893,9 @@ public function drop($columns) } /** - * @inheritdoc - * * @return static + * + * @inheritdoc */ public function newQuery() { @@ -865,8 +905,8 @@ public function newQuery() /** * Perform an update query. * - * @param array $query - * @param array $options + * @param array $query + * * @return int */ protected function performUpdate($query, array $options = []) @@ -880,7 +920,7 @@ protected function performUpdate($query, array $options = []) $wheres = $this->compileWheres(); $result = $this->collection->updateMany($wheres, $query, $options); - if (1 == (int) $result->isAcknowledged()) { + if ($result->isAcknowledged()) { return $result->getModifiedCount() ? $result->getModifiedCount() : $result->getUpsertedCount(); } @@ -890,7 +930,8 @@ protected function performUpdate($query, array $options = []) /** * Convert a key to ObjectID if needed. * - * @param mixed $id + * @param mixed $id + * * @return mixed */ public function convertKey($id) @@ -906,9 +947,7 @@ public function convertKey($id) return $id; } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function where($column, $operator = null, $value = null, $boolean = 'and') { $params = func_get_args(); @@ -922,8 +961,8 @@ public function where($column, $operator = null, $value = null, $boolean = 'and' } } - if (func_num_args() == 1 && is_string($column)) { - throw new \ArgumentCountError(sprintf('Too few arguments to function %s("%s"), 1 passed and at least 2 expected when the 1st is a string.', __METHOD__, $column)); + if (func_num_args() === 1 && is_string($column)) { + throw new ArgumentCountError(sprintf('Too few arguments to function %s("%s"), 1 passed and at least 2 expected when the 1st is a string.', __METHOD__, $column)); } return parent::where(...$params); @@ -953,15 +992,20 @@ protected function compileWheres(): array } } + // Convert column name to string to use as array key + if (isset($where['column']) && $where['column'] instanceof Stringable) { + $where['column'] = (string) $where['column']; + } + // Convert id's. - if (isset($where['column']) && ($where['column'] == '_id' || str_ends_with($where['column'], '._id'))) { - // Multiple values. + if (isset($where['column']) && ($where['column'] === '_id' || str_ends_with($where['column'], '._id'))) { if (isset($where['values'])) { + // Multiple values. foreach ($where['values'] as &$value) { $value = $this->convertKey($value); } - } // Single value. - elseif (isset($where['value'])) { + } elseif (isset($where['value'])) { + // Single value. $where['value'] = $this->convertKey($where['value']); } } @@ -997,21 +1041,16 @@ protected function compileWheres(): array // In a sequence of "where" clauses, the logical operator of the // first "where" is determined by the 2nd "where". // $where['boolean'] = "and", "or", "and not" or "or not" - if ($i == 0 && count($wheres) > 1 + if ( + $i === 0 && count($wheres) > 1 && str_starts_with($where['boolean'], 'and') && str_starts_with($wheres[$i + 1]['boolean'], 'or') ) { - $where['boolean'] = 'or'.(str_ends_with($where['boolean'], 'not') ? ' not' : ''); - } - - // Column name can be a Stringable object. - if (isset($where['column']) && $where['column'] instanceof \Stringable) { - $where['column'] = (string) $where['column']; + $where['boolean'] = 'or' . (str_ends_with($where['boolean'], 'not') ? ' not' : ''); } // We use different methods to compile different wheres. - $method = "compileWhere{$where['type']}"; - + $method = 'compileWhere' . $where['type']; $result = $this->{$method}($where); if (str_ends_with($where['boolean'], 'not')) { @@ -1021,6 +1060,7 @@ protected function compileWheres(): array // Wrap the where with an $or operator. if (str_starts_with($where['boolean'], 'or')) { $result = ['$or' => [$result]]; + // phpcs:ignore Squiz.ControlStructures.ControlSignature.SpaceAfterCloseBrace } // If there are multiple wheres, we will wrap it with $and. This is needed @@ -1037,12 +1077,15 @@ protected function compileWheres(): array } /** - * @param array $where + * @param array $where + * * @return array */ protected function compileWhereBasic(array $where): array { - extract($where); + $column = $where['column']; + $operator = $where['operator']; + $value = $where['value']; // Replace like or not like with a Regex instance. if (in_array($operator, ['like', 'not like'])) { @@ -1062,10 +1105,11 @@ protected function compileWhereBasic(array $where): array // All backslashes are converted to \\, which are needed in matching regexes. preg_quote($value), ); - $value = new Regex('^'.$regex.'$', 'i'); + $value = new Regex('^' . $regex . '$', 'i'); // For inverse like operations, we can just use the $not operator with the Regex $operator = $operator === 'like' ? '=' : 'not'; + // phpcs:ignore Squiz.ControlStructures.ControlSignature.SpaceAfterCloseBrace } // Manipulate regex operations. @@ -1075,18 +1119,20 @@ protected function compileWhereBasic(array $where): array // Detect the delimiter and validate the preg pattern $delimiter = substr($value, 0, 1); if (! in_array($delimiter, self::REGEX_DELIMITERS)) { - throw new \LogicException(sprintf('Missing expected starting delimiter in regular expression "%s", supported delimiters are: %s', $value, implode(' ', self::REGEX_DELIMITERS))); + throw new LogicException(sprintf('Missing expected starting delimiter in regular expression "%s", supported delimiters are: %s', $value, implode(' ', self::REGEX_DELIMITERS))); } + $e = explode($delimiter, $value); // We don't try to detect if the last delimiter is escaped. This would be an invalid regex. if (count($e) < 3) { - throw new \LogicException(sprintf('Missing expected ending delimiter "%s" in regular expression "%s"', $delimiter, $value)); + throw new LogicException(sprintf('Missing expected ending delimiter "%s" in regular expression "%s"', $delimiter, $value)); } + // Flags are after the last delimiter $flags = end($e); // Extract the regex string between the delimiters $regstr = substr($value, 1, -1 - strlen($flags)); - $value = new Regex($regstr, $flags); + $value = new Regex($regstr, $flags); } // For inverse regex operations, we can just use the $not operator with the Regex @@ -1096,76 +1142,48 @@ protected function compileWhereBasic(array $where): array if (! isset($operator) || $operator === '=' || $operator === 'eq') { $query = [$column => $value]; } else { - $query = [$column => ['$'.$operator => $value]]; + $query = [$column => ['$' . $operator => $value]]; } return $query; } - /** - * @param array $where - * @return mixed - */ protected function compileWhereNested(array $where): mixed { - extract($where); - - return $query->compileWheres(); + return $where['query']->compileWheres(); } - /** - * @param array $where - * @return array - */ protected function compileWhereIn(array $where): array { - extract($where); - - return [$column => ['$in' => array_values($values)]]; + return [$where['column'] => ['$in' => array_values($where['values'])]]; } - /** - * @param array $where - * @return array - */ protected function compileWhereNotIn(array $where): array { - extract($where); - - return [$column => ['$nin' => array_values($values)]]; + return [$where['column'] => ['$nin' => array_values($where['values'])]]; } - /** - * @param array $where - * @return array - */ protected function compileWhereNull(array $where): array { $where['operator'] = '='; - $where['value'] = null; + $where['value'] = null; return $this->compileWhereBasic($where); } - /** - * @param array $where - * @return array - */ protected function compileWhereNotNull(array $where): array { $where['operator'] = 'ne'; - $where['value'] = null; + $where['value'] = null; return $this->compileWhereBasic($where); } - /** - * @param array $where - * @return array - */ protected function compileWhereBetween(array $where): array { - extract($where); + $column = $where['column']; + $not = $where['not']; + $values = $where['values']; if ($not) { return [ @@ -1192,16 +1210,12 @@ protected function compileWhereBetween(array $where): array ]; } - /** - * @param array $where - * @return array - */ protected function compileWhereDate(array $where): array { $startOfDay = new UTCDateTime(Carbon::parse($where['value'])->startOfDay()); - $endOfDay = new UTCDateTime(Carbon::parse($where['value'])->endOfDay()); + $endOfDay = new UTCDateTime(Carbon::parse($where['value'])->endOfDay()); - return match($where['operator']) { + return match ($where['operator']) { 'eq', '=' => [ $where['column'] => [ '$gte' => $startOfDay, @@ -1217,29 +1231,21 @@ protected function compileWhereDate(array $where): array ], ], 'lt', 'gte' => [ - $where['column'] => [ - '$'.$where['operator'] => $startOfDay, - ], + $where['column'] => ['$' . $where['operator'] => $startOfDay], ], 'gt', 'lte' => [ - $where['column'] => [ - '$'.$where['operator'] => $endOfDay, - ], + $where['column'] => ['$' . $where['operator'] => $endOfDay], ], }; } - /** - * @param array $where - * @return array - */ protected function compileWhereMonth(array $where): array { return [ '$expr' => [ - '$'.$where['operator'] => [ + '$' . $where['operator'] => [ [ - '$month' => '$'.$where['column'], + '$month' => '$' . $where['column'], ], (int) $where['value'], ], @@ -1247,17 +1253,13 @@ protected function compileWhereMonth(array $where): array ]; } - /** - * @param array $where - * @return array - */ protected function compileWhereDay(array $where): array { return [ '$expr' => [ - '$'.$where['operator'] => [ + '$' . $where['operator'] => [ [ - '$dayOfMonth' => '$'.$where['column'], + '$dayOfMonth' => '$' . $where['column'], ], (int) $where['value'], ], @@ -1265,17 +1267,13 @@ protected function compileWhereDay(array $where): array ]; } - /** - * @param array $where - * @return array - */ protected function compileWhereYear(array $where): array { return [ '$expr' => [ - '$'.$where['operator'] => [ + '$' . $where['operator'] => [ [ - '$year' => '$'.$where['column'], + '$year' => '$' . $where['column'], ], (int) $where['value'], ], @@ -1283,14 +1281,10 @@ protected function compileWhereYear(array $where): array ]; } - /** - * @param array $where - * @return array - */ protected function compileWhereTime(array $where): array { if (! is_string($where['value']) || ! preg_match('/^[0-2][0-9](:[0-6][0-9](:[0-6][0-9])?)?$/', $where['value'], $matches)) { - throw new \InvalidArgumentException(sprintf('Invalid time format, expected HH:MM:SS, HH:MM or HH, got "%s"', is_string($where['value']) ? $where['value'] : get_debug_type($where['value']))); + throw new InvalidArgumentException(sprintf('Invalid time format, expected HH:MM:SS, HH:MM or HH, got "%s"', is_string($where['value']) ? $where['value'] : get_debug_type($where['value']))); } $format = match (count($matches)) { @@ -1301,9 +1295,9 @@ protected function compileWhereTime(array $where): array return [ '$expr' => [ - '$'.$where['operator'] => [ + '$' . $where['operator'] => [ [ - '$dateToString' => ['date' => '$'.$where['column'], 'format' => $format], + '$dateToString' => ['date' => '$' . $where['column'], 'format' => $format], ], $where['value'], ], @@ -1311,10 +1305,6 @@ protected function compileWhereTime(array $where): array ]; } - /** - * @param array $where - * @return mixed - */ protected function compileWhereRaw(array $where): mixed { return $where['sql']; @@ -1323,7 +1313,6 @@ protected function compileWhereRaw(array $where): mixed /** * Set custom options for the query. * - * @param array $options * @return $this */ public function options(array $options) @@ -1338,19 +1327,20 @@ public function options(array $options) */ private function inheritConnectionOptions(array $options = []): array { - if (! isset($options['session']) && ($session = $this->connection->getSession())) { - $options['session'] = $session; + if (! isset($options['session'])) { + $session = $this->connection->getSession(); + if ($session) { + $options['session'] = $session; + } } return $options; } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function __call($method, $parameters) { - if ($method == 'unset') { + if ($method === 'unset') { return $this->drop(...$parameters); } @@ -1360,90 +1350,90 @@ public function __call($method, $parameters) /** @internal This method is not supported by MongoDB. */ public function toSql() { - throw new \BadMethodCallException('This method is not supported by MongoDB. Try "toMql()" instead.'); + throw new BadMethodCallException('This method is not supported by MongoDB. Try "toMql()" instead.'); } /** @internal This method is not supported by MongoDB. */ public function toRawSql() { - throw new \BadMethodCallException('This method is not supported by MongoDB. Try "toMql()" instead.'); + throw new BadMethodCallException('This method is not supported by MongoDB. Try "toMql()" instead.'); } /** @internal This method is not supported by MongoDB. */ public function whereColumn($first, $operator = null, $second = null, $boolean = 'and') { - throw new \BadMethodCallException('This method is not supported by MongoDB'); + throw new BadMethodCallException('This method is not supported by MongoDB'); } /** @internal This method is not supported by MongoDB. */ public function whereFullText($columns, $value, array $options = [], $boolean = 'and') { - throw new \BadMethodCallException('This method is not supported by MongoDB'); + throw new BadMethodCallException('This method is not supported by MongoDB'); } /** @internal This method is not supported by MongoDB. */ public function groupByRaw($sql, array $bindings = []) { - throw new \BadMethodCallException('This method is not supported by MongoDB'); + throw new BadMethodCallException('This method is not supported by MongoDB'); } /** @internal This method is not supported by MongoDB. */ public function orderByRaw($sql, $bindings = []) { - throw new \BadMethodCallException('This method is not supported by MongoDB'); + throw new BadMethodCallException('This method is not supported by MongoDB'); } /** @internal This method is not supported by MongoDB. */ public function unionAll($query) { - throw new \BadMethodCallException('This method is not supported by MongoDB'); + throw new BadMethodCallException('This method is not supported by MongoDB'); } /** @internal This method is not supported by MongoDB. */ public function union($query, $all = false) { - throw new \BadMethodCallException('This method is not supported by MongoDB'); + throw new BadMethodCallException('This method is not supported by MongoDB'); } /** @internal This method is not supported by MongoDB. */ public function having($column, $operator = null, $value = null, $boolean = 'and') { - throw new \BadMethodCallException('This method is not supported by MongoDB'); + throw new BadMethodCallException('This method is not supported by MongoDB'); } /** @internal This method is not supported by MongoDB. */ public function havingRaw($sql, array $bindings = [], $boolean = 'and') { - throw new \BadMethodCallException('This method is not supported by MongoDB'); + throw new BadMethodCallException('This method is not supported by MongoDB'); } /** @internal This method is not supported by MongoDB. */ public function havingBetween($column, iterable $values, $boolean = 'and', $not = false) { - throw new \BadMethodCallException('This method is not supported by MongoDB'); + throw new BadMethodCallException('This method is not supported by MongoDB'); } /** @internal This method is not supported by MongoDB. */ public function whereIntegerInRaw($column, $values, $boolean = 'and', $not = false) { - throw new \BadMethodCallException('This method is not supported by MongoDB'); + throw new BadMethodCallException('This method is not supported by MongoDB'); } /** @internal This method is not supported by MongoDB. */ public function orWhereIntegerInRaw($column, $values) { - throw new \BadMethodCallException('This method is not supported by MongoDB'); + throw new BadMethodCallException('This method is not supported by MongoDB'); } /** @internal This method is not supported by MongoDB. */ public function whereIntegerNotInRaw($column, $values, $boolean = 'and') { - throw new \BadMethodCallException('This method is not supported by MongoDB'); + throw new BadMethodCallException('This method is not supported by MongoDB'); } /** @internal This method is not supported by MongoDB. */ public function orWhereIntegerNotInRaw($column, $values, $boolean = 'and') { - throw new \BadMethodCallException('This method is not supported by MongoDB'); + throw new BadMethodCallException('This method is not supported by MongoDB'); } } diff --git a/src/Query/Grammar.php b/src/Query/Grammar.php index d06e945bc..381a98eaa 100644 --- a/src/Query/Grammar.php +++ b/src/Query/Grammar.php @@ -1,5 +1,7 @@ getTimestamp(); - - $exception = (string) $exception; - - $this->getTable()->insert(compact('connection', 'queue', 'payload', 'failed_at', 'exception')); + $this->getTable()->insert([ + 'connection' => $connection, + 'queue' => $queue, + 'payload' => $payload, + 'failed_at' => Carbon::now()->getTimestamp(), + 'exception' => (string) $exception, + ]); } /** @@ -47,6 +55,7 @@ public function all() * Get a single failed job. * * @param mixed $id + * * @return object */ public function find($id) @@ -66,6 +75,7 @@ public function find($id) * Delete a single failed job from storage. * * @param mixed $id + * * @return bool */ public function forget($id) diff --git a/src/Queue/MongoConnector.php b/src/Queue/MongoConnector.php index d9e5b97e5..4f987694a 100644 --- a/src/Queue/MongoConnector.php +++ b/src/Queue/MongoConnector.php @@ -1,7 +1,10 @@ connections->connection($config['connection'] ?? null), $config['table'], $config['queue'], - $config['expire'] ?? 60 + $config['expire'] ?? 60, ); } } diff --git a/src/Queue/MongoJob.php b/src/Queue/MongoJob.php index ce9bae75e..13e458aac 100644 --- a/src/Queue/MongoJob.php +++ b/src/Queue/MongoJob.php @@ -1,7 +1,10 @@ job->reserved; } - /** - * @return \DateTime - */ + /** @return DateTime */ public function reservedAt() { return $this->job->reserved_at; diff --git a/src/Queue/MongoQueue.php b/src/Queue/MongoQueue.php index fd67a437a..eeac36c78 100644 --- a/src/Queue/MongoQueue.php +++ b/src/Queue/MongoQueue.php @@ -1,11 +1,14 @@ retryAfter = $retryAfter; } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function pop($queue = null) { $queue = $this->getQueue($queue); @@ -43,11 +43,18 @@ public function pop($queue = null) $this->releaseJobsThatHaveBeenReservedTooLong($queue); } - if ($job = $this->getNextAvailableJobAndReserve($queue)) { - return new MongoJob( - $this->container, $this, $job, $this->connectionName, $queue - ); + $job = $this->getNextAvailableJobAndReserve($queue); + if (! $job) { + return null; } + + return new MongoJob( + $this->container, + $this, + $job, + $this->connectionName, + $queue, + ); } /** @@ -55,12 +62,13 @@ public function pop($queue = null) * When using multiple daemon queue listeners to process jobs there * is a possibility that multiple processes can end up reading the * same record before one has flagged it as reserved. - * This race condition can result in random jobs being run more then + * This race condition can result in random jobs being run more than * once. To solve this we use findOneAndUpdate to lock the next jobs * record while flagging it as reserved at the same time. * * @param string|null $queue - * @return \StdClass|null + * + * @return stdClass|null */ protected function getNextAvailableJobAndReserve($queue) { @@ -75,14 +83,12 @@ protected function getNextAvailableJobAndReserve($queue) 'reserved' => 1, 'reserved_at' => Carbon::now()->getTimestamp(), ], - '$inc' => [ - 'attempts' => 1, - ], + '$inc' => ['attempts' => 1], ], [ 'returnDocument' => FindOneAndUpdate::RETURN_DOCUMENT_AFTER, 'sort' => ['available_at' => 1], - ] + ], ); if ($job) { @@ -96,6 +102,7 @@ protected function getNextAvailableJobAndReserve($queue) * Release the jobs that have been reserved for too long. * * @param string $queue + * * @return void */ protected function releaseJobsThatHaveBeenReservedTooLong($queue) @@ -117,7 +124,8 @@ protected function releaseJobsThatHaveBeenReservedTooLong($queue) * Release the given job ID from reservation. * * @param string $id - * @param int $attempts + * @param int $attempts + * * @return void */ protected function releaseJob($id, $attempts) @@ -129,17 +137,13 @@ protected function releaseJob($id, $attempts) ]); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function deleteReserved($queue, $id) { $this->database->collection($this->table)->where('_id', $id)->delete(); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function deleteAndRelease($queue, $job, $delay) { $this->deleteReserved($queue, $job->getJobId()); diff --git a/src/Relations/BelongsTo.php b/src/Relations/BelongsTo.php index b159b3ddf..0a8cb1d9c 100644 --- a/src/Relations/BelongsTo.php +++ b/src/Relations/BelongsTo.php @@ -1,9 +1,13 @@ getOwnerKey(); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function addConstraints() { if (static::$constraints) { @@ -30,9 +32,7 @@ public function addConstraints() } } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function addEagerConstraints(array $models) { // We'll grab the primary key name of the related models since it could be set to @@ -43,9 +43,7 @@ public function addEagerConstraints(array $models) $this->query->whereIn($key, $this->getEagerModelKeys($models)); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function getRelationExistenceQuery(Builder $query, Builder $parentQuery, $columns = ['*']) { return $query; @@ -64,11 +62,11 @@ public function getOwnerKey() /** * Get the name of the "where in" method for eager loading. * - * @param \Illuminate\Database\Eloquent\Model $model * @param string $key + * * @return string */ - protected function whereInMethod(EloquentModel $model, $key) + protected function whereInMethod(Model $model, $key) { return 'whereIn'; } diff --git a/src/Relations/BelongsToMany.php b/src/Relations/BelongsToMany.php index 61ac4a9f2..4afa3663b 100644 --- a/src/Relations/BelongsToMany.php +++ b/src/Relations/BelongsToMany.php @@ -1,5 +1,7 @@ getForeignKey(); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function getRelationExistenceQuery(Builder $query, Builder $parentQuery, $columns = ['*']) { return $query; } - /** - * @inheritdoc - */ + /** @inheritdoc */ protected function hydratePivotRelation(array $models) { // Do nothing. @@ -39,7 +47,6 @@ protected function hydratePivotRelation(array $models) /** * Set the select clause for the relation query. * - * @param array $columns * @return array */ protected function getSelectColumns(array $columns = ['*']) @@ -47,17 +54,13 @@ protected function getSelectColumns(array $columns = ['*']) return $columns; } - /** - * @inheritdoc - */ + /** @inheritdoc */ protected function shouldSelect(array $columns = ['*']) { return $columns; } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function addConstraints() { if (static::$constraints) { @@ -79,9 +82,7 @@ protected function setWhere() return $this; } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function save(Model $model, array $joining = [], $touch = true) { $model->save(['touch' => false]); @@ -91,9 +92,7 @@ public function save(Model $model, array $joining = [], $touch = true) return $model; } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function create(array $attributes = [], array $joining = [], $touch = true) { $instance = $this->related->newInstance($attributes); @@ -108,9 +107,7 @@ public function create(array $attributes = [], array $joining = [], $touch = tru return $instance; } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function sync($ids, $detaching = true) { $changes = [ @@ -158,7 +155,8 @@ public function sync($ids, $detaching = true) // touching until after the entire operation is complete so we don't fire a // ton of touch operations until we are totally done syncing the records. $changes = array_merge( - $changes, $this->attachNew($records, $current, false) + $changes, + $this->attachNew($records, $current, false), ); if (count($changes['attached']) || count($changes['updated'])) { @@ -168,17 +166,13 @@ public function sync($ids, $detaching = true) return $changes; } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function updateExistingPivot($id, array $attributes, $touch = true) { // Do nothing, we have no pivot table. } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function attach($id, array $attributes = [], $touch = true) { if ($id instanceof Model) { @@ -204,14 +198,14 @@ public function attach($id, array $attributes = [], $touch = true) // Attach the new ids to the parent model. $this->parent->push($this->getRelatedKey(), (array) $id, true); - if ($touch) { - $this->touchIfTouching(); + if (! $touch) { + return; } + + $this->touchIfTouching(); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function detach($ids = [], $touch = true) { if ($ids instanceof Model) { @@ -243,9 +237,7 @@ public function detach($ids = [], $touch = true) return count($ids); } - /** - * @inheritdoc - */ + /** @inheritdoc */ protected function buildDictionary(Collection $results) { $foreign = $this->foreignPivotKey; @@ -264,9 +256,7 @@ protected function buildDictionary(Collection $results) return $dictionary; } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function newPivotQuery() { return $this->newRelatedQuery(); @@ -292,17 +282,13 @@ public function getForeignKey() return $this->foreignPivotKey; } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function getQualifiedForeignPivotKeyName() { return $this->foreignPivotKey; } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function getQualifiedRelatedPivotKeyName() { return $this->relatedPivotKey; @@ -312,9 +298,9 @@ public function getQualifiedRelatedPivotKeyName() * Format the sync list so that it is keyed by ID. (Legacy Support) * The original function has been renamed to formatRecordsList since Laravel 5.3. * - * @param array $records - * @return array * @deprecated + * + * @return array */ protected function formatSyncList(array $records) { @@ -323,6 +309,7 @@ protected function formatSyncList(array $records) if (! is_array($attributes)) { [$id, $attributes] = [$attributes, []]; } + $results[$id] = $attributes; } @@ -342,8 +329,8 @@ public function getRelatedKey() /** * Get the name of the "where in" method for eager loading. * - * @param \Illuminate\Database\Eloquent\Model $model * @param string $key + * * @return string */ protected function whereInMethod(Model $model, $key) diff --git a/src/Relations/EmbedsMany.php b/src/Relations/EmbedsMany.php index 5ef9a2e6e..b97849f24 100644 --- a/src/Relations/EmbedsMany.php +++ b/src/Relations/EmbedsMany.php @@ -1,19 +1,25 @@ toCollection($this->getEmbedded()); @@ -34,14 +38,13 @@ public function getResults() /** * Save a new model and attach it to the parent model. * - * @param Model $model * @return Model|bool */ public function performInsert(Model $model) { // Generate a new key if needed. - if ($model->getKeyName() == '_id' && ! $model->getKey()) { - $model->setAttribute('_id', new ObjectID); + if ($model->getKeyName() === '_id' && ! $model->getKey()) { + $model->setAttribute('_id', new ObjectID()); } // For deeply nested documents, let the parent handle the changes. @@ -65,7 +68,6 @@ public function performInsert(Model $model) /** * Save an existing model and attach it to the parent model. * - * @param Model $model * @return Model|bool */ public function performUpdate(Model $model) @@ -80,10 +82,10 @@ public function performUpdate(Model $model) // Get the correct foreign key value. $foreignKey = $this->getForeignKeyValue($model); - $values = $this->getUpdateValues($model->getDirty(), $this->localKey.'.$.'); + $values = $this->getUpdateValues($model->getDirty(), $this->localKey . '.$.'); // Update document in database. - $result = $this->toBase()->where($this->localKey.'.'.$model->getKeyName(), $foreignKey) + $result = $this->toBase()->where($this->localKey . '.' . $model->getKeyName(), $foreignKey) ->update($values); // Attach the model to its parent. @@ -97,7 +99,6 @@ public function performUpdate(Model $model) /** * Delete an existing model and detach it from the parent model. * - * @param Model $model * @return int */ public function performDelete(Model $model) @@ -124,7 +125,6 @@ public function performDelete(Model $model) /** * Associate the model instance to the given parent, without saving it to the database. * - * @param Model $model * @return Model */ public function associate(Model $model) @@ -139,7 +139,8 @@ public function associate(Model $model) /** * Dissociate the model instance from the given parent, without saving it to the database. * - * @param mixed $ids + * @param mixed $ids + * * @return int */ public function dissociate($ids = []) @@ -168,7 +169,8 @@ public function dissociate($ids = []) /** * Destroy the embedded models for the given IDs. * - * @param mixed $ids + * @param mixed $ids + * * @return int */ public function destroy($ids = []) @@ -210,7 +212,8 @@ public function delete() /** * Destroy alias. * - * @param mixed $ids + * @param mixed $ids + * * @return int */ public function detach($ids = []) @@ -221,7 +224,6 @@ public function detach($ids = []) /** * Save alias. * - * @param Model $model * @return Model */ public function attach(Model $model) @@ -232,14 +234,15 @@ public function attach(Model $model) /** * Associate a new model instance to the given parent, without saving it to the database. * - * @param Model $model + * @param Model $model + * * @return Model */ protected function associateNew($model) { // Create a new key if needed. if ($model->getKeyName() === '_id' && ! $model->getAttribute('_id')) { - $model->setAttribute('_id', new ObjectID); + $model->setAttribute('_id', new ObjectID()); } $records = $this->getEmbedded(); @@ -253,7 +256,8 @@ protected function associateNew($model) /** * Associate an existing model instance to the given parent, without saving it to the database. * - * @param Model $model + * @param Model $model + * * @return Model */ protected function associateExisting($model) @@ -267,6 +271,7 @@ protected function associateExisting($model) // Replace the document in the parent model. foreach ($records as &$record) { + // @phpcs:ignore SlevomatCodingStandard.Operators.DisallowEqualOperators if ($record[$primaryKey] == $key) { $record = $model->getAttributes(); break; @@ -277,25 +282,26 @@ protected function associateExisting($model) } /** - * @param int|null $perPage - * @param array $columns - * @param string $pageName - * @param int|null $page + * @param int|null $perPage + * @param array $columns + * @param string $pageName + * @param int|null $page + * * @return \Illuminate\Contracts\Pagination\LengthAwarePaginator */ public function paginate($perPage = null, $columns = ['*'], $pageName = 'page', $page = null) { - $page = $page ?: Paginator::resolveCurrentPage($pageName); + $page = $page ?: Paginator::resolveCurrentPage($pageName); $perPage = $perPage ?: $this->related->getPerPage(); $results = $this->getEmbedded(); $results = $this->toCollection($results); - $total = $results->count(); - $start = ($page - 1) * $perPage; + $total = $results->count(); + $start = ($page - 1) * $perPage; $sliced = $results->slice( $start, - $perPage + $perPage, ); return new LengthAwarePaginator( @@ -305,21 +311,17 @@ public function paginate($perPage = null, $columns = ['*'], $pageName = 'page', $page, [ 'path' => Paginator::resolveCurrentPath(), - ] + ], ); } - /** - * @inheritdoc - */ + /** @inheritdoc */ protected function getEmbedded() { return parent::getEmbedded() ?: []; } - /** - * @inheritdoc - */ + /** @inheritdoc */ protected function setEmbedded($models) { if (! is_array($models)) { @@ -329,9 +331,7 @@ protected function setEmbedded($models) return parent::setEmbedded(array_values($models)); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function __call($method, $parameters) { if (method_exists(Collection::class, $method)) { @@ -344,11 +344,11 @@ public function __call($method, $parameters) /** * Get the name of the "where in" method for eager loading. * - * @param \Illuminate\Database\Eloquent\Model $model - * @param string $key + * @param string $key + * * @return string */ - protected function whereInMethod(EloquentModel $model, $key) + protected function whereInMethod(Model $model, $key) { return 'whereIn'; } diff --git a/src/Relations/EmbedsOne.php b/src/Relations/EmbedsOne.php index 6d82808d9..196415a55 100644 --- a/src/Relations/EmbedsOne.php +++ b/src/Relations/EmbedsOne.php @@ -1,9 +1,10 @@ getKeyName() == '_id' && ! $model->getKey()) { - $model->setAttribute('_id', new ObjectID); + if ($model->getKeyName() === '_id' && ! $model->getKey()) { + $model->setAttribute('_id', new ObjectID()); } // For deeply nested documents, let the parent handle the changes. @@ -63,7 +63,6 @@ public function performInsert(Model $model) /** * Save an existing model and attach it to the parent model. * - * @param Model $model * @return Model|bool */ public function performUpdate(Model $model) @@ -74,7 +73,7 @@ public function performUpdate(Model $model) return $this->parent->save(); } - $values = $this->getUpdateValues($model->getDirty(), $this->localKey.'.'); + $values = $this->getUpdateValues($model->getDirty(), $this->localKey . '.'); $result = $this->toBase()->update($values); @@ -114,7 +113,6 @@ public function performDelete() /** * Attach the model to its parent. * - * @param Model $model * @return Model */ public function associate(Model $model) @@ -145,11 +143,11 @@ public function delete() /** * Get the name of the "where in" method for eager loading. * - * @param \Illuminate\Database\Eloquent\Model $model - * @param string $key + * @param string $key + * * @return string */ - protected function whereInMethod(EloquentModel $model, $key) + protected function whereInMethod(Model $model, $key) { return 'whereIn'; } diff --git a/src/Relations/EmbedsOneOrMany.php b/src/Relations/EmbedsOneOrMany.php index 200cdf65e..46f4f1e72 100644 --- a/src/Relations/EmbedsOneOrMany.php +++ b/src/Relations/EmbedsOneOrMany.php @@ -1,5 +1,7 @@ query = $query; - $this->parent = $parent; - $this->related = $related; - $this->localKey = $localKey; + $this->query = $query; + $this->parent = $parent; + $this->related = $related; + $this->localKey = $localKey; $this->foreignKey = $foreignKey; - $this->relation = $relation; + $this->relation = $relation; // If this is a nested relation, we need to get the parent query instead. - if ($parentRelation = $this->getParentRelation()) { + $parentRelation = $this->getParentRelation(); + if ($parentRelation) { $this->query = $parentRelation->getQuery(); } $this->addConstraints(); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function addConstraints() { if (static::$constraints) { @@ -68,17 +66,13 @@ public function addConstraints() } } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function addEagerConstraints(array $models) { // There are no eager loading constraints. } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function match(array $models, Collection $results, $relation) { foreach ($models as $model) { @@ -95,7 +89,8 @@ public function match(array $models, Collection $results, $relation) /** * Shorthand to get the results of the relationship. * - * @param array $columns + * @param array $columns + * * @return Collection */ public function get($columns = ['*']) @@ -116,7 +111,6 @@ public function count() /** * Attach a model instance to the parent model. * - * @param Model $model * @return Model|bool */ public function save(Model $model) @@ -129,7 +123,8 @@ public function save(Model $model) /** * Attach a collection of models to the parent instance. * - * @param Collection|array $models + * @param Collection|array $models + * * @return Collection|array */ public function saveMany($models) @@ -144,7 +139,6 @@ public function saveMany($models) /** * Create a new instance of the related model. * - * @param array $attributes * @return Model */ public function create(array $attributes = []) @@ -164,7 +158,6 @@ public function create(array $attributes = []) /** * Create an array of new instances of the related model. * - * @param array $records * @return array */ public function createMany(array $records) @@ -181,7 +174,8 @@ public function createMany(array $records) /** * Transform single ID, single Model or array of Models into an array of IDs. * - * @param mixed $ids + * @param mixed $ids + * * @return array */ protected function getIdsArrayFrom($ids) @@ -203,27 +197,21 @@ protected function getIdsArrayFrom($ids) return $ids; } - /** - * @inheritdoc - */ + /** @inheritdoc */ protected function getEmbedded() { // Get raw attributes to skip relations and accessors. $attributes = $this->parent->getAttributes(); // Get embedded models form parent attributes. - $embedded = isset($attributes[$this->localKey]) ? (array) $attributes[$this->localKey] : null; - - return $embedded; + return isset($attributes[$this->localKey]) ? (array) $attributes[$this->localKey] : null; } - /** - * @inheritdoc - */ + /** @inheritdoc */ protected function setEmbedded($records) { // Assign models to parent attributes array. - $attributes = $this->parent->getAttributes(); + $attributes = $this->parent->getAttributes(); $attributes[$this->localKey] = $records; // Set raw attributes to skip mutators. @@ -236,7 +224,8 @@ protected function setEmbedded($records) /** * Get the foreign key value for the relation. * - * @param mixed $id + * @param mixed $id + * * @return mixed */ protected function getForeignKeyValue($id) @@ -252,7 +241,6 @@ protected function getForeignKeyValue($id) /** * Convert an array of records to a Collection. * - * @param array $records * @return Collection */ protected function toCollection(array $records = []) @@ -273,7 +261,8 @@ protected function toCollection(array $records = []) /** * Create a related model instanced. * - * @param array $attributes + * @param array $attributes + * * @return Model */ protected function toModel($attributes = []) @@ -286,7 +275,7 @@ protected function toModel($attributes = []) $model = $this->related->newFromBuilder( (array) $attributes, - $connection ? $connection->getName() : null + $connection ? $connection->getName() : null, ); $model->setParentRelation($this); @@ -309,9 +298,7 @@ protected function getParentRelation() return $this->parent->getParentRelation(); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function getQuery() { // Because we are sharing this relation instance to models, we need @@ -319,9 +306,7 @@ public function getQuery() return clone $this->query; } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function toBase() { // Because we are sharing this relation instance to models, we need @@ -336,31 +321,32 @@ public function toBase() */ protected function isNested() { - return $this->getParentRelation() != null; + return $this->getParentRelation() !== null; } /** * Get the fully qualified local key name. * - * @param string $glue + * @param string $glue + * * @return string */ protected function getPathHierarchy($glue = '.') { - if ($parentRelation = $this->getParentRelation()) { - return $parentRelation->getPathHierarchy($glue).$glue.$this->localKey; + $parentRelation = $this->getParentRelation(); + if ($parentRelation) { + return $parentRelation->getPathHierarchy($glue) . $glue . $this->localKey; } return $this->localKey; } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function getQualifiedParentKeyName() { - if ($parentRelation = $this->getParentRelation()) { - return $parentRelation->getPathHierarchy().'.'.$this->parent->getKeyName(); + $parentRelation = $this->getParentRelation(); + if ($parentRelation) { + return $parentRelation->getPathHierarchy() . '.' . $this->parent->getKeyName(); } return $this->parent->getKeyName(); @@ -379,8 +365,9 @@ protected function getParentKey() /** * Return update values. * - * @param $array - * @param string $prepend + * @param array $array + * @param string $prepend + * * @return array */ public static function getUpdateValues($array, $prepend = '') @@ -388,7 +375,7 @@ public static function getUpdateValues($array, $prepend = '') $results = []; foreach ($array as $key => $value) { - $results[$prepend.$key] = $value; + $results[$prepend . $key] = $value; } return $results; @@ -407,8 +394,9 @@ public function getQualifiedForeignKeyName() /** * Get the name of the "where in" method for eager loading. * - * @param \Illuminate\Database\Eloquent\Model $model - * @param string $key + * @param \Illuminate\Database\Eloquent\Model $model + * @param string $key + * * @return string */ protected function whereInMethod(EloquentModel $model, $key) diff --git a/src/Relations/HasMany.php b/src/Relations/HasMany.php index b2b4d6239..a38fba15a 100644 --- a/src/Relations/HasMany.php +++ b/src/Relations/HasMany.php @@ -1,9 +1,11 @@ getForeignKeyName(); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function getRelationExistenceQuery(Builder $query, Builder $parentQuery, $columns = ['*']) { $foreignKey = $this->getHasCompareKey(); @@ -41,11 +41,11 @@ public function getRelationExistenceQuery(Builder $query, Builder $parentQuery, /** * Get the name of the "where in" method for eager loading. * - * @param \Illuminate\Database\Eloquent\Model $model * @param string $key + * * @return string */ - protected function whereInMethod(EloquentModel $model, $key) + protected function whereInMethod(Model $model, $key) { return 'whereIn'; } diff --git a/src/Relations/HasOne.php b/src/Relations/HasOne.php index ca84e01e7..740a489d8 100644 --- a/src/Relations/HasOne.php +++ b/src/Relations/HasOne.php @@ -1,9 +1,11 @@ getForeignKeyName(); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function getRelationExistenceQuery(Builder $query, Builder $parentQuery, $columns = ['*']) { $foreignKey = $this->getForeignKeyName(); @@ -41,11 +41,11 @@ public function getRelationExistenceQuery(Builder $query, Builder $parentQuery, /** * Get the name of the "where in" method for eager loading. * - * @param \Illuminate\Database\Eloquent\Model $model * @param string $key + * * @return string */ - protected function whereInMethod(EloquentModel $model, $key) + protected function whereInMethod(Model $model, $key) { return 'whereIn'; } diff --git a/src/Relations/MorphMany.php b/src/Relations/MorphMany.php index 2bba05ecf..88f825dc0 100644 --- a/src/Relations/MorphMany.php +++ b/src/Relations/MorphMany.php @@ -1,8 +1,10 @@ createModelByType($type); @@ -47,11 +47,11 @@ public function getOwnerKey() /** * Get the name of the "where in" method for eager loading. * - * @param \Illuminate\Database\Eloquent\Model $model * @param string $key + * * @return string */ - protected function whereInMethod(EloquentModel $model, $key) + protected function whereInMethod(Model $model, $key) { return 'whereIn'; } diff --git a/src/Schema/Blueprint.php b/src/Schema/Blueprint.php index 1272b6136..2580c407f 100644 --- a/src/Schema/Blueprint.php +++ b/src/Schema/Blueprint.php @@ -1,8 +1,19 @@ connection = $connection; $this->collection = $this->connection->getCollection($collection); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function index($columns = null, $name = null, $algorithm = null, $options = []) { $columns = $this->fluent($columns); @@ -65,17 +74,13 @@ public function index($columns = null, $name = null, $algorithm = null, $options return $this; } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function primary($columns = null, $name = null, $algorithm = null, $options = []) { return $this->unique($columns, $name, $algorithm, $options); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function dropIndex($indexOrColumns = null) { $indexOrColumns = $this->transformColumns($indexOrColumns); @@ -88,7 +93,8 @@ public function dropIndex($indexOrColumns = null) /** * Indicate that the given index should be dropped, but do not fail if it didn't exist. * - * @param string|array $indexOrColumns + * @param string|array $indexOrColumns + * * @return Blueprint */ public function dropIndexIfExists($indexOrColumns = null) @@ -103,7 +109,8 @@ public function dropIndexIfExists($indexOrColumns = null) /** * Check whether the given index exists. * - * @param string|array $indexOrColumns + * @param string|array $indexOrColumns + * * @return bool */ public function hasIndex($indexOrColumns = null) @@ -114,7 +121,7 @@ public function hasIndex($indexOrColumns = null) return true; } - if (is_string($indexOrColumns) && $index->getName() == $indexOrColumns) { + if (is_string($indexOrColumns) && $index->getName() === $indexOrColumns) { return true; } } @@ -123,7 +130,8 @@ public function hasIndex($indexOrColumns = null) } /** - * @param string|array $indexOrColumns + * @param string|array $indexOrColumns + * * @return string */ protected function transformColumns($indexOrColumns) @@ -137,15 +145,15 @@ protected function transformColumns($indexOrColumns) foreach ($indexOrColumns as $key => $value) { if (is_int($key)) { // There is no sorting order, use the default. - $column = $value; + $column = $value; $sorting = '1'; } else { // This is a column with sorting order e.g 'my_column' => -1. - $column = $key; + $column = $key; $sorting = $value; } - $transform[$column] = $column.'_'.$sorting; + $transform[$column] = $column . '_' . $sorting; } $indexOrColumns = implode('_', $transform); @@ -154,9 +162,7 @@ protected function transformColumns($indexOrColumns) return $indexOrColumns; } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function unique($columns = null, $name = null, $algorithm = null, $options = []) { $columns = $this->fluent($columns); @@ -172,6 +178,7 @@ public function unique($columns = null, $name = null, $algorithm = null, $option * Specify a non blocking index for the collection. * * @param string|array $columns + * * @return Blueprint */ public function background($columns = null) @@ -187,7 +194,8 @@ public function background($columns = null) * Specify a sparse index for the collection. * * @param string|array $columns - * @param array $options + * @param array $options + * * @return Blueprint */ public function sparse($columns = null, $options = []) @@ -205,13 +213,14 @@ public function sparse($columns = null, $options = []) * Specify a geospatial index for the collection. * * @param string|array $columns - * @param string $index - * @param array $options + * @param string $index + * @param array $options + * * @return Blueprint */ public function geospatial($columns = null, $index = '2d', $options = []) { - if ($index == '2d' || $index == '2dsphere') { + if ($index === '2d' || $index === '2dsphere') { $columns = $this->fluent($columns); $columns = array_flip($columns); @@ -231,7 +240,8 @@ public function geospatial($columns = null, $index = '2d', $options = []) * on the given single-field index containing a date. * * @param string|array $columns - * @param int $seconds + * @param int $seconds + * * @return Blueprint */ public function expire($columns, $seconds) @@ -247,6 +257,7 @@ public function expire($columns, $seconds) * Indicate that the collection needs to be created. * * @param array $options + * * @return void */ public function create($options = []) @@ -259,17 +270,13 @@ public function create($options = []) $db->createCollection($collection, $options); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function drop() { $this->collection->drop(); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function addColumn($type, $name, array $parameters = []) { $this->fluent($name); @@ -281,8 +288,11 @@ public function addColumn($type, $name, array $parameters = []) * Specify a sparse and unique index for the collection. * * @param string|array $columns - * @param array $options + * @param array $options + * * @return Blueprint + * + * phpcs:disable PSR1.Methods.CamelCapsMethodName.NotCamelCaps */ public function sparse_and_unique($columns = null, $options = []) { @@ -300,24 +310,28 @@ public function sparse_and_unique($columns = null, $options = []) * Allow fluent columns. * * @param string|array $columns + * * @return string|array */ protected function fluent($columns = null) { if ($columns === null) { return $this->columns; - } elseif (is_string($columns)) { + } + + if (is_string($columns)) { return $this->columns = [$columns]; - } else { - return $this->columns = $columns; } + + return $this->columns = $columns; } /** * Allows the use of unsupported schema methods. * - * @param $method - * @param $args + * @param string $method + * @param array $args + * * @return Blueprint */ public function __call($method, $args) diff --git a/src/Schema/Builder.php b/src/Schema/Builder.php index be0b7f324..af311df6c 100644 --- a/src/Schema/Builder.php +++ b/src/Schema/Builder.php @@ -1,22 +1,25 @@ connection->getMongoDB(); $collections = iterator_to_array($db->listCollections([ - 'filter' => [ - 'name' => $name, - ], + 'filter' => ['name' => $name], ]), false); - return count($collections) ? true : false; + return count($collections) !== 0; } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function hasTable($collection) { return $this->hasCollection($collection); @@ -53,8 +53,8 @@ public function hasTable($collection) * Modify a collection on the schema. * * @param string $collection - * @param Closure $callback - * @return bool + * + * @return void */ public function collection($collection, Closure $callback) { @@ -65,18 +65,14 @@ public function collection($collection, Closure $callback) } } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function table($collection, Closure $callback) { - return $this->collection($collection, $callback); + $this->collection($collection, $callback); } - /** - * @inheritdoc - */ - public function create($collection, Closure $callback = null, array $options = []) + /** @inheritdoc */ + public function create($collection, ?Closure $callback = null, array $options = []) { $blueprint = $this->createBlueprint($collection); @@ -87,31 +83,23 @@ public function create($collection, Closure $callback = null, array $options = [ } } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function dropIfExists($collection) { if ($this->hasCollection($collection)) { - return $this->drop($collection); + $this->drop($collection); } - - return false; } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function drop($collection) { $blueprint = $this->createBlueprint($collection); - return $blueprint->drop(); + $blueprint->drop(); } - /** - * @inheritdoc - */ + /** @inheritdoc */ public function dropAllTables() { foreach ($this->getAllCollections() as $collection) { @@ -119,10 +107,8 @@ public function dropAllTables() } } - /** - * @inheritdoc - */ - protected function createBlueprint($collection, Closure $callback = null) + /** @inheritdoc */ + protected function createBlueprint($collection, ?Closure $callback = null) { return new Blueprint($this->connection, $collection); } @@ -131,16 +117,15 @@ protected function createBlueprint($collection, Closure $callback = null) * Get collection. * * @param string $name - * @return bool|\MongoDB\Model\CollectionInfo + * + * @return bool|CollectionInfo */ public function getCollection($name) { $db = $this->connection->getMongoDB(); $collections = iterator_to_array($db->listCollections([ - 'filter' => [ - 'name' => $name, - ], + 'filter' => ['name' => $name], ]), false); return count($collections) ? current($collections) : false; diff --git a/src/Schema/Grammar.php b/src/Schema/Grammar.php index 8124ae19c..3b86ec4a1 100644 --- a/src/Schema/Grammar.php +++ b/src/Schema/Grammar.php @@ -1,5 +1,7 @@ table($collection)->where($column, new Regex('^'.preg_quote($value).'$', '/i')); + $query = $this->table($collection)->where($column, new Regex('^' . preg_quote($value) . '$', '/i')); - if ($excludeId !== null && $excludeId != 'NULL') { + if ($excludeId !== null && $excludeId !== 'NULL') { $query->where($idColumn ?: 'id', '<>', $excludeId); } @@ -37,8 +43,9 @@ public function getCount($collection, $column, $value, $excludeId = null, $idCol * * @param string $collection * @param string $column - * @param array $values - * @param array $extra + * @param array $values + * @param array $extra + * * @return int */ public function getMultiCount($collection, $column, array $values, array $extra = []) @@ -49,7 +56,7 @@ public function getMultiCount($collection, $column, array $values, array $extra } // Generates a regex like '/^(a|b|c)$/i' which can query multiple values - $regex = new Regex('^('.implode('|', array_map(preg_quote(...), $values)).')$', 'i'); + $regex = new Regex('^(' . implode('|', array_map(preg_quote(...), $values)) . ')$', 'i'); $query = $this->table($collection)->where($column, 'regex', $regex); diff --git a/src/Validation/ValidationServiceProvider.php b/src/Validation/ValidationServiceProvider.php index 858929fd9..1095e93a3 100644 --- a/src/Validation/ValidationServiceProvider.php +++ b/src/Validation/ValidationServiceProvider.php @@ -1,5 +1,7 @@ truncate(); } @@ -50,8 +55,8 @@ function ($actualUser, $actualToken) use ($user, &$token) { $this->assertEquals($user->_id, $actualUser->_id); // Store token for later use $token = $actualToken; - } - ) + }, + ), ); $this->assertEquals(1, DB::collection('password_reset_tokens')->count()); diff --git a/tests/Casts/BinaryUuidTest.php b/tests/Casts/BinaryUuidTest.php index f6350c8d6..8a79b1500 100644 --- a/tests/Casts/BinaryUuidTest.php +++ b/tests/Casts/BinaryUuidTest.php @@ -1,13 +1,16 @@ [$uuid, $binaryUuid, $binaryUuid]; diff --git a/tests/Casts/ObjectIdTest.php b/tests/Casts/ObjectIdTest.php index fe532eae9..8d3e9daf4 100644 --- a/tests/Casts/ObjectIdTest.php +++ b/tests/Casts/ObjectIdTest.php @@ -1,5 +1,7 @@ [$objectId, $objectId]; @@ -39,7 +41,7 @@ public static function provideObjectIdCast(): Generator public function testQueryByStringDoesNotCast(): void { - $objectId = new ObjectId(); + $objectId = new ObjectId(); $stringObjectId = (string) $objectId; CastObjectId::create(['oid' => $objectId]); diff --git a/tests/CollectionTest.php b/tests/CollectionTest.php index f698b4df1..fbdbf3daf 100644 --- a/tests/CollectionTest.php +++ b/tests/CollectionTest.php @@ -13,9 +13,9 @@ class CollectionTest extends TestCase { public function testExecuteMethodCall() { - $return = ['foo' => 'bar']; - $where = ['id' => new ObjectID('56f94800911dcc276b5723dd')]; - $time = 1.1; + $return = ['foo' => 'bar']; + $where = ['id' => new ObjectID('56f94800911dcc276b5723dd')]; + $time = 1.1; $queryString = 'name-collection.findOne({"id":"56f94800911dcc276b5723dd"})'; $mongoCollection = $this->getMockBuilder(MongoCollection::class) diff --git a/tests/ConnectionTest.php b/tests/ConnectionTest.php index 77a2dce78..51a463c56 100644 --- a/tests/ConnectionTest.php +++ b/tests/ConnectionTest.php @@ -14,6 +14,8 @@ use MongoDB\Laravel\Query\Builder; use MongoDB\Laravel\Schema\Builder as SchemaBuilder; +use function spl_object_hash; + class ConnectionTest extends TestCase { public function testConnection() @@ -162,9 +164,7 @@ public function dataConnectionConfig(): Generator yield 'Database is extracted from DSN if not specified' => [ 'expectedUri' => 'mongodb://some-host:12345/tests', 'expectedDatabaseName' => 'tests', - 'config' => [ - 'dsn' => 'mongodb://some-host:12345/tests', - ], + 'config' => ['dsn' => 'mongodb://some-host:12345/tests'], ]; } @@ -172,7 +172,7 @@ public function dataConnectionConfig(): Generator public function testConnectionConfig(string $expectedUri, string $expectedDatabaseName, array $config): void { $connection = new Connection($config); - $client = $connection->getMongoClient(); + $client = $connection->getMongoClient(); $this->assertSame($expectedUri, (string) $client); $this->assertSame($expectedDatabaseName, $connection->getMongoDB()->getDatabaseName()); diff --git a/tests/Eloquent/MassPrunableTest.php b/tests/Eloquent/MassPrunableTest.php index 3426a2443..a93f864e5 100644 --- a/tests/Eloquent/MassPrunableTest.php +++ b/tests/Eloquent/MassPrunableTest.php @@ -11,6 +11,9 @@ use MongoDB\Laravel\Tests\Models\User; use MongoDB\Laravel\Tests\TestCase; +use function class_uses_recursive; +use function in_array; + class MassPrunableTest extends TestCase { public function tearDown(): void @@ -51,9 +54,7 @@ public function testPruneSoftDelete(): void $this->assertEquals(0, Soft::withTrashed()->count()); } - /** - * @see PruneCommand::isPrunable() - */ + /** @see PruneCommand::isPrunable() */ protected function isPrunable($model) { $uses = class_uses_recursive($model); diff --git a/tests/EmbeddedRelationsTest.php b/tests/EmbeddedRelationsTest.php index 231fec6dc..2dd558679 100644 --- a/tests/EmbeddedRelationsTest.php +++ b/tests/EmbeddedRelationsTest.php @@ -18,6 +18,8 @@ use MongoDB\Laravel\Tests\Models\Role; use MongoDB\Laravel\Tests\Models\User; +use function array_merge; + class EmbeddedRelationsTest extends TestCase { public function tearDown(): void @@ -35,21 +37,21 @@ public function tearDown(): void public function testEmbedsManySave() { - $user = User::create(['name' => 'John Doe']); + $user = User::create(['name' => 'John Doe']); $address = new Address(['city' => 'London']); $address->setEventDispatcher($events = Mockery::mock(Dispatcher::class)); - $events->shouldReceive('dispatch')->with('eloquent.retrieved: '.get_class($address), Mockery::any()); + $events->shouldReceive('dispatch')->with('eloquent.retrieved: ' . $address::class, Mockery::any()); $events->shouldReceive('until') ->once() - ->with('eloquent.saving: '.get_class($address), $address) + ->with('eloquent.saving: ' . $address::class, $address) ->andReturn(true); $events->shouldReceive('until') ->once() - ->with('eloquent.creating: '.get_class($address), $address) + ->with('eloquent.creating: ' . $address::class, $address) ->andReturn(true); - $events->shouldReceive('dispatch')->once()->with('eloquent.created: '.get_class($address), $address); - $events->shouldReceive('dispatch')->once()->with('eloquent.saved: '.get_class($address), $address); + $events->shouldReceive('dispatch')->once()->with('eloquent.created: ' . $address::class, $address); + $events->shouldReceive('dispatch')->once()->with('eloquent.saved: ' . $address::class, $address); $address = $user->addresses()->save($address); $address->unsetEventDispatcher(); @@ -71,17 +73,17 @@ public function testEmbedsManySave() $this->assertEquals(['London', 'Paris'], $user->addresses->pluck('city')->all()); $address->setEventDispatcher($events = Mockery::mock(Dispatcher::class)); - $events->shouldReceive('dispatch')->with('eloquent.retrieved: '.get_class($address), Mockery::any()); + $events->shouldReceive('dispatch')->with('eloquent.retrieved: ' . $address::class, Mockery::any()); $events->shouldReceive('until') ->once() - ->with('eloquent.saving: '.get_class($address), $address) + ->with('eloquent.saving: ' . $address::class, $address) ->andReturn(true); $events->shouldReceive('until') ->once() - ->with('eloquent.updating: '.get_class($address), $address) + ->with('eloquent.updating: ' . $address::class, $address) ->andReturn(true); - $events->shouldReceive('dispatch')->once()->with('eloquent.updated: '.get_class($address), $address); - $events->shouldReceive('dispatch')->once()->with('eloquent.saved: '.get_class($address), $address); + $events->shouldReceive('dispatch')->once()->with('eloquent.updated: ' . $address::class, $address); + $events->shouldReceive('dispatch')->once()->with('eloquent.saved: ' . $address::class, $address); $address->city = 'New York'; $user->addresses()->save($address); @@ -107,7 +109,7 @@ public function testEmbedsManySave() $user->addresses()->save(new Address(['city' => 'Bruxelles'])); $this->assertEquals(['London', 'New York', 'Bruxelles'], $user->addresses->pluck('city')->all()); - $address = $user->addresses[1]; + $address = $user->addresses[1]; $address->city = 'Manhattan'; $user->addresses()->save($address); $this->assertEquals(['London', 'Manhattan', 'Bruxelles'], $user->addresses->pluck('city')->all()); @@ -128,7 +130,7 @@ public function testEmbedsToArray() public function testEmbedsManyAssociate() { - $user = User::create(['name' => 'John Doe']); + $user = User::create(['name' => 'John Doe']); $address = new Address(['city' => 'London']); $user->addresses()->associate($address); @@ -158,7 +160,7 @@ public function testEmbedsManySaveMany() public function testEmbedsManyDuplicate() { - $user = User::create(['name' => 'John Doe']); + $user = User::create(['name' => 'John Doe']); $address = new Address(['city' => 'London']); $user->addresses()->save($address); $user->addresses()->save($address); @@ -180,7 +182,7 @@ public function testEmbedsManyDuplicate() public function testEmbedsManyCreate() { - $user = User::create([]); + $user = User::create([]); $address = $user->addresses()->create(['city' => 'Bruxelles']); $this->assertInstanceOf(Address::class, $address); $this->assertIsString($address->_id); @@ -192,7 +194,7 @@ public function testEmbedsManyCreate() $freshUser = User::find($user->id); $this->assertEquals(['Bruxelles'], $freshUser->addresses->pluck('city')->all()); - $user = User::create([]); + $user = User::create([]); $address = $user->addresses()->create(['_id' => '', 'city' => 'Bruxelles']); $this->assertIsString($address->_id); @@ -202,7 +204,7 @@ public function testEmbedsManyCreate() public function testEmbedsManyCreateMany() { - $user = User::create([]); + $user = User::create([]); [$bruxelles, $paris] = $user->addresses()->createMany([['city' => 'Bruxelles'], ['city' => 'Paris']]); $this->assertInstanceOf(Address::class, $bruxelles); $this->assertEquals('Bruxelles', $bruxelles->city); @@ -224,14 +226,14 @@ public function testEmbedsManyDestroy() $address = $user->addresses->first(); $address->setEventDispatcher($events = Mockery::mock(Dispatcher::class)); - $events->shouldReceive('dispatch')->with('eloquent.retrieved: '.get_class($address), Mockery::any()); + $events->shouldReceive('dispatch')->with('eloquent.retrieved: ' . $address::class, Mockery::any()); $events->shouldReceive('until') ->once() - ->with('eloquent.deleting: '.get_class($address), Mockery::type(Address::class)) + ->with('eloquent.deleting: ' . $address::class, Mockery::type(Address::class)) ->andReturn(true); $events->shouldReceive('dispatch') ->once() - ->with('eloquent.deleted: '.get_class($address), Mockery::type(Address::class)); + ->with('eloquent.deleted: ' . $address::class, Mockery::type(Address::class)); $user->addresses()->destroy($address->_id); $this->assertEquals(['Bristol', 'Bruxelles'], $user->addresses->pluck('city')->all()); @@ -276,14 +278,14 @@ public function testEmbedsManyDelete() $address = $user->addresses->first(); $address->setEventDispatcher($events = Mockery::mock(Dispatcher::class)); - $events->shouldReceive('dispatch')->with('eloquent.retrieved: '.get_class($address), Mockery::any()); + $events->shouldReceive('dispatch')->with('eloquent.retrieved: ' . $address::class, Mockery::any()); $events->shouldReceive('until') ->once() - ->with('eloquent.deleting: '.get_class($address), Mockery::type(Address::class)) + ->with('eloquent.deleting: ' . $address::class, Mockery::type(Address::class)) ->andReturn(true); $events->shouldReceive('dispatch') ->once() - ->with('eloquent.deleted: '.get_class($address), Mockery::type(Address::class)); + ->with('eloquent.deleted: ' . $address::class, Mockery::type(Address::class)); $address->delete(); @@ -302,7 +304,7 @@ public function testEmbedsManyDelete() public function testEmbedsManyDissociate() { - $user = User::create([]); + $user = User::create([]); $cordoba = $user->addresses()->create(['city' => 'Cordoba']); $user->addresses()->dissociate($cordoba->id); @@ -311,25 +313,25 @@ public function testEmbedsManyDissociate() $this->assertEquals(0, $user->addresses->count()); $this->assertEquals(1, $freshUser->addresses->count()); - $broken_address = Address::make(['name' => 'Broken']); + $brokenAddress = Address::make(['name' => 'Broken']); $user->update([ 'addresses' => array_merge( - [$broken_address->toArray()], - $user->addresses()->toArray() + [$brokenAddress->toArray()], + $user->addresses()->toArray(), ), ]); $curitiba = $user->addresses()->create(['city' => 'Curitiba']); $user->addresses()->dissociate($curitiba->id); - $this->assertEquals(1, $user->addresses->where('name', $broken_address->name)->count()); + $this->assertEquals(1, $user->addresses->where('name', $brokenAddress->name)->count()); $this->assertEquals(1, $user->addresses->count()); } public function testEmbedsManyAliases() { - $user = User::create(['name' => 'John Doe']); + $user = User::create(['name' => 'John Doe']); $address = new Address(['city' => 'London']); $address = $user->addresses()->attach($address); @@ -341,18 +343,18 @@ public function testEmbedsManyAliases() public function testEmbedsManyCreatingEventReturnsFalse() { - $user = User::create(['name' => 'John Doe']); + $user = User::create(['name' => 'John Doe']); $address = new Address(['city' => 'London']); $address->setEventDispatcher($events = Mockery::mock(Dispatcher::class)); - $events->shouldReceive('dispatch')->with('eloquent.retrieved: '.get_class($address), Mockery::any()); + $events->shouldReceive('dispatch')->with('eloquent.retrieved: ' . $address::class, Mockery::any()); $events->shouldReceive('until') ->once() - ->with('eloquent.saving: '.get_class($address), $address) + ->with('eloquent.saving: ' . $address::class, $address) ->andReturn(true); $events->shouldReceive('until') ->once() - ->with('eloquent.creating: '.get_class($address), $address) + ->with('eloquent.creating: ' . $address::class, $address) ->andReturn(false); $this->assertFalse($user->addresses()->save($address)); @@ -361,15 +363,15 @@ public function testEmbedsManyCreatingEventReturnsFalse() public function testEmbedsManySavingEventReturnsFalse() { - $user = User::create(['name' => 'John Doe']); - $address = new Address(['city' => 'Paris']); + $user = User::create(['name' => 'John Doe']); + $address = new Address(['city' => 'Paris']); $address->exists = true; $address->setEventDispatcher($events = Mockery::mock(Dispatcher::class)); - $events->shouldReceive('dispatch')->with('eloquent.retrieved: '.get_class($address), Mockery::any()); + $events->shouldReceive('dispatch')->with('eloquent.retrieved: ' . $address::class, Mockery::any()); $events->shouldReceive('until') ->once() - ->with('eloquent.saving: '.get_class($address), $address) + ->with('eloquent.saving: ' . $address::class, $address) ->andReturn(false); $this->assertFalse($user->addresses()->save($address)); @@ -378,19 +380,19 @@ public function testEmbedsManySavingEventReturnsFalse() public function testEmbedsManyUpdatingEventReturnsFalse() { - $user = User::create(['name' => 'John Doe']); + $user = User::create(['name' => 'John Doe']); $address = new Address(['city' => 'New York']); $user->addresses()->save($address); $address->setEventDispatcher($events = Mockery::mock(Dispatcher::class)); - $events->shouldReceive('dispatch')->with('eloquent.retrieved: '.get_class($address), Mockery::any()); + $events->shouldReceive('dispatch')->with('eloquent.retrieved: ' . $address::class, Mockery::any()); $events->shouldReceive('until') ->once() - ->with('eloquent.saving: '.get_class($address), $address) + ->with('eloquent.saving: ' . $address::class, $address) ->andReturn(true); $events->shouldReceive('until') ->once() - ->with('eloquent.updating: '.get_class($address), $address) + ->with('eloquent.updating: ' . $address::class, $address) ->andReturn(false); $address->city = 'Warsaw'; @@ -407,10 +409,10 @@ public function testEmbedsManyDeletingEventReturnsFalse() $address = $user->addresses->first(); $address->setEventDispatcher($events = Mockery::mock(Dispatcher::class)); - $events->shouldReceive('dispatch')->with('eloquent.retrieved: '.get_class($address), Mockery::any()); + $events->shouldReceive('dispatch')->with('eloquent.retrieved: ' . $address::class, Mockery::any()); $events->shouldReceive('until') ->once() - ->with('eloquent.deleting: '.get_class($address), Mockery::mustBe($address)) + ->with('eloquent.deleting: ' . $address::class, Mockery::mustBe($address)) ->andReturn(false); $this->assertEquals(0, $user->addresses()->destroy($address)); @@ -421,7 +423,7 @@ public function testEmbedsManyDeletingEventReturnsFalse() public function testEmbedsManyFindOrContains() { - $user = User::create(['name' => 'John Doe']); + $user = User::create(['name' => 'John Doe']); $address1 = $user->addresses()->save(new Address(['city' => 'New York'])); $address2 = $user->addresses()->save(new Address(['city' => 'Paris'])); @@ -445,13 +447,13 @@ public function testEmbedsManyEagerLoading() $user2->addresses()->save(new Address(['city' => 'Berlin'])); $user2->addresses()->save(new Address(['city' => 'Paris'])); - $user = User::find($user1->id); + $user = User::find($user1->id); $relations = $user->getRelations(); $this->assertArrayNotHasKey('addresses', $relations); $this->assertArrayHasKey('addresses', $user->toArray()); $this->assertIsArray($user->toArray()['addresses']); - $user = User::with('addresses')->get()->first(); + $user = User::with('addresses')->get()->first(); $relations = $user->getRelations(); $this->assertArrayHasKey('addresses', $relations); $this->assertEquals(2, $relations['addresses']->count()); @@ -540,21 +542,21 @@ public function testEmbedsManyCollectionMethods() public function testEmbedsOne() { - $user = User::create(['name' => 'John Doe']); + $user = User::create(['name' => 'John Doe']); $father = new User(['name' => 'Mark Doe']); $father->setEventDispatcher($events = Mockery::mock(Dispatcher::class)); - $events->shouldReceive('dispatch')->with('eloquent.retrieved: '.get_class($father), Mockery::any()); + $events->shouldReceive('dispatch')->with('eloquent.retrieved: ' . $father::class, Mockery::any()); $events->shouldReceive('until') ->once() - ->with('eloquent.saving: '.get_class($father), $father) + ->with('eloquent.saving: ' . $father::class, $father) ->andReturn(true); $events->shouldReceive('until') ->once() - ->with('eloquent.creating: '.get_class($father), $father) + ->with('eloquent.creating: ' . $father::class, $father) ->andReturn(true); - $events->shouldReceive('dispatch')->once()->with('eloquent.created: '.get_class($father), $father); - $events->shouldReceive('dispatch')->once()->with('eloquent.saved: '.get_class($father), $father); + $events->shouldReceive('dispatch')->once()->with('eloquent.created: ' . $father::class, $father); + $events->shouldReceive('dispatch')->once()->with('eloquent.saved: ' . $father::class, $father); $father = $user->father()->save($father); $father->unsetEventDispatcher(); @@ -570,17 +572,17 @@ public function testEmbedsOne() $this->assertInstanceOf(ObjectId::class, $raw['_id']); $father->setEventDispatcher($events = Mockery::mock(Dispatcher::class)); - $events->shouldReceive('dispatch')->with('eloquent.retrieved: '.get_class($father), Mockery::any()); + $events->shouldReceive('dispatch')->with('eloquent.retrieved: ' . $father::class, Mockery::any()); $events->shouldReceive('until') ->once() - ->with('eloquent.saving: '.get_class($father), $father) + ->with('eloquent.saving: ' . $father::class, $father) ->andReturn(true); $events->shouldReceive('until') ->once() - ->with('eloquent.updating: '.get_class($father), $father) + ->with('eloquent.updating: ' . $father::class, $father) ->andReturn(true); - $events->shouldReceive('dispatch')->once()->with('eloquent.updated: '.get_class($father), $father); - $events->shouldReceive('dispatch')->once()->with('eloquent.saved: '.get_class($father), $father); + $events->shouldReceive('dispatch')->once()->with('eloquent.updated: ' . $father::class, $father); + $events->shouldReceive('dispatch')->once()->with('eloquent.saved: ' . $father::class, $father); $father->name = 'Tom Doe'; $user->father()->save($father); @@ -592,17 +594,17 @@ public function testEmbedsOne() $father = new User(['name' => 'Jim Doe']); $father->setEventDispatcher($events = Mockery::mock(Dispatcher::class)); - $events->shouldReceive('dispatch')->with('eloquent.retrieved: '.get_class($father), Mockery::any()); + $events->shouldReceive('dispatch')->with('eloquent.retrieved: ' . $father::class, Mockery::any()); $events->shouldReceive('until') ->once() - ->with('eloquent.saving: '.get_class($father), $father) + ->with('eloquent.saving: ' . $father::class, $father) ->andReturn(true); $events->shouldReceive('until') ->once() - ->with('eloquent.creating: '.get_class($father), $father) + ->with('eloquent.creating: ' . $father::class, $father) ->andReturn(true); - $events->shouldReceive('dispatch')->once()->with('eloquent.created: '.get_class($father), $father); - $events->shouldReceive('dispatch')->once()->with('eloquent.saved: '.get_class($father), $father); + $events->shouldReceive('dispatch')->once()->with('eloquent.created: ' . $father::class, $father); + $events->shouldReceive('dispatch')->once()->with('eloquent.saved: ' . $father::class, $father); $father = $user->father()->save($father); $father->unsetEventDispatcher(); @@ -613,12 +615,12 @@ public function testEmbedsOne() public function testEmbedsOneAssociate() { - $user = User::create(['name' => 'John Doe']); + $user = User::create(['name' => 'John Doe']); $father = new User(['name' => 'Mark Doe']); $father->setEventDispatcher($events = Mockery::mock(Dispatcher::class)); - $events->shouldReceive('dispatch')->with('eloquent.retrieved: '.get_class($father), Mockery::any()); - $events->shouldReceive('until')->times(0)->with('eloquent.saving: '.get_class($father), $father); + $events->shouldReceive('dispatch')->with('eloquent.retrieved: ' . $father::class, Mockery::any()); + $events->shouldReceive('until')->times(0)->with('eloquent.saving: ' . $father::class, $father); $father = $user->father()->associate($father); $father->unsetEventDispatcher(); @@ -635,7 +637,7 @@ public function testEmbedsOneNullAssociation() public function testEmbedsOneDelete() { - $user = User::create(['name' => 'John Doe']); + $user = User::create(['name' => 'John Doe']); $father = $user->father()->save(new User(['name' => 'Mark Doe'])); $user->father()->delete(); @@ -644,7 +646,7 @@ public function testEmbedsOneDelete() public function testEmbedsOneRefresh() { - $user = User::create(['name' => 'John Doe']); + $user = User::create(['name' => 'John Doe']); $father = new User(['name' => 'Mark Doe']); $user->father()->associate($father); @@ -658,7 +660,7 @@ public function testEmbedsOneRefresh() public function testEmbedsOneEmptyRefresh() { - $user = User::create(['name' => 'John Doe']); + $user = User::create(['name' => 'John Doe']); $father = new User(['name' => 'Mark Doe']); $user->father()->associate($father); @@ -674,8 +676,8 @@ public function testEmbedsOneEmptyRefresh() public function testEmbedsManyToArray() { - /** @var User $user */ $user = User::create(['name' => 'John Doe']); + $this->assertInstanceOf(User::class, $user); $user->addresses()->save(new Address(['city' => 'New York'])); $user->addresses()->save(new Address(['city' => 'Paris'])); $user->addresses()->save(new Address(['city' => 'Brussels'])); @@ -687,8 +689,8 @@ public function testEmbedsManyToArray() public function testEmbedsManyRefresh() { - /** @var User $user */ $user = User::create(['name' => 'John Doe']); + $this->assertInstanceOf(User::class, $user); $user->addresses()->save(new Address(['city' => 'New York'])); $user->addresses()->save(new Address(['city' => 'Paris'])); $user->addresses()->save(new Address(['city' => 'Brussels'])); @@ -703,10 +705,10 @@ public function testEmbedsManyRefresh() public function testEmbeddedSave() { - /** @var User $user */ $user = User::create(['name' => 'John Doe']); - /** @var Address $address */ + $this->assertInstanceOf(User::class, $user); $address = $user->addresses()->create(['city' => 'New York']); + $this->assertInstanceOf(Address::class, $address); $father = $user->father()->create(['name' => 'Mark Doe']); $address->city = 'Paris'; @@ -723,7 +725,7 @@ public function testEmbeddedSave() $this->assertEquals('Steve Doe', $user->father->name); $address = $user->addresses()->first(); - $father = $user->father; + $father = $user->father; $address->city = 'Ghent'; $address->save(); @@ -741,9 +743,9 @@ public function testEmbeddedSave() public function testNestedEmbedsOne() { - $user = User::create(['name' => 'John Doe']); - $father = $user->father()->create(['name' => 'Mark Doe']); - $grandfather = $father->father()->create(['name' => 'Steve Doe']); + $user = User::create(['name' => 'John Doe']); + $father = $user->father()->create(['name' => 'Mark Doe']); + $grandfather = $father->father()->create(['name' => 'Steve Doe']); $greatgrandfather = $grandfather->father()->create(['name' => 'Tom Doe']); $user->name = 'Tim Doe'; @@ -769,12 +771,12 @@ public function testNestedEmbedsOne() public function testNestedEmbedsMany() { - $user = User::create(['name' => 'John Doe']); + $user = User::create(['name' => 'John Doe']); $country1 = $user->addresses()->create(['country' => 'France']); $country2 = $user->addresses()->create(['country' => 'Belgium']); - $city1 = $country1->addresses()->create(['city' => 'Paris']); - $city2 = $country2->addresses()->create(['city' => 'Ghent']); - $city3 = $country2->addresses()->create(['city' => 'Brussels']); + $city1 = $country1->addresses()->create(['city' => 'Paris']); + $city2 = $country2->addresses()->create(['city' => 'Ghent']); + $city3 = $country2->addresses()->create(['city' => 'Brussels']); $city3->city = 'Bruges'; $city3->save(); @@ -791,8 +793,8 @@ public function testNestedEmbedsMany() public function testNestedMixedEmbeds() { - $user = User::create(['name' => 'John Doe']); - $father = $user->father()->create(['name' => 'Mark Doe']); + $user = User::create(['name' => 'John Doe']); + $father = $user->father()->create(['name' => 'Mark Doe']); $country1 = $father->addresses()->create(['country' => 'France']); $country2 = $father->addresses()->create(['country' => 'Belgium']); @@ -814,9 +816,9 @@ public function testNestedMixedEmbeds() public function testNestedEmbedsOneDelete() { - $user = User::create(['name' => 'John Doe']); - $father = $user->father()->create(['name' => 'Mark Doe']); - $grandfather = $father->father()->create(['name' => 'Steve Doe']); + $user = User::create(['name' => 'John Doe']); + $father = $user->father()->create(['name' => 'Mark Doe']); + $grandfather = $father->father()->create(['name' => 'Steve Doe']); $greatgrandfather = $grandfather->father()->create(['name' => 'Tom Doe']); $grandfather->delete(); @@ -829,11 +831,11 @@ public function testNestedEmbedsOneDelete() public function testNestedEmbedsManyDelete() { - $user = User::create(['name' => 'John Doe']); + $user = User::create(['name' => 'John Doe']); $country = $user->addresses()->create(['country' => 'France']); - $city1 = $country->addresses()->create(['city' => 'Paris']); - $city2 = $country->addresses()->create(['city' => 'Nice']); - $city3 = $country->addresses()->create(['city' => 'Lyon']); + $city1 = $country->addresses()->create(['city' => 'Paris']); + $city2 = $country->addresses()->create(['city' => 'Nice']); + $city3 = $country->addresses()->create(['city' => 'Lyon']); $city2->delete(); @@ -847,8 +849,8 @@ public function testNestedEmbedsManyDelete() public function testNestedMixedEmbedsDelete() { - $user = User::create(['name' => 'John Doe']); - $father = $user->father()->create(['name' => 'Mark Doe']); + $user = User::create(['name' => 'John Doe']); + $father = $user->father()->create(['name' => 'Mark Doe']); $country1 = $father->addresses()->create(['country' => 'France']); $country2 = $father->addresses()->create(['country' => 'Belgium']); @@ -864,7 +866,7 @@ public function testNestedMixedEmbedsDelete() public function testDoubleAssociate() { - $user = User::create(['name' => 'John Doe']); + $user = User::create(['name' => 'John Doe']); $address = new Address(['city' => 'Paris']); $user->addresses()->associate($address); @@ -885,14 +887,14 @@ public function testDoubleAssociate() public function testSaveEmptyModel() { $user = User::create(['name' => 'John Doe']); - $user->addresses()->save(new Address); + $user->addresses()->save(new Address()); $this->assertNotNull($user->addresses); $this->assertEquals(1, $user->addresses()->count()); } public function testIncrementEmbedded() { - $user = User::create(['name' => 'John Doe']); + $user = User::create(['name' => 'John Doe']); $address = $user->addresses()->create(['city' => 'New York', 'visited' => 5]); $address->increment('visited'); @@ -902,7 +904,7 @@ public function testIncrementEmbedded() $user = User::where('name', 'John Doe')->first(); $this->assertEquals(6, $user->addresses()->first()->visited); - $user = User::where('name', 'John Doe')->first(); + $user = User::where('name', 'John Doe')->first(); $address = $user->addresses()->first(); $address->decrement('visited'); diff --git a/tests/HybridRelationsTest.php b/tests/HybridRelationsTest.php index 35514fe0d..5dc6b307b 100644 --- a/tests/HybridRelationsTest.php +++ b/tests/HybridRelationsTest.php @@ -4,7 +4,6 @@ namespace MongoDB\Laravel\Tests; -use Illuminate\Database\Connection; use Illuminate\Database\MySqlConnection; use Illuminate\Support\Facades\DB; use MongoDB\Laravel\Tests\Models\Book; @@ -21,7 +20,6 @@ public function setUp(): void { parent::setUp(); - /** @var Connection */ try { DB::connection('mysql')->select('SELECT 1'); } catch (PDOException) { @@ -42,7 +40,7 @@ public function tearDown(): void public function testMysqlRelations() { - $user = new MysqlUser; + $user = new MysqlUser(); $this->assertInstanceOf(MysqlUser::class, $user); $this->assertInstanceOf(MySqlConnection::class, $user->getConnection()); @@ -72,7 +70,7 @@ public function testMysqlRelations() $this->assertEquals('John Doe', $role->mysqlUser->name); // MongoDB User - $user = new User; + $user = new User(); $user->name = 'John Doe'; $user->save(); @@ -99,8 +97,8 @@ public function testMysqlRelations() public function testHybridWhereHas() { - $user = new MysqlUser; - $otherUser = new MysqlUser; + $user = new MysqlUser(); + $otherUser = new MysqlUser(); $this->assertInstanceOf(MysqlUser::class, $user); $this->assertInstanceOf(MySqlConnection::class, $user->getConnection()); $this->assertInstanceOf(MysqlUser::class, $otherUser); @@ -108,11 +106,11 @@ public function testHybridWhereHas() //MySql User $user->name = 'John Doe'; - $user->id = 2; + $user->id = 2; $user->save(); // Other user $otherUser->name = 'Other User'; - $otherUser->id = 3; + $otherUser->id = 3; $otherUser->save(); // Make sure they are created $this->assertIsInt($user->id); @@ -153,8 +151,8 @@ public function testHybridWhereHas() public function testHybridWith() { - $user = new MysqlUser; - $otherUser = new MysqlUser; + $user = new MysqlUser(); + $otherUser = new MysqlUser(); $this->assertInstanceOf(MysqlUser::class, $user); $this->assertInstanceOf(MySqlConnection::class, $user->getConnection()); $this->assertInstanceOf(MysqlUser::class, $otherUser); @@ -162,11 +160,11 @@ public function testHybridWith() //MySql User $user->name = 'John Doe'; - $user->id = 2; + $user->id = 2; $user->save(); // Other user $otherUser->name = 'Other User'; - $otherUser->id = 3; + $otherUser->id = 3; $otherUser->save(); // Make sure they are created $this->assertIsInt($user->id); diff --git a/tests/ModelTest.php b/tests/ModelTest.php index d592228ec..44e24b699 100644 --- a/tests/ModelTest.php +++ b/tests/ModelTest.php @@ -6,6 +6,7 @@ use Carbon\Carbon; use DateTime; +use Generator; use Illuminate\Database\Eloquent\Collection as EloquentCollection; use Illuminate\Database\Eloquent\ModelNotFoundException; use Illuminate\Support\Facades\Date; @@ -26,6 +27,16 @@ use MongoDB\Laravel\Tests\Models\Soft; use MongoDB\Laravel\Tests\Models\User; +use function abs; +use function array_keys; +use function array_merge; +use function get_debug_type; +use function hex2bin; +use function sleep; +use function sort; +use function strlen; +use function time; + class ModelTest extends TestCase { public function tearDown(): void @@ -39,7 +50,7 @@ public function tearDown(): void public function testNewModel(): void { - $user = new User; + $user = new User(); $this->assertInstanceOf(Model::class, $user); $this->assertInstanceOf(Connection::class, $user->getConnection()); $this->assertFalse($user->exists); @@ -49,10 +60,10 @@ public function testNewModel(): void public function testInsert(): void { - $user = new User; - $user->name = 'John Doe'; + $user = new User(); + $user->name = 'John Doe'; $user->title = 'admin'; - $user->age = 35; + $user->age = 35; $user->save(); @@ -74,17 +85,17 @@ public function testInsert(): void public function testUpdate(): void { - $user = new User; - $user->name = 'John Doe'; + $user = new User(); + $user->name = 'John Doe'; $user->title = 'admin'; - $user->age = 35; + $user->age = 35; $user->save(); $raw = $user->getAttributes(); $this->assertInstanceOf(ObjectID::class, $raw['_id']); - /** @var User $check */ $check = User::find($user->_id); + $this->assertInstanceOf(User::class, $check); $check->age = 36; $check->save(); @@ -107,11 +118,11 @@ public function testUpdate(): void public function testManualStringId(): void { - $user = new User; - $user->_id = '4af9f23d8ead0e1d32000000'; - $user->name = 'John Doe'; + $user = new User(); + $user->_id = '4af9f23d8ead0e1d32000000'; + $user->name = 'John Doe'; $user->title = 'admin'; - $user->age = 35; + $user->age = 35; $user->save(); $this->assertTrue($user->exists); @@ -120,11 +131,11 @@ public function testManualStringId(): void $raw = $user->getAttributes(); $this->assertInstanceOf(ObjectID::class, $raw['_id']); - $user = new User; - $user->_id = 'customId'; - $user->name = 'John Doe'; + $user = new User(); + $user->_id = 'customId'; + $user->name = 'John Doe'; $user->title = 'admin'; - $user->age = 35; + $user->age = 35; $user->save(); $this->assertTrue($user->exists); @@ -136,11 +147,11 @@ public function testManualStringId(): void public function testManualIntId(): void { - $user = new User; - $user->_id = 1; - $user->name = 'John Doe'; + $user = new User(); + $user->_id = 1; + $user->name = 'John Doe'; $user->title = 'admin'; - $user->age = 35; + $user->age = 35; $user->save(); $this->assertTrue($user->exists); @@ -152,10 +163,10 @@ public function testManualIntId(): void public function testDelete(): void { - $user = new User; - $user->name = 'John Doe'; + $user = new User(); + $user->name = 'John Doe'; $user->title = 'admin'; - $user->age = 35; + $user->age = 35; $user->save(); $this->assertTrue($user->exists); @@ -168,16 +179,16 @@ public function testDelete(): void public function testAll(): void { - $user = new User; - $user->name = 'John Doe'; + $user = new User(); + $user->name = 'John Doe'; $user->title = 'admin'; - $user->age = 35; + $user->age = 35; $user->save(); - $user = new User; - $user->name = 'Jane Doe'; + $user = new User(); + $user->name = 'Jane Doe'; $user->title = 'user'; - $user->age = 32; + $user->age = 32; $user->save(); $all = User::all(); @@ -189,14 +200,14 @@ public function testAll(): void public function testFind(): void { - $user = new User; - $user->name = 'John Doe'; + $user = new User(); + $user->name = 'John Doe'; $user->title = 'admin'; - $user->age = 35; + $user->age = 35; $user->save(); - /** @var User $check */ $check = User::find($user->_id); + $this->assertInstanceOf(User::class, $check); $this->assertInstanceOf(Model::class, $check); $this->assertTrue($check->exists); @@ -226,8 +237,8 @@ public function testFirst(): void ['name' => 'Jane Doe'], ]); - /** @var User $user */ $user = User::first(); + $this->assertInstanceOf(User::class, $user); $this->assertInstanceOf(Model::class, $user); $this->assertEquals('John Doe', $user->name); } @@ -253,24 +264,24 @@ public function testFindOrFail(): void public function testCreate(): void { - /** @var User $user */ $user = User::create(['name' => 'Jane Poe']); + $this->assertInstanceOf(User::class, $user); $this->assertInstanceOf(Model::class, $user); $this->assertTrue($user->exists); $this->assertEquals('Jane Poe', $user->name); - /** @var User $check */ $check = User::where('name', 'Jane Poe')->first(); + $this->assertInstanceOf(User::class, $check); $this->assertEquals($user->_id, $check->_id); } public function testDestroy(): void { - $user = new User; - $user->name = 'John Doe'; + $user = new User(); + $user->name = 'John Doe'; $user->title = 'admin'; - $user->age = 35; + $user->age = 35; $user->save(); User::destroy((string) $user->_id); @@ -280,18 +291,18 @@ public function testDestroy(): void public function testTouch(): void { - $user = new User; - $user->name = 'John Doe'; + $user = new User(); + $user->name = 'John Doe'; $user->title = 'admin'; - $user->age = 35; + $user->age = 35; $user->save(); $old = $user->updated_at; sleep(1); $user->touch(); - /** @var User $check */ $check = User::find($user->_id); + $this->assertInstanceOf(User::class, $check); $this->assertNotEquals($old, $check->updated_at); } @@ -303,40 +314,38 @@ public function testSoftDelete(): void $this->assertEquals(2, Soft::count()); - /** @var Soft $user */ - $user = Soft::where('name', 'John Doe')->first(); - $this->assertTrue($user->exists); - $this->assertFalse($user->trashed()); - $this->assertNull($user->deleted_at); + $object = Soft::where('name', 'John Doe')->first(); + $this->assertInstanceOf(Soft::class, $object); + $this->assertTrue($object->exists); + $this->assertFalse($object->trashed()); + $this->assertNull($object->deleted_at); - $user->delete(); - $this->assertTrue($user->trashed()); - $this->assertNotNull($user->deleted_at); + $object->delete(); + $this->assertTrue($object->trashed()); + $this->assertNotNull($object->deleted_at); - $user = Soft::where('name', 'John Doe')->first(); - $this->assertNull($user); + $object = Soft::where('name', 'John Doe')->first(); + $this->assertNull($object); $this->assertEquals(1, Soft::count()); $this->assertEquals(2, Soft::withTrashed()->count()); - $user = Soft::withTrashed()->where('name', 'John Doe')->first(); - $this->assertNotNull($user); - $this->assertInstanceOf(Carbon::class, $user->deleted_at); - $this->assertTrue($user->trashed()); + $object = Soft::withTrashed()->where('name', 'John Doe')->first(); + $this->assertNotNull($object); + $this->assertInstanceOf(Carbon::class, $object->deleted_at); + $this->assertTrue($object->trashed()); - $user->restore(); + $object->restore(); $this->assertEquals(2, Soft::count()); } - /** - * @dataProvider provideId - */ + /** @dataProvider provideId */ public function testPrimaryKey(string $model, $id, $expected, bool $expectedFound): void { $model::truncate(); $expectedType = get_debug_type($expected); - $document = new $model; + $document = new $model(); $this->assertEquals('_id', $document->getKeyName()); $document->_id = $id; @@ -425,17 +434,17 @@ public static function provideId(): iterable public function testCustomPrimaryKey(): void { - $book = new Book; + $book = new Book(); $this->assertEquals('title', $book->getKeyName()); - $book->title = 'A Game of Thrones'; + $book->title = 'A Game of Thrones'; $book->author = 'George R. R. Martin'; $book->save(); $this->assertEquals('A Game of Thrones', $book->getKey()); - /** @var Book $check */ $check = Book::find('A Game of Thrones'); + $this->assertInstanceOf(Book::class, $check); $this->assertEquals('title', $check->getKeyName()); $this->assertEquals('A Game of Thrones', $check->getKey()); $this->assertEquals('A Game of Thrones', $check->title); @@ -457,7 +466,7 @@ public function testToArray(): void $item = Item::create(['name' => 'fork', 'type' => 'sharp']); $array = $item->toArray(); - $keys = array_keys($array); + $keys = array_keys($array); sort($keys); $this->assertEquals(['_id', 'created_at', 'name', 'type', 'updated_at'], $keys); $this->assertIsString($array['created_at']); @@ -651,14 +660,13 @@ public function testDates(): void ->getTimestamp(), $item->created_at->getTimestamp()); $this->assertLessThan(2, abs(time() - $item->created_at->getTimestamp())); - // test default date format for json output - /** @var Item $item */ $item = Item::create(['name' => 'sword']); + $this->assertInstanceOf(Item::class, $item); $json = $item->toArray(); $this->assertEquals($item->created_at->toISOString(), $json['created_at']); } - public static function provideDate(): \Generator + public static function provideDate(): Generator { yield 'int timestamp' => [time()]; yield 'Carbon date' => [Date::now()]; @@ -674,14 +682,12 @@ public static function provideDate(): \Generator yield 'DateTime date, time and ms before unix epoch' => [new DateTime('1965-08-08 04.08.37.324')]; } - /** - * @dataProvider provideDate - */ + /** @dataProvider provideDate */ public function testDateInputs($date): void { - /** @var User $user */ // Test with create and standard property $user = User::create(['name' => 'Jane Doe', 'birthday' => $date]); + $this->assertInstanceOf(User::class, $user); $this->assertInstanceOf(Carbon::class, $user->birthday); //Test with setAttribute and standard property @@ -747,8 +753,8 @@ public function testCarbonDateMockingWorks() public function testIdAttribute(): void { - /** @var User $user */ $user = User::create(['name' => 'John Doe']); + $this->assertInstanceOf(User::class, $user); $this->assertEquals($user->id, $user->_id); $user = User::create(['id' => 'custom_id', 'name' => 'John Doe']); @@ -757,8 +763,8 @@ public function testIdAttribute(): void public function testPushPull(): void { - /** @var User $user */ $user = User::create(['name' => 'John Doe']); + $this->assertInstanceOf(User::class, $user); $user->push('tags', 'tag1'); $user->push('tags', ['tag1', 'tag2']); @@ -826,18 +832,16 @@ public function testDotNotation(): void $this->assertEquals('Paris', $user->{'address.city'}); // Fill - $user->fill([ - 'address.city' => 'Strasbourg', - ]); + $user->fill(['address.city' => 'Strasbourg']); $this->assertEquals('Strasbourg', $user['address.city']); } public function testAttributeMutator(): void { - $username = 'JaneDoe'; + $username = 'JaneDoe'; $usernameSlug = Str::slug($username); - $user = User::create([ + $user = User::create([ 'name' => 'Jane Doe', 'username' => $username, ]); @@ -852,15 +856,13 @@ public function testAttributeMutator(): void public function testMultipleLevelDotNotation(): void { - /** @var Book $book */ $book = Book::create([ 'title' => 'A Game of Thrones', 'chapters' => [ - 'one' => [ - 'title' => 'The first chapter', - ], + 'one' => ['title' => 'The first chapter'], ], ]); + $this->assertInstanceOf(Book::class, $book); $this->assertEquals(['one' => ['title' => 'The first chapter']], $book->chapters); $this->assertEquals(['title' => 'The first chapter'], $book['chapters.one']); @@ -927,18 +929,17 @@ public function testFirstOrCreate(): void { $name = 'Jane Poe'; - /** @var User $user */ $user = User::where('name', $name)->first(); $this->assertNull($user); - /** @var User $user */ - $user = User::firstOrCreate(compact('name')); + $user = User::firstOrCreate(['name' => $name]); + $this->assertInstanceOf(User::class, $user); $this->assertInstanceOf(Model::class, $user); $this->assertTrue($user->exists); $this->assertEquals($name, $user->name); - /** @var User $check */ $check = User::where('name', $name)->first(); + $this->assertInstanceOf(User::class, $check); $this->assertEquals($user->_id, $check->_id); } @@ -946,13 +947,13 @@ public function testEnumCast(): void { $name = 'John Member'; - $user = new User(); - $user->name = $name; + $user = new User(); + $user->name = $name; $user->member_status = MemberStatus::Member; $user->save(); - /** @var User $check */ $check = User::where('name', $name)->first(); + $this->assertInstanceOf(User::class, $check); $this->assertSame(MemberStatus::Member->value, $check->getRawOriginal('member_status')); $this->assertSame(MemberStatus::Member, $check->member_status); } diff --git a/tests/Models/Address.php b/tests/Models/Address.php index 2aadabd6c..b827dc85f 100644 --- a/tests/Models/Address.php +++ b/tests/Models/Address.php @@ -9,7 +9,7 @@ class Address extends Eloquent { - protected $connection = 'mongodb'; + protected $connection = 'mongodb'; protected static $unguarded = true; public function addresses(): EmbedsMany diff --git a/tests/Models/Birthday.php b/tests/Models/Birthday.php index 0252c9a20..4131357f6 100644 --- a/tests/Models/Birthday.php +++ b/tests/Models/Birthday.php @@ -7,8 +7,6 @@ use MongoDB\Laravel\Eloquent\Model as Eloquent; /** - * Class Birthday. - * * @property string $name * @property string $birthday * @property string $time @@ -17,9 +15,7 @@ class Birthday extends Eloquent { protected $connection = 'mongodb'; protected $collection = 'birthday'; - protected $fillable = ['name', 'birthday']; + protected $fillable = ['name', 'birthday']; - protected $casts = [ - 'birthday' => 'datetime', - ]; + protected $casts = ['birthday' => 'datetime']; } diff --git a/tests/Models/Book.php b/tests/Models/Book.php index 9439ead3c..e196ec4b3 100644 --- a/tests/Models/Book.php +++ b/tests/Models/Book.php @@ -8,18 +8,16 @@ use MongoDB\Laravel\Eloquent\Model as Eloquent; /** - * Class Book. - * * @property string $title * @property string $author * @property array $chapters */ class Book extends Eloquent { - protected $connection = 'mongodb'; - protected $collection = 'books'; + protected $connection = 'mongodb'; + protected $collection = 'books'; protected static $unguarded = true; - protected $primaryKey = 'title'; + protected $primaryKey = 'title'; public function author(): BelongsTo { diff --git a/tests/Models/CastBinaryUuid.php b/tests/Models/CastBinaryUuid.php index a872054d3..3d8b82941 100644 --- a/tests/Models/CastBinaryUuid.php +++ b/tests/Models/CastBinaryUuid.php @@ -9,9 +9,9 @@ class CastBinaryUuid extends Eloquent { - protected $connection = 'mongodb'; + protected $connection = 'mongodb'; protected static $unguarded = true; - protected $casts = [ + protected $casts = [ 'uuid' => BinaryUuid::class, ]; } diff --git a/tests/Models/CastObjectId.php b/tests/Models/CastObjectId.php index 8daca90df..2f4e7f5d5 100644 --- a/tests/Models/CastObjectId.php +++ b/tests/Models/CastObjectId.php @@ -9,9 +9,9 @@ class CastObjectId extends Eloquent { - protected $connection = 'mongodb'; + protected $connection = 'mongodb'; protected static $unguarded = true; - protected $casts = [ + protected $casts = [ 'oid' => ObjectId::class, ]; } diff --git a/tests/Models/Client.php b/tests/Models/Client.php index 2c5f17a68..7ee8cec4a 100644 --- a/tests/Models/Client.php +++ b/tests/Models/Client.php @@ -11,8 +11,8 @@ class Client extends Eloquent { - protected $connection = 'mongodb'; - protected $collection = 'clients'; + protected $connection = 'mongodb'; + protected $collection = 'clients'; protected static $unguarded = true; public function users(): BelongsToMany diff --git a/tests/Models/Group.php b/tests/Models/Group.php index 4fba28493..eda017a03 100644 --- a/tests/Models/Group.php +++ b/tests/Models/Group.php @@ -9,8 +9,8 @@ class Group extends Eloquent { - protected $connection = 'mongodb'; - protected $collection = 'groups'; + protected $connection = 'mongodb'; + protected $collection = 'groups'; protected static $unguarded = true; public function users(): BelongsToMany diff --git a/tests/Models/Guarded.php b/tests/Models/Guarded.php index d396d4f13..540d68996 100644 --- a/tests/Models/Guarded.php +++ b/tests/Models/Guarded.php @@ -10,5 +10,5 @@ class Guarded extends Eloquent { protected $connection = 'mongodb'; protected $collection = 'guarded'; - protected $guarded = ['foobar', 'level1->level2']; + protected $guarded = ['foobar', 'level1->level2']; } diff --git a/tests/Models/IdIsBinaryUuid.php b/tests/Models/IdIsBinaryUuid.php index f16e83a73..56ae89dca 100644 --- a/tests/Models/IdIsBinaryUuid.php +++ b/tests/Models/IdIsBinaryUuid.php @@ -9,9 +9,9 @@ class IdIsBinaryUuid extends Eloquent { - protected $connection = 'mongodb'; + protected $connection = 'mongodb'; protected static $unguarded = true; - protected $casts = [ + protected $casts = [ '_id' => BinaryUuid::class, ]; } diff --git a/tests/Models/IdIsInt.php b/tests/Models/IdIsInt.php index ae3ad26e0..1243fc217 100644 --- a/tests/Models/IdIsInt.php +++ b/tests/Models/IdIsInt.php @@ -8,10 +8,8 @@ class IdIsInt extends Eloquent { - protected $keyType = 'int'; - protected $connection = 'mongodb'; + protected $keyType = 'int'; + protected $connection = 'mongodb'; protected static $unguarded = true; - protected $casts = [ - '_id' => 'int', - ]; + protected $casts = ['_id' => 'int']; } diff --git a/tests/Models/IdIsString.php b/tests/Models/IdIsString.php index 9f74fc941..ed89803ca 100644 --- a/tests/Models/IdIsString.php +++ b/tests/Models/IdIsString.php @@ -8,9 +8,7 @@ class IdIsString extends Eloquent { - protected $connection = 'mongodb'; + protected $connection = 'mongodb'; protected static $unguarded = true; - protected $casts = [ - '_id' => 'string', - ]; + protected $casts = ['_id' => 'string']; } diff --git a/tests/Models/Item.php b/tests/Models/Item.php index 5b54f63d5..8aafc1446 100644 --- a/tests/Models/Item.php +++ b/tests/Models/Item.php @@ -4,19 +4,16 @@ namespace MongoDB\Laravel\Tests\Models; +use Carbon\Carbon; use Illuminate\Database\Eloquent\Relations\BelongsTo; use MongoDB\Laravel\Eloquent\Builder; use MongoDB\Laravel\Eloquent\Model as Eloquent; -/** - * Class Item. - * - * @property \Carbon\Carbon $created_at - */ +/** @property Carbon $created_at */ class Item extends Eloquent { - protected $connection = 'mongodb'; - protected $collection = 'items'; + protected $connection = 'mongodb'; + protected $collection = 'items'; protected static $unguarded = true; public function user(): BelongsTo diff --git a/tests/Models/Location.php b/tests/Models/Location.php index 623699d55..e273fa455 100644 --- a/tests/Models/Location.php +++ b/tests/Models/Location.php @@ -8,7 +8,7 @@ class Location extends Eloquent { - protected $connection = 'mongodb'; - protected $collection = 'locations'; + protected $connection = 'mongodb'; + protected $collection = 'locations'; protected static $unguarded = true; } diff --git a/tests/Models/MemberStatus.php b/tests/Models/MemberStatus.php index 5877125f0..9f14ce6e5 100644 --- a/tests/Models/MemberStatus.php +++ b/tests/Models/MemberStatus.php @@ -1,5 +1,7 @@ hasTable('books')) { - Schema::connection('mysql')->create('books', function (Blueprint $table) { - $table->string('title'); - $table->string('author_id')->nullable(); - $table->integer('mysql_user_id')->unsigned()->nullable(); - $table->timestamps(); - }); + if ($schema->hasTable('books')) { + return; } + + Schema::connection('mysql')->create('books', function (Blueprint $table) { + $table->string('title'); + $table->string('author_id')->nullable(); + $table->integer('mysql_user_id')->unsigned()->nullable(); + $table->timestamps(); + }); } } diff --git a/tests/Models/MysqlRole.php b/tests/Models/MysqlRole.php index 573a4503a..e4f293313 100644 --- a/tests/Models/MysqlRole.php +++ b/tests/Models/MysqlRole.php @@ -7,15 +7,18 @@ use Illuminate\Database\Eloquent\Model as EloquentModel; use Illuminate\Database\Eloquent\Relations\BelongsTo; use Illuminate\Database\Schema\Blueprint; +use Illuminate\Database\Schema\MySqlBuilder; use Illuminate\Support\Facades\Schema; use MongoDB\Laravel\Eloquent\HybridRelations; +use function assert; + class MysqlRole extends EloquentModel { use HybridRelations; - protected $connection = 'mysql'; - protected $table = 'roles'; + protected $connection = 'mysql'; + protected $table = 'roles'; protected static $unguarded = true; public function user(): BelongsTo @@ -33,15 +36,17 @@ public function mysqlUser(): BelongsTo */ public static function executeSchema() { - /** @var \Illuminate\Database\Schema\MySqlBuilder $schema */ $schema = Schema::connection('mysql'); + assert($schema instanceof MySqlBuilder); - if (! $schema->hasTable('roles')) { - Schema::connection('mysql')->create('roles', function (Blueprint $table) { - $table->string('type'); - $table->string('user_id'); - $table->timestamps(); - }); + if ($schema->hasTable('roles')) { + return; } + + Schema::connection('mysql')->create('roles', function (Blueprint $table) { + $table->string('type'); + $table->string('user_id'); + $table->timestamps(); + }); } } diff --git a/tests/Models/MysqlUser.php b/tests/Models/MysqlUser.php index e25d06f51..c16a14220 100644 --- a/tests/Models/MysqlUser.php +++ b/tests/Models/MysqlUser.php @@ -12,12 +12,14 @@ use Illuminate\Support\Facades\Schema; use MongoDB\Laravel\Eloquent\HybridRelations; +use function assert; + class MysqlUser extends EloquentModel { use HybridRelations; - protected $connection = 'mysql'; - protected $table = 'users'; + protected $connection = 'mysql'; + protected $table = 'users'; protected static $unguarded = true; public function books(): HasMany @@ -40,15 +42,17 @@ public function mysqlBooks(): HasMany */ public static function executeSchema(): void { - /** @var MySqlBuilder $schema */ $schema = Schema::connection('mysql'); + assert($schema instanceof MySqlBuilder); - if (! $schema->hasTable('users')) { - Schema::connection('mysql')->create('users', function (Blueprint $table) { - $table->increments('id'); - $table->string('name'); - $table->timestamps(); - }); + if ($schema->hasTable('users')) { + return; } + + Schema::connection('mysql')->create('users', function (Blueprint $table) { + $table->increments('id'); + $table->string('name'); + $table->timestamps(); + }); } } diff --git a/tests/Models/Photo.php b/tests/Models/Photo.php index 2f584bd63..dbb92b0ff 100644 --- a/tests/Models/Photo.php +++ b/tests/Models/Photo.php @@ -9,8 +9,8 @@ class Photo extends Eloquent { - protected $connection = 'mongodb'; - protected $collection = 'photos'; + protected $connection = 'mongodb'; + protected $collection = 'photos'; protected static $unguarded = true; public function hasImage(): MorphTo diff --git a/tests/Models/Role.php b/tests/Models/Role.php index d778a7d8a..2c191ac1b 100644 --- a/tests/Models/Role.php +++ b/tests/Models/Role.php @@ -9,8 +9,8 @@ class Role extends Eloquent { - protected $connection = 'mongodb'; - protected $collection = 'roles'; + protected $connection = 'mongodb'; + protected $collection = 'roles'; protected static $unguarded = true; public function user(): BelongsTo diff --git a/tests/Models/Scoped.php b/tests/Models/Scoped.php index 3a5997f4e..d728b6bec 100644 --- a/tests/Models/Scoped.php +++ b/tests/Models/Scoped.php @@ -11,7 +11,7 @@ class Scoped extends Eloquent { protected $connection = 'mongodb'; protected $collection = 'scoped'; - protected $fillable = ['name', 'favorite']; + protected $fillable = ['name', 'favorite']; protected static function boot() { diff --git a/tests/Models/Soft.php b/tests/Models/Soft.php index 7a5d25704..31b80908a 100644 --- a/tests/Models/Soft.php +++ b/tests/Models/Soft.php @@ -4,25 +4,22 @@ namespace MongoDB\Laravel\Tests\Models; +use Carbon\Carbon; use MongoDB\Laravel\Eloquent\Builder; use MongoDB\Laravel\Eloquent\MassPrunable; use MongoDB\Laravel\Eloquent\Model as Eloquent; use MongoDB\Laravel\Eloquent\SoftDeletes; -/** - * Class Soft. - * - * @property \Carbon\Carbon $deleted_at - */ +/** @property Carbon $deleted_at */ class Soft extends Eloquent { use SoftDeletes; use MassPrunable; - protected $connection = 'mongodb'; - protected $collection = 'soft'; + protected $connection = 'mongodb'; + protected $collection = 'soft'; protected static $unguarded = true; - protected $casts = ['deleted_at' => 'datetime']; + protected $casts = ['deleted_at' => 'datetime']; public function prunable(): Builder { diff --git a/tests/Models/User.php b/tests/Models/User.php index 57319f84a..945d8b074 100644 --- a/tests/Models/User.php +++ b/tests/Models/User.php @@ -4,6 +4,7 @@ namespace MongoDB\Laravel\Tests\Models; +use Carbon\Carbon; use DateTimeInterface; use Illuminate\Auth\Authenticatable; use Illuminate\Auth\Passwords\CanResetPassword; @@ -18,16 +19,14 @@ use MongoDB\Laravel\Eloquent\Model as Eloquent; /** - * Class User. - * * @property string $_id * @property string $name * @property string $email * @property string $title * @property int $age - * @property \Carbon\Carbon $birthday - * @property \Carbon\Carbon $created_at - * @property \Carbon\Carbon $updated_at + * @property Carbon $birthday + * @property Carbon $created_at + * @property Carbon $updated_at * @property string $username * @property MemberStatus member_status */ @@ -39,8 +38,8 @@ class User extends Eloquent implements AuthenticatableContract, CanResetPassword use Notifiable; use MassPrunable; - protected $connection = 'mongodb'; - protected $casts = [ + protected $connection = 'mongodb'; + protected $casts = [ 'birthday' => 'datetime', 'entry.date' => 'datetime', 'member_status' => MemberStatus::class, diff --git a/tests/Query/BuilderTest.php b/tests/Query/BuilderTest.php index b1484a6d9..556239afc 100644 --- a/tests/Query/BuilderTest.php +++ b/tests/Query/BuilderTest.php @@ -4,9 +4,14 @@ namespace MongoDB\Laravel\Tests\Query; +use ArgumentCountError; +use BadMethodCallException; +use Closure; use DateTimeImmutable; use Illuminate\Database\Eloquent\Collection; use Illuminate\Tests\Database\DatabaseQueryBuilderTest; +use InvalidArgumentException; +use LogicException; use Mockery as m; use MongoDB\BSON\Regex; use MongoDB\BSON\UTCDateTime; @@ -15,13 +20,16 @@ use MongoDB\Laravel\Query\Grammar; use MongoDB\Laravel\Query\Processor; use PHPUnit\Framework\TestCase; +use stdClass; + +use function collect; +use function now; +use function var_export; class BuilderTest extends TestCase { - /** - * @dataProvider provideQueryBuilderToMql - */ - public function testMql(array $expected, \Closure $build): void + /** @dataProvider provideQueryBuilderToMql */ + public function testMql(array $expected, Closure $build): void { $builder = $build(self::getBuilder()); $this->assertInstanceOf(Builder::class, $builder); @@ -31,6 +39,7 @@ public function testMql(array $expected, \Closure $build): void if (isset($expected['find'][1])) { $expected['find'][1]['typeMap'] = ['root' => 'array', 'document' => 'array']; } + if (isset($expected['aggregate'][1])) { $expected['aggregate'][1]['typeMap'] = ['root' => 'array', 'document' => 'array']; } @@ -82,13 +91,17 @@ public static function provideQueryBuilderToMql(): iterable ]; yield 'where with single array of conditions' => [ - ['find' => [ - ['$and' => [ - ['foo' => 1], - ['bar' => 2], - ]], - [], // options - ]], + [ + 'find' => [ + [ + '$and' => [ + ['foo' => 1], + ['bar' => 2], + ], + ], + [], // options + ], + ], fn (Builder $builder) => $builder->where(['foo' => 1, 'bar' => 2]), ]; @@ -111,13 +124,17 @@ public static function provideQueryBuilderToMql(): iterable ]; yield 'orWhereIn' => [ - ['find' => [ - ['$or' => [ - ['id' => 1], - ['id' => ['$in' => [1, 2, 3]]], - ]], - [], // options - ]], + [ + 'find' => [ + [ + '$or' => [ + ['id' => 1], + ['id' => ['$in' => [1, 2, 3]]], + ], + ], + [], // options + ], + ], fn (Builder $builder) => $builder->where('id', '=', 1) ->orWhereIn('id', [1, 2, 3]), ]; @@ -129,13 +146,17 @@ public static function provideQueryBuilderToMql(): iterable ]; yield 'orWhereNotIn' => [ - ['find' => [ - ['$or' => [ - ['id' => 1], - ['id' => ['$nin' => [1, 2, 3]]], - ]], - [], // options - ]], + [ + 'find' => [ + [ + '$or' => [ + ['id' => 1], + ['id' => ['$nin' => [1, 2, 3]]], + ], + ], + [], // options + ], + ], fn (Builder $builder) => $builder->where('id', '=', 1) ->orWhereNotIn('id', [1, 2, 3]), ]; @@ -152,13 +173,17 @@ public static function provideQueryBuilderToMql(): iterable ]; yield 'where accepts $ in operators' => [ - ['find' => [ - ['$or' => [ - ['foo' => ['$type' => 2]], - ['foo' => ['$type' => 4]], - ]], - [], // options - ]], + [ + 'find' => [ + [ + '$or' => [ + ['foo' => ['$type' => 2]], + ['foo' => ['$type' => 4]], + ], + ], + [], // options + ], + ], fn (Builder $builder) => $builder ->where('foo', '$type', 2) ->orWhere('foo', '$type', 4), @@ -166,13 +191,17 @@ public static function provideQueryBuilderToMql(): iterable /** @see DatabaseQueryBuilderTest::testBasicWhereNot() */ yield 'whereNot (multiple)' => [ - ['find' => [ - ['$and' => [ - ['$not' => ['name' => 'foo']], - ['$not' => ['name' => ['$ne' => 'bar']]], - ]], - [], // options - ]], + [ + 'find' => [ + [ + '$and' => [ + ['$not' => ['name' => 'foo']], + ['$not' => ['name' => ['$ne' => 'bar']]], + ], + ], + [], // options + ], + ], fn (Builder $builder) => $builder ->whereNot('name', 'foo') ->whereNot('name', '<>', 'bar'), @@ -180,13 +209,17 @@ public static function provideQueryBuilderToMql(): iterable /** @see DatabaseQueryBuilderTest::testBasicOrWheres() */ yield 'where orWhere' => [ - ['find' => [ - ['$or' => [ - ['id' => 1], - ['email' => 'foo'], - ]], - [], // options - ]], + [ + 'find' => [ + [ + '$or' => [ + ['id' => 1], + ['email' => 'foo'], + ], + ], + [], // options + ], + ], fn (Builder $builder) => $builder ->where('id', '=', 1) ->orWhere('email', '=', 'foo'), @@ -194,26 +227,34 @@ public static function provideQueryBuilderToMql(): iterable /** @see DatabaseQueryBuilderTest::testBasicOrWhereNot() */ yield 'orWhereNot' => [ - ['find' => [ - ['$or' => [ - ['$not' => ['name' => 'foo']], - ['$not' => ['name' => ['$ne' => 'bar']]], - ]], - [], // options - ]], + [ + 'find' => [ + [ + '$or' => [ + ['$not' => ['name' => 'foo']], + ['$not' => ['name' => ['$ne' => 'bar']]], + ], + ], + [], // options + ], + ], fn (Builder $builder) => $builder ->orWhereNot('name', 'foo') ->orWhereNot('name', '<>', 'bar'), ]; yield 'whereNot orWhere' => [ - ['find' => [ - ['$or' => [ - ['$not' => ['name' => 'foo']], - ['name' => ['$ne' => 'bar']], - ]], - [], // options - ]], + [ + 'find' => [ + [ + '$or' => [ + ['$not' => ['name' => 'foo']], + ['name' => ['$ne' => 'bar']], + ], + ], + [], // options + ], + ], fn (Builder $builder) => $builder ->whereNot('name', 'foo') ->orWhere('name', '<>', 'bar'), @@ -221,22 +262,28 @@ public static function provideQueryBuilderToMql(): iterable /** @see DatabaseQueryBuilderTest::testWhereNot() */ yield 'whereNot callable' => [ - ['find' => [ - ['$not' => ['name' => 'foo']], - [], // options - ]], + [ + 'find' => [ + ['$not' => ['name' => 'foo']], + [], // options + ], + ], fn (Builder $builder) => $builder ->whereNot(fn (Builder $q) => $q->where('name', 'foo')), ]; yield 'where whereNot' => [ - ['find' => [ - ['$and' => [ - ['name' => 'bar'], - ['$not' => ['email' => 'foo']], - ]], - [], // options - ]], + [ + 'find' => [ + [ + '$and' => [ + ['name' => 'bar'], + ['$not' => ['email' => 'foo']], + ], + ], + [], // options + ], + ], fn (Builder $builder) => $builder ->where('name', '=', 'bar') ->whereNot(function (Builder $q) { @@ -245,15 +292,19 @@ public static function provideQueryBuilderToMql(): iterable ]; yield 'whereNot (nested)' => [ - ['find' => [ - ['$not' => [ - '$and' => [ - ['name' => 'foo'], - ['$not' => ['email' => ['$ne' => 'bar']]], + [ + 'find' => [ + [ + '$not' => [ + '$and' => [ + ['name' => 'foo'], + ['$not' => ['email' => ['$ne' => 'bar']]], + ], + ], ], - ]], - [], // options - ]], + [], // options + ], + ], fn (Builder $builder) => $builder ->whereNot(function (Builder $q) { $q->where('name', '=', 'foo') @@ -262,13 +313,17 @@ public static function provideQueryBuilderToMql(): iterable ]; yield 'orWhere orWhereNot' => [ - ['find' => [ - ['$or' => [ - ['name' => 'bar'], - ['$not' => ['email' => 'foo']], - ]], - [], // options - ]], + [ + 'find' => [ + [ + '$or' => [ + ['name' => 'bar'], + ['$not' => ['email' => 'foo']], + ], + ], + [], // options + ], + ], fn (Builder $builder) => $builder ->orWhere('name', '=', 'bar') ->orWhereNot(function (Builder $q) { @@ -277,13 +332,17 @@ public static function provideQueryBuilderToMql(): iterable ]; yield 'where orWhereNot' => [ - ['find' => [ - ['$or' => [ - ['name' => 'bar'], - ['$not' => ['email' => 'foo']], - ]], - [], // options - ]], + [ + 'find' => [ + [ + '$or' => [ + ['name' => 'bar'], + ['$not' => ['email' => 'foo']], + ], + ], + [], // options + ], + ], fn (Builder $builder) => $builder ->where('name', '=', 'bar') ->orWhereNot('email', '=', 'foo'), @@ -291,43 +350,55 @@ public static function provideQueryBuilderToMql(): iterable /** @see DatabaseQueryBuilderTest::testWhereNotWithArrayConditions() */ yield 'whereNot with arrays of single condition' => [ - ['find' => [ - ['$not' => [ - '$and' => [ - ['foo' => 1], - ['bar' => 2], + [ + 'find' => [ + [ + '$not' => [ + '$and' => [ + ['foo' => 1], + ['bar' => 2], + ], + ], ], - ]], - [], // options - ]], + [], // options + ], + ], fn (Builder $builder) => $builder ->whereNot([['foo', 1], ['bar', 2]]), ]; yield 'whereNot with single array of conditions' => [ - ['find' => [ - ['$not' => [ - '$and' => [ - ['foo' => 1], - ['bar' => 2], + [ + 'find' => [ + [ + '$not' => [ + '$and' => [ + ['foo' => 1], + ['bar' => 2], + ], + ], ], - ]], - [], // options - ]], + [], // options + ], + ], fn (Builder $builder) => $builder ->whereNot(['foo' => 1, 'bar' => 2]), ]; yield 'whereNot with arrays of single condition with operator' => [ - ['find' => [ - ['$not' => [ - '$and' => [ - ['foo' => 1], - ['bar' => ['$lt' => 2]], + [ + 'find' => [ + [ + '$not' => [ + '$and' => [ + ['foo' => 1], + ['bar' => ['$lt' => 2]], + ], + ], ], - ]], - [], // options - ]], + [], // options + ], + ], fn (Builder $builder) => $builder ->whereNot([ ['foo', 1], @@ -341,10 +412,19 @@ public static function provideQueryBuilderToMql(): iterable ]; yield 'where all nested operators' => [ - ['find' => [['tags' => ['$all' => [ - ['$elemMatch' => ['size' => 'M', 'num' => ['$gt' => 50]]], - ['$elemMatch' => ['num' => 100, 'color' => 'green']], - ]]], []]], + [ + 'find' => [ + [ + 'tags' => [ + '$all' => [ + ['$elemMatch' => ['size' => 'M', 'num' => ['$gt' => 50]]], + ['$elemMatch' => ['num' => 100, 'color' => 'green']], + ], + ], + ], + [], + ], + ], fn (Builder $builder) => $builder->where('tags', 'all', [ ['$elemMatch' => ['size' => 'M', 'num' => ['$gt' => 50]]], ['$elemMatch' => ['num' => 100, 'color' => 'green']], @@ -445,10 +525,12 @@ function (Builder $builder) { /** @link https://www.mongodb.com/docs/manual/reference/method/cursor.sort/#text-score-metadata-sort */ yield 'orderBy array meta' => [ - ['find' => [ - ['$text' => ['$search' => 'operating']], - ['sort' => ['score' => ['$meta' => 'textScore']]], - ]], + [ + 'find' => [ + ['$text' => ['$search' => 'operating']], + ['sort' => ['score' => ['$meta' => 'textScore']]], + ], + ], fn (Builder $builder) => $builder ->where('$text', ['$search' => 'operating']) ->orderBy('score', ['$meta' => 'textScore']), @@ -467,10 +549,12 @@ function (Builder $builder) { $period = now()->toPeriod(now()->addMonth()); yield 'whereBetween CarbonPeriod' => [ - ['find' => [ - ['created_at' => ['$gte' => new UTCDateTime($period->start), '$lte' => new UTCDateTime($period->end)]], - [], // options - ]], + [ + 'find' => [ + ['created_at' => ['$gte' => new UTCDateTime($period->start), '$lte' => new UTCDateTime($period->end)]], + [], // options + ], + ], fn (Builder $builder) => $builder->whereBetween('created_at', $period), ]; @@ -481,13 +565,17 @@ function (Builder $builder) { /** @see DatabaseQueryBuilderTest::testOrWhereBetween() */ yield 'orWhereBetween array of numbers' => [ - ['find' => [ - ['$or' => [ - ['id' => 1], - ['id' => ['$gte' => 3, '$lte' => 5]], - ]], - [], // options - ]], + [ + 'find' => [ + [ + '$or' => [ + ['id' => 1], + ['id' => ['$gte' => 3, '$lte' => 5]], + ], + ], + [], // options + ], + ], fn (Builder $builder) => $builder ->where('id', '=', 1) ->orWhereBetween('id', [3, 5]), @@ -495,86 +583,116 @@ function (Builder $builder) { /** @link https://www.mongodb.com/docs/manual/reference/bson-type-comparison-order/#arrays */ yield 'orWhereBetween nested array of numbers' => [ - ['find' => [ - ['$or' => [ - ['id' => 1], - ['id' => ['$gte' => [4], '$lte' => [6, 8]]], - ]], - [], // options - ]], + [ + 'find' => [ + [ + '$or' => [ + ['id' => 1], + ['id' => ['$gte' => [4], '$lte' => [6, 8]]], + ], + ], + [], // options + ], + ], fn (Builder $builder) => $builder ->where('id', '=', 1) ->orWhereBetween('id', [[4], [6, 8]]), ]; yield 'orWhereBetween collection' => [ - ['find' => [ - ['$or' => [ - ['id' => 1], - ['id' => ['$gte' => 3, '$lte' => 4]], - ]], - [], // options - ]], + [ + 'find' => [ + [ + '$or' => [ + ['id' => 1], + ['id' => ['$gte' => 3, '$lte' => 4]], + ], + ], + [], // options + ], + ], fn (Builder $builder) => $builder ->where('id', '=', 1) ->orWhereBetween('id', collect([3, 4])), ]; yield 'whereNotBetween array of numbers' => [ - ['find' => [ - ['$or' => [ - ['id' => ['$lte' => 1]], - ['id' => ['$gte' => 2]], - ]], - [], // options - ]], + [ + 'find' => [ + [ + '$or' => [ + ['id' => ['$lte' => 1]], + ['id' => ['$gte' => 2]], + ], + ], + [], // options + ], + ], fn (Builder $builder) => $builder->whereNotBetween('id', [1, 2]), ]; /** @see DatabaseQueryBuilderTest::testOrWhereNotBetween() */ yield 'orWhereNotBetween array of numbers' => [ - ['find' => [ - ['$or' => [ - ['id' => 1], - ['$or' => [ - ['id' => ['$lte' => 3]], - ['id' => ['$gte' => 5]], - ]], - ]], - [], // options - ]], + [ + 'find' => [ + [ + '$or' => [ + ['id' => 1], + [ + '$or' => [ + ['id' => ['$lte' => 3]], + ['id' => ['$gte' => 5]], + ], + ], + ], + ], + [], // options + ], + ], fn (Builder $builder) => $builder ->where('id', '=', 1) ->orWhereNotBetween('id', [3, 5]), ]; yield 'orWhereNotBetween nested array of numbers' => [ - ['find' => [ - ['$or' => [ - ['id' => 1], - ['$or' => [ - ['id' => ['$lte' => [2, 3]]], - ['id' => ['$gte' => [5]]], - ]], - ]], - [], // options - ]], + [ + 'find' => [ + [ + '$or' => [ + ['id' => 1], + [ + '$or' => [ + ['id' => ['$lte' => [2, 3]]], + ['id' => ['$gte' => [5]]], + ], + ], + ], + ], + [], // options + ], + ], fn (Builder $builder) => $builder ->where('id', '=', 1) ->orWhereNotBetween('id', [[2, 3], [5]]), ]; yield 'orWhereNotBetween collection' => [ - ['find' => [ - ['$or' => [ - ['id' => 1], - ['$or' => [ - ['id' => ['$lte' => 3]], - ['id' => ['$gte' => 4]], - ]], - ]], - [], // options - ]], + [ + 'find' => [ + [ + '$or' => [ + ['id' => 1], + [ + '$or' => [ + ['id' => ['$lte' => 3]], + ['id' => ['$gte' => 4]], + ], + ], + ], + ], + [], // options + ], + ], fn (Builder $builder) => $builder ->where('id', '=', 1) ->orWhereNotBetween('id', collect([3, 4])), @@ -647,166 +765,292 @@ function (Builder $builder) { ]; yield 'where date' => [ - ['find' => [['created_at' => [ - '$gte' => new UTCDateTime(new DateTimeImmutable('2018-09-30 00:00:00.000 +00:00')), - '$lte' => new UTCDateTime(new DateTimeImmutable('2018-09-30 23:59:59.999 +00:00')), - ]], []]], + [ + 'find' => [ + [ + 'created_at' => [ + '$gte' => new UTCDateTime(new DateTimeImmutable('2018-09-30 00:00:00.000 +00:00')), + '$lte' => new UTCDateTime(new DateTimeImmutable('2018-09-30 23:59:59.999 +00:00')), + ], + ], + [], + ], + ], fn (Builder $builder) => $builder->whereDate('created_at', '2018-09-30'), ]; yield 'where date DateTimeImmutable' => [ - ['find' => [['created_at' => [ - '$gte' => new UTCDateTime(new DateTimeImmutable('2018-09-30 00:00:00.000 +00:00')), - '$lte' => new UTCDateTime(new DateTimeImmutable('2018-09-30 23:59:59.999 +00:00')), - ]], []]], + [ + 'find' => [ + [ + 'created_at' => [ + '$gte' => new UTCDateTime(new DateTimeImmutable('2018-09-30 00:00:00.000 +00:00')), + '$lte' => new UTCDateTime(new DateTimeImmutable('2018-09-30 23:59:59.999 +00:00')), + ], + ], + [], + ], + ], fn (Builder $builder) => $builder->whereDate('created_at', '=', new DateTimeImmutable('2018-09-30 15:00:00 +02:00')), ]; yield 'where date !=' => [ - ['find' => [['created_at' => [ - '$not' => [ - '$gte' => new UTCDateTime(new DateTimeImmutable('2018-09-30 00:00:00.000 +00:00')), - '$lte' => new UTCDateTime(new DateTimeImmutable('2018-09-30 23:59:59.999 +00:00')), + [ + 'find' => [ + [ + 'created_at' => [ + '$not' => [ + '$gte' => new UTCDateTime(new DateTimeImmutable('2018-09-30 00:00:00.000 +00:00')), + '$lte' => new UTCDateTime(new DateTimeImmutable('2018-09-30 23:59:59.999 +00:00')), + ], + ], + ], + [], ], - ]], []]], + ], fn (Builder $builder) => $builder->whereDate('created_at', '!=', '2018-09-30'), ]; yield 'where date <' => [ - ['find' => [['created_at' => [ - '$lt' => new UTCDateTime(new DateTimeImmutable('2018-09-30 00:00:00.000 +00:00')), - ]], []]], + [ + 'find' => [ + [ + 'created_at' => [ + '$lt' => new UTCDateTime(new DateTimeImmutable('2018-09-30 00:00:00.000 +00:00')), + ], + ], + [], + ], + ], fn (Builder $builder) => $builder->whereDate('created_at', '<', '2018-09-30'), ]; yield 'where date >=' => [ - ['find' => [['created_at' => [ - '$gte' => new UTCDateTime(new DateTimeImmutable('2018-09-30 00:00:00.000 +00:00')), - ]], []]], + [ + 'find' => [ + [ + 'created_at' => [ + '$gte' => new UTCDateTime(new DateTimeImmutable('2018-09-30 00:00:00.000 +00:00')), + ], + ], + [], + ], + ], fn (Builder $builder) => $builder->whereDate('created_at', '>=', '2018-09-30'), ]; yield 'where date >' => [ - ['find' => [['created_at' => [ - '$gt' => new UTCDateTime(new DateTimeImmutable('2018-09-30 23:59:59.999 +00:00')), - ]], []]], + [ + 'find' => [ + [ + 'created_at' => [ + '$gt' => new UTCDateTime(new DateTimeImmutable('2018-09-30 23:59:59.999 +00:00')), + ], + ], + [], + ], + ], fn (Builder $builder) => $builder->whereDate('created_at', '>', '2018-09-30'), ]; yield 'where date <=' => [ - ['find' => [['created_at' => [ - '$lte' => new UTCDateTime(new DateTimeImmutable('2018-09-30 23:59:59.999 +00:00')), - ]], []]], + [ + 'find' => [ + [ + 'created_at' => [ + '$lte' => new UTCDateTime(new DateTimeImmutable('2018-09-30 23:59:59.999 +00:00')), + ], + ], + [], + ], + ], fn (Builder $builder) => $builder->whereDate('created_at', '<=', '2018-09-30'), ]; yield 'where day' => [ - ['find' => [['$expr' => [ - '$eq' => [ - ['$dayOfMonth' => '$created_at'], - 5, + [ + 'find' => [ + [ + '$expr' => [ + '$eq' => [ + ['$dayOfMonth' => '$created_at'], + 5, + ], + ], + ], + [], ], - ]], []]], + ], fn (Builder $builder) => $builder->whereDay('created_at', 5), ]; yield 'where day > string' => [ - ['find' => [['$expr' => [ - '$gt' => [ - ['$dayOfMonth' => '$created_at'], - 5, + [ + 'find' => [ + [ + '$expr' => [ + '$gt' => [ + ['$dayOfMonth' => '$created_at'], + 5, + ], + ], + ], + [], ], - ]], []]], + ], fn (Builder $builder) => $builder->whereDay('created_at', '>', '05'), ]; yield 'where month' => [ - ['find' => [['$expr' => [ - '$eq' => [ - ['$month' => '$created_at'], - 10, + [ + 'find' => [ + [ + '$expr' => [ + '$eq' => [ + ['$month' => '$created_at'], + 10, + ], + ], + ], + [], ], - ]], []]], + ], fn (Builder $builder) => $builder->whereMonth('created_at', 10), ]; yield 'where month > string' => [ - ['find' => [['$expr' => [ - '$gt' => [ - ['$month' => '$created_at'], - 5, + [ + 'find' => [ + [ + '$expr' => [ + '$gt' => [ + ['$month' => '$created_at'], + 5, + ], + ], + ], + [], ], - ]], []]], + ], fn (Builder $builder) => $builder->whereMonth('created_at', '>', '05'), ]; yield 'where year' => [ - ['find' => [['$expr' => [ - '$eq' => [ - ['$year' => '$created_at'], - 2023, + [ + 'find' => [ + [ + '$expr' => [ + '$eq' => [ + ['$year' => '$created_at'], + 2023, + ], + ], + ], + [], ], - ]], []]], + ], fn (Builder $builder) => $builder->whereYear('created_at', 2023), ]; yield 'where year > string' => [ - ['find' => [['$expr' => [ - '$gt' => [ - ['$year' => '$created_at'], - 2023, + [ + 'find' => [ + [ + '$expr' => [ + '$gt' => [ + ['$year' => '$created_at'], + 2023, + ], + ], + ], + [], ], - ]], []]], + ], fn (Builder $builder) => $builder->whereYear('created_at', '>', '2023'), ]; yield 'where time HH:MM:SS' => [ - ['find' => [['$expr' => [ - '$eq' => [ - ['$dateToString' => ['date' => '$created_at', 'format' => '%H:%M:%S']], - '10:11:12', + [ + 'find' => [ + [ + '$expr' => [ + '$eq' => [ + ['$dateToString' => ['date' => '$created_at', 'format' => '%H:%M:%S']], + '10:11:12', + ], + ], + ], + [], ], - ]], []]], + ], fn (Builder $builder) => $builder->whereTime('created_at', '10:11:12'), ]; yield 'where time HH:MM' => [ - ['find' => [['$expr' => [ - '$eq' => [ - ['$dateToString' => ['date' => '$created_at', 'format' => '%H:%M']], - '10:11', + [ + 'find' => [ + [ + '$expr' => [ + '$eq' => [ + ['$dateToString' => ['date' => '$created_at', 'format' => '%H:%M']], + '10:11', + ], + ], + ], + [], ], - ]], []]], + ], fn (Builder $builder) => $builder->whereTime('created_at', '10:11'), ]; yield 'where time HH' => [ - ['find' => [['$expr' => [ - '$eq' => [ - ['$dateToString' => ['date' => '$created_at', 'format' => '%H']], - '10', + [ + 'find' => [ + [ + '$expr' => [ + '$eq' => [ + ['$dateToString' => ['date' => '$created_at', 'format' => '%H']], + '10', + ], + ], + ], + [], ], - ]], []]], + ], fn (Builder $builder) => $builder->whereTime('created_at', '10'), ]; yield 'where time DateTime' => [ - ['find' => [['$expr' => [ - '$eq' => [ - ['$dateToString' => ['date' => '$created_at', 'format' => '%H:%M:%S']], - '10:11:12', + [ + 'find' => [ + [ + '$expr' => [ + '$eq' => [ + ['$dateToString' => ['date' => '$created_at', 'format' => '%H:%M:%S']], + '10:11:12', + ], + ], + ], + [], ], - ]], []]], - fn (Builder $builder) => $builder->whereTime('created_at', new \DateTimeImmutable('2023-08-22 10:11:12')), + ], + fn (Builder $builder) => $builder->whereTime('created_at', new DateTimeImmutable('2023-08-22 10:11:12')), ]; yield 'where time >' => [ - ['find' => [['$expr' => [ - '$gt' => [ - ['$dateToString' => ['date' => '$created_at', 'format' => '%H:%M:%S']], - '10:11:12', + [ + 'find' => [ + [ + '$expr' => [ + '$gt' => [ + ['$dateToString' => ['date' => '$created_at', 'format' => '%H:%M:%S']], + '10:11:12', + ], + ], + ], + [], ], - ]], []]], + ], fn (Builder $builder) => $builder->whereTime('created_at', '>', '10:11:12'), ]; @@ -862,18 +1106,18 @@ function (Builder $builder) { ]; yield 'groupBy' => [ - ['aggregate' => [ - [['$group' => ['_id' => ['foo' => '$foo'], 'foo' => ['$last' => '$foo']]]], - [], // options - ]], + [ + 'aggregate' => [ + [['$group' => ['_id' => ['foo' => '$foo'], 'foo' => ['$last' => '$foo']]]], + [], // options + ], + ], fn (Builder $builder) => $builder->groupBy('foo'), ]; } - /** - * @dataProvider provideExceptions - */ - public function testException($class, $message, \Closure $build): void + /** @dataProvider provideExceptions */ + public function testException($class, $message, Closure $build): void { $builder = self::getBuilder(); @@ -885,85 +1129,85 @@ public function testException($class, $message, \Closure $build): void public static function provideExceptions(): iterable { yield 'orderBy invalid direction' => [ - \InvalidArgumentException::class, + InvalidArgumentException::class, 'Order direction must be "asc" or "desc"', fn (Builder $builder) => $builder->orderBy('_id', 'dasc'), ]; /** @see DatabaseQueryBuilderTest::testWhereBetweens */ yield 'whereBetween array too short' => [ - \InvalidArgumentException::class, + InvalidArgumentException::class, 'Between $values must be a list with exactly two elements: [min, max]', fn (Builder $builder) => $builder->whereBetween('id', [1]), ]; yield 'whereBetween array too short (nested)' => [ - \InvalidArgumentException::class, + InvalidArgumentException::class, 'Between $values must be a list with exactly two elements: [min, max]', fn (Builder $builder) => $builder->whereBetween('id', [[1, 2]]), ]; yield 'whereBetween array too long' => [ - \InvalidArgumentException::class, + InvalidArgumentException::class, 'Between $values must be a list with exactly two elements: [min, max]', fn (Builder $builder) => $builder->whereBetween('id', [1, 2, 3]), ]; yield 'whereBetween collection too long' => [ - \InvalidArgumentException::class, + InvalidArgumentException::class, 'Between $values must be a list with exactly two elements: [min, max]', fn (Builder $builder) => $builder->whereBetween('id', new Collection([1, 2, 3])), ]; yield 'whereBetween array is not a list' => [ - \InvalidArgumentException::class, + InvalidArgumentException::class, 'Between $values must be a list with exactly two elements: [min, max]', fn (Builder $builder) => $builder->whereBetween('id', ['min' => 1, 'max' => 2]), ]; yield 'find with single string argument' => [ - \ArgumentCountError::class, + ArgumentCountError::class, 'Too few arguments to function MongoDB\Laravel\Query\Builder::where("foo"), 1 passed and at least 2 expected when the 1st is a string', fn (Builder $builder) => $builder->where('foo'), ]; yield 'where regex not starting with /' => [ - \LogicException::class, + LogicException::class, 'Missing expected starting delimiter in regular expression "^ac/me$", supported delimiters are: / # ~', fn (Builder $builder) => $builder->where('name', 'regex', '^ac/me$'), ]; yield 'where regex not ending with /' => [ - \LogicException::class, + LogicException::class, 'Missing expected ending delimiter "/" in regular expression "/foo#bar"', fn (Builder $builder) => $builder->where('name', 'regex', '/foo#bar'), ]; yield 'whereTime with invalid time' => [ - \InvalidArgumentException::class, + InvalidArgumentException::class, 'Invalid time format, expected HH:MM:SS, HH:MM or HH, got "10:11:12:13"', fn (Builder $builder) => $builder->whereTime('created_at', '10:11:12:13'), ]; yield 'whereTime out of range' => [ - \InvalidArgumentException::class, + InvalidArgumentException::class, 'Invalid time format, expected HH:MM:SS, HH:MM or HH, got "23:70"', fn (Builder $builder) => $builder->whereTime('created_at', '23:70'), ]; yield 'whereTime invalid type' => [ - \InvalidArgumentException::class, + InvalidArgumentException::class, 'Invalid time format, expected HH:MM:SS, HH:MM or HH, got "stdClass"', - fn (Builder $builder) => $builder->whereTime('created_at', new \stdClass()), + fn (Builder $builder) => $builder->whereTime('created_at', new stdClass()), ]; } /** @dataProvider getEloquentMethodsNotSupported */ - public function testEloquentMethodsNotSupported(\Closure $callback) + public function testEloquentMethodsNotSupported(Closure $callback) { $builder = self::getBuilder(); - $this->expectException(\BadMethodCallException::class); + $this->expectException(BadMethodCallException::class); $this->expectExceptionMessage('This method is not supported by MongoDB'); $callback($builder); @@ -1019,7 +1263,7 @@ public static function getEloquentMethodsNotSupported() private static function getBuilder(): Builder { $connection = m::mock(Connection::class); - $processor = m::mock(Processor::class); + $processor = m::mock(Processor::class); $connection->shouldReceive('getSession')->andReturn(null); $connection->shouldReceive('getQueryGrammar')->andReturn(new Grammar()); diff --git a/tests/QueryBuilderTest.php b/tests/QueryBuilderTest.php index eabdaca1c..4320e6a54 100644 --- a/tests/QueryBuilderTest.php +++ b/tests/QueryBuilderTest.php @@ -11,6 +11,7 @@ use Illuminate\Support\LazyCollection; use Illuminate\Support\Str; use Illuminate\Testing\Assert; +use InvalidArgumentException; use MongoDB\BSON\ObjectId; use MongoDB\BSON\Regex; use MongoDB\BSON\UTCDateTime; @@ -23,6 +24,14 @@ use MongoDB\Laravel\Query\Builder; use MongoDB\Laravel\Tests\Models\Item; use MongoDB\Laravel\Tests\Models\User; +use Stringable; + +use function count; +use function key; +use function md5; +use function sort; +use function strlen; +use function strtotime; class QueryBuilderTest extends TestCase { @@ -38,20 +47,20 @@ public function testDeleteWithId() ['name' => 'Jane Doe', 'age' => 20], ]); - $user_id = (string) $user; + $userId = (string) $user; DB::collection('items')->insert([ - ['name' => 'one thing', 'user_id' => $user_id], - ['name' => 'last thing', 'user_id' => $user_id], - ['name' => 'another thing', 'user_id' => $user_id], - ['name' => 'one more thing', 'user_id' => $user_id], + ['name' => 'one thing', 'user_id' => $userId], + ['name' => 'last thing', 'user_id' => $userId], + ['name' => 'another thing', 'user_id' => $userId], + ['name' => 'one more thing', 'user_id' => $userId], ]); $product = DB::collection('items')->first(); $pid = (string) ($product['_id']); - DB::collection('items')->where('user_id', $user_id)->delete($pid); + DB::collection('items')->where('user_id', $userId)->delete($pid); $this->assertEquals(3, DB::collection('items')->count()); @@ -59,9 +68,9 @@ public function testDeleteWithId() $pid = $product['_id']; - DB::collection('items')->where('user_id', $user_id)->delete($pid); + DB::collection('items')->where('user_id', $userId)->delete($pid); - DB::collection('items')->where('user_id', $user_id)->delete(md5('random-id')); + DB::collection('items')->where('user_id', $userId)->delete(md5('random-id')); $this->assertEquals(2, DB::collection('items')->count()); } @@ -215,14 +224,14 @@ public function testUpdateOperators() [ '$unset' => ['age' => 1], 'ageless' => true, - ] + ], ); DB::collection('users')->where('name', 'Jane Doe')->update( [ '$inc' => ['age' => 1], '$set' => ['pronoun' => 'she'], 'ageless' => false, - ] + ], ); $john = DB::collection('users')->where('name', 'John Doe')->first(); @@ -379,7 +388,7 @@ public function testPush() public function testPushRefuses2ndArgumentWhen1stIsAnArray() { - $this->expectException(\InvalidArgumentException::class); + $this->expectException(InvalidArgumentException::class); $this->expectExceptionMessage('2nd argument of MongoDB\Laravel\Query\Builder::push() must be "null" when 1st argument is an array. Got "string" instead.'); DB::collection('users')->push(['tags' => 'tag1'], 'tag2'); @@ -584,7 +593,7 @@ public function testUpsert() DB::collection('items')->where('name', 'knife') ->update( ['amount' => 1], - ['upsert' => true] + ['upsert' => true], ); $this->assertEquals(1, DB::collection('items')->count()); @@ -592,7 +601,7 @@ public function testUpsert() Item::where('name', 'spoon') ->update( ['amount' => 1], - ['upsert' => true] + ['upsert' => true], ); $this->assertEquals(2, DB::collection('items')->count()); @@ -653,7 +662,7 @@ public function testDates() $this->assertEquals('John Doe', $user['name']); $start = new UTCDateTime(1000 * strtotime('1950-01-01 00:00:00')); - $stop = new UTCDateTime(1000 * strtotime('1981-01-01 00:00:00')); + $stop = new UTCDateTime(1000 * strtotime('1981-01-01 00:00:00')); $users = DB::collection('users')->whereBetween('birthday', [$start, $stop])->get(); $this->assertCount(2, $users); @@ -743,11 +752,11 @@ public function testOperators() $results = DB::collection('items')->where('tags', 'size', 4)->get(); $this->assertCount(1, $results); - $regex = new Regex('.*doe', 'i'); + $regex = new Regex('.*doe', 'i'); $results = DB::collection('users')->where('name', 'regex', $regex)->get(); $this->assertCount(2, $results); - $regex = new Regex('.*doe', 'i'); + $regex = new Regex('.*doe', 'i'); $results = DB::collection('users')->where('name', 'regexp', $regex)->get(); $this->assertCount(2, $results); @@ -900,12 +909,12 @@ public function testCursor() public function testStringableColumn() { DB::collection('users')->insert([ - ['name' => 'Jane Doe', 'age' => 36, 'birthday' => new UTCDateTime(new \DateTime('1987-01-01 00:00:00'))], - ['name' => 'John Doe', 'age' => 28, 'birthday' => new UTCDateTime(new \DateTime('1995-01-01 00:00:00'))], + ['name' => 'Jane Doe', 'age' => 36, 'birthday' => new UTCDateTime(new DateTime('1987-01-01 00:00:00'))], + ['name' => 'John Doe', 'age' => 28, 'birthday' => new UTCDateTime(new DateTime('1995-01-01 00:00:00'))], ]); $nameColumn = Str::of('name'); - $this->assertInstanceOf(\Stringable::class, $nameColumn, 'Ensure we are testing the feature with a Stringable instance'); + $this->assertInstanceOf(Stringable::class, $nameColumn, 'Ensure we are testing the feature with a Stringable instance'); $user = DB::collection('users')->where($nameColumn, 'John Doe')->first(); $this->assertEquals('John Doe', $user['name']); @@ -925,18 +934,17 @@ public function testStringableColumn() $user = DB::collection('users')->whereNotIn($nameColumn, ['John Doe'])->first(); $this->assertEquals('Jane Doe', $user['name']); - // whereBetween and whereNotBetween $ageColumn = Str::of('age'); + // whereBetween and whereNotBetween $user = DB::collection('users')->whereBetween($ageColumn, [30, 40])->first(); $this->assertEquals('Jane Doe', $user['name']); // whereBetween and whereNotBetween - $ageColumn = Str::of('age'); $user = DB::collection('users')->whereNotBetween($ageColumn, [30, 40])->first(); $this->assertEquals('John Doe', $user['name']); - // whereDate $birthdayColumn = Str::of('birthday'); + // whereDate $user = DB::collection('users')->whereDate($birthdayColumn, '1995-01-01')->first(); $this->assertEquals('John Doe', $user['name']); diff --git a/tests/QueryTest.php b/tests/QueryTest.php index 2a9bd4085..3d1df99f0 100644 --- a/tests/QueryTest.php +++ b/tests/QueryTest.php @@ -5,10 +5,13 @@ namespace MongoDB\Laravel\Tests; use DateTimeImmutable; +use LogicException; use MongoDB\Laravel\Tests\Models\Birthday; use MongoDB\Laravel\Tests\Models\Scoped; use MongoDB\Laravel\Tests\Models\User; +use function str; + class QueryTest extends TestCase { protected static $started = false; @@ -16,6 +19,7 @@ class QueryTest extends TestCase public function setUp(): void { parent::setUp(); + User::create(['name' => 'John Doe', 'age' => 35, 'title' => 'admin']); User::create(['name' => 'Jane Doe', 'age' => 33, 'title' => 'admin']); User::create(['name' => 'Harry Hoe', 'age' => 13, 'title' => 'user']); @@ -39,6 +43,7 @@ public function tearDown(): void User::truncate(); Scoped::truncate(); Birthday::truncate(); + parent::tearDown(); } @@ -422,7 +427,7 @@ public function testWhereRaw(): void $where1 = ['age' => ['$gt' => 30, '$lte' => 35]]; $where2 = ['age' => ['$gt' => 35, '$lt' => 40]]; - $users = User::whereRaw($where1)->orWhereRaw($where2)->get(); + $users = User::whereRaw($where1)->orWhereRaw($where2)->get(); $this->assertCount(6, $users); } @@ -580,7 +585,7 @@ public function testDelete(): void */ public function testDeleteException(int $limit): void { - $this->expectException(\LogicException::class); + $this->expectException(LogicException::class); $this->expectExceptionMessage('Delete limit can be 1 or null (unlimited).'); User::limit($limit)->delete(); } diff --git a/tests/QueueTest.php b/tests/QueueTest.php index 072835b32..24afcedff 100644 --- a/tests/QueueTest.php +++ b/tests/QueueTest.php @@ -10,8 +10,12 @@ use Illuminate\Support\Str; use Mockery; use MongoDB\Laravel\Queue\Failed\MongoFailedJobProvider; +use MongoDB\Laravel\Queue\MongoJob; use MongoDB\Laravel\Queue\MongoQueue; +use function app; +use function json_encode; + class QueueTest extends TestCase { public function setUp(): void @@ -36,7 +40,7 @@ public function testQueueJobLifeCycle(): void // Get and reserve the test job (next available) $job = Queue::pop('test'); - $this->assertInstanceOf(\MongoDB\Laravel\Queue\MongoJob::class, $job); + $this->assertInstanceOf(MongoJob::class, $job); $this->assertEquals(1, $job->isReserved()); $this->assertEquals(json_encode([ 'uuid' => $uuid, @@ -95,28 +99,28 @@ public function testFindFailJobNull(): void public function testIncrementAttempts(): void { - $job_id = Queue::push('test1', ['action' => 'QueueJobExpired'], 'test'); - $this->assertNotNull($job_id); - $job_id = Queue::push('test2', ['action' => 'QueueJobExpired'], 'test'); - $this->assertNotNull($job_id); + $jobId = Queue::push('test1', ['action' => 'QueueJobExpired'], 'test'); + $this->assertNotNull($jobId); + $jobId = Queue::push('test2', ['action' => 'QueueJobExpired'], 'test'); + $this->assertNotNull($jobId); $job = Queue::pop('test'); $this->assertEquals(1, $job->attempts()); $job->delete(); - $others_jobs = Queue::getDatabase() + $othersJobs = Queue::getDatabase() ->table(Config::get('queue.connections.database.table')) ->get(); - $this->assertCount(1, $others_jobs); - $this->assertEquals(0, $others_jobs[0]['attempts']); + $this->assertCount(1, $othersJobs); + $this->assertEquals(0, $othersJobs[0]['attempts']); } public function testJobRelease(): void { $queue = 'test'; - $job_id = Queue::push($queue, ['action' => 'QueueJobRelease'], 'test'); - $this->assertNotNull($job_id); + $jobId = Queue::push($queue, ['action' => 'QueueJobRelease'], 'test'); + $this->assertNotNull($jobId); $job = Queue::pop($queue); $job->release(); @@ -132,9 +136,9 @@ public function testJobRelease(): void public function testQueueDeleteReserved(): void { $queue = 'test'; - $job_id = Queue::push($queue, ['action' => 'QueueDeleteReserved'], 'test'); + $jobId = Queue::push($queue, ['action' => 'QueueDeleteReserved'], 'test'); - Queue::deleteReserved($queue, $job_id, 0); + Queue::deleteReserved($queue, $jobId, 0); $jobs = Queue::getDatabase() ->table(Config::get('queue.connections.database.table')) ->get(); @@ -149,23 +153,23 @@ public function testQueueRelease(): void $delay = 123; Queue::push($queue, ['action' => 'QueueRelease'], 'test'); - $job = Queue::pop($queue); - $released_job_id = Queue::release($queue, $job->getJobRecord(), $delay); + $job = Queue::pop($queue); + $releasedJobId = Queue::release($queue, $job->getJobRecord(), $delay); - $released_job = Queue::getDatabase() + $releasedJob = Queue::getDatabase() ->table(Config::get('queue.connections.database.table')) - ->where('_id', $released_job_id) + ->where('_id', $releasedJobId) ->first(); - $this->assertEquals($queue, $released_job['queue']); - $this->assertEquals(1, $released_job['attempts']); - $this->assertNull($released_job['reserved_at']); + $this->assertEquals($queue, $releasedJob['queue']); + $this->assertEquals(1, $releasedJob['attempts']); + $this->assertNull($releasedJob['reserved_at']); $this->assertEquals( Carbon::now()->addRealSeconds($delay)->getTimestamp(), - $released_job['available_at'] + $releasedJob['available_at'], ); - $this->assertEquals(Carbon::now()->getTimestamp(), $released_job['created_at']); - $this->assertEquals($job->getRawBody(), $released_job['payload']); + $this->assertEquals(Carbon::now()->getTimestamp(), $releasedJob['created_at']); + $this->assertEquals($job->getRawBody(), $releasedJob['payload']); } public function testQueueDeleteAndRelease(): void diff --git a/tests/RelationsTest.php b/tests/RelationsTest.php index f418bf384..214c6f506 100644 --- a/tests/RelationsTest.php +++ b/tests/RelationsTest.php @@ -144,7 +144,7 @@ public function testEasyRelation(): void $item = Item::create(['type' => 'knife']); $user->items()->save($item); - $user = User::find($user->_id); + $user = User::find($user->_id); $items = $user->items; $this->assertCount(1, $items); $this->assertInstanceOf(Item::class, $items[0]); @@ -171,7 +171,7 @@ public function testBelongsToMany(): void $user->clients()->create(['name' => 'Buffet Bar Inc.']); // Refetch - $user = User::with('clients')->find($user->_id); + $user = User::with('clients')->find($user->_id); $client = Client::with('users')->first(); // Check for relation attributes @@ -179,7 +179,7 @@ public function testBelongsToMany(): void $this->assertArrayHasKey('client_ids', $user->getAttributes()); $clients = $user->getRelation('clients'); - $users = $client->getRelation('users'); + $users = $client->getRelation('users'); $this->assertInstanceOf(Collection::class, $users); $this->assertInstanceOf(Collection::class, $clients); @@ -196,7 +196,7 @@ public function testBelongsToMany(): void $this->assertCount(1, $user->clients); // Get user and unattached client - $user = User::where('name', '=', 'Jane Doe')->first(); + $user = User::where('name', '=', 'Jane Doe')->first(); $client = Client::Where('name', '=', 'Buffet Bar Inc.')->first(); // Check the models are what they should be @@ -213,7 +213,7 @@ public function testBelongsToMany(): void $user->clients()->attach($client); // Get the new user model - $user = User::where('name', '=', 'Jane Doe')->first(); + $user = User::where('name', '=', 'Jane Doe')->first(); $client = Client::Where('name', '=', 'Buffet Bar Inc.')->first(); // Assert they are attached @@ -226,7 +226,7 @@ public function testBelongsToMany(): void $user->clients()->sync([]); // Get the new user model - $user = User::where('name', '=', 'Jane Doe')->first(); + $user = User::where('name', '=', 'Jane Doe')->first(); $client = Client::Where('name', '=', 'Buffet Bar Inc.')->first(); // Assert they are not attached @@ -278,7 +278,7 @@ public function testBelongsToManyAttachesExistingModels(): void public function testBelongsToManySync(): void { // create test instances - $user = User::create(['name' => 'John Doe']); + $user = User::create(['name' => 'John Doe']); $client1 = Client::create(['name' => 'Pork Pies Ltd.'])->_id; $client2 = Client::create(['name' => 'Buffet Bar Inc.'])->_id; @@ -296,7 +296,7 @@ public function testBelongsToManySync(): void public function testBelongsToManyAttachArray(): void { - $user = User::create(['name' => 'John Doe']); + $user = User::create(['name' => 'John Doe']); $client1 = Client::create(['name' => 'Test 1'])->_id; $client2 = Client::create(['name' => 'Test 2'])->_id; @@ -308,8 +308,8 @@ public function testBelongsToManyAttachArray(): void public function testBelongsToManyAttachEloquentCollection(): void { User::create(['name' => 'John Doe']); - $client1 = Client::create(['name' => 'Test 1']); - $client2 = Client::create(['name' => 'Test 2']); + $client1 = Client::create(['name' => 'Test 1']); + $client2 = Client::create(['name' => 'Test 2']); $collection = new Collection([$client1, $client2]); $user = User::where('name', '=', 'John Doe')->first(); @@ -319,7 +319,7 @@ public function testBelongsToManyAttachEloquentCollection(): void public function testBelongsToManySyncAlreadyPresent(): void { - $user = User::create(['name' => 'John Doe']); + $user = User::create(['name' => 'John Doe']); $client1 = Client::create(['name' => 'Test 1'])->_id; $client2 = Client::create(['name' => 'Test 2'])->_id; @@ -336,11 +336,11 @@ public function testBelongsToManySyncAlreadyPresent(): void public function testBelongsToManyCustom(): void { - $user = User::create(['name' => 'John Doe']); + $user = User::create(['name' => 'John Doe']); $group = $user->groups()->create(['name' => 'Admins']); // Refetch - $user = User::find($user->_id); + $user = User::find($user->_id); $group = Group::find($group->_id); // Check for custom relation attributes @@ -356,7 +356,7 @@ public function testBelongsToManyCustom(): void public function testMorph(): void { - $user = User::create(['name' => 'John Doe']); + $user = User::create(['name' => 'John Doe']); $client = Client::create(['name' => 'Jane Doe']); $photo = Photo::create(['url' => 'http://graph.facebook.com/john.doe/picture']); @@ -382,12 +382,12 @@ public function testMorph(): void $photo = Photo::first(); $this->assertEquals($photo->hasImage->name, $user->name); - $user = User::with('photos')->find($user->_id); + $user = User::with('photos')->find($user->_id); $relations = $user->getRelations(); $this->assertArrayHasKey('photos', $relations); $this->assertEquals(1, $relations['photos']->count()); - $photos = Photo::with('hasImage')->get(); + $photos = Photo::with('hasImage')->get(); $relations = $photos[0]->getRelations(); $this->assertArrayHasKey('hasImage', $relations); $this->assertInstanceOf(User::class, $photos[0]->hasImage); @@ -498,7 +498,7 @@ public function testNestedKeys(): void public function testDoubleSaveOneToMany(): void { $author = User::create(['name' => 'George R. R. Martin']); - $book = Book::create(['title' => 'A Game of Thrones']); + $book = Book::create(['title' => 'A Game of Thrones']); $author->books()->save($book); $author->books()->save($book); @@ -507,7 +507,7 @@ public function testDoubleSaveOneToMany(): void $this->assertEquals($author->_id, $book->author_id); $author = User::where('name', 'George R. R. Martin')->first(); - $book = Book::where('title', 'A Game of Thrones')->first(); + $book = Book::where('title', 'A Game of Thrones')->first(); $this->assertEquals(1, $author->books()->count()); $this->assertEquals($author->_id, $book->author_id); @@ -520,7 +520,7 @@ public function testDoubleSaveOneToMany(): void public function testDoubleSaveManyToMany(): void { - $user = User::create(['name' => 'John Doe']); + $user = User::create(['name' => 'John Doe']); $client = Client::create(['name' => 'Admins']); $user->clients()->save($client); @@ -531,7 +531,7 @@ public function testDoubleSaveManyToMany(): void $this->assertEquals([$user->_id], $client->user_ids); $this->assertEquals([$client->_id], $user->client_ids); - $user = User::where('name', 'John Doe')->first(); + $user = User::where('name', 'John Doe')->first(); $client = Client::where('name', 'Admins')->first(); $this->assertEquals(1, $user->clients()->count()); $this->assertEquals([$user->_id], $client->user_ids); diff --git a/tests/Seeder/DatabaseSeeder.php b/tests/Seeder/DatabaseSeeder.php index 27e4468ad..ef512b869 100644 --- a/tests/Seeder/DatabaseSeeder.php +++ b/tests/Seeder/DatabaseSeeder.php @@ -1,5 +1,7 @@ run(); $user = User::where('name', 'John Doe')->first(); diff --git a/tests/TestCase.php b/tests/TestCase.php index 0efddb4ce..f54c01405 100644 --- a/tests/TestCase.php +++ b/tests/TestCase.php @@ -13,12 +13,15 @@ use MongoDB\Laravel\Validation\ValidationServiceProvider; use Orchestra\Testbench\TestCase as OrchestraTestCase; +use function array_search; + class TestCase extends OrchestraTestCase { /** * Get application providers. * - * @param Application $app + * @param Application $app + * * @return array */ protected function getApplicationProviders($app) @@ -33,7 +36,8 @@ protected function getApplicationProviders($app) /** * Get package providers. * - * @param Application $app + * @param Application $app + * * @return array */ protected function getPackageProviders($app) @@ -49,7 +53,8 @@ protected function getPackageProviders($app) /** * Define environment setup. * - * @param Application $app + * @param Application $app + * * @return void */ protected function getEnvironmentSetUp($app) diff --git a/tests/TransactionTest.php b/tests/TransactionTest.php index 707c0b977..1086171d7 100644 --- a/tests/TransactionTest.php +++ b/tests/TransactionTest.php @@ -1,5 +1,7 @@ 'klinson', 'age' => 20, 'title' => 'admin']); + $this->assertInstanceOf(User::class, $klinson); DB::commit(); $this->assertInstanceOf(Model::class, $klinson); @@ -50,8 +52,8 @@ public function testCreateWithCommit(): void public function testCreateRollBack(): void { DB::beginTransaction(); - /** @var User $klinson */ $klinson = User::create(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + $this->assertInstanceOf(User::class, $klinson); DB::rollBack(); $this->assertInstanceOf(Model::class, $klinson); @@ -82,8 +84,8 @@ public function testInsertWithRollBack(): void public function testEloquentCreateWithCommit(): void { DB::beginTransaction(); - /** @var User $klinson */ $klinson = User::getModel(); + $this->assertInstanceOf(User::class, $klinson); $klinson->name = 'klinson'; $klinson->save(); DB::commit(); @@ -99,8 +101,8 @@ public function testEloquentCreateWithCommit(): void public function testEloquentCreateWithRollBack(): void { DB::beginTransaction(); - /** @var User $klinson */ $klinson = User::getModel(); + $this->assertInstanceOf(User::class, $klinson); $klinson->name = 'klinson'; $klinson->save(); DB::rollBack(); @@ -159,10 +161,10 @@ public function testUpdateWithRollback(): void public function testEloquentUpdateWithCommit(): void { - /** @var User $klinson */ $klinson = User::create(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); - /** @var User $alcaeus */ + $this->assertInstanceOf(User::class, $klinson); $alcaeus = User::create(['name' => 'alcaeus', 'age' => 38, 'title' => 'admin']); + $this->assertInstanceOf(User::class, $alcaeus); DB::beginTransaction(); $klinson->age = 21; @@ -180,10 +182,10 @@ public function testEloquentUpdateWithCommit(): void public function testEloquentUpdateWithRollBack(): void { - /** @var User $klinson */ $klinson = User::create(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); - /** @var User $alcaeus */ + $this->assertInstanceOf(User::class, $klinson); $alcaeus = User::create(['name' => 'klinson', 'age' => 38, 'title' => 'admin']); + $this->assertInstanceOf(User::class, $alcaeus); DB::beginTransaction(); $klinson->age = 21; @@ -225,8 +227,8 @@ public function testDeleteWithRollBack(): void public function testEloquentDeleteWithCommit(): void { - /** @var User $klinson */ $klinson = User::create(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + $this->assertInstanceOf(User::class, $klinson); DB::beginTransaction(); $klinson->delete(); @@ -237,8 +239,8 @@ public function testEloquentDeleteWithCommit(): void public function testEloquentDeleteWithRollBack(): void { - /** @var User $klinson */ $klinson = User::create(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + $this->assertInstanceOf(User::class, $klinson); DB::beginTransaction(); $klinson->delete(); @@ -349,7 +351,7 @@ public function testTransactionRepeatsOnTransientFailure(): void User::create(['name' => 'alcaeus', 'age' => 38, 'title' => 'admin']); // Update user outside of the session - if ($timesRun == 1) { + if ($timesRun === 1) { DB::getCollection('users')->updateOne(['name' => 'klinson'], ['$set' => ['age' => 22]]); } diff --git a/tests/ValidationTest.php b/tests/ValidationTest.php index c0521bfaa..d5122ce7b 100644 --- a/tests/ValidationTest.php +++ b/tests/ValidationTest.php @@ -18,7 +18,7 @@ public function testUnique(): void { $validator = Validator::make( ['name' => 'John Doe'], - ['name' => 'required|unique:users'] + ['name' => 'required|unique:users'], ); $this->assertFalse($validator->fails()); @@ -26,31 +26,31 @@ public function testUnique(): void $validator = Validator::make( ['name' => 'John Doe'], - ['name' => 'required|unique:users'] + ['name' => 'required|unique:users'], ); $this->assertTrue($validator->fails()); $validator = Validator::make( ['name' => 'John doe'], - ['name' => 'required|unique:users'] + ['name' => 'required|unique:users'], ); $this->assertTrue($validator->fails()); $validator = Validator::make( ['name' => 'john doe'], - ['name' => 'required|unique:users'] + ['name' => 'required|unique:users'], ); $this->assertTrue($validator->fails()); $validator = Validator::make( ['name' => 'test doe'], - ['name' => 'required|unique:users'] + ['name' => 'required|unique:users'], ); $this->assertFalse($validator->fails()); $validator = Validator::make( ['name' => 'John'], // Part of an existing value - ['name' => 'required|unique:users'] + ['name' => 'required|unique:users'], ); $this->assertFalse($validator->fails()); @@ -58,19 +58,19 @@ public function testUnique(): void $validator = Validator::make( ['email' => 'johnny.cash+200@gmail.com'], - ['email' => 'required|unique:users'] + ['email' => 'required|unique:users'], ); $this->assertTrue($validator->fails()); $validator = Validator::make( ['email' => 'johnny.cash+20@gmail.com'], - ['email' => 'required|unique:users'] + ['email' => 'required|unique:users'], ); $this->assertFalse($validator->fails()); $validator = Validator::make( ['email' => 'johnny.cash+1@gmail.com'], - ['email' => 'required|unique:users'] + ['email' => 'required|unique:users'], ); $this->assertFalse($validator->fails()); } @@ -79,7 +79,7 @@ public function testExists(): void { $validator = Validator::make( ['name' => 'John Doe'], - ['name' => 'required|exists:users'] + ['name' => 'required|exists:users'], ); $this->assertTrue($validator->fails()); @@ -88,37 +88,37 @@ public function testExists(): void $validator = Validator::make( ['name' => 'John Doe'], - ['name' => 'required|exists:users'] + ['name' => 'required|exists:users'], ); $this->assertFalse($validator->fails()); $validator = Validator::make( ['name' => 'john Doe'], - ['name' => 'required|exists:users'] + ['name' => 'required|exists:users'], ); $this->assertFalse($validator->fails()); $validator = Validator::make( ['name' => ['test name', 'john doe']], - ['name' => 'required|exists:users'] + ['name' => 'required|exists:users'], ); $this->assertFalse($validator->fails()); $validator = Validator::make( ['name' => ['test name', 'john']], // Part of an existing value - ['name' => 'required|exists:users'] + ['name' => 'required|exists:users'], ); $this->assertTrue($validator->fails()); $validator = Validator::make( ['name' => '(invalid regex{'], - ['name' => 'required|exists:users'] + ['name' => 'required|exists:users'], ); $this->assertTrue($validator->fails()); $validator = Validator::make( ['name' => ['foo', '(invalid regex{']], - ['name' => 'required|exists:users'] + ['name' => 'required|exists:users'], ); $this->assertTrue($validator->fails()); @@ -126,7 +126,7 @@ public function testExists(): void $validator = Validator::make( ['name' => []], - ['name' => 'exists:users'] + ['name' => 'exists:users'], ); $this->assertFalse($validator->fails()); } diff --git a/tests/config/database.php b/tests/config/database.php index 498e4e7e0..24fee24f4 100644 --- a/tests/config/database.php +++ b/tests/config/database.php @@ -1,5 +1,7 @@ [ 'mongodb' => [ diff --git a/tests/config/queue.php b/tests/config/queue.php index d287780e9..613e0867e 100644 --- a/tests/config/queue.php +++ b/tests/config/queue.php @@ -1,5 +1,7 @@ env('QUEUE_CONNECTION'), From f5f93a330a9407ef7484b69191a028ea2f909aa5 Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Fri, 8 Sep 2023 15:10:49 +0200 Subject: [PATCH 099/446] PHPORM-83: Document release process (#2604) * PHPORM-83: Document release process * Update branch-alias in composer.json * Use correct identifier for laravel versions * Apply review feedback --- CONTRIBUTING.md | 7 +- RELEASING.md | 190 ++++++++++++++++++++++++++++++++++++++++++++++++ composer.json | 3 + 3 files changed, 199 insertions(+), 1 deletion(-) create mode 100644 RELEASING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2587ca24c..9f7202a59 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -52,4 +52,9 @@ If the project maintainer has any additional requirements, you will find them li - **Send coherent history** - Make sure each individual commit in your pull request is meaningful. If you had to make multiple intermediate commits while developing, please [squash them](https://www.git-scm.com/book/en/v2/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages) before submitting. -**Happy coding**! \ No newline at end of file +Happy coding! + +## Releasing + +The releases are created by the maintainers of the library. The process is documented in +the [RELEASING.md](RELEASING.md) file. diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 000000000..35dfbf342 --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,190 @@ +# Releasing + +The following steps outline the release process for both new minor versions (e.g. +releasing the `master` branch as X.Y.0) and patch versions (e.g. releasing the +`vX.Y` branch as X.Y.Z). + +The command examples below assume that the canonical "mongodb" repository has +the remote name "mongodb". You may need to adjust these commands if you've given +the remote another name (e.g. "upstream"). The "origin" remote name was not used +as it likely refers to your personal fork. + +It helps to keep your own fork in sync with the "mongodb" repository (i.e. any +branches and tags on the main repository should also exist in your fork). This +is left as an exercise to the reader. + +## Ensure PHP version compatibility + +Ensure that the test suite completes on supported versions of PHP. + +## Transition JIRA issues and version + +All issues associated with the release version should be in the "Closed" state +and have a resolution of "Fixed". Issues with other resolutions (e.g. +"Duplicate", "Works as Designed") should be removed from the release version so +that they do not appear in the release notes. + +Check the corresponding "laravel-*.x" fix version to see if it contains any +issues that are resolved as "Fixed" and should be included in this release +version. + +Update the version's release date and status from the +[Manage Versions](https://jira.mongodb.org/plugins/servlet/project-config/PHPORM/versions) +page. + +## Update version info + +This uses [semantic versioning](https://semver.org/). Do not break +backwards compatibility in a non-major release or your users will kill you. + +Before proceeding, ensure that the `master` branch is up-to-date with all code +changes in this maintenance branch. This is important because we will later +merge the ensuing release commits up to master with `--strategy=ours`, which +will ignore changes from the merged commits. + +## Update composer.json + +This is especially important before releasing a new minor version. + +Ensure that the extension and PHP library requirements, as well as the branch +alias in `composer.json` are correct for the version being released. For +example, the branch alias for the 4.1.0 release in the `master` branch should +be `4.1.x-dev`. + +Commit and push any changes: + +```console +$ git commit -m "Update composer.json X.Y.Z" composer.json +$ git push mongodb +``` + +## Tag the release + +Create a tag for the release and push: + +```console +$ git tag -a -m "Release X.Y.Z" X.Y.Z +$ git push mongodb --tags +``` + +## Branch management + +# Creating a maintenance branch and updating master branch alias + +After releasing a new major or minor version (e.g. 4.0.0), a maintenance branch +(e.g. v4.0) should be created. Any development towards a patch release (e.g. +4.0.1) would then be done within that branch and any development for the next +major or minor release can continue in master. + +After creating a maintenance branch, the `extra.branch-alias.dev-master` field +in the master branch's `composer.json` file should be updated. For example, +after branching v4.0, `composer.json` in the master branch may still read: + +``` +"branch-alias": { + "dev-master": "4.0.x-dev" +} +``` + +The above would be changed to: + +``` +"branch-alias": { + "dev-master": "4.1.x-dev" +} +``` + +Commit this change: + +```console +$ git commit -m "Master is now 4.1-dev" composer.json +``` + +### After releasing a new minor version + +After a new minor version is released (i.e. `master` was tagged), a maintenance +branch should be created for future patch releases: + +```console +$ git checkout -b vX.Y +$ git push mongodb vX.Y +``` + +Update the master branch alias in `composer.json`: + +```diff + "extra": { + "branch-alias": { +- "dev-master": "4.0.x-dev" ++ "dev-master": "4.1.x-dev" + } + }, +``` + +Commit and push this change: + +```console +$ git commit -m "Master is now X.Y-dev" composer.json +$ git push mongodb +``` + +### After releasing a patch version + +If this was a patch release, the maintenance branch must be merged up to master: + +```console +$ git checkout master +$ git pull mongodb master +$ git merge vX.Y --strategy=ours +$ git push mongodb +``` + +The `--strategy=ours` option ensures that all changes from the merged commits +will be ignored. This is OK because we previously ensured that the `master` +branch was up-to-date with all code changes in this maintenance branch before +tagging. + + +## Publish release notes + +The following template should be used for creating GitHub release notes via +[this form](https://github.com/mongodb/laravel-mongodb/releases/new). + +```markdown +The PHP team is happy to announce that version X.Y.Z of the MongoDB integration for Laravel is now available. + +**Release Highlights** + + + +A complete list of resolved issues in this release may be found in [JIRA]($JIRA_URL). + +**Documentation** + +Documentation for this library may be found in the [Readme](https://github.com/mongodb/laravel-mongodb/blob/$VERSION/README.md). + +**Installation** + +This library may be installed or upgraded with: + + composer require mongodb/laravel-mongodb:X.Y.Z + +Installation instructions for the `mongodb` extension may be found in the [PHP.net documentation](https://php.net/manual/en/mongodb.installation.php). +``` + +The URL for the list of resolved JIRA issues will need to be updated with each +release. You may obtain the list from +[this form](https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=22488). + +If commits from community contributors were included in this release, append the +following section: + +```markdown +**Thanks** + +Thanks for our community contributors for this release: + + * [$CONTRIBUTOR_NAME](https://github.com/$GITHUB_USERNAME) +``` + +Release announcements should also be posted in the [MongoDB Product & Driver Announcements: Driver Releases](https://mongodb.com/community/forums/tags/c/announcements/driver-releases/110/php) forum and shared on Twitter. diff --git a/composer.json b/composer.json index eb0ac3d9e..6a4ac97aa 100644 --- a/composer.json +++ b/composer.json @@ -50,6 +50,9 @@ } }, "extra": { + "branch-alias": { + "dev-master": "4.0.x-dev" + }, "laravel": { "providers": [ "MongoDB\\Laravel\\MongodbServiceProvider", From b55e5dabc7974687f5c31aa989d148a9c502483f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 11 Sep 2023 10:02:48 +0200 Subject: [PATCH 100/446] PHPORM-31 Split documentation into multiple files (#2610) Split readme into smaller files to helps the reader. Fix letter case of MongoDBServiceProvider Add more details in the new upgrade file Update contributing docs and fix the docker config to avoid php version conflicts in docker --- .codacy.yml | 2 - .styleci.yml | 2 - CONTRIBUTING.md | 28 +- Dockerfile | 10 +- README.md | 1232 +---------------- composer.json | 7 +- docs/eloquent-models.md | 464 +++++++ docs/install.md | 64 + docs/query-builder.md | 530 +++++++ docs/queues.md | 34 + docs/transactions.md | 56 + docs/upgrade.md | 19 + docs/user-authentication.md | 15 + ...er.php => MongoDBQueueServiceProvider.php} | 2 +- ...rovider.php => MongoDBServiceProvider.php} | 2 +- tests/TestCase.php | 8 +- 16 files changed, 1249 insertions(+), 1226 deletions(-) delete mode 100644 .codacy.yml delete mode 100644 .styleci.yml create mode 100644 docs/eloquent-models.md create mode 100644 docs/install.md create mode 100644 docs/query-builder.md create mode 100644 docs/queues.md create mode 100644 docs/transactions.md create mode 100644 docs/upgrade.md create mode 100644 docs/user-authentication.md rename src/{MongodbQueueServiceProvider.php => MongoDBQueueServiceProvider.php} (96%) rename src/{MongodbServiceProvider.php => MongoDBServiceProvider.php} (95%) diff --git a/.codacy.yml b/.codacy.yml deleted file mode 100644 index 59b32a797..000000000 --- a/.codacy.yml +++ /dev/null @@ -1,2 +0,0 @@ -exclude_paths: - - '.github/**' diff --git a/.styleci.yml b/.styleci.yml deleted file mode 100644 index c579f8e80..000000000 --- a/.styleci.yml +++ /dev/null @@ -1,2 +0,0 @@ -risky: true -preset: laravel diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9f7202a59..096fd8a06 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,6 +36,32 @@ Before submitting a pull request: - Check the codebase to ensure that your feature doesn't already exist. - Check the pull requests to ensure that another person hasn't already submitted the feature or fix. +## Run Tests + +The full test suite requires PHP cli with mongodb extension, a running MongoDB server and a running MySQL server. +Tests requiring MySQL will be skipped if it is not running. +Duplicate the `phpunit.xml.dist` file to `phpunit.xml` and edit the environment variables to match your setup. + +```bash +$ docker-compose up -d mongodb mysql +$ docker-compose run tests +``` + +Docker can be slow to start. You can run the command `php vendor/bin/phpunit --testdox` locally or in a docker container. + +```bash +$ docker-compose run -it tests bash +# Inside the container +$ composer install +$ vendor/bin/phpunit --testdox +``` + +For fixing style issues, you can run the PHP Code Beautifier and Fixer: + +```bash +$ php vendor/bin/phpcbf +``` + ## Requirements If the project maintainer has any additional requirements, you will find them listed here. @@ -44,7 +70,7 @@ If the project maintainer has any additional requirements, you will find them li - **Add tests!** - Your patch won't be accepted if it doesn't have tests. -- **Document any change in behaviour** - Make sure the `README.md` and any other relevant documentation are kept up-to-date. +- **Document any change in behaviour** - Make sure the documentation is kept up-to-date. - **Consider our release cycle** - We try to follow [SemVer v2.0.0](https://semver.org/). Randomly breaking public APIs is not an option. diff --git a/Dockerfile b/Dockerfile index d13553499..49a2ce736 100644 --- a/Dockerfile +++ b/Dockerfile @@ -8,14 +8,12 @@ RUN apt-get update && \ pecl install xdebug && docker-php-ext-enable xdebug && \ docker-php-ext-install -j$(nproc) pdo_mysql zip -COPY --from=composer:2.5.8 /usr/bin/composer /usr/local/bin/composer +COPY --from=composer:2.6.2 /usr/bin/composer /usr/local/bin/composer + +ENV COMPOSER_ALLOW_SUPERUSER=1 WORKDIR /code COPY ./ ./ -ENV COMPOSER_ALLOW_SUPERUSER=1 - -RUN composer install - -CMD ["./vendor/bin/phpunit", "--testdox"] +CMD ["bash", "-c", "composer install && ./vendor/bin/phpunit --testdox"] diff --git a/README.md b/README.md index e5e599cfd..b8ab3c893 100644 --- a/README.md +++ b/README.md @@ -4,1221 +4,39 @@ Laravel MongoDB [![Latest Stable Version](http://img.shields.io/github/release/mongodb/laravel-mongodb.svg)](https://packagist.org/packages/mongodb/laravel-mongodb) [![Total Downloads](http://img.shields.io/packagist/dm/mongodb/laravel-mongodb.svg)](https://packagist.org/packages/mongodb/laravel-mongodb) [![Build Status](https://img.shields.io/github/workflow/status/mongodb/laravel-mongodb/CI)](https://github.com/mongodb/laravel-mongodb/actions) -[![codecov](https://codecov.io/gh/mongodb/laravel-mongodb/branch/master/graph/badge.svg)](https://codecov.io/gh/mongodb/laravel-mongodb/branch/master) -This package adds functionalities to the Eloquent model and Query builder for MongoDB, using the original Laravel API. *This library extends the original Laravel classes, so it uses exactly the same methods.* +This package adds functionalities to the Eloquent model and Query builder for MongoDB, using the original Laravel API. +*This library extends the original Laravel classes, so it uses exactly the same methods.* This package was renamed to `mongodb/laravel-mongodb` because of a transfer of ownership to MongoDB, Inc. -It is compatible with Laravel 10.x. For older versions of Laravel, please refer to the [old versions](https://github.com/mongodb/laravel-mongodb/tree/3.9#laravel-version-compatibility). +It is compatible with Laravel 10.x. For older versions of Laravel, please refer to the +[old versions](https://github.com/mongodb/laravel-mongodb/tree/3.9#laravel-version-compatibility). -- [Laravel MongoDB](#laravel-mongodb) - - [Installation](#installation) - - [Testing](#testing) - - [Database Testing](#database-testing) - - [Configuration](#configuration) - - [Eloquent](#eloquent) - - [Extending the base model](#extending-the-base-model) - - [Extending the Authenticable base model](#extending-the-authenticable-base-model) - - [Soft Deletes](#soft-deletes) - - [Guarding attributes](#guarding-attributes) - - [Dates](#dates) - - [Basic Usage](#basic-usage) - - [MongoDB-specific operators](#mongodb-specific-operators) - - [MongoDB-specific Geo operations](#mongodb-specific-geo-operations) - - [Inserts, updates and deletes](#inserts-updates-and-deletes) - - [MongoDB specific operations](#mongodb-specific-operations) - - [Relationships](#relationships) - - [Basic Usage](#basic-usage-1) - - [belongsToMany and pivots](#belongstomany-and-pivots) - - [EmbedsMany Relationship](#embedsmany-relationship) - - [EmbedsOne Relationship](#embedsone-relationship) - - [Query Builder](#query-builder) - - [Basic Usage](#basic-usage-2) - - [Available operations](#available-operations) - - [Transactions](#transactions) - - [Basic Usage](#basic-usage-3) - - [Schema](#schema) - - [Basic Usage](#basic-usage-4) - - [Geospatial indexes](#geospatial-indexes) - - [Extending](#extending) - - [Cross-Database Relationships](#cross-database-relationships) - - [Authentication](#authentication) - - [Queues](#queues) - - [Prunable](#prunable) - - [Upgrading](#upgrading) - - [Upgrading from version 2 to 3](#upgrading-from-version-2-to-3) - - [Security contact information](#security-contact-information) +- [Installation](docs/install.md) +- [Eloquent Models](docs/eloquent-models.md) +- [Query Builder](docs/query-builder.md) +- [Transactions](docs/transactions.md) +- [User Authentication](docs/authentication.md) +- [Queues](docs/queues.md) +- [Upgrading](docs/upgrade.md) -Installation ------------- +## Reporting Issues -Make sure you have the MongoDB PHP driver installed. You can find installation instructions at https://php.net/manual/en/mongodb.installation.php +Issues pertaining to the library should be reported as +[GitHub Issue](https://github.com/mongodb/laravel-mongodb/issues/new/choose). -Install the package via Composer: +For general questions and support requests, please use one of MongoDB's +[Technical Support](https://mongodb.com/docs/manual/support/) channels. -```bash -$ composer require mongodb/laravel-mongodb -``` +### Security Vulnerabilities -In case your Laravel version does NOT autoload the packages, add the service provider to `config/app.php`: +If you've identified a security vulnerability in a driver or any other MongoDB +project, please report it according to the instructions in +[Create a Vulnerability Report](https://mongodb.com/docs/manual/tutorial/create-a-vulnerability-report). -```php -MongoDB\Laravel\MongodbServiceProvider::class, -``` +## Development -Testing -------- - -To run the test for this package, run: - -``` -docker-compose up -``` - -Database Testing -------- - -To reset the database after each test, add: - -```php -use Illuminate\Foundation\Testing\DatabaseMigrations; -``` - -Also inside each test classes, add: - -```php -use DatabaseMigrations; -``` - -Keep in mind that these traits are not yet supported: - -- `use Database Transactions;` -- `use RefreshDatabase;` - -Configuration -------------- - -To configure a new MongoDB connection, add a new connection entry to `config/database.php`: - -```php -'mongodb' => [ - 'driver' => 'mongodb', - 'dsn' => env('DB_DSN'), - 'database' => env('DB_DATABASE', 'homestead'), -], -``` - -The `dsn` key contains the connection string used to connect to your MongoDB deployment. The format and available options are documented in the [MongoDB documentation](https://docs.mongodb.com/manual/reference/connection-string/). - -Instead of using a connection string, you can also use the `host` and `port` configuration options to have the connection string created for you. - -```php -'mongodb' => [ - 'driver' => 'mongodb', - 'host' => env('DB_HOST', '127.0.0.1'), - 'port' => env('DB_PORT', 27017), - 'database' => env('DB_DATABASE', 'homestead'), - 'username' => env('DB_USERNAME', 'homestead'), - 'password' => env('DB_PASSWORD', 'secret'), - 'options' => [ - 'appname' => 'homestead', - ], -], -``` - -The `options` key in the connection configuration corresponds to the [`uriOptions` parameter](https://www.php.net/manual/en/mongodb-driver-manager.construct.php#mongodb-driver-manager.construct-urioptions). - -Eloquent --------- - -### Extending the base model - -This package includes a MongoDB enabled Eloquent class that you can use to define models for corresponding collections. - -```php -use MongoDB\Laravel\Eloquent\Model; - -class Book extends Model -{ - // -} -``` - -Just like a normal model, the MongoDB model class will know which collection to use based on the model name. For `Book`, the collection `books` will be used. - -To change the collection, pass the `$collection` property: - -```php -use MongoDB\Laravel\Eloquent\Model; - -class Book extends Model -{ - protected $collection = 'my_books_collection'; -} -``` - -**NOTE:** MongoDB documents are automatically stored with a unique ID that is stored in the `_id` property. If you wish to use your own ID, substitute the `$primaryKey` property and set it to your own primary key attribute name. - -```php -use MongoDB\Laravel\Eloquent\Model; - -class Book extends Model -{ - protected $primaryKey = 'id'; -} - -// MongoDB will also create _id, but the 'id' property will be used for primary key actions like find(). -Book::create(['id' => 1, 'title' => 'The Fault in Our Stars']); -``` - -Likewise, you may define a `connection` property to override the name of the database connection that should be used when utilizing the model. - -```php -use MongoDB\Laravel\Eloquent\Model; - -class Book extends Model -{ - protected $connection = 'mongodb'; -} -``` - -### Extending the Authenticatable base model - -This package includes a MongoDB Authenticatable Eloquent class `MongoDB\Laravel\Auth\User` that you can use to replace the default Authenticatable class `Illuminate\Foundation\Auth\User` for your `User` model. - -```php -use MongoDB\Laravel\Auth\User as Authenticatable; - -class User extends Authenticatable -{ - -} -``` - -### Soft Deletes - -When soft deleting a model, it is not actually removed from your database. Instead, a deleted_at timestamp is set on the record. - -To enable soft deletes for a model, apply the `MongoDB\Laravel\Eloquent\SoftDeletes` Trait to the model: - -```php -use MongoDB\Laravel\Eloquent\SoftDeletes; - -class User extends Model -{ - use SoftDeletes; -} -``` - -For more information check [Laravel Docs about Soft Deleting](http://laravel.com/docs/eloquent#soft-deleting). - -### Guarding attributes - -When choosing between guarding attributes or marking some as fillable, Taylor Otwell prefers the fillable route. -This is in light of [recent security issues described here](https://blog.laravel.com/security-release-laravel-61835-7240). - -Keep in mind guarding still works, but you may experience unexpected behavior. - -### Dates - -Eloquent allows you to work with Carbon or DateTime objects instead of MongoDate objects. Internally, these dates will be converted to MongoDate objects when saved to the database. - -```php -use MongoDB\Laravel\Eloquent\Model; - -class User extends Model -{ - protected $casts = ['birthday' => 'datetime']; -} -``` - -This allows you to execute queries like this: - -```php -$users = User::where( - 'birthday', '>', - new DateTime('-18 years') -)->get(); -``` - -### Basic Usage - -**Retrieving all models** - -```php -$users = User::all(); -``` - -**Retrieving a record by primary key** - -```php -$user = User::find('517c43667db388101e00000f'); -``` - -**Where** - -```php -$posts = - Post::where('author.name', 'John') - ->take(10) - ->get(); -``` - -**OR Statements** - -```php -$posts = - Post::where('votes', '>', 0) - ->orWhere('is_approved', true) - ->get(); -``` - -**AND statements** - -```php -$users = - User::where('age', '>', 18) - ->where('name', '!=', 'John') - ->get(); -``` - -**NOT statements** - -```php -$users = User::whereNot('age', '>', 18)->get(); -``` - -**whereIn** - -```php -$users = User::whereIn('age', [16, 18, 20])->get(); -``` - -When using `whereNotIn` objects will be returned if the field is non-existent. Combine with `whereNotNull('age')` to leave out those documents. - -**whereBetween** - -```php -$posts = Post::whereBetween('votes', [1, 100])->get(); -``` - -**whereNull** - -```php -$users = User::whereNull('age')->get(); -``` - -**whereDate** - -```php -$users = User::whereDate('birthday', '2021-5-12')->get(); -``` - -The usage is the same as `whereMonth` / `whereDay` / `whereYear` / `whereTime` - -**Advanced wheres** - -```php -$users = - User::where('name', 'John') - ->orWhere(function ($query) { - return $query - ->where('votes', '>', 100) - ->where('title', '<>', 'Admin'); - })->get(); -``` - -**orderBy** - -```php -$users = User::orderBy('age', 'desc')->get(); -``` - -**Offset & Limit (skip & take)** - -```php -$users = - User::skip(10) - ->take(5) - ->get(); -``` - -**groupBy** - -Selected columns that are not grouped will be aggregated with the `$last` function. - -```php -$users = - Users::groupBy('title') - ->get(['title', 'name']); -``` - -**Distinct** - -Distinct requires a field for which to return the distinct values. - -```php -$users = User::distinct()->get(['name']); - -// Equivalent to: -$users = User::distinct('name')->get(); -``` - -Distinct can be combined with **where**: - -```php -$users = - User::where('active', true) - ->distinct('name') - ->get(); -``` - -**Like** - -```php -$spamComments = Comment::where('body', 'like', '%spam%')->get(); -``` - -**Aggregation** - -**Aggregations are only available for MongoDB versions greater than 2.2.x** - -```php -$total = Product::count(); -$price = Product::max('price'); -$price = Product::min('price'); -$price = Product::avg('price'); -$total = Product::sum('price'); -``` - -Aggregations can be combined with **where**: - -```php -$sold = Orders::where('sold', true)->sum('price'); -``` - -Aggregations can be also used on sub-documents: - -```php -$total = Order::max('suborder.price'); -``` - -**NOTE**: This aggregation only works with single sub-documents (like `EmbedsOne`) not subdocument arrays (like `EmbedsMany`). - -**Incrementing/Decrementing the value of a column** - -Perform increments or decrements (default 1) on specified attributes: - -```php -Cat::where('name', 'Kitty')->increment('age'); - -Car::where('name', 'Toyota')->decrement('weight', 50); -``` - -The number of updated objects is returned: - -```php -$count = User::increment('age'); -``` - -You may also specify additional columns to update: - -```php -Cat::where('age', 3) - ->increment('age', 1, ['group' => 'Kitty Club']); - -Car::where('weight', 300) - ->decrement('weight', 100, ['latest_change' => 'carbon fiber']); -``` - -### MongoDB-specific operators - -In addition to the Laravel Eloquent operators, all available MongoDB query operators can be used with `where`: - -```php -User::where($fieldName, $operator, $value)->get(); -``` - -It generates the following MongoDB filter: -```ts -{ $fieldName: { $operator: $value } } -``` - -**Exists** - -Matches documents that have the specified field. - -```php -User::where('age', 'exists', true)->get(); -``` - -**All** - -Matches arrays that contain all elements specified in the query. - -```php -User::where('roles', 'all', ['moderator', 'author'])->get(); -``` - -**Size** - -Selects documents if the array field is a specified size. - -```php -Post::where('tags', 'size', 3)->get(); -``` - -**Regex** - -Selects documents where values match a specified regular expression. - -```php -use MongoDB\BSON\Regex; - -User::where('name', 'regex', new Regex('.*doe', 'i'))->get(); -``` - -**NOTE:** you can also use the Laravel regexp operations. These are a bit more flexible and will automatically convert your regular expression string to a `MongoDB\BSON\Regex` object. - -```php -User::where('name', 'regexp', '/.*doe/i')->get(); -``` - -The inverse of regexp: - -```php -User::where('name', 'not regexp', '/.*doe/i')->get(); -``` - -**Type** - -Selects documents if a field is of the specified type. For more information check: http://docs.mongodb.org/manual/reference/operator/query/type/#op._S_type - -```php -User::where('age', 'type', 2)->get(); -``` - -**Mod** - -Performs a modulo operation on the value of a field and selects documents with a specified result. - -```php -User::where('age', 'mod', [10, 0])->get(); -``` - -### MongoDB-specific Geo operations - -**Near** - -```php -$bars = Bar::where('location', 'near', [ - '$geometry' => [ - 'type' => 'Point', - 'coordinates' => [ - -0.1367563, // longitude - 51.5100913, // latitude - ], - ], - '$maxDistance' => 50, -])->get(); -``` - -**GeoWithin** - -```php -$bars = Bar::where('location', 'geoWithin', [ - '$geometry' => [ - 'type' => 'Polygon', - 'coordinates' => [ - [ - [-0.1450383, 51.5069158], - [-0.1367563, 51.5100913], - [-0.1270247, 51.5013233], - [-0.1450383, 51.5069158], - ], - ], - ], -])->get(); -``` - -**GeoIntersects** - -```php -$bars = Bar::where('location', 'geoIntersects', [ - '$geometry' => [ - 'type' => 'LineString', - 'coordinates' => [ - [-0.144044, 51.515215], - [-0.129545, 51.507864], - ], - ], -])->get(); -``` - -**GeoNear** - -You are able to make a `geoNear` query on mongoDB. -You don't need to specify the automatic fields on the model. -The returned instance is a collection. So you're able to make the [Collection](https://laravel.com/docs/9.x/collections) operations. -Just make sure that your model has a `location` field, and a [2ndSphereIndex](https://www.mongodb.com/docs/manual/core/2dsphere). -The data in the `location` field must be saved as [GeoJSON](https://www.mongodb.com/docs/manual/reference/geojson/). -The `location` points must be saved as [WGS84](https://www.mongodb.com/docs/manual/reference/glossary/#std-term-WGS84) reference system for geometry calculation. That means, basically, you need to save `longitude and latitude`, in that order specifically, and to find near with calculated distance, you `need to do the same way`. - -``` -Bar::find("63a0cd574d08564f330ceae2")->update( - [ - 'location' => [ - 'type' => 'Point', - 'coordinates' => [ - -0.1367563, - 51.5100913 - ] - ] - ] -); -$bars = Bar::raw(function ($collection) { - return $collection->aggregate([ - [ - '$geoNear' => [ - "near" => [ "type" => "Point", "coordinates" => [-0.132239, 51.511874] ], - "distanceField" => "dist.calculated", - "minDistance" => 0, - "maxDistance" => 6000, - "includeLocs" => "dist.location", - "spherical" => true, - ] - ] - ]); -}); -``` - -### Inserts, updates and deletes - -Inserting, updating and deleting records works just like the original Eloquent. Please check [Laravel Docs' Eloquent section](https://laravel.com/docs/6.x/eloquent). - -Here, only the MongoDB-specific operations are specified. - -### MongoDB specific operations - -**Raw Expressions** - -These expressions will be injected directly into the query. - -```php -User::whereRaw([ - 'age' => ['$gt' => 30, '$lt' => 40], -])->get(); - -User::whereRaw([ - '$where' => '/.*123.*/.test(this.field)', -])->get(); - -User::whereRaw([ - '$where' => '/.*123.*/.test(this["hyphenated-field"])', -])->get(); -``` - -You can also perform raw expressions on the internal MongoCollection object. If this is executed on the model class, it will return a collection of models. - -If this is executed on the query builder, it will return the original response. - -**Cursor timeout** - -To prevent `MongoCursorTimeout` exceptions, you can manually set a timeout value that will be applied to the cursor: - -```php -DB::collection('users')->timeout(-1)->get(); -``` - -**Upsert** - -Update or insert a document. Additional options for the update method are passed directly to the native update method. - -```php -// Query Builder -DB::collection('users') - ->where('name', 'John') - ->update($data, ['upsert' => true]); - -// Eloquent -$user->update($data, ['upsert' => true]); -``` - -**Projections** - -You can apply projections to your queries using the `project` method. - -```php -DB::collection('items') - ->project(['tags' => ['$slice' => 1]]) - ->get(); - -DB::collection('items') - ->project(['tags' => ['$slice' => [3, 7]]]) - ->get(); -``` - -**Projections with Pagination** - -```php -$limit = 25; -$projections = ['id', 'name']; - -DB::collection('items') - ->paginate($limit, $projections); -``` - -**Push** - -Add items to an array. - -```php -DB::collection('users') - ->where('name', 'John') - ->push('items', 'boots'); - -$user->push('items', 'boots'); -``` - -```php -DB::collection('users') - ->where('name', 'John') - ->push('messages', [ - 'from' => 'Jane Doe', - 'message' => 'Hi John', - ]); - -$user->push('messages', [ - 'from' => 'Jane Doe', - 'message' => 'Hi John', -]); -``` - -If you **DON'T** want duplicate items, set the third parameter to `true`: - -```php -DB::collection('users') - ->where('name', 'John') - ->push('items', 'boots', true); - -$user->push('items', 'boots', true); -``` - -**Pull** - -Remove an item from an array. - -```php -DB::collection('users') - ->where('name', 'John') - ->pull('items', 'boots'); - -$user->pull('items', 'boots'); -``` - -```php -DB::collection('users') - ->where('name', 'John') - ->pull('messages', [ - 'from' => 'Jane Doe', - 'message' => 'Hi John', - ]); - -$user->pull('messages', [ - 'from' => 'Jane Doe', - 'message' => 'Hi John', -]); -``` - -**Unset** - -Remove one or more fields from a document. - -```php -DB::collection('users') - ->where('name', 'John') - ->unset('note'); - -$user->unset('note'); -``` - -Relationships -------------- - -### Basic Usage - -The only available relationships are: - -- hasOne -- hasMany -- belongsTo -- belongsToMany - -The MongoDB-specific relationships are: - -- embedsOne -- embedsMany - -Here is a small example: - -```php -use MongoDB\Laravel\Eloquent\Model; - -class User extends Model -{ - public function items() - { - return $this->hasMany(Item::class); - } -} -``` - -The inverse relation of `hasMany` is `belongsTo`: - -```php -use MongoDB\Laravel\Eloquent\Model; - -class Item extends Model -{ - public function user() - { - return $this->belongsTo(User::class); - } -} -``` - -### belongsToMany and pivots - -The belongsToMany relation will not use a pivot "table" but will push id's to a __related_ids__ attribute instead. This makes the second parameter for the belongsToMany method useless. - -If you want to define custom keys for your relation, set it to `null`: - -```php -use MongoDB\Laravel\Eloquent\Model; - -class User extends Model -{ - public function groups() - { - return $this->belongsToMany( - Group::class, null, 'user_ids', 'group_ids' - ); - } -} -``` - -### EmbedsMany Relationship - -If you want to embed models, rather than referencing them, you can use the `embedsMany` relation. This relation is similar to the `hasMany` relation but embeds the models inside the parent object. - -**REMEMBER**: These relations return Eloquent collections, they don't return query builder objects! - -```php -use MongoDB\Laravel\Eloquent\Model; - -class User extends Model -{ - public function books() - { - return $this->embedsMany(Book::class); - } -} -``` - -You can access the embedded models through the dynamic property: - -```php -$user = User::first(); - -foreach ($user->books as $book) { - // -} -``` - -The inverse relation is auto*magically* available. You don't need to define this reverse relation. - -```php -$book = Book::first(); - -$user = $book->user; -``` - -Inserting and updating embedded models works similar to the `hasMany` relation: - -```php -$book = $user->books()->save( - new Book(['title' => 'A Game of Thrones']) -); - -// or -$book = - $user->books() - ->create(['title' => 'A Game of Thrones']); -``` - -You can update embedded models using their `save` method (available since release 2.0.0): - -```php -$book = $user->books()->first(); - -$book->title = 'A Game of Thrones'; -$book->save(); -``` - -You can remove an embedded model by using the `destroy` method on the relation, or the `delete` method on the model (available since release 2.0.0): - -```php -$book->delete(); - -// Similar operation -$user->books()->destroy($book); -``` - -If you want to add or remove an embedded model, without touching the database, you can use the `associate` and `dissociate` methods. - -To eventually write the changes to the database, save the parent object: - -```php -$user->books()->associate($book); -$user->save(); -``` - -Like other relations, embedsMany assumes the local key of the relationship based on the model name. You can override the default local key by passing a second argument to the embedsMany method: - -```php -use MongoDB\Laravel\Eloquent\Model; - -class User extends Model -{ - public function books() - { - return $this->embedsMany(Book::class, 'local_key'); - } -} -``` - -Embedded relations will return a Collection of embedded items instead of a query builder. Check out the available operations here: https://laravel.com/docs/master/collections - -### EmbedsOne Relationship - -The embedsOne relation is similar to the embedsMany relation, but only embeds a single model. - -```php -use MongoDB\Laravel\Eloquent\Model; - -class Book extends Model -{ - public function author() - { - return $this->embedsOne(Author::class); - } -} -``` - -You can access the embedded models through the dynamic property: - -```php -$book = Book::first(); -$author = $book->author; -``` - -Inserting and updating embedded models works similar to the `hasOne` relation: - -```php -$author = $book->author()->save( - new Author(['name' => 'John Doe']) -); - -// Similar -$author = - $book->author() - ->create(['name' => 'John Doe']); -``` - -You can update the embedded model using the `save` method (available since release 2.0.0): - -```php -$author = $book->author; - -$author->name = 'Jane Doe'; -$author->save(); -``` - -You can replace the embedded model with a new model like this: - -```php -$newAuthor = new Author(['name' => 'Jane Doe']); - -$book->author()->save($newAuthor); -``` - -Query Builder -------------- - -### Basic Usage - -The database driver plugs right into the original query builder. - -When using MongoDB connections, you will be able to build fluent queries to perform database operations. - -For your convenience, there is a `collection` alias for `table` as well as some additional MongoDB specific operators/operations. - -```php -$books = DB::collection('books')->get(); - -$hungerGames = - DB::collection('books') - ->where('name', 'Hunger Games') - ->first(); -``` - -If you are familiar with [Eloquent Queries](http://laravel.com/docs/queries), there is the same functionality. - -### Available operations - -To see the available operations, check the [Eloquent](#eloquent) section. - -Transactions ------------- - -Transactions require MongoDB version ^4.0 as well as deployment of replica set or sharded clusters. You can find more information [in the MongoDB docs](https://docs.mongodb.com/manual/core/transactions/) - -### Basic Usage - -```php -DB::transaction(function () { - User::create(['name' => 'john', 'age' => 19, 'title' => 'admin', 'email' => 'john@example.com']); - DB::collection('users')->where('name', 'john')->update(['age' => 20]); - DB::collection('users')->where('name', 'john')->delete(); -}); -``` - -```php -// begin a transaction -DB::beginTransaction(); -User::create(['name' => 'john', 'age' => 19, 'title' => 'admin', 'email' => 'john@example.com']); -DB::collection('users')->where('name', 'john')->update(['age' => 20]); -DB::collection('users')->where('name', 'john')->delete(); - -// commit changes -DB::commit(); -``` - -To abort a transaction, call the `rollBack` method at any point during the transaction: - -```php -DB::beginTransaction(); -User::create(['name' => 'john', 'age' => 19, 'title' => 'admin', 'email' => 'john@example.com']); - -// Abort the transaction, discarding any data created as part of it -DB::rollBack(); -``` - -**NOTE:** Transactions in MongoDB cannot be nested. DB::beginTransaction() function will start new transactions in a new created or existing session and will raise the RuntimeException when transactions already exist. See more in MongoDB official docs [Transactions and Sessions](https://www.mongodb.com/docs/manual/core/transactions/#transactions-and-sessions) - -```php -DB::beginTransaction(); -User::create(['name' => 'john', 'age' => 20, 'title' => 'admin']); - -// This call to start a nested transaction will raise a RuntimeException -DB::beginTransaction(); -DB::collection('users')->where('name', 'john')->update(['age' => 20]); -DB::commit(); -DB::rollBack(); -``` - -Schema ------- - -The database driver also has (limited) schema builder support. You can easily manipulate collections and set indexes. - -### Basic Usage - -```php -Schema::create('users', function ($collection) { - $collection->index('name'); - $collection->unique('email'); -}); -``` - -You can also pass all the parameters specified [in the MongoDB docs](https://docs.mongodb.com/manual/reference/method/db.collection.createIndex/#options-for-all-index-types) to the `$options` parameter: - -```php -Schema::create('users', function ($collection) { - $collection->index( - 'username', - null, - null, - [ - 'sparse' => true, - 'unique' => true, - 'background' => true, - ] - ); -}); -``` - -Inherited operations: - -- create and drop -- collection -- hasCollection -- index and dropIndex (compound indexes supported as well) -- unique - -MongoDB specific operations: - -- background -- sparse -- expire -- geospatial - -All other (unsupported) operations are implemented as dummy pass-through methods because MongoDB does not use a predefined schema. - -Read more about the schema builder on [Laravel Docs](https://laravel.com/docs/10.x/migrations#tables) - -### Geospatial indexes - -Geospatial indexes are handy for querying location-based documents. - -They come in two forms: `2d` and `2dsphere`. Use the schema builder to add these to a collection. - -```php -Schema::create('bars', function ($collection) { - $collection->geospatial('location', '2d'); -}); -``` - -To add a `2dsphere` index: - -```php -Schema::create('bars', function ($collection) { - $collection->geospatial('location', '2dsphere'); -}); -``` - -Extending ---------- - -### Cross-Database Relationships - -If you're using a hybrid MongoDB and SQL setup, you can define relationships across them. - -The model will automatically return a MongoDB-related or SQL-related relation based on the type of the related model. - -If you want this functionality to work both ways, your SQL-models will need to use the `MongoDB\Laravel\Eloquent\HybridRelations` trait. - -**This functionality only works for `hasOne`, `hasMany` and `belongsTo`.** - -The MySQL model should use the `HybridRelations` trait: - -```php -use MongoDB\Laravel\Eloquent\HybridRelations; - -class User extends Model -{ - use HybridRelations; - - protected $connection = 'mysql'; - - public function messages() - { - return $this->hasMany(Message::class); - } -} -``` - -Within your MongoDB model, you should define the relationship: - -```php -use MongoDB\Laravel\Eloquent\Model; - -class Message extends Model -{ - protected $connection = 'mongodb'; - - public function user() - { - return $this->belongsTo(User::class); - } -} -``` - -### Authentication - -If you want to use Laravel's native Auth functionality, register this included service provider: - -```php -MongoDB\Laravel\Auth\PasswordResetServiceProvider::class, -``` - -This service provider will slightly modify the internal DatabaseReminderRepository to add support for MongoDB based password reminders. - -If you don't use password reminders, you don't have to register this service provider and everything else should work just fine. - -### Queues - -If you want to use MongoDB as your database backend, change the driver in `config/queue.php`: - -```php -'connections' => [ - 'database' => [ - 'driver' => 'mongodb', - // You can also specify your jobs specific database created on config/database.php - 'connection' => 'mongodb-job', - 'table' => 'jobs', - 'queue' => 'default', - 'expire' => 60, - ], -], -``` - -If you want to use MongoDB to handle failed jobs, change the database in `config/queue.php`: - -```php -'failed' => [ - 'driver' => 'mongodb', - // You can also specify your jobs specific database created on config/database.php - 'database' => 'mongodb-job', - 'table' => 'failed_jobs', -], -``` - -Add the service provider in `config/app.php`: - -```php -MongoDB\Laravel\MongodbQueueServiceProvider::class, -``` - -### Prunable - -`Prunable` and `MassPrunable` traits are Laravel features to automatically remove models from your database. You can use -`Illuminate\Database\Eloquent\Prunable` trait to remove models one by one. If you want to remove models in bulk, you need -to use the `MongoDB\Laravel\Eloquent\MassPrunable` trait instead: it will be more performant but can break links with -other documents as it does not load the models. - - -```php -use MongoDB\Laravel\Eloquent\Model; -use MongoDB\Laravel\Eloquent\MassPrunable; - -class Book extends Model -{ - use MassPrunable; -} -``` - -Upgrading ---------- - -#### Upgrading from version 3 to 4 - -Change project name in composer.json to `mongodb/laravel` and run `composer update`. - -Change namespace from `Jenssegers\Mongodb` to `MongoDB\Laravel` in your models and config. - -Replace `Illuminate\Database\Eloquent\MassPrunable` with `MongoDB\Laravel\Eloquent\MassPrunable` in your models. - -## Security contact information - -To report a security vulnerability, follow [these steps](https://tidelift.com/security). +Development is tracked in the +[PHPORM](https://jira.mongodb.org/projects/PHPORM/summary) project in MongoDB's +JIRA. Documentation for contributing to this project may be found in +[CONTRIBUTING.md](CONTRIBUTING.md). diff --git a/composer.json b/composer.json index 6a4ac97aa..cf8e5509f 100644 --- a/composer.json +++ b/composer.json @@ -55,13 +55,16 @@ }, "laravel": { "providers": [ - "MongoDB\\Laravel\\MongodbServiceProvider", - "MongoDB\\Laravel\\MongodbQueueServiceProvider" + "MongoDB\\Laravel\\MongoDBServiceProvider", + "MongoDB\\Laravel\\MongoDBQueueServiceProvider" ] } }, "minimum-stability": "dev", "config": { + "platform": { + "php": "8.1" + }, "allow-plugins": { "dealerdirect/phpcodesniffer-composer-installer": true } diff --git a/docs/eloquent-models.md b/docs/eloquent-models.md new file mode 100644 index 000000000..f8dabb91a --- /dev/null +++ b/docs/eloquent-models.md @@ -0,0 +1,464 @@ +Eloquent Models +=============== + +Previous: [Installation and configuration](install.md) + +This package includes a MongoDB enabled Eloquent class that you can use to define models for corresponding collections. + +### Extending the base model + +To get started, create a new model class in your `app\Models\` directory. + +```php +namespace App\Models; + +use MongoDB\Laravel\Eloquent\Model; + +class Book extends Model +{ + // +} +``` + +Just like a normal model, the MongoDB model class will know which collection to use based on the model name. For `Book`, the collection `books` will be used. + +To change the collection, pass the `$collection` property: + +```php +use MongoDB\Laravel\Eloquent\Model; + +class Book extends Model +{ + protected $collection = 'my_books_collection'; +} +``` + +**NOTE:** MongoDB documents are automatically stored with a unique ID that is stored in the `_id` property. If you wish to use your own ID, substitute the `$primaryKey` property and set it to your own primary key attribute name. + +```php +use MongoDB\Laravel\Eloquent\Model; + +class Book extends Model +{ + protected $primaryKey = 'id'; +} + +// MongoDB will also create _id, but the 'id' property will be used for primary key actions like find(). +Book::create(['id' => 1, 'title' => 'The Fault in Our Stars']); +``` + +Likewise, you may define a `connection` property to override the name of the database connection that should be used when utilizing the model. + +```php +use MongoDB\Laravel\Eloquent\Model; + +class Book extends Model +{ + protected $connection = 'mongodb'; +} +``` + +### Soft Deletes + +When soft deleting a model, it is not actually removed from your database. Instead, a `deleted_at` timestamp is set on the record. + +To enable soft delete for a model, apply the `MongoDB\Laravel\Eloquent\SoftDeletes` Trait to the model: + +```php +use MongoDB\Laravel\Eloquent\SoftDeletes; + +class User extends Model +{ + use SoftDeletes; +} +``` + +For more information check [Laravel Docs about Soft Deleting](http://laravel.com/docs/eloquent#soft-deleting). + +### Prunable + +`Prunable` and `MassPrunable` traits are Laravel features to automatically remove models from your database. You can use +`Illuminate\Database\Eloquent\Prunable` trait to remove models one by one. If you want to remove models in bulk, you need +to use the `MongoDB\Laravel\Eloquent\MassPrunable` trait instead: it will be more performant but can break links with +other documents as it does not load the models. + +```php +use MongoDB\Laravel\Eloquent\Model; +use MongoDB\Laravel\Eloquent\MassPrunable; + +class Book extends Model +{ + use MassPrunable; +} +``` + +For more information check [Laravel Docs about Pruning Models](http://laravel.com/docs/eloquent#pruning-models). + +### Dates + +Eloquent allows you to work with Carbon or DateTime objects instead of MongoDate objects. Internally, these dates will be converted to MongoDate objects when saved to the database. + +```php +use MongoDB\Laravel\Eloquent\Model; + +class User extends Model +{ + protected $casts = ['birthday' => 'datetime']; +} +``` + +This allows you to execute queries like this: + +```php +$users = User::where( + 'birthday', '>', + new DateTime('-18 years') +)->get(); +``` + +### Extending the Authenticatable base model + +This package includes a MongoDB Authenticatable Eloquent class `MongoDB\Laravel\Auth\User` that you can use to replace the default Authenticatable class `Illuminate\Foundation\Auth\User` for your `User` model. + +```php +use MongoDB\Laravel\Auth\User as Authenticatable; + +class User extends Authenticatable +{ + +} +``` + +### Guarding attributes + +When choosing between guarding attributes or marking some as fillable, Taylor Otwell prefers the fillable route. +This is in light of [recent security issues described here](https://blog.laravel.com/security-release-laravel-61835-7240). + +Keep in mind guarding still works, but you may experience unexpected behavior. + +Schema +------ + +The database driver also has (limited) schema builder support. You can easily manipulate collections and set indexes. + +### Basic Usage + +```php +Schema::create('users', function ($collection) { + $collection->index('name'); + $collection->unique('email'); +}); +``` + +You can also pass all the parameters specified [in the MongoDB docs](https://docs.mongodb.com/manual/reference/method/db.collection.createIndex/#options-for-all-index-types) to the `$options` parameter: + +```php +Schema::create('users', function ($collection) { + $collection->index( + 'username', + null, + null, + [ + 'sparse' => true, + 'unique' => true, + 'background' => true, + ] + ); +}); +``` + +Inherited operations: + +- create and drop +- collection +- hasCollection +- index and dropIndex (compound indexes supported as well) +- unique + +MongoDB specific operations: + +- background +- sparse +- expire +- geospatial + +All other (unsupported) operations are implemented as dummy pass-through methods because MongoDB does not use a predefined schema. + +Read more about the schema builder on [Laravel Docs](https://laravel.com/docs/10.x/migrations#tables) + +### Geospatial indexes + +Geospatial indexes are handy for querying location-based documents. + +They come in two forms: `2d` and `2dsphere`. Use the schema builder to add these to a collection. + +```php +Schema::create('bars', function ($collection) { + $collection->geospatial('location', '2d'); +}); +``` + +To add a `2dsphere` index: + +```php +Schema::create('bars', function ($collection) { + $collection->geospatial('location', '2dsphere'); +}); +``` + +Relationships +------------- + +### Basic Usage + +The only available relationships are: + +- hasOne +- hasMany +- belongsTo +- belongsToMany + +The MongoDB-specific relationships are: + +- embedsOne +- embedsMany + +Here is a small example: + +```php +use MongoDB\Laravel\Eloquent\Model; + +class User extends Model +{ + public function items() + { + return $this->hasMany(Item::class); + } +} +``` + +The inverse relation of `hasMany` is `belongsTo`: + +```php +use MongoDB\Laravel\Eloquent\Model; + +class Item extends Model +{ + public function user() + { + return $this->belongsTo(User::class); + } +} +``` + +### belongsToMany and pivots + +The belongsToMany relation will not use a pivot "table" but will push id's to a __related_ids__ attribute instead. This makes the second parameter for the belongsToMany method useless. + +If you want to define custom keys for your relation, set it to `null`: + +```php +use MongoDB\Laravel\Eloquent\Model; + +class User extends Model +{ + public function groups() + { + return $this->belongsToMany( + Group::class, null, 'user_ids', 'group_ids' + ); + } +} +``` + +### EmbedsMany Relationship + +If you want to embed models, rather than referencing them, you can use the `embedsMany` relation. This relation is similar to the `hasMany` relation but embeds the models inside the parent object. + +**REMEMBER**: These relations return Eloquent collections, they don't return query builder objects! + +```php +use MongoDB\Laravel\Eloquent\Model; + +class User extends Model +{ + public function books() + { + return $this->embedsMany(Book::class); + } +} +``` + +You can access the embedded models through the dynamic property: + +```php +$user = User::first(); + +foreach ($user->books as $book) { + // +} +``` + +The inverse relation is auto*magically* available. You don't need to define this reverse relation. + +```php +$book = Book::first(); + +$user = $book->user; +``` + +Inserting and updating embedded models works similar to the `hasMany` relation: + +```php +$book = $user->books()->save( + new Book(['title' => 'A Game of Thrones']) +); + +// or +$book = + $user->books() + ->create(['title' => 'A Game of Thrones']); +``` + +You can update embedded models using their `save` method (available since release 2.0.0): + +```php +$book = $user->books()->first(); + +$book->title = 'A Game of Thrones'; +$book->save(); +``` + +You can remove an embedded model by using the `destroy` method on the relation, or the `delete` method on the model (available since release 2.0.0): + +```php +$book->delete(); + +// Similar operation +$user->books()->destroy($book); +``` + +If you want to add or remove an embedded model, without touching the database, you can use the `associate` and `dissociate` methods. + +To eventually write the changes to the database, save the parent object: + +```php +$user->books()->associate($book); +$user->save(); +``` + +Like other relations, embedsMany assumes the local key of the relationship based on the model name. You can override the default local key by passing a second argument to the embedsMany method: + +```php +use MongoDB\Laravel\Eloquent\Model; + +class User extends Model +{ + public function books() + { + return $this->embedsMany(Book::class, 'local_key'); + } +} +``` + +Embedded relations will return a Collection of embedded items instead of a query builder. Check out the available operations here: https://laravel.com/docs/master/collections + +### EmbedsOne Relationship + +The embedsOne relation is similar to the embedsMany relation, but only embeds a single model. + +```php +use MongoDB\Laravel\Eloquent\Model; + +class Book extends Model +{ + public function author() + { + return $this->embedsOne(Author::class); + } +} +``` + +You can access the embedded models through the dynamic property: + +```php +$book = Book::first(); +$author = $book->author; +``` + +Inserting and updating embedded models works similar to the `hasOne` relation: + +```php +$author = $book->author()->save( + new Author(['name' => 'John Doe']) +); + +// Similar +$author = + $book->author() + ->create(['name' => 'John Doe']); +``` + +You can update the embedded model using the `save` method (available since release 2.0.0): + +```php +$author = $book->author; + +$author->name = 'Jane Doe'; +$author->save(); +``` + +You can replace the embedded model with a new model like this: + +```php +$newAuthor = new Author(['name' => 'Jane Doe']); + +$book->author()->save($newAuthor); +``` + +Cross-Database Relationships +---------------------------- + +If you're using a hybrid MongoDB and SQL setup, you can define relationships across them. + +The model will automatically return a MongoDB-related or SQL-related relation based on the type of the related model. + +If you want this functionality to work both ways, your SQL-models will need to use the `MongoDB\Laravel\Eloquent\HybridRelations` trait. + +**This functionality only works for `hasOne`, `hasMany` and `belongsTo`.** + +The MySQL model should use the `HybridRelations` trait: + +```php +use MongoDB\Laravel\Eloquent\HybridRelations; + +class User extends Model +{ + use HybridRelations; + + protected $connection = 'mysql'; + + public function messages() + { + return $this->hasMany(Message::class); + } +} +``` + +Within your MongoDB model, you should define the relationship: + +```php +use MongoDB\Laravel\Eloquent\Model; + +class Message extends Model +{ + protected $connection = 'mongodb'; + + public function user() + { + return $this->belongsTo(User::class); + } +} +``` + + diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 000000000..d09628fec --- /dev/null +++ b/docs/install.md @@ -0,0 +1,64 @@ +Getting Started +=============== + +Installation +------------ + +Make sure you have the MongoDB PHP driver installed. You can find installation instructions at https://php.net/manual/en/mongodb.installation.php + +Install the package via Composer: + +```bash +$ composer require mongodb/laravel-mongodb +``` + +In case your Laravel version does NOT autoload the packages, add the service provider to `config/app.php`: + +```php +'providers' => [ + // ... + MongoDB\Laravel\MongoDBServiceProvider::class, +], +``` + +Configuration +------------- + +To configure a new MongoDB connection, add a new connection entry to `config/database.php`: + +```php +'default' => env('DB_CONNECTION', 'mongodb'), + +'connections' => [ + 'mongodb' => [ + 'driver' => 'mongodb', + 'dsn' => env('DB_DSN'), + 'database' => env('DB_DATABASE', 'homestead'), + ], + // ... +], +``` + +The `dsn` key contains the connection string used to connect to your MongoDB deployment. The format and available options are documented in the [MongoDB documentation](https://docs.mongodb.com/manual/reference/connection-string/). + +Instead of using a connection string, you can also use the `host` and `port` configuration options to have the connection string created for you. + +```php +'connections' => [ + 'mongodb' => [ + 'driver' => 'mongodb', + 'host' => env('DB_HOST', '127.0.0.1'), + 'port' => env('DB_PORT', 27017), + 'database' => env('DB_DATABASE', 'homestead'), + 'username' => env('DB_USERNAME', 'homestead'), + 'password' => env('DB_PASSWORD', 'secret'), + 'options' => [ + 'appname' => 'homestead', + ], + ], +], +``` + +The `options` key in the connection configuration corresponds to the [`uriOptions` parameter](https://www.php.net/manual/en/mongodb-driver-manager.construct.php#mongodb-driver-manager.construct-urioptions). + +You are ready to [create your first MongoDB model](eloquent-models.md). diff --git a/docs/query-builder.md b/docs/query-builder.md new file mode 100644 index 000000000..9672e21ef --- /dev/null +++ b/docs/query-builder.md @@ -0,0 +1,530 @@ +Query Builder +============= + +The database driver plugs right into the original query builder. + +When using MongoDB connections, you will be able to build fluent queries to perform database operations. + +For your convenience, there is a `collection` alias for `table` as well as some additional MongoDB specific operators/operations. + +```php +$books = DB::collection('books')->get(); + +$hungerGames = + DB::collection('books') + ->where('name', 'Hunger Games') + ->first(); +``` + +If you are familiar with [Eloquent Queries](http://laravel.com/docs/queries), there is the same functionality. + +Available operations +-------------------- + +**Retrieving all models** + +```php +$users = User::all(); +``` + +**Retrieving a record by primary key** + +```php +$user = User::find('517c43667db388101e00000f'); +``` + +**Where** + +```php +$posts = + Post::where('author.name', 'John') + ->take(10) + ->get(); +``` + +**OR Statements** + +```php +$posts = + Post::where('votes', '>', 0) + ->orWhere('is_approved', true) + ->get(); +``` + +**AND statements** + +```php +$users = + User::where('age', '>', 18) + ->where('name', '!=', 'John') + ->get(); +``` + +**NOT statements** + +```php +$users = User::whereNot('age', '>', 18)->get(); +``` + +**whereIn** + +```php +$users = User::whereIn('age', [16, 18, 20])->get(); +``` + +When using `whereNotIn` objects will be returned if the field is non-existent. Combine with `whereNotNull('age')` to leave out those documents. + +**whereBetween** + +```php +$posts = Post::whereBetween('votes', [1, 100])->get(); +``` + +**whereNull** + +```php +$users = User::whereNull('age')->get(); +``` + +**whereDate** + +```php +$users = User::whereDate('birthday', '2021-5-12')->get(); +``` + +The usage is the same as `whereMonth` / `whereDay` / `whereYear` / `whereTime` + +**Advanced wheres** + +```php +$users = + User::where('name', 'John') + ->orWhere(function ($query) { + return $query + ->where('votes', '>', 100) + ->where('title', '<>', 'Admin'); + })->get(); +``` + +**orderBy** + +```php +$users = User::orderBy('age', 'desc')->get(); +``` + +**Offset & Limit (skip & take)** + +```php +$users = + User::skip(10) + ->take(5) + ->get(); +``` + +**groupBy** + +Selected columns that are not grouped will be aggregated with the `$last` function. + +```php +$users = + Users::groupBy('title') + ->get(['title', 'name']); +``` + +**Distinct** + +Distinct requires a field for which to return the distinct values. + +```php +$users = User::distinct()->get(['name']); + +// Equivalent to: +$users = User::distinct('name')->get(); +``` + +Distinct can be combined with **where**: + +```php +$users = + User::where('active', true) + ->distinct('name') + ->get(); +``` + +**Like** + +```php +$spamComments = Comment::where('body', 'like', '%spam%')->get(); +``` + +**Aggregation** + +**Aggregations are only available for MongoDB versions greater than 2.2.x** + +```php +$total = Product::count(); +$price = Product::max('price'); +$price = Product::min('price'); +$price = Product::avg('price'); +$total = Product::sum('price'); +``` + +Aggregations can be combined with **where**: + +```php +$sold = Orders::where('sold', true)->sum('price'); +``` + +Aggregations can be also used on sub-documents: + +```php +$total = Order::max('suborder.price'); +``` + +**NOTE**: This aggregation only works with single sub-documents (like `EmbedsOne`) not subdocument arrays (like `EmbedsMany`). + +**Incrementing/Decrementing the value of a column** + +Perform increments or decrements (default 1) on specified attributes: + +```php +Cat::where('name', 'Kitty')->increment('age'); + +Car::where('name', 'Toyota')->decrement('weight', 50); +``` + +The number of updated objects is returned: + +```php +$count = User::increment('age'); +``` + +You may also specify additional columns to update: + +```php +Cat::where('age', 3) + ->increment('age', 1, ['group' => 'Kitty Club']); + +Car::where('weight', 300) + ->decrement('weight', 100, ['latest_change' => 'carbon fiber']); +``` + +### MongoDB-specific operators + +In addition to the Laravel Eloquent operators, all available MongoDB query operators can be used with `where`: + +```php +User::where($fieldName, $operator, $value)->get(); +``` + +It generates the following MongoDB filter: +```ts +{ $fieldName: { $operator: $value } } +``` + +**Exists** + +Matches documents that have the specified field. + +```php +User::where('age', 'exists', true)->get(); +``` + +**All** + +Matches arrays that contain all elements specified in the query. + +```php +User::where('roles', 'all', ['moderator', 'author'])->get(); +``` + +**Size** + +Selects documents if the array field is a specified size. + +```php +Post::where('tags', 'size', 3)->get(); +``` + +**Regex** + +Selects documents where values match a specified regular expression. + +```php +use MongoDB\BSON\Regex; + +User::where('name', 'regex', new Regex('.*doe', 'i'))->get(); +``` + +**NOTE:** you can also use the Laravel regexp operations. These will automatically convert your regular expression string to a `MongoDB\BSON\Regex` object. + +```php +User::where('name', 'regexp', '/.*doe/i')->get(); +``` + +The inverse of regexp: + +```php +User::where('name', 'not regexp', '/.*doe/i')->get(); +``` + +**Type** + +Selects documents if a field is of the specified type. For more information check: http://docs.mongodb.org/manual/reference/operator/query/type/#op._S_type + +```php +User::where('age', 'type', 2)->get(); +``` + +**Mod** + +Performs a modulo operation on the value of a field and selects documents with a specified result. + +```php +User::where('age', 'mod', [10, 0])->get(); +``` + +### MongoDB-specific Geo operations + +**Near** + +```php +$bars = Bar::where('location', 'near', [ + '$geometry' => [ + 'type' => 'Point', + 'coordinates' => [ + -0.1367563, // longitude + 51.5100913, // latitude + ], + ], + '$maxDistance' => 50, +])->get(); +``` + +**GeoWithin** + +```php +$bars = Bar::where('location', 'geoWithin', [ + '$geometry' => [ + 'type' => 'Polygon', + 'coordinates' => [ + [ + [-0.1450383, 51.5069158], + [-0.1367563, 51.5100913], + [-0.1270247, 51.5013233], + [-0.1450383, 51.5069158], + ], + ], + ], +])->get(); +``` + +**GeoIntersects** + +```php +$bars = Bar::where('location', 'geoIntersects', [ + '$geometry' => [ + 'type' => 'LineString', + 'coordinates' => [ + [-0.144044, 51.515215], + [-0.129545, 51.507864], + ], + ], +])->get(); +``` + +**GeoNear** + +You are able to make a `geoNear` query on mongoDB. +You don't need to specify the automatic fields on the model. +The returned instance is a collection. So you're able to make the [Collection](https://laravel.com/docs/9.x/collections) operations. +Just make sure that your model has a `location` field, and a [2ndSphereIndex](https://www.mongodb.com/docs/manual/core/2dsphere). +The data in the `location` field must be saved as [GeoJSON](https://www.mongodb.com/docs/manual/reference/geojson/). +The `location` points must be saved as [WGS84](https://www.mongodb.com/docs/manual/reference/glossary/#std-term-WGS84) reference system for geometry calculation. That means, basically, you need to save `longitude and latitude`, in that order specifically, and to find near with calculated distance, you `need to do the same way`. + +``` +Bar::find("63a0cd574d08564f330ceae2")->update( + [ + 'location' => [ + 'type' => 'Point', + 'coordinates' => [ + -0.1367563, + 51.5100913 + ] + ] + ] +); +$bars = Bar::raw(function ($collection) { + return $collection->aggregate([ + [ + '$geoNear' => [ + "near" => [ "type" => "Point", "coordinates" => [-0.132239, 51.511874] ], + "distanceField" => "dist.calculated", + "minDistance" => 0, + "maxDistance" => 6000, + "includeLocs" => "dist.location", + "spherical" => true, + ] + ] + ]); +}); +``` + +### Inserts, updates and deletes + +Inserting, updating and deleting records works just like the original Eloquent. Please check [Laravel Docs' Eloquent section](https://laravel.com/docs/6.x/eloquent). + +Here, only the MongoDB-specific operations are specified. + +### MongoDB specific operations + +**Raw Expressions** + +These expressions will be injected directly into the query. + +```php +User::whereRaw([ + 'age' => ['$gt' => 30, '$lt' => 40], +])->get(); + +User::whereRaw([ + '$where' => '/.*123.*/.test(this.field)', +])->get(); + +User::whereRaw([ + '$where' => '/.*123.*/.test(this["hyphenated-field"])', +])->get(); +``` + +You can also perform raw expressions on the internal MongoCollection object. If this is executed on the model class, it will return a collection of models. + +If this is executed on the query builder, it will return the original response. + +**Cursor timeout** + +To prevent `MongoCursorTimeout` exceptions, you can manually set a timeout value that will be applied to the cursor: + +```php +DB::collection('users')->timeout(-1)->get(); +``` + +**Upsert** + +Update or insert a document. Additional options for the update method are passed directly to the native update method. + +```php +// Query Builder +DB::collection('users') + ->where('name', 'John') + ->update($data, ['upsert' => true]); + +// Eloquent +$user->update($data, ['upsert' => true]); +``` + +**Projections** + +You can apply projections to your queries using the `project` method. + +```php +DB::collection('items') + ->project(['tags' => ['$slice' => 1]]) + ->get(); + +DB::collection('items') + ->project(['tags' => ['$slice' => [3, 7]]]) + ->get(); +``` + +**Projections with Pagination** + +```php +$limit = 25; +$projections = ['id', 'name']; + +DB::collection('items') + ->paginate($limit, $projections); +``` + +**Push** + +Add items to an array. + +```php +DB::collection('users') + ->where('name', 'John') + ->push('items', 'boots'); + +$user->push('items', 'boots'); +``` + +```php +DB::collection('users') + ->where('name', 'John') + ->push('messages', [ + 'from' => 'Jane Doe', + 'message' => 'Hi John', + ]); + +$user->push('messages', [ + 'from' => 'Jane Doe', + 'message' => 'Hi John', +]); +``` + +If you **DON'T** want duplicate items, set the third parameter to `true`: + +```php +DB::collection('users') + ->where('name', 'John') + ->push('items', 'boots', true); + +$user->push('items', 'boots', true); +``` + +**Pull** + +Remove an item from an array. + +```php +DB::collection('users') + ->where('name', 'John') + ->pull('items', 'boots'); + +$user->pull('items', 'boots'); +``` + +```php +DB::collection('users') + ->where('name', 'John') + ->pull('messages', [ + 'from' => 'Jane Doe', + 'message' => 'Hi John', + ]); + +$user->pull('messages', [ + 'from' => 'Jane Doe', + 'message' => 'Hi John', +]); +``` + +**Unset** + +Remove one or more fields from a document. + +```php +DB::collection('users') + ->where('name', 'John') + ->unset('note'); + +$user->unset('note'); + +$user->save(); +``` + +Using the native `unset` on models will work as well: + +```php +unset($user['note']); +unset($user->node); +``` diff --git a/docs/queues.md b/docs/queues.md new file mode 100644 index 000000000..0645a3d9e --- /dev/null +++ b/docs/queues.md @@ -0,0 +1,34 @@ +Queues +====== + +If you want to use MongoDB as your database backend for Laravel Queue, change the driver in `config/queue.php`: + +```php +'connections' => [ + 'database' => [ + 'driver' => 'mongodb', + // You can also specify your jobs specific database created on config/database.php + 'connection' => 'mongodb-job', + 'table' => 'jobs', + 'queue' => 'default', + 'expire' => 60, + ], +], +``` + +If you want to use MongoDB to handle failed jobs, change the database in `config/queue.php`: + +```php +'failed' => [ + 'driver' => 'mongodb', + // You can also specify your jobs specific database created on config/database.php + 'database' => 'mongodb-job', + 'table' => 'failed_jobs', +], +``` + +Add the service provider in `config/app.php`: + +```php +MongoDB\Laravel\MongoDBQueueServiceProvider::class, +``` diff --git a/docs/transactions.md b/docs/transactions.md new file mode 100644 index 000000000..fad0df803 --- /dev/null +++ b/docs/transactions.md @@ -0,0 +1,56 @@ +Transactions +============ + +Transactions require MongoDB version ^4.0 as well as deployment of replica set or sharded clusters. You can find more information [in the MongoDB docs](https://docs.mongodb.com/manual/core/transactions/) + +```php +DB::transaction(function () { + User::create(['name' => 'john', 'age' => 19, 'title' => 'admin', 'email' => 'john@example.com']); + DB::collection('users')->where('name', 'john')->update(['age' => 20]); + DB::collection('users')->where('name', 'john')->delete(); +}); +``` + +```php +// begin a transaction +DB::beginTransaction(); +User::create(['name' => 'john', 'age' => 19, 'title' => 'admin', 'email' => 'john@example.com']); +DB::collection('users')->where('name', 'john')->update(['age' => 20]); +DB::collection('users')->where('name', 'john')->delete(); + +// commit changes +DB::commit(); +``` + +To abort a transaction, call the `rollBack` method at any point during the transaction: + +```php +DB::beginTransaction(); +User::create(['name' => 'john', 'age' => 19, 'title' => 'admin', 'email' => 'john@example.com']); + +// Abort the transaction, discarding any data created as part of it +DB::rollBack(); +``` + +**NOTE:** Transactions in MongoDB cannot be nested. DB::beginTransaction() function will start new transactions in a new created or existing session and will raise the RuntimeException when transactions already exist. See more in MongoDB official docs [Transactions and Sessions](https://www.mongodb.com/docs/manual/core/transactions/#transactions-and-sessions) + +```php +DB::beginTransaction(); +User::create(['name' => 'john', 'age' => 20, 'title' => 'admin']); + +// This call to start a nested transaction will raise a RuntimeException +DB::beginTransaction(); +DB::collection('users')->where('name', 'john')->update(['age' => 20]); +DB::commit(); +DB::rollBack(); +``` + +Database Testing +---------------- + +For testing, the traits `Illuminate\Foundation\Testing\DatabaseTransactions` and `Illuminate\Foundation\Testing\RefreshDatabase` are not yet supported. +Instead, create migrations and use the `DatabaseMigrations` trait to reset the database after each test: + +```php +use Illuminate\Foundation\Testing\DatabaseMigrations; +``` diff --git a/docs/upgrade.md b/docs/upgrade.md new file mode 100644 index 000000000..612dd27af --- /dev/null +++ b/docs/upgrade.md @@ -0,0 +1,19 @@ +Upgrading +========= + +The PHP library uses [semantic versioning](https://semver.org/). Upgrading to a new major version may require changes to your application. + +Upgrading from version 3 to 4 +----------------------------- + +- Laravel 10.x is required +- Change dependency name in your composer.json to `"mongodb/laravel-mongodb": "^4.0"` and run `composer update` +- Change namespace from `Jenssegers\Mongodb\` to `MongoDB\Laravel\` in your models and config +- Remove support for non-Laravel projects +- Replace `$dates` with `$casts` in your models +- Call `$model->save()` after `$model->unset('field')` to persist the change +- Replace calls to `Query\Builder::whereAll($column, $values)` with `Query\Builder::where($column, 'all', $values)` +- `Query\Builder::delete()` doesn't accept `limit()` other than `1` or `null`. +- `whereDate`, `whereDay`, `whereMonth`, `whereYear`, `whereTime` now use MongoDB operators on date fields +- Replace `Illuminate\Database\Eloquent\MassPrunable` with `MongoDB\Laravel\Eloquent\MassPrunable` in your models +- Remove calls to not-supported methods of `Query\Builder`: `toSql`, `toRawSql`, `whereColumn`, `whereFullText`, `groupByRaw`, `orderByRaw`, `unionAll`, `union`, `having`, `havingRaw`, `havingBetween`, `whereIntegerInRaw`, `orWhereIntegerInRaw`, `whereIntegerNotInRaw`, `orWhereIntegerNotInRaw`. diff --git a/docs/user-authentication.md b/docs/user-authentication.md new file mode 100644 index 000000000..72341ceae --- /dev/null +++ b/docs/user-authentication.md @@ -0,0 +1,15 @@ +User authentication +================== + +If you want to use Laravel's native Auth functionality, register this included service provider: + +```php +MongoDB\Laravel\Auth\PasswordResetServiceProvider::class, +``` + +This service provider will slightly modify the internal `DatabaseReminderRepository` to add support for MongoDB based password reminders. + +If you don't use password reminders, you don't have to register this service provider and everything else should work just fine. + + + diff --git a/src/MongodbQueueServiceProvider.php b/src/MongoDBQueueServiceProvider.php similarity index 96% rename from src/MongodbQueueServiceProvider.php rename to src/MongoDBQueueServiceProvider.php index 7b2066ecb..aa67f7405 100644 --- a/src/MongodbQueueServiceProvider.php +++ b/src/MongoDBQueueServiceProvider.php @@ -10,7 +10,7 @@ use function array_key_exists; -class MongodbQueueServiceProvider extends QueueServiceProvider +class MongoDBQueueServiceProvider extends QueueServiceProvider { /** * Register the failed job services. diff --git a/src/MongodbServiceProvider.php b/src/MongoDBServiceProvider.php similarity index 95% rename from src/MongodbServiceProvider.php rename to src/MongoDBServiceProvider.php index a9ebc1d17..d7af0c714 100644 --- a/src/MongodbServiceProvider.php +++ b/src/MongoDBServiceProvider.php @@ -8,7 +8,7 @@ use MongoDB\Laravel\Eloquent\Model; use MongoDB\Laravel\Queue\MongoConnector; -class MongodbServiceProvider extends ServiceProvider +class MongoDBServiceProvider extends ServiceProvider { /** * Bootstrap the application events. diff --git a/tests/TestCase.php b/tests/TestCase.php index f54c01405..7098f729f 100644 --- a/tests/TestCase.php +++ b/tests/TestCase.php @@ -7,8 +7,8 @@ use Illuminate\Auth\Passwords\PasswordResetServiceProvider as BasePasswordResetServiceProviderAlias; use Illuminate\Foundation\Application; use MongoDB\Laravel\Auth\PasswordResetServiceProvider; -use MongoDB\Laravel\MongodbQueueServiceProvider; -use MongoDB\Laravel\MongodbServiceProvider; +use MongoDB\Laravel\MongoDBQueueServiceProvider; +use MongoDB\Laravel\MongoDBServiceProvider; use MongoDB\Laravel\Tests\Models\User; use MongoDB\Laravel\Validation\ValidationServiceProvider; use Orchestra\Testbench\TestCase as OrchestraTestCase; @@ -43,8 +43,8 @@ protected function getApplicationProviders($app) protected function getPackageProviders($app) { return [ - MongodbServiceProvider::class, - MongodbQueueServiceProvider::class, + MongoDBServiceProvider::class, + MongoDBQueueServiceProvider::class, PasswordResetServiceProvider::class, ValidationServiceProvider::class, ]; From cc005bfb7b7ea1ff4be9f7e0f18726e07802b3a4 Mon Sep 17 00:00:00 2001 From: behrooz Date: Mon, 11 Sep 2023 11:10:29 +0300 Subject: [PATCH 101/446] Changed failed_at field as ISODate (#2607) --- src/Queue/Failed/MongoFailedJobProvider.php | 3 ++- tests/QueueTest.php | 22 +++++++++++++++++---- 2 files changed, 20 insertions(+), 5 deletions(-) diff --git a/src/Queue/Failed/MongoFailedJobProvider.php b/src/Queue/Failed/MongoFailedJobProvider.php index 6052e1f90..0525c272e 100644 --- a/src/Queue/Failed/MongoFailedJobProvider.php +++ b/src/Queue/Failed/MongoFailedJobProvider.php @@ -7,6 +7,7 @@ use Carbon\Carbon; use Exception; use Illuminate\Queue\Failed\DatabaseFailedJobProvider; +use MongoDB\BSON\UTCDateTime; use function array_map; @@ -28,7 +29,7 @@ public function log($connection, $queue, $payload, $exception) 'connection' => $connection, 'queue' => $queue, 'payload' => $payload, - 'failed_at' => Carbon::now()->getTimestamp(), + 'failed_at' => new UTCDateTime(Carbon::now()), 'exception' => (string) $exception, ]); } diff --git a/tests/QueueTest.php b/tests/QueueTest.php index 24afcedff..c23e711ab 100644 --- a/tests/QueueTest.php +++ b/tests/QueueTest.php @@ -5,10 +5,12 @@ namespace MongoDB\Laravel\Tests; use Carbon\Carbon; +use Exception; use Illuminate\Support\Facades\Config; use Illuminate\Support\Facades\Queue; use Illuminate\Support\Str; use Mockery; +use MongoDB\BSON\UTCDateTime; use MongoDB\Laravel\Queue\Failed\MongoFailedJobProvider; use MongoDB\Laravel\Queue\MongoJob; use MongoDB\Laravel\Queue\MongoQueue; @@ -30,10 +32,7 @@ public function setUp(): void public function testQueueJobLifeCycle(): void { $uuid = Str::uuid(); - - Str::createUuidsUsing(function () use ($uuid) { - return $uuid; - }); + Str::createUuidsUsing(fn () => $uuid); $id = Queue::push('test', ['action' => 'QueueJobLifeCycle'], 'test'); $this->assertNotNull($id); @@ -185,4 +184,19 @@ public function testQueueDeleteAndRelease(): void $mock->deleteAndRelease($queue, $job, $delay); } + + public function testFailedJobLogging() + { + Carbon::setTestNow('2019-01-01 00:00:00'); + $provider = app('queue.failer'); + $provider->log('test_connection', 'test_queue', 'test_payload', new Exception('test_exception')); + + $failedJob = Queue::getDatabase()->table(Config::get('queue.failed.table'))->first(); + + $this->assertSame('test_connection', $failedJob['connection']); + $this->assertSame('test_queue', $failedJob['queue']); + $this->assertSame('test_payload', $failedJob['payload']); + $this->assertEquals(new UTCDateTime(Carbon::now()), $failedJob['failed_at']); + $this->assertStringStartsWith('Exception: test_exception in ', $failedJob['exception']); + } } From 02c3378245b85076eb2aa938a96e10d446a98122 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 11 Sep 2023 12:32:43 +0200 Subject: [PATCH 102/446] Upgrade PHPUnit 10.3 (#2611) --- .gitignore | 1 - composer.json | 3 +-- phpunit.xml.dist | 24 +++++++++++++++++------- tests/ConnectionTest.php | 2 +- 4 files changed, 19 insertions(+), 11 deletions(-) diff --git a/.gitignore b/.gitignore index 4a03159de..3dd9edec0 100644 --- a/.gitignore +++ b/.gitignore @@ -8,5 +8,4 @@ /vendor composer.lock composer.phar -phpunit.phar phpunit.xml diff --git a/composer.json b/composer.json index cf8e5509f..33a797d46 100644 --- a/composer.json +++ b/composer.json @@ -31,7 +31,7 @@ "mongodb/mongodb": "^1.15" }, "require-dev": { - "phpunit/phpunit": "^9.5.10", + "phpunit/phpunit": "^10.3", "orchestra/testbench": "^8.0", "mockery/mockery": "^1.4.4", "doctrine/coding-standard": "12.0.x-dev" @@ -60,7 +60,6 @@ ] } }, - "minimum-stability": "dev", "config": { "platform": { "php": "8.1" diff --git a/phpunit.xml.dist b/phpunit.xml.dist index 120898c08..cd883f311 100644 --- a/phpunit.xml.dist +++ b/phpunit.xml.dist @@ -1,10 +1,15 @@ - - - - ./src - - + + tests/ @@ -38,7 +43,7 @@ - + @@ -46,4 +51,9 @@ + + + ./src + + diff --git a/tests/ConnectionTest.php b/tests/ConnectionTest.php index 51a463c56..b46168df8 100644 --- a/tests/ConnectionTest.php +++ b/tests/ConnectionTest.php @@ -43,7 +43,7 @@ public function testDb() $this->assertInstanceOf(Client::class, $connection->getMongoClient()); } - public function dataConnectionConfig(): Generator + public static function dataConnectionConfig(): Generator { yield 'Single host' => [ 'expectedUri' => 'mongodb://some-host', From 66acce659c0d4a3c6956cb7e0cbdafeb6abe0903 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 11 Sep 2023 13:14:16 +0200 Subject: [PATCH 103/446] Bump actions/checkout from 3 to 4 (#2612) * Bump actions/checkout from 3 to 4 * Enable dependabot --- .github/dependabot.yml | 6 ++++++ .github/workflows/build-ci.yml | 2 +- .github/workflows/coding-standards.yml | 2 +- .gitignore | 2 +- 4 files changed, 9 insertions(+), 3 deletions(-) create mode 100644 .github/dependabot.yml diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 000000000..5ace4600a --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,6 @@ +version: 2 +updates: + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" diff --git a/.github/workflows/build-ci.yml b/.github/workflows/build-ci.yml index ecbf50b50..9693261dc 100644 --- a/.github/workflows/build-ci.yml +++ b/.github/workflows/build-ci.yml @@ -33,7 +33,7 @@ jobs: MYSQL_ROOT_PASSWORD: steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Create MongoDB Replica Set run: | docker run --name mongodb -p 27017:27017 -e MONGO_INITDB_DATABASE=unittest --detach mongo:${{ matrix.mongodb }} mongod --replSet rs --setParameter transactionLifetimeLimitSeconds=5 diff --git a/.github/workflows/coding-standards.yml b/.github/workflows/coding-standards.yml index 45daae584..e75ca3c53 100644 --- a/.github/workflows/coding-standards.yml +++ b/.github/workflows/coding-standards.yml @@ -17,7 +17,7 @@ jobs: steps: - name: "Checkout" - uses: "actions/checkout@v3" + uses: "actions/checkout@v4" - name: Setup cache environment id: extcache diff --git a/.gitignore b/.gitignore index 3dd9edec0..d69c89d6f 100644 --- a/.gitignore +++ b/.gitignore @@ -3,7 +3,7 @@ *.sublime-workspace .DS_Store .idea/ -.phpunit.result.cache +.phpunit.cache/ .phpcs-cache /vendor composer.lock From 50ef087bd42671f62e0541017679142b814d9f7e Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 11 Sep 2023 13:35:41 +0200 Subject: [PATCH 104/446] Bump actions/cache from 1 to 3 (#2613) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Bump actions/cache from 1 to 3 Bumps [actions/cache](https://github.com/actions/cache) from 1 to 3. - [Release notes](https://github.com/actions/cache/releases) - [Changelog](https://github.com/actions/cache/blob/main/RELEASES.md) - [Commits](https://github.com/actions/cache/compare/v1...v3) --- updated-dependencies: - dependency-name: actions/cache dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] * Update deprecated ::set-output in @actions/cache --------- Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Jérôme Tamarelle --- .github/workflows/build-ci.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/build-ci.yml b/.github/workflows/build-ci.yml index 9693261dc..fc646e688 100644 --- a/.github/workflows/build-ci.yml +++ b/.github/workflows/build-ci.yml @@ -62,9 +62,9 @@ jobs: DEBUG: ${{secrets.DEBUG}} - name: Download Composer cache dependencies from cache id: composer-cache - run: echo "::set-output name=dir::$(composer config cache-files-dir)" + run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT - name: Cache Composer dependencies - uses: actions/cache@v1 + uses: actions/cache@v3 with: path: ${{ steps.composer-cache.outputs.dir }} key: ${{ matrix.os }}-composer-${{ hashFiles('**/composer.json') }} From f14204fe306a50117706941a1a3b592d6e229daa Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 11 Sep 2023 13:55:07 +0200 Subject: [PATCH 105/446] Bump codecov/codecov-action from 1 to 3 (#2614) Bumps [codecov/codecov-action](https://github.com/codecov/codecov-action) from 1 to 3. - [Release notes](https://github.com/codecov/codecov-action/releases) - [Changelog](https://github.com/codecov/codecov-action/blob/main/CHANGELOG.md) - [Commits](https://github.com/codecov/codecov-action/compare/v1...v3) --- updated-dependencies: - dependency-name: codecov/codecov-action dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/build-ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build-ci.yml b/.github/workflows/build-ci.yml index fc646e688..390ac1ac9 100644 --- a/.github/workflows/build-ci.yml +++ b/.github/workflows/build-ci.yml @@ -79,7 +79,7 @@ jobs: MONGODB_URI: 'mongodb://127.0.0.1/?replicaSet=rs' MYSQL_HOST: 0.0.0.0 MYSQL_PORT: 3307 - - uses: codecov/codecov-action@v1 + - uses: codecov/codecov-action@v3 with: token: ${{ secrets.CODECOV_TOKEN }} fail_ci_if_error: false From 9956dc5cecbbd359290de4518dcf1d1acdc3945a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 13 Sep 2023 07:59:03 +0200 Subject: [PATCH 106/446] Remove call to getBelongsToManyCaller for compatibility with Laravel before 5.x (#2615) https://github.com/laravel/framework/commit/4ff006035a2e48dfa5ebc15a1572fe3ee1ad12ed Introduced by https://github.com/mongodb/laravel-mongodb/commit/3e26e05b90cf5e207c66e30ea2021ff9ddb16bf9 https://github.com/mongodb/laravel-mongodb/pull/1116 --- src/Eloquent/HybridRelations.php | 15 --------------- src/Relations/BelongsTo.php | 20 +++----------------- src/Relations/BelongsToMany.php | 17 +++-------------- src/Relations/MorphTo.php | 14 +------------- 4 files changed, 7 insertions(+), 59 deletions(-) diff --git a/src/Eloquent/HybridRelations.php b/src/Eloquent/HybridRelations.php index 9d6aa90e1..9e11605a3 100644 --- a/src/Eloquent/HybridRelations.php +++ b/src/Eloquent/HybridRelations.php @@ -18,7 +18,6 @@ use function debug_backtrace; use function is_subclass_of; -use function method_exists; use const DEBUG_BACKTRACE_IGNORE_ARGS; @@ -324,20 +323,6 @@ public function belongsToMany( ); } - /** - * Get the relationship name of the belongs to many. - * - * @return string - */ - protected function guessBelongsToManyRelation() - { - if (method_exists($this, 'getBelongsToManyCaller')) { - return $this->getBelongsToManyCaller(); - } - - return parent::guessBelongsToManyRelation(); - } - /** @inheritdoc */ public function newEloquentBuilder($query) { diff --git a/src/Relations/BelongsTo.php b/src/Relations/BelongsTo.php index 0a8cb1d9c..175a53e49 100644 --- a/src/Relations/BelongsTo.php +++ b/src/Relations/BelongsTo.php @@ -7,8 +7,6 @@ use Illuminate\Database\Eloquent\Builder; use Illuminate\Database\Eloquent\Model; -use function property_exists; - class BelongsTo extends \Illuminate\Database\Eloquent\Relations\BelongsTo { /** @@ -18,7 +16,7 @@ class BelongsTo extends \Illuminate\Database\Eloquent\Relations\BelongsTo */ public function getHasCompareKey() { - return $this->getOwnerKey(); + return $this->ownerKey; } /** @inheritdoc */ @@ -28,7 +26,7 @@ public function addConstraints() // For belongs to relationships, which are essentially the inverse of has one // or has many relationships, we need to actually query on the primary key // of the related models matching on the foreign key that's on a parent. - $this->query->where($this->getOwnerKey(), '=', $this->parent->{$this->foreignKey}); + $this->query->where($this->ownerKey, '=', $this->parent->{$this->foreignKey}); } } @@ -38,9 +36,7 @@ public function addEagerConstraints(array $models) // We'll grab the primary key name of the related models since it could be set to // a non-standard name and not "id". We will then construct the constraint for // our eagerly loading query so it returns the proper models from execution. - $key = $this->getOwnerKey(); - - $this->query->whereIn($key, $this->getEagerModelKeys($models)); + $this->query->whereIn($this->ownerKey, $this->getEagerModelKeys($models)); } /** @inheritdoc */ @@ -49,16 +45,6 @@ public function getRelationExistenceQuery(Builder $query, Builder $parentQuery, return $query; } - /** - * Get the owner key with backwards compatible support. - * - * @return string - */ - public function getOwnerKey() - { - return property_exists($this, 'ownerKey') ? $this->ownerKey : $this->otherKey; - } - /** * Get the name of the "where in" method for eager loading. * diff --git a/src/Relations/BelongsToMany.php b/src/Relations/BelongsToMany.php index 4afa3663b..2bd74b8db 100644 --- a/src/Relations/BelongsToMany.php +++ b/src/Relations/BelongsToMany.php @@ -18,7 +18,6 @@ use function count; use function is_array; use function is_numeric; -use function property_exists; class BelongsToMany extends EloquentBelongsToMany { @@ -123,7 +122,7 @@ public function sync($ids, $detaching = true) // First we need to attach any of the associated models that are not currently // in this joining table. We'll spin through the given IDs, checking to see // if they exist in the array of current ones, and if not we will insert. - $current = $this->parent->{$this->getRelatedKey()} ?: []; + $current = $this->parent->{$this->relatedPivotKey} ?: []; // See issue #256. if ($current instanceof Collection) { @@ -196,7 +195,7 @@ public function attach($id, array $attributes = [], $touch = true) } // Attach the new ids to the parent model. - $this->parent->push($this->getRelatedKey(), (array) $id, true); + $this->parent->push($this->relatedPivotKey, (array) $id, true); if (! $touch) { return; @@ -220,7 +219,7 @@ public function detach($ids = [], $touch = true) $ids = (array) $ids; // Detach all ids from the parent model. - $this->parent->pull($this->getRelatedKey(), $ids); + $this->parent->pull($this->relatedPivotKey, $ids); // Prepare the query to select all related objects. if (count($ids) > 0) { @@ -316,16 +315,6 @@ protected function formatSyncList(array $records) return $results; } - /** - * Get the related key with backwards compatible support. - * - * @return string - */ - public function getRelatedKey() - { - return property_exists($this, 'relatedPivotKey') ? $this->relatedPivotKey : $this->relatedKey; - } - /** * Get the name of the "where in" method for eager loading. * diff --git a/src/Relations/MorphTo.php b/src/Relations/MorphTo.php index 160901088..53b93f8d7 100644 --- a/src/Relations/MorphTo.php +++ b/src/Relations/MorphTo.php @@ -7,8 +7,6 @@ use Illuminate\Database\Eloquent\Model; use Illuminate\Database\Eloquent\Relations\MorphTo as EloquentMorphTo; -use function property_exists; - class MorphTo extends EloquentMorphTo { /** @inheritdoc */ @@ -18,7 +16,7 @@ public function addConstraints() // For belongs to relationships, which are essentially the inverse of has one // or has many relationships, we need to actually query on the primary key // of the related models matching on the foreign key that's on a parent. - $this->query->where($this->getOwnerKey(), '=', $this->parent->{$this->foreignKey}); + $this->query->where($this->ownerKey, '=', $this->parent->{$this->foreignKey}); } } @@ -34,16 +32,6 @@ protected function getResultsByType($type) return $query->whereIn($key, $this->gatherKeysByType($type, $instance->getKeyType()))->get(); } - /** - * Get the owner key with backwards compatible support. - * - * @return string - */ - public function getOwnerKey() - { - return property_exists($this, 'ownerKey') ? $this->ownerKey : $this->otherKey; - } - /** * Get the name of the "where in" method for eager loading. * From c112ef77d180b9c941d9c7905610d1af555da334 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 13 Sep 2023 10:43:07 +0200 Subject: [PATCH 107/446] Switch tests to SQLite to remove the need for MySQL server (#2616) --- .github/workflows/build-ci.yml | 11 -- CONTRIBUTING.md | 3 +- Dockerfile | 2 +- docker-compose.yml | 13 --- docs/eloquent-models.md | 2 +- phpunit.xml.dist | 34 +----- src/Query/Builder.php | 2 +- tests/HybridRelationsTest.php | 118 ++++++++++---------- tests/Models/Book.php | 4 +- tests/Models/Role.php | 4 +- tests/Models/{MysqlBook.php => SqlBook.php} | 19 ++-- tests/Models/{MysqlRole.php => SqlRole.php} | 21 ++-- tests/Models/{MysqlUser.php => SqlUser.php} | 21 ++-- tests/Models/User.php | 8 +- tests/TestCase.php | 2 +- tests/config/database.php | 10 +- 16 files changed, 103 insertions(+), 171 deletions(-) rename tests/Models/{MysqlBook.php => SqlBook.php} (65%) rename tests/Models/{MysqlRole.php => SqlRole.php} (62%) rename tests/Models/{MysqlUser.php => SqlUser.php} (66%) diff --git a/.github/workflows/build-ci.yml b/.github/workflows/build-ci.yml index 390ac1ac9..f3ff7a625 100644 --- a/.github/workflows/build-ci.yml +++ b/.github/workflows/build-ci.yml @@ -22,15 +22,6 @@ jobs: php: - '8.1' - '8.2' - services: - mysql: - image: mysql:8.0 - ports: - - 3307:3306 - env: - MYSQL_ALLOW_EMPTY_PASSWORD: 'yes' - MYSQL_DATABASE: 'unittest' - MYSQL_ROOT_PASSWORD: steps: - uses: actions/checkout@v4 @@ -77,8 +68,6 @@ jobs: ./vendor/bin/phpunit --coverage-clover coverage.xml env: MONGODB_URI: 'mongodb://127.0.0.1/?replicaSet=rs' - MYSQL_HOST: 0.0.0.0 - MYSQL_PORT: 3307 - uses: codecov/codecov-action@v3 with: token: ${{ secrets.CODECOV_TOKEN }} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 096fd8a06..4de5b27bd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -39,11 +39,10 @@ Before submitting a pull request: ## Run Tests The full test suite requires PHP cli with mongodb extension, a running MongoDB server and a running MySQL server. -Tests requiring MySQL will be skipped if it is not running. Duplicate the `phpunit.xml.dist` file to `phpunit.xml` and edit the environment variables to match your setup. ```bash -$ docker-compose up -d mongodb mysql +$ docker-compose up -d mongodb $ docker-compose run tests ``` diff --git a/Dockerfile b/Dockerfile index 49a2ce736..5d22eb513 100644 --- a/Dockerfile +++ b/Dockerfile @@ -6,7 +6,7 @@ RUN apt-get update && \ apt-get install -y autoconf pkg-config libssl-dev git unzip libzip-dev zlib1g-dev && \ pecl install mongodb && docker-php-ext-enable mongodb && \ pecl install xdebug && docker-php-ext-enable xdebug && \ - docker-php-ext-install -j$(nproc) pdo_mysql zip + docker-php-ext-install -j$(nproc) zip COPY --from=composer:2.6.2 /usr/bin/composer /usr/local/bin/composer diff --git a/docker-compose.yml b/docker-compose.yml index 7ae2b00d8..fec4aa191 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -12,22 +12,9 @@ services: working_dir: /code environment: MONGODB_URI: 'mongodb://mongodb/' - MYSQL_HOST: 'mysql' depends_on: mongodb: condition: service_healthy - mysql: - condition: service_started - - mysql: - container_name: mysql - image: mysql:8.0 - ports: - - "3306:3306" - environment: - MYSQL_ROOT_PASSWORD: - MYSQL_DATABASE: unittest - MYSQL_ALLOW_EMPTY_PASSWORD: 'yes' mongodb: container_name: mongodb diff --git a/docs/eloquent-models.md b/docs/eloquent-models.md index f8dabb91a..c64bb76b6 100644 --- a/docs/eloquent-models.md +++ b/docs/eloquent-models.md @@ -427,7 +427,7 @@ If you want this functionality to work both ways, your SQL-models will need to u **This functionality only works for `hasOne`, `hasMany` and `belongsTo`.** -The MySQL model should use the `HybridRelations` trait: +The SQL model should use the `HybridRelations` trait: ```php use MongoDB\Laravel\Eloquent\HybridRelations; diff --git a/phpunit.xml.dist b/phpunit.xml.dist index cd883f311..7a38678eb 100644 --- a/phpunit.xml.dist +++ b/phpunit.xml.dist @@ -11,44 +11,14 @@ > - + tests/ - - tests/SchemaTest.php - - - tests/SeederTest.php - - - tests/QueryBuilderTest.php - tests/QueryTest.php - - - tests/TransactionTest.php - - - tests/ModelTest.php - tests/RelationsTest.php - - - tests/RelationsTest.php - tests/EmbeddedRelationsTest.php - - - tests/RelationsTest.php - - - tests/ValidationTest.php - - - - - + diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 6bcea4158..1494a7345 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -276,7 +276,7 @@ public function toMql(): array $group['_id'][$column] = '$' . $column; // When grouping, also add the $last operator to each grouped field, - // this mimics MySQL's behaviour a bit. + // this mimics SQL's behaviour a bit. $group[$column] = ['$last' => '$' . $column]; } diff --git a/tests/HybridRelationsTest.php b/tests/HybridRelationsTest.php index 5dc6b307b..9ff6264e5 100644 --- a/tests/HybridRelationsTest.php +++ b/tests/HybridRelationsTest.php @@ -4,13 +4,13 @@ namespace MongoDB\Laravel\Tests; -use Illuminate\Database\MySqlConnection; +use Illuminate\Database\SQLiteConnection; use Illuminate\Support\Facades\DB; use MongoDB\Laravel\Tests\Models\Book; -use MongoDB\Laravel\Tests\Models\MysqlBook; -use MongoDB\Laravel\Tests\Models\MysqlRole; -use MongoDB\Laravel\Tests\Models\MysqlUser; use MongoDB\Laravel\Tests\Models\Role; +use MongoDB\Laravel\Tests\Models\SqlBook; +use MongoDB\Laravel\Tests\Models\SqlRole; +use MongoDB\Laravel\Tests\Models\SqlUser; use MongoDB\Laravel\Tests\Models\User; use PDOException; @@ -21,30 +21,30 @@ public function setUp(): void parent::setUp(); try { - DB::connection('mysql')->select('SELECT 1'); + DB::connection('sqlite')->select('SELECT 1'); } catch (PDOException) { - $this->markTestSkipped('MySQL connection is not available.'); + $this->markTestSkipped('SQLite connection is not available.'); } - MysqlUser::executeSchema(); - MysqlBook::executeSchema(); - MysqlRole::executeSchema(); + SqlUser::executeSchema(); + SqlBook::executeSchema(); + SqlRole::executeSchema(); } public function tearDown(): void { - MysqlUser::truncate(); - MysqlBook::truncate(); - MysqlRole::truncate(); + SqlUser::truncate(); + SqlBook::truncate(); + SqlRole::truncate(); } - public function testMysqlRelations() + public function testSqlRelations() { - $user = new MysqlUser(); - $this->assertInstanceOf(MysqlUser::class, $user); - $this->assertInstanceOf(MySqlConnection::class, $user->getConnection()); + $user = new SqlUser(); + $this->assertInstanceOf(SqlUser::class, $user); + $this->assertInstanceOf(SQLiteConnection::class, $user->getConnection()); - // Mysql User + // SQL User $user->name = 'John Doe'; $user->save(); $this->assertIsInt($user->id); @@ -52,22 +52,22 @@ public function testMysqlRelations() // SQL has many $book = new Book(['title' => 'Game of Thrones']); $user->books()->save($book); - $user = MysqlUser::find($user->id); // refetch + $user = SqlUser::find($user->id); // refetch $this->assertCount(1, $user->books); // MongoDB belongs to $book = $user->books()->first(); // refetch - $this->assertEquals('John Doe', $book->mysqlAuthor->name); + $this->assertEquals('John Doe', $book->sqlAuthor->name); // SQL has one $role = new Role(['type' => 'admin']); $user->role()->save($role); - $user = MysqlUser::find($user->id); // refetch + $user = SqlUser::find($user->id); // refetch $this->assertEquals('admin', $user->role->type); // MongoDB belongs to $role = $user->role()->first(); // refetch - $this->assertEquals('John Doe', $role->mysqlUser->name); + $this->assertEquals('John Doe', $role->sqlUser->name); // MongoDB User $user = new User(); @@ -75,36 +75,36 @@ public function testMysqlRelations() $user->save(); // MongoDB has many - $book = new MysqlBook(['title' => 'Game of Thrones']); - $user->mysqlBooks()->save($book); + $book = new SqlBook(['title' => 'Game of Thrones']); + $user->sqlBooks()->save($book); $user = User::find($user->_id); // refetch - $this->assertCount(1, $user->mysqlBooks); + $this->assertCount(1, $user->sqlBooks); // SQL belongs to - $book = $user->mysqlBooks()->first(); // refetch + $book = $user->sqlBooks()->first(); // refetch $this->assertEquals('John Doe', $book->author->name); // MongoDB has one - $role = new MysqlRole(['type' => 'admin']); - $user->mysqlRole()->save($role); + $role = new SqlRole(['type' => 'admin']); + $user->sqlRole()->save($role); $user = User::find($user->_id); // refetch - $this->assertEquals('admin', $user->mysqlRole->type); + $this->assertEquals('admin', $user->sqlRole->type); // SQL belongs to - $role = $user->mysqlRole()->first(); // refetch + $role = $user->sqlRole()->first(); // refetch $this->assertEquals('John Doe', $role->user->name); } public function testHybridWhereHas() { - $user = new MysqlUser(); - $otherUser = new MysqlUser(); - $this->assertInstanceOf(MysqlUser::class, $user); - $this->assertInstanceOf(MySqlConnection::class, $user->getConnection()); - $this->assertInstanceOf(MysqlUser::class, $otherUser); - $this->assertInstanceOf(MySqlConnection::class, $otherUser->getConnection()); - - //MySql User + $user = new SqlUser(); + $otherUser = new SqlUser(); + $this->assertInstanceOf(SqlUser::class, $user); + $this->assertInstanceOf(SQLiteConnection::class, $user->getConnection()); + $this->assertInstanceOf(SqlUser::class, $otherUser); + $this->assertInstanceOf(SQLiteConnection::class, $otherUser->getConnection()); + + // SQL User $user->name = 'John Doe'; $user->id = 2; $user->save(); @@ -130,19 +130,19 @@ public function testHybridWhereHas() new Book(['title' => 'Harry Planter']), ]); - $users = MysqlUser::whereHas('books', function ($query) { + $users = SqlUser::whereHas('books', function ($query) { return $query->where('title', 'LIKE', 'Har%'); })->get(); $this->assertEquals(2, $users->count()); - $users = MysqlUser::whereHas('books', function ($query) { + $users = SqlUser::whereHas('books', function ($query) { return $query->where('title', 'LIKE', 'Harry%'); }, '>=', 2)->get(); $this->assertEquals(1, $users->count()); - $books = Book::whereHas('mysqlAuthor', function ($query) { + $books = Book::whereHas('sqlAuthor', function ($query) { return $query->where('name', 'LIKE', 'Other%'); })->get(); @@ -151,14 +151,14 @@ public function testHybridWhereHas() public function testHybridWith() { - $user = new MysqlUser(); - $otherUser = new MysqlUser(); - $this->assertInstanceOf(MysqlUser::class, $user); - $this->assertInstanceOf(MySqlConnection::class, $user->getConnection()); - $this->assertInstanceOf(MysqlUser::class, $otherUser); - $this->assertInstanceOf(MySqlConnection::class, $otherUser->getConnection()); - - //MySql User + $user = new SqlUser(); + $otherUser = new SqlUser(); + $this->assertInstanceOf(SqlUser::class, $user); + $this->assertInstanceOf(SQLiteConnection::class, $user->getConnection()); + $this->assertInstanceOf(SqlUser::class, $otherUser); + $this->assertInstanceOf(SQLiteConnection::class, $otherUser->getConnection()); + + // SQL User $user->name = 'John Doe'; $user->id = 2; $user->save(); @@ -171,18 +171,18 @@ public function testHybridWith() $this->assertIsInt($otherUser->id); // Clear to start Book::truncate(); - MysqlBook::truncate(); + SqlBook::truncate(); // Create books - // Mysql relation - $user->mysqlBooks()->saveMany([ - new MysqlBook(['title' => 'Game of Thrones']), - new MysqlBook(['title' => 'Harry Potter']), + // SQL relation + $user->sqlBooks()->saveMany([ + new SqlBook(['title' => 'Game of Thrones']), + new SqlBook(['title' => 'Harry Potter']), ]); - $otherUser->mysqlBooks()->saveMany([ - new MysqlBook(['title' => 'Harry Plants']), - new MysqlBook(['title' => 'Harveys']), - new MysqlBook(['title' => 'Harry Planter']), + $otherUser->sqlBooks()->saveMany([ + new SqlBook(['title' => 'Harry Plants']), + new SqlBook(['title' => 'Harveys']), + new SqlBook(['title' => 'Harry Planter']), ]); // SQL has many Hybrid $user->books()->saveMany([ @@ -196,12 +196,12 @@ public function testHybridWith() new Book(['title' => 'Harry Planter']), ]); - MysqlUser::with('books')->get() + SqlUser::with('books')->get() ->each(function ($user) { $this->assertEquals($user->id, $user->books->count()); }); - MysqlUser::whereHas('mysqlBooks', function ($query) { + SqlUser::whereHas('sqlBooks', function ($query) { return $query->where('title', 'LIKE', 'Harry%'); }) ->with('books') diff --git a/tests/Models/Book.php b/tests/Models/Book.php index e196ec4b3..70d566fe2 100644 --- a/tests/Models/Book.php +++ b/tests/Models/Book.php @@ -24,8 +24,8 @@ public function author(): BelongsTo return $this->belongsTo(User::class, 'author_id'); } - public function mysqlAuthor(): BelongsTo + public function sqlAuthor(): BelongsTo { - return $this->belongsTo(MysqlUser::class, 'author_id'); + return $this->belongsTo(SqlUser::class, 'author_id'); } } diff --git a/tests/Models/Role.php b/tests/Models/Role.php index 2c191ac1b..ab5eaa029 100644 --- a/tests/Models/Role.php +++ b/tests/Models/Role.php @@ -18,8 +18,8 @@ public function user(): BelongsTo return $this->belongsTo(User::class); } - public function mysqlUser(): BelongsTo + public function sqlUser(): BelongsTo { - return $this->belongsTo(MysqlUser::class); + return $this->belongsTo(SqlUser::class); } } diff --git a/tests/Models/MysqlBook.php b/tests/Models/SqlBook.php similarity index 65% rename from tests/Models/MysqlBook.php rename to tests/Models/SqlBook.php index 0a3662686..babc984eb 100644 --- a/tests/Models/MysqlBook.php +++ b/tests/Models/SqlBook.php @@ -7,17 +7,17 @@ use Illuminate\Database\Eloquent\Model as EloquentModel; use Illuminate\Database\Eloquent\Relations\BelongsTo; use Illuminate\Database\Schema\Blueprint; -use Illuminate\Database\Schema\MySqlBuilder; +use Illuminate\Database\Schema\SQLiteBuilder; use Illuminate\Support\Facades\Schema; use MongoDB\Laravel\Eloquent\HybridRelations; use function assert; -class MysqlBook extends EloquentModel +class SqlBook extends EloquentModel { use HybridRelations; - protected $connection = 'mysql'; + protected $connection = 'sqlite'; protected $table = 'books'; protected static $unguarded = true; protected $primaryKey = 'title'; @@ -32,17 +32,14 @@ public function author(): BelongsTo */ public static function executeSchema(): void { - $schema = Schema::connection('mysql'); - assert($schema instanceof MySqlBuilder); + $schema = Schema::connection('sqlite'); + assert($schema instanceof SQLiteBuilder); - if ($schema->hasTable('books')) { - return; - } - - Schema::connection('mysql')->create('books', function (Blueprint $table) { + $schema->dropIfExists('books'); + $schema->create('books', function (Blueprint $table) { $table->string('title'); $table->string('author_id')->nullable(); - $table->integer('mysql_user_id')->unsigned()->nullable(); + $table->integer('sql_user_id')->unsigned()->nullable(); $table->timestamps(); }); } diff --git a/tests/Models/MysqlRole.php b/tests/Models/SqlRole.php similarity index 62% rename from tests/Models/MysqlRole.php rename to tests/Models/SqlRole.php index e4f293313..17c01e819 100644 --- a/tests/Models/MysqlRole.php +++ b/tests/Models/SqlRole.php @@ -7,17 +7,17 @@ use Illuminate\Database\Eloquent\Model as EloquentModel; use Illuminate\Database\Eloquent\Relations\BelongsTo; use Illuminate\Database\Schema\Blueprint; -use Illuminate\Database\Schema\MySqlBuilder; +use Illuminate\Database\Schema\SQLiteBuilder; use Illuminate\Support\Facades\Schema; use MongoDB\Laravel\Eloquent\HybridRelations; use function assert; -class MysqlRole extends EloquentModel +class SqlRole extends EloquentModel { use HybridRelations; - protected $connection = 'mysql'; + protected $connection = 'sqlite'; protected $table = 'roles'; protected static $unguarded = true; @@ -26,9 +26,9 @@ public function user(): BelongsTo return $this->belongsTo(User::class); } - public function mysqlUser(): BelongsTo + public function sqlUser(): BelongsTo { - return $this->belongsTo(MysqlUser::class); + return $this->belongsTo(SqlUser::class); } /** @@ -36,14 +36,11 @@ public function mysqlUser(): BelongsTo */ public static function executeSchema() { - $schema = Schema::connection('mysql'); - assert($schema instanceof MySqlBuilder); + $schema = Schema::connection('sqlite'); + assert($schema instanceof SQLiteBuilder); - if ($schema->hasTable('roles')) { - return; - } - - Schema::connection('mysql')->create('roles', function (Blueprint $table) { + $schema->dropIfExists('roles'); + $schema->create('roles', function (Blueprint $table) { $table->string('type'); $table->string('user_id'); $table->timestamps(); diff --git a/tests/Models/MysqlUser.php b/tests/Models/SqlUser.php similarity index 66% rename from tests/Models/MysqlUser.php rename to tests/Models/SqlUser.php index c16a14220..1fe11276a 100644 --- a/tests/Models/MysqlUser.php +++ b/tests/Models/SqlUser.php @@ -8,17 +8,17 @@ use Illuminate\Database\Eloquent\Relations\HasMany; use Illuminate\Database\Eloquent\Relations\HasOne; use Illuminate\Database\Schema\Blueprint; -use Illuminate\Database\Schema\MySqlBuilder; +use Illuminate\Database\Schema\SQLiteBuilder; use Illuminate\Support\Facades\Schema; use MongoDB\Laravel\Eloquent\HybridRelations; use function assert; -class MysqlUser extends EloquentModel +class SqlUser extends EloquentModel { use HybridRelations; - protected $connection = 'mysql'; + protected $connection = 'sqlite'; protected $table = 'users'; protected static $unguarded = true; @@ -32,9 +32,9 @@ public function role(): HasOne return $this->hasOne(Role::class); } - public function mysqlBooks(): HasMany + public function sqlBooks(): HasMany { - return $this->hasMany(MysqlBook::class); + return $this->hasMany(SqlBook::class); } /** @@ -42,14 +42,11 @@ public function mysqlBooks(): HasMany */ public static function executeSchema(): void { - $schema = Schema::connection('mysql'); - assert($schema instanceof MySqlBuilder); + $schema = Schema::connection('sqlite'); + assert($schema instanceof SQLiteBuilder); - if ($schema->hasTable('users')) { - return; - } - - Schema::connection('mysql')->create('users', function (Blueprint $table) { + $schema->dropIfExists('users'); + $schema->create('users', function (Blueprint $table) { $table->increments('id'); $table->string('name'); $table->timestamps(); diff --git a/tests/Models/User.php b/tests/Models/User.php index 945d8b074..523b489e7 100644 --- a/tests/Models/User.php +++ b/tests/Models/User.php @@ -51,9 +51,9 @@ public function books() return $this->hasMany(Book::class, 'author_id'); } - public function mysqlBooks() + public function sqlBooks() { - return $this->hasMany(MysqlBook::class, 'author_id'); + return $this->hasMany(SqlBook::class, 'author_id'); } public function items() @@ -66,9 +66,9 @@ public function role() return $this->hasOne(Role::class); } - public function mysqlRole() + public function sqlRole() { - return $this->hasOne(MysqlRole::class); + return $this->hasOne(SqlRole::class); } public function clients() diff --git a/tests/TestCase.php b/tests/TestCase.php index 7098f729f..9f3a76e00 100644 --- a/tests/TestCase.php +++ b/tests/TestCase.php @@ -67,7 +67,7 @@ protected function getEnvironmentSetUp($app) $app['config']->set('app.key', 'ZsZewWyUJ5FsKp9lMwv4tYbNlegQilM7'); $app['config']->set('database.default', 'mongodb'); - $app['config']->set('database.connections.mysql', $config['connections']['mysql']); + $app['config']->set('database.connections.sqlite', $config['connections']['sqlite']); $app['config']->set('database.connections.mongodb', $config['connections']['mongodb']); $app['config']->set('database.connections.mongodb2', $config['connections']['mongodb']); diff --git a/tests/config/database.php b/tests/config/database.php index 24fee24f4..275dce61a 100644 --- a/tests/config/database.php +++ b/tests/config/database.php @@ -15,13 +15,9 @@ ], ], - 'mysql' => [ - 'driver' => 'mysql', - 'host' => env('MYSQL_HOST', 'mysql'), - 'port' => env('MYSQL_PORT') ? (int) env('MYSQL_PORT') : 3306, - 'database' => env('MYSQL_DATABASE', 'unittest'), - 'username' => env('MYSQL_USERNAME', 'root'), - 'password' => env('MYSQL_PASSWORD', ''), + 'sqlite' => [ + 'driver' => 'sqlite', + 'database' => env('SQLITE_DATABASE', ':memory:'), 'charset' => 'utf8', 'collation' => 'utf8_unicode_ci', 'prefix' => '', From 7880990a567e0b40eed6c709cb5b62f4e9582a23 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 19 Sep 2023 15:39:24 +0200 Subject: [PATCH 108/446] PHPORM-90 Fix whereNot to use `$nor` (#2624) --- src/Query/Builder.php | 3 +- tests/Query/BuilderTest.php | 58 +++++++++++++++++++++---------------- tests/QueryTest.php | 44 ++++++++++++++++++++++++++++ 3 files changed, 79 insertions(+), 26 deletions(-) diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 1494a7345..a145ecb3e 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -1053,8 +1053,9 @@ protected function compileWheres(): array $method = 'compileWhere' . $where['type']; $result = $this->{$method}($where); + // Negate the expression if (str_ends_with($where['boolean'], 'not')) { - $result = ['$not' => $result]; + $result = ['$nor' => [$result]]; } // Wrap the where with an $or operator. diff --git a/tests/Query/BuilderTest.php b/tests/Query/BuilderTest.php index 556239afc..2bfc03515 100644 --- a/tests/Query/BuilderTest.php +++ b/tests/Query/BuilderTest.php @@ -195,8 +195,8 @@ public static function provideQueryBuilderToMql(): iterable 'find' => [ [ '$and' => [ - ['$not' => ['name' => 'foo']], - ['$not' => ['name' => ['$ne' => 'bar']]], + ['$nor' => [['name' => 'foo']]], + ['$nor' => [['name' => ['$ne' => 'bar']]]], ], ], [], // options @@ -231,8 +231,8 @@ public static function provideQueryBuilderToMql(): iterable 'find' => [ [ '$or' => [ - ['$not' => ['name' => 'foo']], - ['$not' => ['name' => ['$ne' => 'bar']]], + ['$nor' => [['name' => 'foo']]], + ['$nor' => [['name' => ['$ne' => 'bar']]]], ], ], [], // options @@ -248,7 +248,7 @@ public static function provideQueryBuilderToMql(): iterable 'find' => [ [ '$or' => [ - ['$not' => ['name' => 'foo']], + ['$nor' => [['name' => 'foo']]], ['name' => ['$ne' => 'bar']], ], ], @@ -264,7 +264,7 @@ public static function provideQueryBuilderToMql(): iterable yield 'whereNot callable' => [ [ 'find' => [ - ['$not' => ['name' => 'foo']], + ['$nor' => [['name' => 'foo']]], [], // options ], ], @@ -278,7 +278,7 @@ public static function provideQueryBuilderToMql(): iterable [ '$and' => [ ['name' => 'bar'], - ['$not' => ['email' => 'foo']], + ['$nor' => [['email' => 'foo']]], ], ], [], // options @@ -295,10 +295,12 @@ public static function provideQueryBuilderToMql(): iterable [ 'find' => [ [ - '$not' => [ - '$and' => [ - ['name' => 'foo'], - ['$not' => ['email' => ['$ne' => 'bar']]], + '$nor' => [ + [ + '$and' => [ + ['name' => 'foo'], + ['$nor' => [['email' => ['$ne' => 'bar']]]], + ], ], ], ], @@ -318,7 +320,7 @@ public static function provideQueryBuilderToMql(): iterable [ '$or' => [ ['name' => 'bar'], - ['$not' => ['email' => 'foo']], + ['$nor' => [['email' => 'foo']]], ], ], [], // options @@ -337,7 +339,7 @@ public static function provideQueryBuilderToMql(): iterable [ '$or' => [ ['name' => 'bar'], - ['$not' => ['email' => 'foo']], + ['$nor' => [['email' => 'foo']]], ], ], [], // options @@ -353,10 +355,12 @@ public static function provideQueryBuilderToMql(): iterable [ 'find' => [ [ - '$not' => [ - '$and' => [ - ['foo' => 1], - ['bar' => 2], + '$nor' => [ + [ + '$and' => [ + ['foo' => 1], + ['bar' => 2], + ], ], ], ], @@ -371,10 +375,12 @@ public static function provideQueryBuilderToMql(): iterable [ 'find' => [ [ - '$not' => [ - '$and' => [ - ['foo' => 1], - ['bar' => 2], + '$nor' => [ + [ + '$and' => [ + ['foo' => 1], + ['bar' => 2], + ], ], ], ], @@ -389,10 +395,12 @@ public static function provideQueryBuilderToMql(): iterable [ 'find' => [ [ - '$not' => [ - '$and' => [ - ['foo' => 1], - ['bar' => ['$lt' => 2]], + '$nor' => [ + [ + '$and' => [ + ['foo' => 1], + ['bar' => ['$lt' => 2]], + ], ], ], ], diff --git a/tests/QueryTest.php b/tests/QueryTest.php index 3d1df99f0..a5e834e53 100644 --- a/tests/QueryTest.php +++ b/tests/QueryTest.php @@ -6,6 +6,8 @@ use DateTimeImmutable; use LogicException; +use MongoDB\BSON\Regex; +use MongoDB\Laravel\Eloquent\Builder; use MongoDB\Laravel\Tests\Models\Birthday; use MongoDB\Laravel\Tests\Models\Scoped; use MongoDB\Laravel\Tests\Models\User; @@ -154,6 +156,48 @@ public function testSelect(): void $this->assertNull($user->age); } + public function testWhereNot(): void + { + // implicit equality operator + $users = User::whereNot('title', 'admin')->get(); + $this->assertCount(6, $users); + + // nested query + $users = User::whereNot(fn (Builder $builder) => $builder->where('title', 'admin'))->get(); + $this->assertCount(6, $users); + + // double negation + $users = User::whereNot('title', '!=', 'admin')->get(); + $this->assertCount(3, $users); + + // nested negation + $users = User::whereNot(fn (Builder $builder) => $builder + ->whereNot('title', 'admin'))->get(); + $this->assertCount(3, $users); + + // explicit equality operator + $users = User::whereNot('title', '=', 'admin')->get(); + $this->assertCount(6, $users); + + // custom query operator + $users = User::whereNot('title', ['$in' => ['admin']])->get(); + $this->assertCount(6, $users); + + // regex + $users = User::whereNot('title', new Regex('^admin$'))->get(); + $this->assertCount(6, $users); + + // equals null + $users = User::whereNot('title', null)->get(); + $this->assertCount(8, $users); + + // nested $or + $users = User::whereNot(fn (Builder $builder) => $builder + ->where('title', 'admin') + ->orWhere('age', 35))->get(); + $this->assertCount(5, $users); + } + public function testOrWhere(): void { $users = User::where('age', 13)->orWhere('title', 'admin')->get(); From 1af8b9dcfe336c83b0aa8f09193747129c2bb663 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Thu, 28 Sep 2023 13:54:46 +0200 Subject: [PATCH 109/446] Prepare v4.0.0 release (#2631) --- CHANGELOG.md | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3841b715c..5f897386a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,28 +1,28 @@ # Changelog All notable changes to this project will be documented in this file. -## [4.0.0] - unreleased +## [4.0.0] - 2023-09-28 - Rename package to `mongodb/laravel-mongodb` - Change namespace to `MongoDB\Laravel` -- Add classes to cast `ObjectId` and `UUID` instances [#1](https://github.com/GromNaN/laravel-mongodb/pull/1) by [@alcaeus](https://github.com/alcaeus). -- Add `Query\Builder::toMql()` to simplify comprehensive query tests [#6](https://github.com/GromNaN/laravel-mongodb/pull/6) by [@GromNaN](https://github.com/GromNaN). -- Fix `Query\Builder::whereNot` to use MongoDB [`$not`](https://www.mongodb.com/docs/manual/reference/operator/query/not/) operator [#13](https://github.com/GromNaN/laravel-mongodb/pull/13) by [@GromNaN](https://github.com/GromNaN). -- Fix `Query\Builder::whereBetween` to accept `Carbon\Period` object [#10](https://github.com/GromNaN/laravel-mongodb/pull/10) by [@GromNaN](https://github.com/GromNaN). -- Throw an exception for unsupported `Query\Builder` methods [#9](https://github.com/GromNaN/laravel-mongodb/pull/9) by [@GromNaN](https://github.com/GromNaN). -- Throw an exception when `Query\Builder::orderBy()` is used with invalid direction [#7](https://github.com/GromNaN/laravel-mongodb/pull/7) by [@GromNaN](https://github.com/GromNaN). -- Throw an exception when `Query\Builder::push()` is used incorrectly [#5](https://github.com/GromNaN/laravel-mongodb/pull/5) by [@GromNaN](https://github.com/GromNaN). -- Remove public property `Query\Builder::$paginating` [#15](https://github.com/GromNaN/laravel-mongodb/pull/15) by [@GromNaN](https://github.com/GromNaN). -- Remove call to deprecated `Collection::count` for `countDocuments` [#18](https://github.com/GromNaN/laravel-mongodb/pull/18) by [@GromNaN](https://github.com/GromNaN). -- Accept operators prefixed by `$` in `Query\Builder::orWhere` [#20](https://github.com/GromNaN/laravel-mongodb/pull/20) by [@GromNaN](https://github.com/GromNaN). -- Remove `Query\Builder::whereAll($column, $values)`. Use `Query\Builder::where($column, 'all', $values)` instead. [#16](https://github.com/GromNaN/laravel-mongodb/pull/16) by [@GromNaN](https://github.com/GromNaN). -- Fix validation of unique values when the validated value is found as part of an existing value. [#21](https://github.com/GromNaN/laravel-mongodb/pull/21) by [@GromNaN](https://github.com/GromNaN). -- Support `%` and `_` in `like` expression [#17](https://github.com/GromNaN/laravel-mongodb/pull/17) by [@GromNaN](https://github.com/GromNaN). -- Change signature of `Query\Builder::__constructor` to match the parent class [#26](https://github.com/GromNaN/laravel-mongodb-private/pull/26) by [@GromNaN](https://github.com/GromNaN). -- Fix Query on `whereDate`, `whereDay`, `whereMonth`, `whereYear`, `whereTime` to use MongoDB operators [#2570](https://github.com/mongodb/laravel-mongodb/pull/2376) by [@Davpyu](https://github.com/Davpyu) and [@GromNaN](https://github.com/GromNaN). -- `Model::unset()` does not persist the change. Call `Model::save()` to persist the change [#2578](https://github.com/mongodb/laravel-mongodb/pull/2578) by [@GromNaN](https://github.com/GromNaN). -- Support delete one document with `Query\Builder::limit(1)->delete()` [#2591](https://github.com/mongodb/laravel-mongodb/pull/2591) by [@GromNaN](https://github.com/GromNaN) -- Add trait `MongoDB\Laravel\Eloquent\MassPrunable` to replace the Eloquent trait on MongoDB models [#2598](https://github.com/mongodb/laravel-mongodb/pull/2598) by [@GromNaN](https://github.com/GromNaN) +- Add classes to cast `ObjectId` and `UUID` instances [5105553](https://github.com/mongodb/laravel-mongodb/commit/5105553cbb672a982ccfeaa5b653d33aaca1553e) by [@alcaeus](https://github.com/alcaeus). +- Add `Query\Builder::toMql()` to simplify comprehensive query tests [ae3e0d5](https://github.com/mongodb/laravel-mongodb/commit/ae3e0d5f72c24edcb2a78d321910397f4134e90f) by @GromNaN. +- Fix `Query\Builder::whereNot` to use MongoDB [`$not`](https://www.mongodb.com/docs/manual/reference/operator/query/not/) operator [e045fab](https://github.com/mongodb/laravel-mongodb/commit/e045fab6c315fe6d17f75669665898ed98b88107) by @GromNaN. +- Fix `Query\Builder::whereBetween` to accept `Carbon\Period` object [f729baa](https://github.com/mongodb/laravel-mongodb/commit/f729baad59b4baf3307121df7f60c5cd03a504f5) by @GromNaN. +- Throw an exception for unsupported `Query\Builder` methods [e1a83f4](https://github.com/mongodb/laravel-mongodb/commit/e1a83f47f16054286bc433fc9ccfee078bb40741) by @GromNaN. +- Throw an exception when `Query\Builder::orderBy()` is used with invalid direction [edd0871](https://github.com/mongodb/laravel-mongodb/commit/edd08715a0dd64bab9fd1194e70fface09e02900) by @GromNaN. +- Throw an exception when `Query\Builder::push()` is used incorrectly [19cf7a2](https://github.com/mongodb/laravel-mongodb/commit/19cf7a2ee2c0f2c69459952c4207ee8279b818d3) by @GromNaN. +- Remove public property `Query\Builder::$paginating` [e045fab](https://github.com/mongodb/laravel-mongodb/commit/e045fab6c315fe6d17f75669665898ed98b88107) by @GromNaN. +- Remove call to deprecated `Collection::count` for `countDocuments` [4514964](https://github.com/mongodb/laravel-mongodb/commit/4514964145c70c37e6221be8823f8f73a201c259) by @GromNaN. +- Accept operators prefixed by `$` in `Query\Builder::orWhere` [0fb83af](https://github.com/mongodb/laravel-mongodb/commit/0fb83af01284cb16def1eda6987432ebbd64bb8f) by @GromNaN. +- Remove `Query\Builder::whereAll($column, $values)`. Use `Query\Builder::where($column, 'all', $values)` instead. [1d74dc3](https://github.com/mongodb/laravel-mongodb/commit/1d74dc3d3df9f7a579b343f3109160762050ca01) by @GromNaN. +- Fix validation of unique values when the validated value is found as part of an existing value. [d5f1bb9](https://github.com/mongodb/laravel-mongodb/commit/d5f1bb901f3e3c6777bc604be1af0a8238dc089a) by @GromNaN. +- Support `%` and `_` in `like` expression [ea89e86](https://github.com/mongodb/laravel-mongodb/commit/ea89e8631350cd81c8d5bf977efb4c09e60d7807) by @GromNaN. +- Change signature of `Query\Builder::__constructor` to match the parent class [#2570](https://github.com/mongodb/laravel-mongodb/pull/2570) by @GromNaN. +- Fix Query on `whereDate`, `whereDay`, `whereMonth`, `whereYear`, `whereTime` to use MongoDB operators [#2376](https://github.com/mongodb/laravel-mongodb/pull/2376) by [@Davpyu](https://github.com/Davpyu) and @GromNaN. +- `Model::unset()` does not persist the change. Call `Model::save()` to persist the change [#2578](https://github.com/mongodb/laravel-mongodb/pull/2578) by @GromNaN. +- Support delete one document with `Query\Builder::limit(1)->delete()` [#2591](https://github.com/mongodb/laravel-mongodb/pull/2591) by @GromNaN +- Add trait `MongoDB\Laravel\Eloquent\MassPrunable` to replace the Eloquent trait on MongoDB models [#2598](https://github.com/mongodb/laravel-mongodb/pull/2598) by @GromNaN ## [3.9.2] - 2022-09-01 From 849cb1fe3cdf9c0618dc91ccf8a46f2faad55d0e Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Thu, 28 Sep 2023 19:26:03 +0200 Subject: [PATCH 110/446] Update documentation to reflect new branching strategy (#2632) --- RELEASING.md | 100 ++++++++++---------------------------------------- composer.json | 3 -- 2 files changed, 20 insertions(+), 83 deletions(-) diff --git a/RELEASING.md b/RELEASING.md index 35dfbf342..e0b494d08 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -1,8 +1,7 @@ # Releasing -The following steps outline the release process for both new minor versions (e.g. -releasing the `master` branch as X.Y.0) and patch versions (e.g. releasing the -`vX.Y` branch as X.Y.Z). +The following steps outline the release process for both new minor versions and +patch versions. The command examples below assume that the canonical "mongodb" repository has the remote name "mongodb". You may need to adjust these commands if you've given @@ -37,26 +36,10 @@ page. This uses [semantic versioning](https://semver.org/). Do not break backwards compatibility in a non-major release or your users will kill you. -Before proceeding, ensure that the `master` branch is up-to-date with all code +Before proceeding, ensure that the default branch is up-to-date with all code changes in this maintenance branch. This is important because we will later -merge the ensuing release commits up to master with `--strategy=ours`, which -will ignore changes from the merged commits. - -## Update composer.json - -This is especially important before releasing a new minor version. - -Ensure that the extension and PHP library requirements, as well as the branch -alias in `composer.json` are correct for the version being released. For -example, the branch alias for the 4.1.0 release in the `master` branch should -be `4.1.x-dev`. - -Commit and push any changes: - -```console -$ git commit -m "Update composer.json X.Y.Z" composer.json -$ git push mongodb -``` +merge the ensuing release commits with `--strategy=ours`, which will ignore +changes from the merged commits. ## Tag the release @@ -69,78 +52,35 @@ $ git push mongodb --tags ## Branch management -# Creating a maintenance branch and updating master branch alias +# Creating a maintenance branch and updating default branch name -After releasing a new major or minor version (e.g. 4.0.0), a maintenance branch -(e.g. v4.0) should be created. Any development towards a patch release (e.g. -4.0.1) would then be done within that branch and any development for the next -major or minor release can continue in master. +When releasing a new major or minor version (e.g. 4.0.0), the default branch +should be renamed to the next version (e.g. 4.1). Renaming the default branch +using GitHub's UI ensures that all open pull request are changed to target the +new version. -After creating a maintenance branch, the `extra.branch-alias.dev-master` field -in the master branch's `composer.json` file should be updated. For example, -after branching v4.0, `composer.json` in the master branch may still read: - -``` -"branch-alias": { - "dev-master": "4.0.x-dev" -} -``` - -The above would be changed to: - -``` -"branch-alias": { - "dev-master": "4.1.x-dev" -} -``` - -Commit this change: - -```console -$ git commit -m "Master is now 4.1-dev" composer.json -``` - -### After releasing a new minor version - -After a new minor version is released (i.e. `master` was tagged), a maintenance -branch should be created for future patch releases: - -```console -$ git checkout -b vX.Y -$ git push mongodb vX.Y -``` - -Update the master branch alias in `composer.json`: - -```diff - "extra": { - "branch-alias": { -- "dev-master": "4.0.x-dev" -+ "dev-master": "4.1.x-dev" - } - }, -``` - -Commit and push this change: +Once the default branch has been renamed, create the maintenance branch for the +version to be released (e.g. 4.0): ```console -$ git commit -m "Master is now X.Y-dev" composer.json -$ git push mongodb +$ git checkout -b X.Y +$ git push mongodb X.Y ``` ### After releasing a patch version -If this was a patch release, the maintenance branch must be merged up to master: +If this was a patch release, the maintenance branch must be merged up to the +default branch (e.g. 4.1): ```console -$ git checkout master -$ git pull mongodb master -$ git merge vX.Y --strategy=ours +$ git checkout 4.1 +$ git pull mongodb 4.1 +$ git merge 4.0 --strategy=ours $ git push mongodb ``` The `--strategy=ours` option ensures that all changes from the merged commits -will be ignored. This is OK because we previously ensured that the `master` +will be ignored. This is OK because we previously ensured that the `4.1` branch was up-to-date with all code changes in this maintenance branch before tagging. diff --git a/composer.json b/composer.json index 33a797d46..c58e9d761 100644 --- a/composer.json +++ b/composer.json @@ -50,9 +50,6 @@ } }, "extra": { - "branch-alias": { - "dev-master": "4.0.x-dev" - }, "laravel": { "providers": [ "MongoDB\\Laravel\\MongoDBServiceProvider", From 7fee8be85fa0581b3bb1b37d5c18372dd85b12ed Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Mon, 9 Oct 2023 15:11:09 +0200 Subject: [PATCH 111/446] Test on PHP 8.3 (#2637) --- .github/workflows/build-ci.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/build-ci.yml b/.github/workflows/build-ci.yml index f3ff7a625..213ca5323 100644 --- a/.github/workflows/build-ci.yml +++ b/.github/workflows/build-ci.yml @@ -22,6 +22,7 @@ jobs: php: - '8.1' - '8.2' + - '8.3' steps: - uses: actions/checkout@v4 From 56a7233f955fb7182f7111a7ffe1aaa8619eb031 Mon Sep 17 00:00:00 2001 From: Mohammad Mortazavi <39920372+hans-thomas@users.noreply.github.com> Date: Thu, 19 Oct 2023 00:15:43 +0330 Subject: [PATCH 112/446] Add tests on Adding New Fields and fetch relationships withThrashed (#2644) --- tests/ModelTest.php | 8 ++++++++ tests/Models/Soft.php | 5 +++++ tests/Models/User.php | 10 ++++++++++ tests/RelationsTest.php | 19 +++++++++++++++++++ 4 files changed, 42 insertions(+) diff --git a/tests/ModelTest.php b/tests/ModelTest.php index 44e24b699..9d6acb127 100644 --- a/tests/ModelTest.php +++ b/tests/ModelTest.php @@ -114,6 +114,14 @@ public function testUpdate(): void $check = User::find($user->_id); $this->assertEquals(20, $check->age); + + $check->age = 24; + $check->fullname = 'Hans Thomas'; // new field + $check->save(); + + $check = User::find($user->_id); + $this->assertEquals(24, $check->age); + $this->assertEquals('Hans Thomas', $check->fullname); } public function testManualStringId(): void diff --git a/tests/Models/Soft.php b/tests/Models/Soft.php index 31b80908a..763aafb41 100644 --- a/tests/Models/Soft.php +++ b/tests/Models/Soft.php @@ -25,4 +25,9 @@ public function prunable(): Builder { return $this->newQuery(); } + + public function user() + { + return $this->belongsTo(User::class); + } } diff --git a/tests/Models/User.php b/tests/Models/User.php index 523b489e7..4e0d7294c 100644 --- a/tests/Models/User.php +++ b/tests/Models/User.php @@ -51,6 +51,16 @@ public function books() return $this->hasMany(Book::class, 'author_id'); } + public function softs() + { + return $this->hasMany(Soft::class); + } + + public function softsWithTrashed() + { + return $this->hasMany(Soft::class)->withTrashed(); + } + public function sqlBooks() { return $this->hasMany(SqlBook::class, 'author_id'); diff --git a/tests/RelationsTest.php b/tests/RelationsTest.php index 214c6f506..156e656bd 100644 --- a/tests/RelationsTest.php +++ b/tests/RelationsTest.php @@ -13,6 +13,7 @@ use MongoDB\Laravel\Tests\Models\Item; use MongoDB\Laravel\Tests\Models\Photo; use MongoDB\Laravel\Tests\Models\Role; +use MongoDB\Laravel\Tests\Models\Soft; use MongoDB\Laravel\Tests\Models\User; class RelationsTest extends TestCase @@ -50,6 +51,24 @@ public function testHasMany(): void $this->assertCount(3, $items); } + public function testHasManyWithTrashed(): void + { + $user = User::create(['name' => 'George R. R. Martin']); + $first = Soft::create(['title' => 'A Game of Thrones', 'user_id' => $user->_id]); + $second = Soft::create(['title' => 'The Witcher', 'user_id' => $user->_id]); + + self::assertNull($first->deleted_at); + self::assertEquals($user->_id, $first->user->_id); + self::assertEquals([$first->_id, $second->_id], $user->softs->pluck('_id')->toArray()); + + $first->delete(); + $user->refresh(); + + self::assertNotNull($first->deleted_at); + self::assertEquals([$second->_id], $user->softs->pluck('_id')->toArray()); + self::assertEquals([$first->_id, $second->_id], $user->softsWithTrashed->pluck('_id')->toArray()); + } + public function testBelongsTo(): void { $user = User::create(['name' => 'George R. R. Martin']); From 25bd20365b5a09b281dd7262aec9370f3880488b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Thu, 19 Oct 2023 09:14:07 +0200 Subject: [PATCH 113/446] PHPORM-101 Allow empty insert batch for consistency with Eloquent SQL (#2645) --- src/Query/Builder.php | 5 +++++ tests/ModelTest.php | 6 ++++++ 2 files changed, 11 insertions(+) diff --git a/src/Query/Builder.php b/src/Query/Builder.php index a145ecb3e..82ba9d09a 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -613,6 +613,11 @@ public function whereBetween($column, iterable $values, $boolean = 'and', $not = /** @inheritdoc */ public function insert(array $values) { + // Allow empty insert batch for consistency with Eloquent SQL + if ($values === []) { + return true; + } + // Since every insert gets treated like a batch insert, we will have to detect // if the user is inserting a single document or an array of documents. $batch = true; diff --git a/tests/ModelTest.php b/tests/ModelTest.php index 9d6acb127..afa95c203 100644 --- a/tests/ModelTest.php +++ b/tests/ModelTest.php @@ -225,6 +225,12 @@ public function testFind(): void $this->assertEquals(35, $check->age); } + public function testInsertEmpty(): void + { + $success = User::insert([]); + $this->assertTrue($success); + } + public function testGet(): void { User::insert([ From f80501d61b18d0da548cd8ef6425aab99c3ad5a9 Mon Sep 17 00:00:00 2001 From: bisht2050 <108942387+bisht2050@users.noreply.github.com> Date: Thu, 19 Oct 2023 18:00:11 +0530 Subject: [PATCH 114/446] Update Readme to fix broken link and info about reporting issues in JIRA. (#2646) * Update Readme Update readme to fix broken link and add info about reporting issues in JIRA. * minor update --------- Co-authored-by: bisht42 <108942387+bisht42@users.noreply.github.com> --- README.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index b8ab3c893..1f5b308d4 100644 --- a/README.md +++ b/README.md @@ -16,14 +16,19 @@ It is compatible with Laravel 10.x. For older versions of Laravel, please refer - [Eloquent Models](docs/eloquent-models.md) - [Query Builder](docs/query-builder.md) - [Transactions](docs/transactions.md) -- [User Authentication](docs/authentication.md) +- [User Authentication](docs/user-authentication.md) - [Queues](docs/queues.md) - [Upgrading](docs/upgrade.md) ## Reporting Issues -Issues pertaining to the library should be reported as -[GitHub Issue](https://github.com/mongodb/laravel-mongodb/issues/new/choose). +Think you’ve found a bug in the library? Want to see a new feature? Please open a case in our issue management tool, JIRA: + +- [Create an account and login.](https://jira.mongodb.org/) +- Navigate to the [PHPORM](https://jira.mongodb.org/browse/PHPORM) project. +- Click Create - Please provide as much information as possible about the issue type and how to reproduce it. + +Note: All reported issues in JIRA project are public. For general questions and support requests, please use one of MongoDB's [Technical Support](https://mongodb.com/docs/manual/support/) channels. From 063d73ff2a9284e6a5b561544a94213a2ea8bb2a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Thu, 19 Oct 2023 18:22:11 +0200 Subject: [PATCH 115/446] PHPORM-100 Support query on numerical field names (#2642) --- src/Eloquent/Model.php | 8 +++++++ src/Query/Builder.php | 48 ++++++++++++++++++++++++++++--------- tests/ModelTest.php | 16 +++++++++++++ tests/Query/BuilderTest.php | 19 ++++++++++++++- 4 files changed, 79 insertions(+), 12 deletions(-) diff --git a/src/Eloquent/Model.php b/src/Eloquent/Model.php index 05a20bb31..30497ad86 100644 --- a/src/Eloquent/Model.php +++ b/src/Eloquent/Model.php @@ -169,6 +169,8 @@ public function getAttribute($key) return null; } + $key = (string) $key; + // An unset attribute is null or throw an exception. if (isset($this->unset[$key])) { return $this->throwMissingAttributeExceptionIfApplicable($key); @@ -194,6 +196,8 @@ public function getAttribute($key) /** @inheritdoc */ protected function getAttributeFromArray($key) { + $key = (string) $key; + // Support keys in dot notation. if (str_contains($key, '.')) { return Arr::get($this->attributes, $key); @@ -205,6 +209,8 @@ protected function getAttributeFromArray($key) /** @inheritdoc */ public function setAttribute($key, $value) { + $key = (string) $key; + // Convert _id to ObjectID. if ($key === '_id' && is_string($value)) { $builder = $this->newBaseQueryBuilder(); @@ -314,6 +320,8 @@ public function originalIsEquivalent($key) /** @inheritdoc */ public function offsetUnset($offset): void { + $offset = (string) $offset; + if (str_contains($offset, '.')) { // Update the field in the subdocument Arr::forget($this->attributes, $offset); diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 82ba9d09a..cd2326dce 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -23,13 +23,12 @@ use MongoDB\BSON\UTCDateTime; use MongoDB\Driver\Cursor; use RuntimeException; -use Stringable; use function array_fill_keys; use function array_is_list; use function array_key_exists; +use function array_map; use function array_merge; -use function array_merge_recursive; use function array_values; use function array_walk_recursive; use function assert; @@ -46,7 +45,11 @@ use function implode; use function in_array; use function is_array; +use function is_bool; +use function is_callable; +use function is_float; use function is_int; +use function is_null; use function is_string; use function md5; use function preg_match; @@ -60,6 +63,7 @@ use function strlen; use function strtolower; use function substr; +use function var_export; class Builder extends BaseBuilder { @@ -665,7 +669,7 @@ public function update(array $values, array $options = []) { // Use $set as default operator for field names that are not in an operator foreach ($values as $key => $value) { - if (str_starts_with($key, '$')) { + if (is_string($key) && str_starts_with($key, '$')) { continue; } @@ -952,7 +956,20 @@ public function convertKey($id) return $id; } - /** @inheritdoc */ + /** + * Add a basic where clause to the query. + * + * If 1 argument, the signature is: where(array|Closure $where) + * If 2 arguments, the signature is: where(string $column, mixed $value) + * If 3 arguments, the signature is: where(string $colum, string $operator, mixed $value) + * + * @param Closure|string|array $column + * @param mixed $operator + * @param mixed $value + * @param string $boolean + * + * @return $this + */ public function where($column, $operator = null, $value = null, $boolean = 'and') { $params = func_get_args(); @@ -966,8 +983,12 @@ public function where($column, $operator = null, $value = null, $boolean = 'and' } } - if (func_num_args() === 1 && is_string($column)) { - throw new ArgumentCountError(sprintf('Too few arguments to function %s("%s"), 1 passed and at least 2 expected when the 1st is a string.', __METHOD__, $column)); + if (func_num_args() === 1 && ! is_array($column) && ! is_callable($column)) { + throw new ArgumentCountError(sprintf('Too few arguments to function %s(%s), 1 passed and at least 2 expected when the 1st is not an array or a callable', __METHOD__, var_export($column, true))); + } + + if (is_float($column) || is_bool($column) || is_null($column)) { + throw new InvalidArgumentException(sprintf('First argument of %s must be a field path as "string". Got "%s"', __METHOD__, get_debug_type($column))); } return parent::where(...$params); @@ -998,7 +1019,7 @@ protected function compileWheres(): array } // Convert column name to string to use as array key - if (isset($where['column']) && $where['column'] instanceof Stringable) { + if (isset($where['column'])) { $where['column'] = (string) $where['column']; } @@ -1006,9 +1027,7 @@ protected function compileWheres(): array if (isset($where['column']) && ($where['column'] === '_id' || str_ends_with($where['column'], '._id'))) { if (isset($where['values'])) { // Multiple values. - foreach ($where['values'] as &$value) { - $value = $this->convertKey($value); - } + $where['values'] = array_map($this->convertKey(...), $where['values']); } elseif (isset($where['value'])) { // Single value. $where['value'] = $this->convertKey($where['value']); @@ -1076,7 +1095,14 @@ protected function compileWheres(): array } // Merge the compiled where with the others. - $compiled = array_merge_recursive($compiled, $result); + // array_merge_recursive can't be used here because it converts int keys to sequential int. + foreach ($result as $key => $value) { + if (in_array($key, ['$and', '$or', '$nor'])) { + $compiled[$key] = array_merge($compiled[$key] ?? [], $value); + } else { + $compiled[$key] = $value; + } + } } return $compiled; diff --git a/tests/ModelTest.php b/tests/ModelTest.php index afa95c203..ef25ebaef 100644 --- a/tests/ModelTest.php +++ b/tests/ModelTest.php @@ -971,4 +971,20 @@ public function testEnumCast(): void $this->assertSame(MemberStatus::Member->value, $check->getRawOriginal('member_status')); $this->assertSame(MemberStatus::Member, $check->member_status); } + + public function testNumericFieldName(): void + { + $user = new User(); + $user->{1} = 'one'; + $user->{2} = ['3' => 'two.three']; + $user->save(); + + $found = User::where(1, 'one')->first(); + $this->assertInstanceOf(User::class, $found); + $this->assertEquals('one', $found[1]); + + $found = User::where('2.3', 'two.three')->first(); + $this->assertInstanceOf(User::class, $found); + $this->assertEquals([3 => 'two.three'], $found[2]); + } } diff --git a/tests/Query/BuilderTest.php b/tests/Query/BuilderTest.php index 2bfc03515..1b3dcd2ad 100644 --- a/tests/Query/BuilderTest.php +++ b/tests/Query/BuilderTest.php @@ -90,6 +90,11 @@ public static function provideQueryBuilderToMql(): iterable fn (Builder $builder) => $builder->where('foo', 'bar'), ]; + yield 'find with numeric field name' => [ + ['find' => [['123' => 'bar'], []]], + fn (Builder $builder) => $builder->where(123, 'bar'), + ]; + yield 'where with single array of conditions' => [ [ 'find' => [ @@ -1175,10 +1180,16 @@ public static function provideExceptions(): iterable yield 'find with single string argument' => [ ArgumentCountError::class, - 'Too few arguments to function MongoDB\Laravel\Query\Builder::where("foo"), 1 passed and at least 2 expected when the 1st is a string', + 'Too few arguments to function MongoDB\Laravel\Query\Builder::where(\'foo\'), 1 passed and at least 2 expected when the 1st is not an array', fn (Builder $builder) => $builder->where('foo'), ]; + yield 'find with single numeric argument' => [ + ArgumentCountError::class, + 'Too few arguments to function MongoDB\Laravel\Query\Builder::where(123), 1 passed and at least 2 expected when the 1st is not an array', + fn (Builder $builder) => $builder->where(123), + ]; + yield 'where regex not starting with /' => [ LogicException::class, 'Missing expected starting delimiter in regular expression "^ac/me$", supported delimiters are: / # ~', @@ -1208,6 +1219,12 @@ public static function provideExceptions(): iterable 'Invalid time format, expected HH:MM:SS, HH:MM or HH, got "stdClass"', fn (Builder $builder) => $builder->whereTime('created_at', new stdClass()), ]; + + yield 'where invalid column type' => [ + InvalidArgumentException::class, + 'First argument of MongoDB\Laravel\Query\Builder::where must be a field path as "string". Got "float"', + fn (Builder $builder) => $builder->where(2.3, '>', 1), + ]; } /** @dataProvider getEloquentMethodsNotSupported */ From f5ed7bf689f19184258fe3be1aaa6474436cf1e8 Mon Sep 17 00:00:00 2001 From: shoito <37051+shoito@users.noreply.github.com> Date: Fri, 20 Oct 2023 22:45:37 +0900 Subject: [PATCH 116/446] fix GitHub workflow badge URL (#2647) See https://github.com/badges/shields/issues/8671 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 1f5b308d4..60a48f725 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ Laravel MongoDB [![Latest Stable Version](http://img.shields.io/github/release/mongodb/laravel-mongodb.svg)](https://packagist.org/packages/mongodb/laravel-mongodb) [![Total Downloads](http://img.shields.io/packagist/dm/mongodb/laravel-mongodb.svg)](https://packagist.org/packages/mongodb/laravel-mongodb) -[![Build Status](https://img.shields.io/github/workflow/status/mongodb/laravel-mongodb/CI)](https://github.com/mongodb/laravel-mongodb/actions) +[![Build Status](https://img.shields.io/github/actions/workflow/status/mongodb/laravel-mongodb/build-ci.yml)](https://github.com/mongodb/laravel-mongodb/actions/workflows/build-ci.yml) This package adds functionalities to the Eloquent model and Query builder for MongoDB, using the original Laravel API. *This library extends the original Laravel classes, so it uses exactly the same methods.* From bc209f7a202dc077357cbba18f324d834aaa02de Mon Sep 17 00:00:00 2001 From: Mohammad Mortazavi <39920372+hans-thomas@users.noreply.github.com> Date: Mon, 30 Oct 2023 22:54:31 +0330 Subject: [PATCH 117/446] Fix casting when setting an attribute (#2653) --- src/Eloquent/Model.php | 33 +++++++++++++++++ tests/Casts/BinaryUuidTest.php | 12 +++---- tests/Casts/BooleanTest.php | 54 ++++++++++++++++++++++++++++ tests/Casts/CollectionTest.php | 34 ++++++++++++++++++ tests/Casts/DateTest.php | 64 +++++++++++++++++++++++++++++++++ tests/Casts/DatetimeTest.php | 53 +++++++++++++++++++++++++++ tests/Casts/DecimalTest.php | 45 +++++++++++++++++++++++ tests/Casts/FloatTest.php | 44 +++++++++++++++++++++++ tests/Casts/IntegerTest.php | 54 ++++++++++++++++++++++++++++ tests/Casts/JsonTest.php | 33 +++++++++++++++++ tests/Casts/ObjectTest.php | 31 ++++++++++++++++ tests/Casts/StringTest.php | 31 ++++++++++++++++ tests/Models/CastBinaryUuid.php | 17 --------- tests/Models/Casting.php | 43 ++++++++++++++++++++++ 14 files changed, 525 insertions(+), 23 deletions(-) create mode 100644 tests/Casts/BooleanTest.php create mode 100644 tests/Casts/CollectionTest.php create mode 100644 tests/Casts/DateTest.php create mode 100644 tests/Casts/DatetimeTest.php create mode 100644 tests/Casts/DecimalTest.php create mode 100644 tests/Casts/FloatTest.php create mode 100644 tests/Casts/IntegerTest.php create mode 100644 tests/Casts/JsonTest.php create mode 100644 tests/Casts/ObjectTest.php create mode 100644 tests/Casts/StringTest.php delete mode 100644 tests/Models/CastBinaryUuid.php create mode 100644 tests/Models/Casting.php diff --git a/src/Eloquent/Model.php b/src/Eloquent/Model.php index 30497ad86..72c4d2a5f 100644 --- a/src/Eloquent/Model.php +++ b/src/Eloquent/Model.php @@ -4,16 +4,22 @@ namespace MongoDB\Laravel\Eloquent; +use Brick\Math\BigDecimal; +use Brick\Math\Exception\MathException as BrickMathException; +use Brick\Math\RoundingMode; use DateTimeInterface; use Illuminate\Contracts\Queue\QueueableCollection; use Illuminate\Contracts\Queue\QueueableEntity; use Illuminate\Contracts\Support\Arrayable; +use Illuminate\Database\Eloquent\Casts\Json; use Illuminate\Database\Eloquent\Model as BaseModel; use Illuminate\Database\Eloquent\Relations\Relation; use Illuminate\Support\Arr; +use Illuminate\Support\Exceptions\MathException; use Illuminate\Support\Facades\Date; use Illuminate\Support\Str; use MongoDB\BSON\Binary; +use MongoDB\BSON\Decimal128; use MongoDB\BSON\ObjectID; use MongoDB\BSON\UTCDateTime; use MongoDB\Laravel\Query\Builder as QueryBuilder; @@ -211,6 +217,11 @@ public function setAttribute($key, $value) { $key = (string) $key; + //Add casts + if ($this->hasCast($key)) { + $value = $this->castAttribute($key, $value); + } + // Convert _id to ObjectID. if ($key === '_id' && is_string($value)) { $builder = $this->newBaseQueryBuilder(); @@ -237,6 +248,28 @@ public function setAttribute($key, $value) return parent::setAttribute($key, $value); } + /** @inheritdoc */ + protected function asDecimal($value, $decimals) + { + try { + $value = (string) BigDecimal::of((string) $value)->toScale((int) $decimals, RoundingMode::HALF_UP); + + return new Decimal128($value); + } catch (BrickMathException $e) { + throw new MathException('Unable to cast value to a decimal.', previous: $e); + } + } + + /** @inheritdoc */ + public function fromJson($value, $asObject = false) + { + if (! is_string($value)) { + $value = Json::encode($value ?? ''); + } + + return Json::decode($value ?? '', ! $asObject); + } + /** @inheritdoc */ public function attributesToArray() { diff --git a/tests/Casts/BinaryUuidTest.php b/tests/Casts/BinaryUuidTest.php index 8a79b1500..2183c12fa 100644 --- a/tests/Casts/BinaryUuidTest.php +++ b/tests/Casts/BinaryUuidTest.php @@ -6,7 +6,7 @@ use Generator; use MongoDB\BSON\Binary; -use MongoDB\Laravel\Tests\Models\CastBinaryUuid; +use MongoDB\Laravel\Tests\Models\Casting; use MongoDB\Laravel\Tests\TestCase; use function hex2bin; @@ -17,15 +17,15 @@ protected function setUp(): void { parent::setUp(); - CastBinaryUuid::truncate(); + Casting::truncate(); } /** @dataProvider provideBinaryUuidCast */ public function testBinaryUuidCastModel(string $expectedUuid, string|Binary $saveUuid, Binary $queryUuid): void { - CastBinaryUuid::create(['uuid' => $saveUuid]); + Casting::create(['uuid' => $saveUuid]); - $model = CastBinaryUuid::firstWhere('uuid', $queryUuid); + $model = Casting::firstWhere('uuid', $queryUuid); $this->assertNotNull($model); $this->assertSame($expectedUuid, $model->uuid); } @@ -43,9 +43,9 @@ public function testQueryByStringDoesNotCast(): void { $uuid = '0c103357-3806-48c9-a84b-867dcb625cfb'; - CastBinaryUuid::create(['uuid' => $uuid]); + Casting::create(['uuid' => $uuid]); - $model = CastBinaryUuid::firstWhere('uuid', $uuid); + $model = Casting::firstWhere('uuid', $uuid); $this->assertNull($model); } } diff --git a/tests/Casts/BooleanTest.php b/tests/Casts/BooleanTest.php new file mode 100644 index 000000000..8be2a4def --- /dev/null +++ b/tests/Casts/BooleanTest.php @@ -0,0 +1,54 @@ +create(['booleanValue' => true]); + + self::assertIsBool($model->booleanValue); + self::assertSame(true, $model->booleanValue); + + $model->update(['booleanValue' => false]); + + self::assertIsBool($model->booleanValue); + self::assertSame(false, $model->booleanValue); + + $model->update(['booleanValue' => 1]); + + self::assertIsBool($model->booleanValue); + self::assertSame(true, $model->booleanValue); + + $model->update(['booleanValue' => 0]); + + self::assertIsBool($model->booleanValue); + self::assertSame(false, $model->booleanValue); + } + + public function testBoolAsString(): void + { + $model = Casting::query()->create(['booleanValue' => '1.79']); + + self::assertIsBool($model->booleanValue); + self::assertSame(true, $model->booleanValue); + + $model->update(['booleanValue' => '0']); + + self::assertIsBool($model->booleanValue); + self::assertSame(false, $model->booleanValue); + } +} diff --git a/tests/Casts/CollectionTest.php b/tests/Casts/CollectionTest.php new file mode 100644 index 000000000..67498c092 --- /dev/null +++ b/tests/Casts/CollectionTest.php @@ -0,0 +1,34 @@ +create(['collectionValue' => ['g' => 'G-Eazy']]); + + self::assertInstanceOf(Collection::class, $model->collectionValue); + self::assertEquals(collect(['g' => 'G-Eazy']), $model->collectionValue); + + $model->update(['collectionValue' => ['Dont let me go' => 'Even the longest of nights turn days']]); + + self::assertInstanceOf(Collection::class, $model->collectionValue); + self::assertEquals(collect(['Dont let me go' => 'Even the longest of nights turn days']), $model->collectionValue); + } +} diff --git a/tests/Casts/DateTest.php b/tests/Casts/DateTest.php new file mode 100644 index 000000000..e0c775503 --- /dev/null +++ b/tests/Casts/DateTest.php @@ -0,0 +1,64 @@ +create(['dateField' => now()]); + + self::assertInstanceOf(Carbon::class, $model->dateField); + self::assertEquals(now()->startOfDay()->format('Y-m-d H:i:s'), (string) $model->dateField); + + $model->update(['dateField' => now()->subDay()]); + + self::assertInstanceOf(Carbon::class, $model->dateField); + self::assertEquals(now()->subDay()->startOfDay()->format('Y-m-d H:i:s'), (string) $model->dateField); + + $model->update(['dateField' => new DateTime()]); + + self::assertInstanceOf(Carbon::class, $model->dateField); + self::assertEquals(now()->startOfDay()->format('Y-m-d H:i:s'), (string) $model->dateField); + + $model->update(['dateField' => (new DateTime())->modify('-1 day')]); + + self::assertInstanceOf(Carbon::class, $model->dateField); + self::assertEquals(now()->subDay()->startOfDay()->format('Y-m-d H:i:s'), (string) $model->dateField); + } + + public function testDateAsString(): void + { + $model = Casting::query()->create(['dateField' => '2023-10-29']); + + self::assertInstanceOf(Carbon::class, $model->dateField); + self::assertEquals( + Carbon::createFromTimestamp(1698577443)->startOfDay()->format('Y-m-d H:i:s'), + (string) $model->dateField, + ); + + $model->update(['dateField' => '2023-10-28']); + + self::assertInstanceOf(Carbon::class, $model->dateField); + self::assertEquals( + Carbon::createFromTimestamp(1698577443)->subDay()->startOfDay()->format('Y-m-d H:i:s'), + (string) $model->dateField, + ); + } +} diff --git a/tests/Casts/DatetimeTest.php b/tests/Casts/DatetimeTest.php new file mode 100644 index 000000000..77a9cb4b6 --- /dev/null +++ b/tests/Casts/DatetimeTest.php @@ -0,0 +1,53 @@ +create(['datetimeField' => now()]); + + self::assertInstanceOf(Carbon::class, $model->datetimeField); + self::assertEquals(now()->format('Y-m-d H:i:s'), (string) $model->datetimeField); + + $model->update(['datetimeField' => now()->subDay()]); + + self::assertInstanceOf(Carbon::class, $model->datetimeField); + self::assertEquals(now()->subDay()->format('Y-m-d H:i:s'), (string) $model->datetimeField); + } + + public function testDateAsString(): void + { + $model = Casting::query()->create(['datetimeField' => '2023-10-29']); + + self::assertInstanceOf(Carbon::class, $model->datetimeField); + self::assertEquals( + Carbon::createFromTimestamp(1698577443)->startOfDay()->format('Y-m-d H:i:s'), + (string) $model->datetimeField, + ); + + $model->update(['datetimeField' => '2023-10-28 11:04:03']); + + self::assertInstanceOf(Carbon::class, $model->datetimeField); + self::assertEquals( + Carbon::createFromTimestamp(1698577443)->subDay()->format('Y-m-d H:i:s'), + (string) $model->datetimeField, + ); + } +} diff --git a/tests/Casts/DecimalTest.php b/tests/Casts/DecimalTest.php new file mode 100644 index 000000000..535328fe4 --- /dev/null +++ b/tests/Casts/DecimalTest.php @@ -0,0 +1,45 @@ +create(['decimalNumber' => 100.99]); + + self::assertInstanceOf(Decimal128::class, $model->decimalNumber); + self::assertEquals('100.99', $model->decimalNumber); + + $model->update(['decimalNumber' => 9999.9]); + + self::assertInstanceOf(Decimal128::class, $model->decimalNumber); + self::assertEquals('9999.90', $model->decimalNumber); + } + + public function testDecimalAsString(): void + { + $model = Casting::query()->create(['decimalNumber' => '120.79']); + + self::assertInstanceOf(Decimal128::class, $model->decimalNumber); + self::assertEquals('120.79', $model->decimalNumber); + + $model->update(['decimalNumber' => '795']); + + self::assertInstanceOf(Decimal128::class, $model->decimalNumber); + self::assertEquals('795.00', $model->decimalNumber); + } +} diff --git a/tests/Casts/FloatTest.php b/tests/Casts/FloatTest.php new file mode 100644 index 000000000..e4d90cae9 --- /dev/null +++ b/tests/Casts/FloatTest.php @@ -0,0 +1,44 @@ +create(['floatNumber' => 1.79]); + + self::assertIsFloat($model->floatNumber); + self::assertEquals(1.79, $model->floatNumber); + + $model->update(['floatNumber' => 7E-5]); + + self::assertIsFloat($model->floatNumber); + self::assertEquals(7E-5, $model->floatNumber); + } + + public function testFloatAsString(): void + { + $model = Casting::query()->create(['floatNumber' => '1.79']); + + self::assertIsFloat($model->floatNumber); + self::assertEquals(1.79, $model->floatNumber); + + $model->update(['floatNumber' => '7E-5']); + + self::assertIsFloat($model->floatNumber); + self::assertEquals(7E-5, $model->floatNumber); + } +} diff --git a/tests/Casts/IntegerTest.php b/tests/Casts/IntegerTest.php new file mode 100644 index 000000000..f1a11dba5 --- /dev/null +++ b/tests/Casts/IntegerTest.php @@ -0,0 +1,54 @@ +create(['intNumber' => 1]); + + self::assertIsInt($model->intNumber); + self::assertEquals(1, $model->intNumber); + + $model->update(['intNumber' => 2]); + + self::assertIsInt($model->intNumber); + self::assertEquals(2, $model->intNumber); + + $model->update(['intNumber' => 9.6]); + + self::assertIsInt($model->intNumber); + self::assertEquals(9, $model->intNumber); + } + + public function testIntAsString(): void + { + $model = Casting::query()->create(['intNumber' => '1']); + + self::assertIsInt($model->intNumber); + self::assertEquals(1, $model->intNumber); + + $model->update(['intNumber' => '2']); + + self::assertIsInt($model->intNumber); + self::assertEquals(2, $model->intNumber); + + $model->update(['intNumber' => '9.6']); + + self::assertIsInt($model->intNumber); + self::assertEquals(9, $model->intNumber); + } +} diff --git a/tests/Casts/JsonTest.php b/tests/Casts/JsonTest.php new file mode 100644 index 000000000..99473c5d8 --- /dev/null +++ b/tests/Casts/JsonTest.php @@ -0,0 +1,33 @@ +create(['jsonValue' => ['g' => 'G-Eazy']]); + + self::assertIsArray($model->jsonValue); + self::assertEquals(['g' => 'G-Eazy'], $model->jsonValue); + + $model->update(['jsonValue' => json_encode(['Dont let me go' => 'Even the longest of nights turn days'])]); + + self::assertIsArray($model->jsonValue); + self::assertEquals(['Dont let me go' => 'Even the longest of nights turn days'], $model->jsonValue); + } +} diff --git a/tests/Casts/ObjectTest.php b/tests/Casts/ObjectTest.php new file mode 100644 index 000000000..3217b23fc --- /dev/null +++ b/tests/Casts/ObjectTest.php @@ -0,0 +1,31 @@ +create(['objectValue' => ['g' => 'G-Eazy']]); + + self::assertIsObject($model->objectValue); + self::assertEquals((object) ['g' => 'G-Eazy'], $model->objectValue); + + $model->update(['objectValue' => ['Dont let me go' => 'Even the brightest of colors turn greys']]); + + self::assertIsObject($model->objectValue); + self::assertEquals((object) ['Dont let me go' => 'Even the brightest of colors turn greys'], $model->objectValue); + } +} diff --git a/tests/Casts/StringTest.php b/tests/Casts/StringTest.php new file mode 100644 index 000000000..120fb9b19 --- /dev/null +++ b/tests/Casts/StringTest.php @@ -0,0 +1,31 @@ +create(['stringContent' => 'Home is behind The world ahead And there are many paths to tread']); + + self::assertIsString($model->stringContent); + self::assertEquals('Home is behind The world ahead And there are many paths to tread', $model->stringContent); + + $model->update(['stringContent' => "Losing hope, don't mean I'm hopeless And maybe all I need is time"]); + + self::assertIsString($model->stringContent); + self::assertEquals("Losing hope, don't mean I'm hopeless And maybe all I need is time", $model->stringContent); + } +} diff --git a/tests/Models/CastBinaryUuid.php b/tests/Models/CastBinaryUuid.php deleted file mode 100644 index 3d8b82941..000000000 --- a/tests/Models/CastBinaryUuid.php +++ /dev/null @@ -1,17 +0,0 @@ - BinaryUuid::class, - ]; -} diff --git a/tests/Models/Casting.php b/tests/Models/Casting.php new file mode 100644 index 000000000..5f825f954 --- /dev/null +++ b/tests/Models/Casting.php @@ -0,0 +1,43 @@ + BinaryUuid::class, + 'intNumber' => 'int', + 'floatNumber' => 'float', + 'decimalNumber' => 'decimal:2', + 'stringContent' => 'string', + 'booleanValue' => 'boolean', + 'objectValue' => 'object', + 'jsonValue' => 'json', + 'collectionValue' => 'collection', + 'dateField' => 'date', + 'datetimeField' => 'datetime', + ]; +} From 698711ce63f8662e1579944ba47854fa0c5366e8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 30 Oct 2023 20:55:13 +0100 Subject: [PATCH 118/446] Fix CS --- src/Query/Builder.php | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/Query/Builder.php b/src/Query/Builder.php index cd2326dce..bfbb323e0 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -49,7 +49,6 @@ use function is_callable; use function is_float; use function is_int; -use function is_null; use function is_string; use function md5; use function preg_match; @@ -987,7 +986,7 @@ public function where($column, $operator = null, $value = null, $boolean = 'and' throw new ArgumentCountError(sprintf('Too few arguments to function %s(%s), 1 passed and at least 2 expected when the 1st is not an array or a callable', __METHOD__, var_export($column, true))); } - if (is_float($column) || is_bool($column) || is_null($column)) { + if (is_float($column) || is_bool($column) || $column === null) { throw new InvalidArgumentException(sprintf('First argument of %s must be a field path as "string". Got "%s"', __METHOD__, get_debug_type($column))); } From bd6f1c3bed5dba75e598a928dcfdb1f847faa56f Mon Sep 17 00:00:00 2001 From: Tonko Mulder Date: Thu, 2 Nov 2023 17:22:11 +0100 Subject: [PATCH 119/446] Fix compatibility with Laravel 10.30.0+ (#2661) lowercase the `$passthru` array values --- phpcs.xml.dist | 2 + src/Eloquent/Builder.php | 25 ++++--- tests/Eloquent/CallBuilderTest.php | 107 ++++++++++++++++++++++++++++ tests/Eloquent/MassPrunableTest.php | 2 +- 4 files changed, 127 insertions(+), 9 deletions(-) create mode 100644 tests/Eloquent/CallBuilderTest.php diff --git a/phpcs.xml.dist b/phpcs.xml.dist index 36cc870e9..23bc44ab7 100644 --- a/phpcs.xml.dist +++ b/phpcs.xml.dist @@ -34,5 +34,7 @@ + + diff --git a/src/Eloquent/Builder.php b/src/Eloquent/Builder.php index 4d210c873..909207959 100644 --- a/src/Eloquent/Builder.php +++ b/src/Eloquent/Builder.php @@ -30,16 +30,16 @@ class Builder extends EloquentBuilder 'avg', 'count', 'dd', - 'doesntExist', + 'doesntexist', 'dump', 'exists', - 'getBindings', - 'getConnection', - 'getGrammar', + 'getbindings', + 'getconnection', + 'getgrammar', 'insert', - 'insertGetId', - 'insertOrIgnore', - 'insertUsing', + 'insertgetid', + 'insertorignore', + 'insertusing', 'max', 'min', 'pluck', @@ -47,7 +47,16 @@ class Builder extends EloquentBuilder 'push', 'raw', 'sum', - 'toSql', + 'tomql', + // Kept for compatibility with Laravel < 10.3 + 'doesntExist', + 'getBindings', + 'getConnection', + 'getGrammar', + 'insertGetId', + 'insertOrIgnore', + 'insertUsing', + 'toMql', ]; /** @inheritdoc */ diff --git a/tests/Eloquent/CallBuilderTest.php b/tests/Eloquent/CallBuilderTest.php new file mode 100644 index 000000000..226fe1f25 --- /dev/null +++ b/tests/Eloquent/CallBuilderTest.php @@ -0,0 +1,107 @@ +newQuery(); + assert($builder instanceof Builder); + + self::assertNotInstanceOf(expected: $className, actual: $builder->{$method}(...$parameters)); + } + + public static function provideFunctionNames(): Generator + { + yield 'does not exist' => ['doesntExist', Builder::class]; + yield 'get bindings' => ['getBindings', Builder::class]; + yield 'get connection' => ['getConnection', Builder::class]; + yield 'get grammar' => ['getGrammar', Builder::class]; + yield 'insert get id' => ['insertGetId', Builder::class, [['user' => 'foo']]]; + yield 'to Mql' => ['toMql', Builder::class]; + yield 'average' => ['average', Builder::class, ['name']]; + yield 'avg' => ['avg', Builder::class, ['name']]; + yield 'count' => ['count', Builder::class, ['name']]; + yield 'exists' => ['exists', Builder::class]; + yield 'insert' => ['insert', Builder::class, [['name']]]; + yield 'max' => ['max', Builder::class, ['name']]; + yield 'min' => ['min', Builder::class, ['name']]; + yield 'pluck' => ['pluck', Builder::class, ['name']]; + yield 'pull' => ['pull', Builder::class, ['name']]; + yield 'push' => ['push', Builder::class, ['name']]; + yield 'raw' => ['raw', Builder::class]; + yield 'sum' => ['sum', Builder::class, ['name']]; + } + + #[Test] + #[DataProvider('provideUnsupportedMethods')] + public function callingUnsupportedMethodThrowsAnException(string $method, string $exceptionClass, string $exceptionMessage, $parameters = []): void + { + $builder = User::query()->newQuery(); + assert($builder instanceof Builder); + + $this->expectException($exceptionClass); + $this->expectExceptionMessage($exceptionMessage); + + $builder->{$method}(...$parameters); + } + + public static function provideUnsupportedMethods(): Generator + { + yield 'insert or ignore' => [ + 'insertOrIgnore', + RuntimeException::class, + 'This database engine does not support inserting while ignoring errors', + [['name' => 'Jane']], + ]; + + yield 'insert using' => [ + 'insertUsing', + BadMethodCallException::class, + 'This method is not supported by MongoDB. Try "toMql()" instead', + [[['name' => 'Jane']], fn (QueryBuilder $builder) => $builder], + ]; + + yield 'to sql' => [ + 'toSql', + BadMethodCallException::class, + 'This method is not supported by MongoDB. Try "toMql()" instead', + [[['name' => 'Jane']], fn (QueryBuilder $builder) => $builder], + ]; + + yield 'dd' => [ + 'dd', + BadMethodCallException::class, + 'This method is not supported by MongoDB. Try "toMql()" instead', + [[['name' => 'Jane']], fn (QueryBuilder $builder) => $builder], + ]; + + yield 'dump' => [ + 'dump', + BadMethodCallException::class, + 'This method is not supported by MongoDB. Try "toMql()" instead', + [[['name' => 'Jane']], fn (QueryBuilder $builder) => $builder], + ]; + } +} diff --git a/tests/Eloquent/MassPrunableTest.php b/tests/Eloquent/MassPrunableTest.php index a93f864e5..0f6f2ab15 100644 --- a/tests/Eloquent/MassPrunableTest.php +++ b/tests/Eloquent/MassPrunableTest.php @@ -2,7 +2,7 @@ declare(strict_types=1); -namespace Eloquent; +namespace MongoDB\Laravel\Tests\Eloquent; use Illuminate\Database\Console\PruneCommand; use Illuminate\Database\Eloquent\MassPrunable; From 070e9e6d3496829d38c68faea47a6afddfa39b83 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Thu, 2 Nov 2023 21:30:11 +0100 Subject: [PATCH 120/446] Test with lowest dependencies in CI (#2663) --- .github/workflows/build-ci.yml | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/.github/workflows/build-ci.yml b/.github/workflows/build-ci.yml index 213ca5323..97b1e8a32 100644 --- a/.github/workflows/build-ci.yml +++ b/.github/workflows/build-ci.yml @@ -9,7 +9,7 @@ on: jobs: build: runs-on: ${{ matrix.os }} - name: PHP v${{ matrix.php }} with MongoDB ${{ matrix.mongodb }} + name: PHP v${{ matrix.php }} with MongoDB ${{ matrix.mongodb }} ${{ matrix.mode }} strategy: matrix: os: @@ -23,6 +23,10 @@ jobs: - '8.1' - '8.2' - '8.3' + include: + - php: '8.1' + mongodb: '5.0' + mode: 'low-deps' steps: - uses: actions/checkout@v4 @@ -63,7 +67,7 @@ jobs: restore-keys: ${{ matrix.os }}-composer- - name: Install dependencies run: | - composer install --no-interaction + composer update --no-interaction $([[ "${{ matrix.mode }}" == low-deps ]] && echo ' --prefer-lowest --prefer-stable') - name: Run tests run: | ./vendor/bin/phpunit --coverage-clover coverage.xml From 744c8aeb1a5cb46c6695480c116fdb546512132e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Fri, 3 Nov 2023 10:44:39 +0100 Subject: [PATCH 121/446] Upgrage minimum laravel version to 10.30 (#2665) --- composer.json | 2 +- src/Eloquent/Builder.php | 9 --------- 2 files changed, 1 insertion(+), 10 deletions(-) diff --git a/composer.json b/composer.json index c58e9d761..94b049785 100644 --- a/composer.json +++ b/composer.json @@ -26,7 +26,7 @@ "ext-mongodb": "^1.15", "illuminate/support": "^10.0", "illuminate/container": "^10.0", - "illuminate/database": "^10.0", + "illuminate/database": "^10.30", "illuminate/events": "^10.0", "mongodb/mongodb": "^1.15" }, diff --git a/src/Eloquent/Builder.php b/src/Eloquent/Builder.php index 909207959..948182ad3 100644 --- a/src/Eloquent/Builder.php +++ b/src/Eloquent/Builder.php @@ -48,15 +48,6 @@ class Builder extends EloquentBuilder 'raw', 'sum', 'tomql', - // Kept for compatibility with Laravel < 10.3 - 'doesntExist', - 'getBindings', - 'getConnection', - 'getGrammar', - 'insertGetId', - 'insertOrIgnore', - 'insertUsing', - 'toMql', ]; /** @inheritdoc */ From 0cdba6a63952ef88547718d01f98772297e9c96f Mon Sep 17 00:00:00 2001 From: Mohammad Mortazavi <39920372+hans-thomas@users.noreply.github.com> Date: Fri, 3 Nov 2023 13:41:14 +0330 Subject: [PATCH 122/446] Handle single model in sync method; (#2648) --- src/Relations/BelongsToMany.php | 2 ++ tests/RelationsTest.php | 30 ++++++++++++++++++++++++++++++ 2 files changed, 32 insertions(+) diff --git a/src/Relations/BelongsToMany.php b/src/Relations/BelongsToMany.php index 2bd74b8db..08e7ac984 100644 --- a/src/Relations/BelongsToMany.php +++ b/src/Relations/BelongsToMany.php @@ -117,6 +117,8 @@ public function sync($ids, $detaching = true) if ($ids instanceof Collection) { $ids = $ids->modelKeys(); + } elseif ($ids instanceof Model) { + $ids = $this->parseIds($ids); } // First we need to attach any of the associated models that are not currently diff --git a/tests/RelationsTest.php b/tests/RelationsTest.php index 156e656bd..b087ca481 100644 --- a/tests/RelationsTest.php +++ b/tests/RelationsTest.php @@ -255,6 +255,36 @@ public function testBelongsToMany(): void $this->assertCount(1, $client->users); } + public function testSyncBelongsToMany() + { + $user = User::create(['name' => 'John Doe']); + + $first = Client::query()->create(['name' => 'Hans']); + $second = Client::query()->create(['name' => 'Thomas']); + + $user->load('clients'); + self::assertEmpty($user->clients); + + $user->clients()->sync($first); + + $user->load('clients'); + self::assertCount(1, $user->clients); + self::assertTrue($user->clients->first()->is($first)); + + $user->clients()->sync($second); + + $user->load('clients'); + self::assertCount(1, $user->clients); + self::assertTrue($user->clients->first()->is($second)); + + $user->clients()->syncWithoutDetaching($first); + + $user->load('clients'); + self::assertCount(2, $user->clients); + self::assertTrue($user->clients->first()->is($first)); + self::assertTrue($user->clients->last()->is($second)); + } + public function testBelongsToManyAttachesExistingModels(): void { $user = User::create(['name' => 'John Doe', 'client_ids' => ['1234523']]); From 5387d548b0009feb128ee32d91d1a8213d23a0c4 Mon Sep 17 00:00:00 2001 From: Mohammad Mortazavi <39920372+hans-thomas@users.noreply.github.com> Date: Mon, 6 Nov 2023 12:47:24 +0330 Subject: [PATCH 123/446] [Fix] BelongsToMany sync does't use configured keys (#2667) * Merge testSyncBelongsToMany into testBelongsToManySync; * modelKeys replaced with parseIds in sync method; * Add test for handling a collection in sync method; --- src/Relations/BelongsToMany.php | 8 +-- tests/Models/Experience.php | 26 ++++++++ tests/Models/Skill.php | 14 +++++ tests/RelationsTest.php | 102 ++++++++++++++++++++------------ 4 files changed, 108 insertions(+), 42 deletions(-) create mode 100644 tests/Models/Experience.php create mode 100644 tests/Models/Skill.php diff --git a/src/Relations/BelongsToMany.php b/src/Relations/BelongsToMany.php index 08e7ac984..a1b028c9f 100644 --- a/src/Relations/BelongsToMany.php +++ b/src/Relations/BelongsToMany.php @@ -76,7 +76,7 @@ protected function setWhere() { $foreign = $this->getForeignKey(); - $this->query->where($foreign, '=', $this->parent->getKey()); + $this->query->where($foreign, '=', $this->parent->{$this->parentKey}); return $this; } @@ -116,7 +116,7 @@ public function sync($ids, $detaching = true) ]; if ($ids instanceof Collection) { - $ids = $ids->modelKeys(); + $ids = $this->parseIds($ids); } elseif ($ids instanceof Model) { $ids = $this->parseIds($ids); } @@ -190,10 +190,10 @@ public function attach($id, array $attributes = [], $touch = true) $query = $this->newRelatedQuery(); - $query->whereIn($this->related->getKeyName(), (array) $id); + $query->whereIn($this->relatedKey, (array) $id); // Attach the new parent id to the related model. - $query->push($this->foreignPivotKey, $this->parent->getKey(), true); + $query->push($this->foreignPivotKey, $this->parent->{$this->parentKey}, true); } // Attach the new ids to the parent model. diff --git a/tests/Models/Experience.php b/tests/Models/Experience.php new file mode 100644 index 000000000..617073c79 --- /dev/null +++ b/tests/Models/Experience.php @@ -0,0 +1,26 @@ + 'int']; + + public function skillsWithCustomRelatedKey() + { + return $this->belongsToMany(Skill::class, relatedKey: 'cskill_id'); + } + + public function skillsWithCustomParentKey() + { + return $this->belongsToMany(Skill::class, parentKey: 'cexperience_id'); + } +} diff --git a/tests/Models/Skill.php b/tests/Models/Skill.php new file mode 100644 index 000000000..c4c1dbd0a --- /dev/null +++ b/tests/Models/Skill.php @@ -0,0 +1,14 @@ +assertCount(1, $client->users); } - public function testSyncBelongsToMany() - { - $user = User::create(['name' => 'John Doe']); - - $first = Client::query()->create(['name' => 'Hans']); - $second = Client::query()->create(['name' => 'Thomas']); - - $user->load('clients'); - self::assertEmpty($user->clients); - - $user->clients()->sync($first); - - $user->load('clients'); - self::assertCount(1, $user->clients); - self::assertTrue($user->clients->first()->is($first)); - - $user->clients()->sync($second); - - $user->load('clients'); - self::assertCount(1, $user->clients); - self::assertTrue($user->clients->first()->is($second)); - - $user->clients()->syncWithoutDetaching($first); - - $user->load('clients'); - self::assertCount(2, $user->clients); - self::assertTrue($user->clients->first()->is($first)); - self::assertTrue($user->clients->last()->is($second)); - } - public function testBelongsToManyAttachesExistingModels(): void { $user = User::create(['name' => 'John Doe', 'client_ids' => ['1234523']]); @@ -327,20 +302,27 @@ public function testBelongsToManyAttachesExistingModels(): void public function testBelongsToManySync(): void { // create test instances - $user = User::create(['name' => 'John Doe']); - $client1 = Client::create(['name' => 'Pork Pies Ltd.'])->_id; - $client2 = Client::create(['name' => 'Buffet Bar Inc.'])->_id; + $user = User::create(['name' => 'Hans Thomas']); + $client1 = Client::create(['name' => 'Pork Pies Ltd.']); + $client2 = Client::create(['name' => 'Buffet Bar Inc.']); // Sync multiple - $user->clients()->sync([$client1, $client2]); + $user->clients()->sync([$client1->_id, $client2->_id]); $this->assertCount(2, $user->clients); - // Refresh user - $user = User::where('name', '=', 'John Doe')->first(); + // Sync single wrapped by an array + $user->clients()->sync([$client1->_id]); + $user->load('clients'); + + $this->assertCount(1, $user->clients); + self::assertTrue($user->clients->first()->is($client1)); + + // Sync single model + $user->clients()->sync($client2); + $user->load('clients'); - // Sync single - $user->clients()->sync([$client1]); $this->assertCount(1, $user->clients); + self::assertTrue($user->clients->first()->is($client2)); } public function testBelongsToManyAttachArray(): void @@ -366,6 +348,50 @@ public function testBelongsToManyAttachEloquentCollection(): void $this->assertCount(2, $user->clients); } + public function testBelongsToManySyncEloquentCollectionWithCustomRelatedKey(): void + { + $experience = Experience::create(['years' => '5']); + $skill1 = Skill::create(['cskill_id' => (string) (new ObjectId()), 'name' => 'PHP']); + $skill2 = Skill::create(['cskill_id' => (string) (new ObjectId()), 'name' => 'Laravel']); + $collection = new Collection([$skill1, $skill2]); + + $experience = Experience::query()->find($experience->id); + $experience->skillsWithCustomRelatedKey()->sync($collection); + $this->assertCount(2, $experience->skillsWithCustomRelatedKey); + + self::assertIsString($skill1->cskill_id); + self::assertContains($skill1->cskill_id, $experience->skillsWithCustomRelatedKey->pluck('cskill_id')); + + self::assertIsString($skill2->cskill_id); + self::assertContains($skill2->cskill_id, $experience->skillsWithCustomRelatedKey->pluck('cskill_id')); + + $skill1->refresh(); + self::assertIsString($skill1->_id); + self::assertNotContains($skill1->_id, $experience->skillsWithCustomRelatedKey->pluck('cskill_id')); + + $skill2->refresh(); + self::assertIsString($skill2->_id); + self::assertNotContains($skill2->_id, $experience->skillsWithCustomRelatedKey->pluck('cskill_id')); + } + + public function testBelongsToManySyncEloquentCollectionWithCustomParentKey(): void + { + $experience = Experience::create(['cexperience_id' => (string) (new ObjectId()), 'years' => '5']); + $skill1 = Skill::create(['name' => 'PHP']); + $skill2 = Skill::create(['name' => 'Laravel']); + $collection = new Collection([$skill1, $skill2]); + + $experience = Experience::query()->find($experience->id); + $experience->skillsWithCustomParentKey()->sync($collection); + $this->assertCount(2, $experience->skillsWithCustomParentKey); + + self::assertIsString($skill1->_id); + self::assertContains($skill1->_id, $experience->skillsWithCustomParentKey->pluck('_id')); + + self::assertIsString($skill2->_id); + self::assertContains($skill2->_id, $experience->skillsWithCustomParentKey->pluck('_id')); + } + public function testBelongsToManySyncAlreadyPresent(): void { $user = User::create(['name' => 'John Doe']); From bfbe0550f156cc532c82396c616361f665fe7fb9 Mon Sep 17 00:00:00 2001 From: Mohammad Mortazavi <39920372+hans-thomas@users.noreply.github.com> Date: Wed, 8 Nov 2023 10:59:24 +0330 Subject: [PATCH 124/446] [Fix] morphTo relationship (#2669) * KeyName as default value for ownerKey; * Add test for inverse MorphTo; * Add test for inverse MorphTo with custom ownerKey; * Remove comment; * Fix phpcs; * keyName of queried model as default ownerKey; * Update test; * Revert "KeyName as default value for ownerKey;" This reverts commit 54c9a859 * Fix phpcs; * Update MorphTo.php * Default value for ownerKey; * Check if the related model is original; * Fix phpcs; --- src/Eloquent/HybridRelations.php | 7 ++++++- src/Relations/MorphTo.php | 6 +++++- tests/Models/Photo.php | 5 +++++ tests/RelationsTest.php | 19 +++++++++++++++++++ 4 files changed, 35 insertions(+), 2 deletions(-) diff --git a/src/Eloquent/HybridRelations.php b/src/Eloquent/HybridRelations.php index 9e11605a3..f0824c9fb 100644 --- a/src/Eloquent/HybridRelations.php +++ b/src/Eloquent/HybridRelations.php @@ -221,7 +221,7 @@ public function morphTo($name = null, $type = null, $id = null, $ownerKey = null $this->newQuery(), $this, $id, - $ownerKey, + $ownerKey ?: $this->getKeyName(), $type, $name, ); @@ -236,6 +236,11 @@ public function morphTo($name = null, $type = null, $id = null, $ownerKey = null $ownerKey ??= $instance->getKeyName(); + // Check if it is a relation with an original model. + if (! is_subclass_of($instance, MongoDBModel::class)) { + return parent::morphTo($name, $type, $id, $ownerKey); + } + return new MorphTo( $instance->newQuery(), $this, diff --git a/src/Relations/MorphTo.php b/src/Relations/MorphTo.php index 53b93f8d7..1eff5e53b 100644 --- a/src/Relations/MorphTo.php +++ b/src/Relations/MorphTo.php @@ -16,7 +16,11 @@ public function addConstraints() // For belongs to relationships, which are essentially the inverse of has one // or has many relationships, we need to actually query on the primary key // of the related models matching on the foreign key that's on a parent. - $this->query->where($this->ownerKey, '=', $this->parent->{$this->foreignKey}); + $this->query->where( + $this->ownerKey, + '=', + $this->getForeignKeyFrom($this->parent), + ); } } diff --git a/tests/Models/Photo.php b/tests/Models/Photo.php index dbb92b0ff..74852dc28 100644 --- a/tests/Models/Photo.php +++ b/tests/Models/Photo.php @@ -17,4 +17,9 @@ public function hasImage(): MorphTo { return $this->morphTo(); } + + public function hasImageWithCustomOwnerKey(): MorphTo + { + return $this->morphTo(ownerKey: 'cclient_id'); + } } diff --git a/tests/RelationsTest.php b/tests/RelationsTest.php index 6b2e2539f..a4a1c7a84 100644 --- a/tests/RelationsTest.php +++ b/tests/RelationsTest.php @@ -470,6 +470,25 @@ public function testMorph(): void $relations = $photos[1]->getRelations(); $this->assertArrayHasKey('hasImage', $relations); $this->assertInstanceOf(Client::class, $photos[1]->hasImage); + + // inverse + $photo = Photo::query()->create(['url' => 'https://graph.facebook.com/hans.thomas/picture']); + $client = Client::create(['name' => 'Hans Thomas']); + $photo->hasImage()->associate($client)->save(); + + $this->assertCount(1, $photo->hasImage()->get()); + $this->assertInstanceOf(Client::class, $photo->hasImage); + $this->assertEquals($client->_id, $photo->hasImage->_id); + + // inverse with custom ownerKey + $photo = Photo::query()->create(['url' => 'https://graph.facebook.com/young.gerald/picture']); + $client = Client::create(['cclient_id' => (string) (new ObjectId()), 'name' => 'Young Gerald']); + $photo->hasImageWithCustomOwnerKey()->associate($client)->save(); + + $this->assertCount(1, $photo->hasImageWithCustomOwnerKey()->get()); + $this->assertInstanceOf(Client::class, $photo->hasImageWithCustomOwnerKey); + $this->assertEquals($client->cclient_id, $photo->has_image_with_custom_owner_key_id); + $this->assertEquals($client->_id, $photo->hasImageWithCustomOwnerKey->_id); } public function testHasManyHas(): void From 899a23580a26d8bd5dfd6925cb6d7b9bc79d7ad4 Mon Sep 17 00:00:00 2001 From: Mohammad Mortazavi <39920372+hans-thomas@users.noreply.github.com> Date: Wed, 8 Nov 2023 14:09:00 +0330 Subject: [PATCH 125/446] Datetime casting with custom format (#2658) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit As mentioned in the #2655 issue, casting date types with a custom format did not work properly. So I decided to cover all date types and fix this issue. I tested these date types: - immutable_date - immutable_date with custom formatting - immutable_datetime - immutable_datetime with custom formatting To achieve this goal, I override one of the cases in castAttribute method to handle immutable_date date type. Also, I override transformModelValue method to check if the result is a DateTimeInterface or not for applying defined custom formatting on the Carbon instance and resetting time in a custom date type. In the end, I should say that all date values will be stored in DB as Date type. (not as an object or string anymore) --------- Co-authored-by: Jérôme Tamarelle --- src/Eloquent/Model.php | 48 +++++++++++++++++++++++++++- tests/Casts/DateTest.php | 56 +++++++++++++++++++++++++++++++++ tests/Casts/DatetimeTest.php | 61 ++++++++++++++++++++++++++++++++++-- tests/Models/Casting.php | 13 ++++++++ 4 files changed, 175 insertions(+), 3 deletions(-) diff --git a/src/Eloquent/Model.php b/src/Eloquent/Model.php index 72c4d2a5f..c4c73d67d 100644 --- a/src/Eloquent/Model.php +++ b/src/Eloquent/Model.php @@ -7,6 +7,7 @@ use Brick\Math\BigDecimal; use Brick\Math\Exception\MathException as BrickMathException; use Brick\Math\RoundingMode; +use Carbon\CarbonInterface; use DateTimeInterface; use Illuminate\Contracts\Queue\QueueableCollection; use Illuminate\Contracts\Queue\QueueableEntity; @@ -27,6 +28,7 @@ use function abs; use function array_key_exists; use function array_keys; +use function array_merge; use function array_unique; use function array_values; use function class_basename; @@ -41,6 +43,7 @@ use function method_exists; use function sprintf; use function str_contains; +use function str_starts_with; use function strcmp; use function uniqid; @@ -199,6 +202,36 @@ public function getAttribute($key) return parent::getAttribute($key); } + /** @inheritdoc */ + protected function transformModelValue($key, $value) + { + $value = parent::transformModelValue($key, $value); + // Casting attributes to any of date types, will convert that attribute + // to a Carbon or CarbonImmutable instance. + // @see Model::setAttribute() + if ($this->hasCast($key) && $value instanceof CarbonInterface) { + $value->settings(array_merge($value->getSettings(), ['toStringFormat' => $this->getDateFormat()])); + + $castType = $this->getCasts()[$key]; + if ($this->isCustomDateTimeCast($castType) && str_starts_with($castType, 'date:')) { + $value->startOfDay(); + } + } + + return $value; + } + + /** @inheritdoc */ + protected function getCastType($key) + { + $castType = $this->getCasts()[$key]; + if ($this->isCustomDateTimeCast($castType) || $this->isImmutableCustomDateTimeCast($castType)) { + $this->setDateFormat(Str::after($castType, ':')); + } + + return parent::getCastType($key); + } + /** @inheritdoc */ protected function getAttributeFromArray($key) { @@ -217,7 +250,7 @@ public function setAttribute($key, $value) { $key = (string) $key; - //Add casts + // Add casts if ($this->hasCast($key)) { $value = $this->castAttribute($key, $value); } @@ -270,6 +303,19 @@ public function fromJson($value, $asObject = false) return Json::decode($value ?? '', ! $asObject); } + /** @inheritdoc */ + protected function castAttribute($key, $value) + { + $castType = $this->getCastType($key); + + return match ($castType) { + 'immutable_custom_datetime','immutable_datetime' => str_starts_with($this->getCasts()[$key], 'immutable_date:') ? + $this->asDate($value)->toImmutable() : + $this->asDateTime($value)->toImmutable(), + default => parent::castAttribute($key, $value) + }; + } + /** @inheritdoc */ public function attributesToArray() { diff --git a/tests/Casts/DateTest.php b/tests/Casts/DateTest.php index e0c775503..bd4b76424 100644 --- a/tests/Casts/DateTest.php +++ b/tests/Casts/DateTest.php @@ -4,6 +4,7 @@ namespace MongoDB\Laravel\Tests\Casts; +use Carbon\CarbonImmutable; use DateTime; use Illuminate\Support\Carbon; use MongoDB\Laravel\Tests\Models\Casting; @@ -61,4 +62,59 @@ public function testDateAsString(): void (string) $model->dateField, ); } + + public function testDateWithCustomFormat(): void + { + $model = Casting::query()->create(['dateWithFormatField' => new DateTime()]); + + self::assertInstanceOf(Carbon::class, $model->dateWithFormatField); + self::assertEquals(now()->startOfDay()->format('j.n.Y H:i'), (string) $model->dateWithFormatField); + + $model->update(['dateWithFormatField' => now()->subDay()]); + + self::assertInstanceOf(Carbon::class, $model->dateWithFormatField); + self::assertEquals(now()->startOfDay()->subDay()->format('j.n.Y H:i'), (string) $model->dateWithFormatField); + } + + public function testImmutableDate(): void + { + $model = Casting::query()->create(['immutableDateField' => new DateTime()]); + + self::assertInstanceOf(CarbonImmutable::class, $model->immutableDateField); + self::assertEquals(now()->startOfDay()->format('Y-m-d H:i:s'), (string) $model->immutableDateField); + + $model->update(['immutableDateField' => now()->subDay()]); + + self::assertInstanceOf(CarbonImmutable::class, $model->immutableDateField); + self::assertEquals(now()->startOfDay()->subDay()->format('Y-m-d H:i:s'), (string) $model->immutableDateField); + + $model->update(['immutableDateField' => '2023-10-28']); + + self::assertInstanceOf(CarbonImmutable::class, $model->immutableDateField); + self::assertEquals( + Carbon::createFromTimestamp(1698577443)->subDay()->startOfDay()->format('Y-m-d H:i:s'), + (string) $model->immutableDateField, + ); + } + + public function testImmutableDateWithCustomFormat(): void + { + $model = Casting::query()->create(['immutableDateWithFormatField' => new DateTime()]); + + self::assertInstanceOf(CarbonImmutable::class, $model->immutableDateWithFormatField); + self::assertEquals(now()->startOfDay()->format('j.n.Y H:i'), (string) $model->immutableDateWithFormatField); + + $model->update(['immutableDateWithFormatField' => now()->startOfDay()->subDay()]); + + self::assertInstanceOf(CarbonImmutable::class, $model->immutableDateWithFormatField); + self::assertEquals(now()->startOfDay()->subDay()->format('j.n.Y H:i'), (string) $model->immutableDateWithFormatField); + + $model->update(['immutableDateWithFormatField' => '2023-10-28']); + + self::assertInstanceOf(CarbonImmutable::class, $model->immutableDateWithFormatField); + self::assertEquals( + Carbon::createFromTimestamp(1698577443)->subDay()->startOfDay()->format('j.n.Y H:i'), + (string) $model->immutableDateWithFormatField, + ); + } } diff --git a/tests/Casts/DatetimeTest.php b/tests/Casts/DatetimeTest.php index 77a9cb4b6..a90901a82 100644 --- a/tests/Casts/DatetimeTest.php +++ b/tests/Casts/DatetimeTest.php @@ -4,6 +4,8 @@ namespace MongoDB\Laravel\Tests\Casts; +use Carbon\CarbonImmutable; +use DateTime; use Illuminate\Support\Carbon; use MongoDB\Laravel\Tests\Models\Casting; use MongoDB\Laravel\Tests\TestCase; @@ -19,7 +21,7 @@ protected function setUp(): void Casting::truncate(); } - public function testDate(): void + public function testDatetime(): void { $model = Casting::query()->create(['datetimeField' => now()]); @@ -32,7 +34,7 @@ public function testDate(): void self::assertEquals(now()->subDay()->format('Y-m-d H:i:s'), (string) $model->datetimeField); } - public function testDateAsString(): void + public function testDatetimeAsString(): void { $model = Casting::query()->create(['datetimeField' => '2023-10-29']); @@ -50,4 +52,59 @@ public function testDateAsString(): void (string) $model->datetimeField, ); } + + public function testDatetimeWithCustomFormat(): void + { + $model = Casting::query()->create(['datetimeWithFormatField' => new DateTime()]); + + self::assertInstanceOf(Carbon::class, $model->datetimeWithFormatField); + self::assertEquals(now()->format('j.n.Y H:i'), (string) $model->datetimeWithFormatField); + + $model->update(['datetimeWithFormatField' => now()->subDay()]); + + self::assertInstanceOf(Carbon::class, $model->datetimeWithFormatField); + self::assertEquals(now()->subDay()->format('j.n.Y H:i'), (string) $model->datetimeWithFormatField); + } + + public function testImmutableDatetime(): void + { + $model = Casting::query()->create(['immutableDatetimeField' => new DateTime()]); + + self::assertInstanceOf(CarbonImmutable::class, $model->immutableDatetimeField); + self::assertEquals(now()->format('Y-m-d H:i:s'), (string) $model->immutableDatetimeField); + + $model->update(['immutableDatetimeField' => now()->subDay()]); + + self::assertInstanceOf(CarbonImmutable::class, $model->immutableDatetimeField); + self::assertEquals(now()->subDay()->format('Y-m-d H:i:s'), (string) $model->immutableDatetimeField); + + $model->update(['immutableDatetimeField' => '2023-10-28 11:04:03']); + + self::assertInstanceOf(CarbonImmutable::class, $model->immutableDatetimeField); + self::assertEquals( + Carbon::createFromTimestamp(1698577443)->subDay()->format('Y-m-d H:i:s'), + (string) $model->immutableDatetimeField, + ); + } + + public function testImmutableDatetimeWithCustomFormat(): void + { + $model = Casting::query()->create(['immutableDatetimeWithFormatField' => new DateTime()]); + + self::assertInstanceOf(CarbonImmutable::class, $model->immutableDatetimeWithFormatField); + self::assertEquals(now()->format('j.n.Y H:i'), (string) $model->immutableDatetimeWithFormatField); + + $model->update(['immutableDatetimeWithFormatField' => now()->subDay()]); + + self::assertInstanceOf(CarbonImmutable::class, $model->immutableDatetimeWithFormatField); + self::assertEquals(now()->subDay()->format('j.n.Y H:i'), (string) $model->immutableDatetimeWithFormatField); + + $model->update(['immutableDatetimeWithFormatField' => '2023-10-28 11:04:03']); + + self::assertInstanceOf(CarbonImmutable::class, $model->immutableDatetimeWithFormatField); + self::assertEquals( + Carbon::createFromTimestamp(1698577443)->subDay()->format('j.n.Y H:i'), + (string) $model->immutableDatetimeWithFormatField, + ); + } } diff --git a/tests/Models/Casting.php b/tests/Models/Casting.php index 5f825f954..9e232cf15 100644 --- a/tests/Models/Casting.php +++ b/tests/Models/Casting.php @@ -24,7 +24,14 @@ class Casting extends Eloquent 'jsonValue', 'collectionValue', 'dateField', + 'dateWithFormatField', + 'immutableDateField', + 'immutableDateWithFormatField', 'datetimeField', + 'dateWithFormatField', + 'datetimeWithFormatField', + 'immutableDatetimeField', + 'immutableDatetimeWithFormatField', ]; protected $casts = [ @@ -38,6 +45,12 @@ class Casting extends Eloquent 'jsonValue' => 'json', 'collectionValue' => 'collection', 'dateField' => 'date', + 'dateWithFormatField' => 'date:j.n.Y H:i', + 'immutableDateField' => 'immutable_date', + 'immutableDateWithFormatField' => 'immutable_date:j.n.Y H:i', 'datetimeField' => 'datetime', + 'datetimeWithFormatField' => 'datetime:j.n.Y H:i', + 'immutableDatetimeField' => 'immutable_datetime', + 'immutableDatetimeWithFormatField' => 'immutable_datetime:j.n.Y H:i', ]; } From 1eda4de271c78ae1bbd20fc911d3128cfa0fce90 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Thu, 9 Nov 2023 19:52:33 +0100 Subject: [PATCH 126/446] PHPORM-106 Implement pagination for groupBy queries (#2672) --- src/Query/Builder.php | 22 ++++++++++++++++++++++ tests/QueryTest.php | 39 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+) diff --git a/src/Query/Builder.php b/src/Query/Builder.php index bfbb323e0..60d6b01da 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -910,6 +910,28 @@ public function newQuery() return new static($this->connection, $this->grammar, $this->processor); } + public function runPaginationCountQuery($columns = ['*']) + { + if ($this->distinct) { + throw new BadMethodCallException('Distinct queries cannot be used for pagination. Use GroupBy instead'); + } + + if ($this->groups || $this->havings) { + $without = $this->unions ? ['orders', 'limit', 'offset'] : ['columns', 'orders', 'limit', 'offset']; + + $mql = $this->cloneWithout($without) + ->cloneWithoutBindings($this->unions ? ['order'] : ['select', 'order']) + ->toMql(); + + // Adds the $count stage to the pipeline + $mql['aggregate'][0][] = ['$count' => 'aggregate']; + + return $this->collection->aggregate($mql['aggregate'][0], $mql['aggregate'][1])->toArray(); + } + + return parent::runPaginationCountQuery($columns); + } + /** * Perform an update query. * diff --git a/tests/QueryTest.php b/tests/QueryTest.php index a5e834e53..60645c985 100644 --- a/tests/QueryTest.php +++ b/tests/QueryTest.php @@ -4,6 +4,7 @@ namespace MongoDB\Laravel\Tests; +use BadMethodCallException; use DateTimeImmutable; use LogicException; use MongoDB\BSON\Regex; @@ -534,6 +535,44 @@ public function testCursorPaginate(): void $this->assertNull($results->first()->title); } + public function testPaginateGroup(): void + { + // First page + $results = User::groupBy('age')->paginate(2); + $this->assertEquals(2, $results->count()); + $this->assertEquals(6, $results->total()); + $this->assertEquals(3, $results->lastPage()); + $this->assertEquals(1, $results->currentPage()); + $this->assertCount(2, $results->items()); + $this->assertArrayHasKey('age', $results->first()->getAttributes()); + + // Last page has fewer results + $results = User::groupBy('age')->paginate(4, page: 2); + $this->assertEquals(2, $results->count()); + $this->assertEquals(6, $results->total()); + $this->assertEquals(2, $results->lastPage()); + $this->assertEquals(2, $results->currentPage()); + $this->assertCount(2, $results->items()); + $this->assertArrayHasKey('age', $results->first()->getAttributes()); + + // Using a filter + $results = User::where('title', 'admin')->groupBy('age')->paginate(4); + $this->assertEquals(2, $results->count()); + $this->assertEquals(2, $results->total()); + $this->assertEquals(1, $results->lastPage()); + $this->assertEquals(1, $results->currentPage()); + $this->assertCount(2, $results->items()); + $this->assertArrayHasKey('age', $results->last()->getAttributes()); + } + + public function testPaginateDistinct(): void + { + $this->expectException(BadMethodCallException::class); + $this->expectExceptionMessage('Distinct queries cannot be used for pagination. Use GroupBy instead'); + + User::distinct('age')->paginate(2); + } + public function testUpdate(): void { $this->assertEquals(1, User::where(['name' => 'John Doe'])->update(['name' => 'Jim Morrison'])); From 3982f17fbcae10e9fa7d2404017525b74f897a0e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Sat, 11 Nov 2023 13:16:27 +0100 Subject: [PATCH 127/446] Avoid time-sensible tests from failing randomly (#2674) Freeze the clock for tests that use now() function. --- tests/Casts/DatetimeTest.php | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/tests/Casts/DatetimeTest.php b/tests/Casts/DatetimeTest.php index a90901a82..dc2bdd877 100644 --- a/tests/Casts/DatetimeTest.php +++ b/tests/Casts/DatetimeTest.php @@ -18,6 +18,7 @@ protected function setUp(): void { parent::setUp(); + Carbon::setTestNow(now()); Casting::truncate(); } @@ -55,7 +56,7 @@ public function testDatetimeAsString(): void public function testDatetimeWithCustomFormat(): void { - $model = Casting::query()->create(['datetimeWithFormatField' => new DateTime()]); + $model = Casting::query()->create(['datetimeWithFormatField' => DateTime::createFromInterface(now())]); self::assertInstanceOf(Carbon::class, $model->datetimeWithFormatField); self::assertEquals(now()->format('j.n.Y H:i'), (string) $model->datetimeWithFormatField); @@ -68,7 +69,7 @@ public function testDatetimeWithCustomFormat(): void public function testImmutableDatetime(): void { - $model = Casting::query()->create(['immutableDatetimeField' => new DateTime()]); + $model = Casting::query()->create(['immutableDatetimeField' => DateTime::createFromInterface(now())]); self::assertInstanceOf(CarbonImmutable::class, $model->immutableDatetimeField); self::assertEquals(now()->format('Y-m-d H:i:s'), (string) $model->immutableDatetimeField); @@ -89,7 +90,7 @@ public function testImmutableDatetime(): void public function testImmutableDatetimeWithCustomFormat(): void { - $model = Casting::query()->create(['immutableDatetimeWithFormatField' => new DateTime()]); + $model = Casting::query()->create(['immutableDatetimeWithFormatField' => DateTime::createFromInterface(now())]); self::assertInstanceOf(CarbonImmutable::class, $model->immutableDatetimeWithFormatField); self::assertEquals(now()->format('j.n.Y H:i'), (string) $model->immutableDatetimeWithFormatField); From 1b7b5e49880dcf6692a945241100304c202d8722 Mon Sep 17 00:00:00 2001 From: Mohammad Mortazavi <39920372+hans-thomas@users.noreply.github.com> Date: Mon, 13 Nov 2023 17:00:16 +0330 Subject: [PATCH 128/446] Add method Connection::ping() to check server connection (#2677) --- src/Connection.php | 16 ++++++++++++++++ tests/ConnectionTest.php | 27 +++++++++++++++++++++++++++ 2 files changed, 43 insertions(+) diff --git a/src/Connection.php b/src/Connection.php index d802e83f6..a859bfa63 100644 --- a/src/Connection.php +++ b/src/Connection.php @@ -9,6 +9,10 @@ use InvalidArgumentException; use MongoDB\Client; use MongoDB\Database; +use MongoDB\Driver\Exception\AuthenticationException; +use MongoDB\Driver\Exception\ConnectionException; +use MongoDB\Driver\Exception\RuntimeException; +use MongoDB\Driver\ReadPreference; use MongoDB\Laravel\Concerns\ManagesTransactions; use Throwable; @@ -189,6 +193,18 @@ protected function createConnection(string $dsn, array $config, array $options): return new Client($dsn, $options, $driverOptions); } + /** + * Check the connection to the MongoDB server + * + * @throws ConnectionException if connection to the server fails (for reasons other than authentication). + * @throws AuthenticationException if authentication is needed and fails. + * @throws RuntimeException if a server matching the read preference could not be found. + */ + public function ping(): void + { + $this->getMongoClient()->getManager()->selectServer(new ReadPreference(ReadPreference::PRIMARY_PREFERRED)); + } + /** @inheritdoc */ public function disconnect() { diff --git a/tests/ConnectionTest.php b/tests/ConnectionTest.php index b46168df8..262c4cafc 100644 --- a/tests/ConnectionTest.php +++ b/tests/ConnectionTest.php @@ -9,11 +9,13 @@ use InvalidArgumentException; use MongoDB\Client; use MongoDB\Database; +use MongoDB\Driver\Exception\ConnectionTimeoutException; use MongoDB\Laravel\Collection; use MongoDB\Laravel\Connection; use MongoDB\Laravel\Query\Builder; use MongoDB\Laravel\Schema\Builder as SchemaBuilder; +use function env; use function spl_object_hash; class ConnectionTest extends TestCase @@ -231,4 +233,29 @@ public function testDriverName() $driver = DB::connection('mongodb')->getDriverName(); $this->assertEquals('mongodb', $driver); } + + public function testPingMethod() + { + $config = [ + 'name' => 'mongodb', + 'driver' => 'mongodb', + 'dsn' => env('MONGODB_URI', 'mongodb://127.0.0.1/'), + 'database' => 'unittest', + 'options' => [ + 'connectTimeoutMS' => 100, + 'serverSelectionTimeoutMS' => 250, + ], + ]; + + $instance = new Connection($config); + $instance->ping(); + + $this->expectException(ConnectionTimeoutException::class); + $this->expectExceptionMessage("No suitable servers found (`serverSelectionTryOnce` set): [Failed to resolve 'wrong-host']"); + + $config['dsn'] = 'mongodb://wrong-host/'; + + $instance = new Connection($config); + $instance->ping(); + } } From 1c2d1fe29a53278ec34a50c1a289b5e3a8f1a838 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 13 Nov 2023 14:38:21 +0100 Subject: [PATCH 129/446] PHPORM-119 Fix integration with Spacie Query Builder - Don't qualify field names in document models (#2676) --- composer.json | 3 ++- src/Eloquent/Model.php | 6 +++++ tests/ExternalPackageTest.php | 50 +++++++++++++++++++++++++++++++++++ tests/ModelTest.php | 12 +++++++++ 4 files changed, 70 insertions(+), 1 deletion(-) create mode 100644 tests/ExternalPackageTest.php diff --git a/composer.json b/composer.json index 94b049785..9f605c667 100644 --- a/composer.json +++ b/composer.json @@ -34,7 +34,8 @@ "phpunit/phpunit": "^10.3", "orchestra/testbench": "^8.0", "mockery/mockery": "^1.4.4", - "doctrine/coding-standard": "12.0.x-dev" + "doctrine/coding-standard": "12.0.x-dev", + "spatie/laravel-query-builder": "^5.6" }, "replace": { "jenssegers/mongodb": "self.version" diff --git a/src/Eloquent/Model.php b/src/Eloquent/Model.php index c4c73d67d..bbd45a32b 100644 --- a/src/Eloquent/Model.php +++ b/src/Eloquent/Model.php @@ -577,6 +577,12 @@ public function newEloquentBuilder($query) return new Builder($query); } + /** @inheritdoc */ + public function qualifyColumn($column) + { + return $column; + } + /** @inheritdoc */ protected function newBaseQueryBuilder() { diff --git a/tests/ExternalPackageTest.php b/tests/ExternalPackageTest.php new file mode 100644 index 000000000..f72842874 --- /dev/null +++ b/tests/ExternalPackageTest.php @@ -0,0 +1,50 @@ + 'Jimmy Doe', 'birthday' => '2012-11-12', 'role' => 'user'], + ['name' => 'John Doe', 'birthday' => '1980-07-08', 'role' => 'admin'], + ['name' => 'Jane Doe', 'birthday' => '1983-09-10', 'role' => 'admin'], + ['name' => 'Jess Doe', 'birthday' => '2014-05-06', 'role' => 'user'], + ]); + + $request = Request::create('/users', 'GET', ['filter' => ['role' => 'admin'], 'sort' => '-birthday']); + $result = QueryBuilder::for(User::class, $request) + ->allowedFilters([ + AllowedFilter::exact('role'), + ]) + ->allowedSorts([ + AllowedSort::field('birthday'), + ]) + ->get(); + + $this->assertCount(2, $result); + $this->assertSame('Jane Doe', $result[0]->name); + } +} diff --git a/tests/ModelTest.php b/tests/ModelTest.php index ef25ebaef..9f230de09 100644 --- a/tests/ModelTest.php +++ b/tests/ModelTest.php @@ -25,6 +25,7 @@ use MongoDB\Laravel\Tests\Models\Item; use MongoDB\Laravel\Tests\Models\MemberStatus; use MongoDB\Laravel\Tests\Models\Soft; +use MongoDB\Laravel\Tests\Models\SqlUser; use MongoDB\Laravel\Tests\Models\User; use function abs; @@ -58,6 +59,17 @@ public function testNewModel(): void $this->assertEquals('_id', $user->getKeyName()); } + public function testQualifyColumn(): void + { + // Don't qualify field names in document models + $user = new User(); + $this->assertEquals('name', $user->qualifyColumn('name')); + + // Qualify column names in hybrid SQL models + $sqlUser = new SqlUser(); + $this->assertEquals('users.name', $sqlUser->qualifyColumn('name')); + } + public function testInsert(): void { $user = new User(); From bcadf52045a83a0c06f542c24af7cbe5a17bd386 Mon Sep 17 00:00:00 2001 From: Mohammad Mortazavi <39920372+hans-thomas@users.noreply.github.com> Date: Wed, 22 Nov 2023 13:22:12 +0330 Subject: [PATCH 130/446] Support renaming columns in migrations (#2682) --- src/Schema/Blueprint.php | 11 ++++++++++- tests/SchemaTest.php | 40 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 50 insertions(+), 1 deletion(-) diff --git a/src/Schema/Blueprint.php b/src/Schema/Blueprint.php index 2580c407f..6dd28d3b2 100644 --- a/src/Schema/Blueprint.php +++ b/src/Schema/Blueprint.php @@ -5,6 +5,7 @@ namespace MongoDB\Laravel\Schema; use Illuminate\Database\Connection; +use Illuminate\Database\Schema\Blueprint as SchemaBlueprint; use MongoDB\Laravel\Collection; use function array_flip; @@ -15,7 +16,7 @@ use function is_string; use function key; -class Blueprint extends \Illuminate\Database\Schema\Blueprint +class Blueprint extends SchemaBlueprint { /** * The MongoConnection object for this blueprint. @@ -276,6 +277,14 @@ public function drop() $this->collection->drop(); } + /** @inheritdoc */ + public function renameColumn($from, $to) + { + $this->collection->updateMany([$from => ['$exists' => true]], ['$rename' => [$from => $to]]); + + return $this; + } + /** @inheritdoc */ public function addColumn($type, $name, array $parameters = []) { diff --git a/tests/SchemaTest.php b/tests/SchemaTest.php index 6befaa942..6e6248beb 100644 --- a/tests/SchemaTest.php +++ b/tests/SchemaTest.php @@ -337,6 +337,46 @@ public function testSparseUnique(): void $this->assertEquals(1, $index['unique']); } + public function testRenameColumn(): void + { + DB::connection()->collection('newcollection')->insert(['test' => 'value']); + DB::connection()->collection('newcollection')->insert(['test' => 'value 2']); + DB::connection()->collection('newcollection')->insert(['column' => 'column value']); + + $check = DB::connection()->collection('newcollection')->get(); + $this->assertCount(3, $check); + + $this->assertArrayHasKey('test', $check[0]); + $this->assertArrayNotHasKey('newtest', $check[0]); + + $this->assertArrayHasKey('test', $check[1]); + $this->assertArrayNotHasKey('newtest', $check[1]); + + $this->assertArrayHasKey('column', $check[2]); + $this->assertArrayNotHasKey('test', $check[2]); + $this->assertArrayNotHasKey('newtest', $check[2]); + + Schema::collection('newcollection', function (Blueprint $collection) { + $collection->renameColumn('test', 'newtest'); + }); + + $check2 = DB::connection()->collection('newcollection')->get(); + $this->assertCount(3, $check2); + + $this->assertArrayHasKey('newtest', $check2[0]); + $this->assertArrayNotHasKey('test', $check2[0]); + $this->assertSame($check[0]['test'], $check2[0]['newtest']); + + $this->assertArrayHasKey('newtest', $check2[1]); + $this->assertArrayNotHasKey('test', $check2[1]); + $this->assertSame($check[1]['test'], $check2[1]['newtest']); + + $this->assertArrayHasKey('column', $check2[2]); + $this->assertArrayNotHasKey('test', $check2[2]); + $this->assertArrayNotHasKey('newtest', $check2[2]); + $this->assertSame($check[2]['column'], $check2[2]['column']); + } + protected function getIndex(string $collection, string $name) { $collection = DB::getCollection($collection); From 82ddb839ed2f3c027d4b810a66d056ba5221d4bb Mon Sep 17 00:00:00 2001 From: Mohammad Mortazavi <39920372+hans-thomas@users.noreply.github.com> Date: Wed, 22 Nov 2023 14:35:33 +0330 Subject: [PATCH 131/446] [Feature] Add MorphToMany support (#2670) --- src/Eloquent/HybridRelations.php | 124 ++++++++ src/Helpers/QueriesRelationships.php | 40 ++- src/Relations/MorphToMany.php | 397 ++++++++++++++++++++++++ tests/Models/Client.php | 18 ++ tests/Models/Label.php | 51 +++ tests/Models/User.php | 19 +- tests/RelationsTest.php | 446 +++++++++++++++++++++++++++ 7 files changed, 1092 insertions(+), 3 deletions(-) create mode 100644 src/Relations/MorphToMany.php create mode 100644 tests/Models/Label.php diff --git a/src/Eloquent/HybridRelations.php b/src/Eloquent/HybridRelations.php index f0824c9fb..9551a6c43 100644 --- a/src/Eloquent/HybridRelations.php +++ b/src/Eloquent/HybridRelations.php @@ -15,11 +15,16 @@ use MongoDB\Laravel\Relations\HasOne; use MongoDB\Laravel\Relations\MorphMany; use MongoDB\Laravel\Relations\MorphTo; +use MongoDB\Laravel\Relations\MorphToMany; +use function array_pop; use function debug_backtrace; +use function implode; use function is_subclass_of; +use function preg_split; use const DEBUG_BACKTRACE_IGNORE_ARGS; +use const PREG_SPLIT_DELIM_CAPTURE; /** * Cross-database relationships between SQL and MongoDB. @@ -328,6 +333,125 @@ public function belongsToMany( ); } + /** + * Define a morph-to-many relationship. + * + * @param string $related + * @param string $name + * @param null $table + * @param null $foreignPivotKey + * @param null $relatedPivotKey + * @param null $parentKey + * @param null $relatedKey + * @param null $relation + * @param bool $inverse + * + * @return \Illuminate\Database\Eloquent\Relations\MorphToMany + */ + public function morphToMany( + $related, + $name, + $table = null, + $foreignPivotKey = null, + $relatedPivotKey = null, + $parentKey = null, + $relatedKey = null, + $relation = null, + $inverse = false, + ) { + // If no relationship name was passed, we will pull backtraces to get the + // name of the calling function. We will use that function name as the + // title of this relation since that is a great convention to apply. + if ($relation === null) { + $relation = $this->guessBelongsToManyRelation(); + } + + // Check if it is a relation with an original model. + if (! is_subclass_of($related, Model::class)) { + return parent::morphToMany( + $related, + $name, + $table, + $foreignPivotKey, + $relatedPivotKey, + $parentKey, + $relatedKey, + $relation, + $inverse, + ); + } + + $instance = new $related(); + + $foreignPivotKey = $foreignPivotKey ?: $name . '_id'; + $relatedPivotKey = $relatedPivotKey ?: Str::plural($instance->getForeignKey()); + + // Now we're ready to create a new query builder for the related model and + // the relationship instances for this relation. This relation will set + // appropriate query constraints then entirely manage the hydration. + if (! $table) { + $words = preg_split('/(_)/u', $name, -1, PREG_SPLIT_DELIM_CAPTURE); + $lastWord = array_pop($words); + $table = implode('', $words) . Str::plural($lastWord); + } + + return new MorphToMany( + $instance->newQuery(), + $this, + $name, + $table, + $foreignPivotKey, + $relatedPivotKey, + $parentKey ?: $this->getKeyName(), + $relatedKey ?: $instance->getKeyName(), + $relation, + $inverse, + ); + } + + /** + * Define a polymorphic, inverse many-to-many relationship. + * + * @param string $related + * @param string $name + * @param null $table + * @param null $foreignPivotKey + * @param null $relatedPivotKey + * @param null $parentKey + * @param null $relatedKey + * + * @return \Illuminate\Database\Eloquent\Relations\MorphToMany + */ + public function morphedByMany( + $related, + $name, + $table = null, + $foreignPivotKey = null, + $relatedPivotKey = null, + $parentKey = null, + $relatedKey = null, + $relation = null, + ) { + $foreignPivotKey = $foreignPivotKey ?: Str::plural($this->getForeignKey()); + + // For the inverse of the polymorphic many-to-many relations, we will change + // the way we determine the foreign and other keys, as it is the opposite + // of the morph-to-many method since we're figuring out these inverses. + $relatedPivotKey = $relatedPivotKey ?: $name . '_id'; + + return $this->morphToMany( + $related, + $name, + $table, + $foreignPivotKey, + $relatedPivotKey, + $parentKey, + $relatedKey, + $relatedKey, + true, + ); + } + /** @inheritdoc */ public function newEloquentBuilder($query) { diff --git a/src/Helpers/QueriesRelationships.php b/src/Helpers/QueriesRelationships.php index a83c96e3e..b1234124b 100644 --- a/src/Helpers/QueriesRelationships.php +++ b/src/Helpers/QueriesRelationships.php @@ -13,12 +13,15 @@ use Illuminate\Database\Eloquent\Relations\Relation; use Illuminate\Support\Collection; use MongoDB\Laravel\Eloquent\Model; +use MongoDB\Laravel\Relations\MorphToMany; use function array_count_values; use function array_filter; use function array_keys; use function array_map; use function class_basename; +use function collect; +use function get_class; use function in_array; use function is_array; use function is_string; @@ -114,13 +117,48 @@ public function addHybridHas(Relation $relation, $operator = '>=', $count = 1, $ $not = ! $not; } - $relations = $hasQuery->pluck($this->getHasCompareKey($relation)); + $relations = match (true) { + $relation instanceof MorphToMany => $relation->getInverse() ? + $this->handleMorphedByMany($hasQuery, $relation) : + $this->handleMorphToMany($hasQuery, $relation), + default => $hasQuery->pluck($this->getHasCompareKey($relation)) + }; $relatedIds = $this->getConstrainedRelatedIds($relations, $operator, $count); return $this->whereIn($this->getRelatedConstraintKey($relation), $relatedIds, $boolean, $not); } + /** + * @param Builder $hasQuery + * @param Relation $relation + * + * @return Collection + */ + private function handleMorphToMany($hasQuery, $relation) + { + // First we select the parent models that have a relation to our related model, + // Then extracts related model's ids from the pivot column + $hasQuery->where($relation->getTable() . '.' . $relation->getMorphType(), get_class($relation->getParent())); + $relations = $hasQuery->pluck($relation->getTable()); + $relations = $relation->extractIds($relations->flatten(1)->toArray(), $relation->getForeignPivotKeyName()); + + return collect($relations); + } + + /** + * @param Builder $hasQuery + * @param Relation $relation + * + * @return Collection + */ + private function handleMorphedByMany($hasQuery, $relation) + { + $hasQuery->whereNotNull($relation->getForeignPivotKeyName()); + + return $hasQuery->pluck($relation->getForeignPivotKeyName())->flatten(1); + } + /** @return string */ protected function getHasCompareKey(Relation $relation) { diff --git a/src/Relations/MorphToMany.php b/src/Relations/MorphToMany.php new file mode 100644 index 000000000..9c9576d90 --- /dev/null +++ b/src/Relations/MorphToMany.php @@ -0,0 +1,397 @@ +setWhere(); + } + } + + /** @inheritdoc */ + public function addEagerConstraints(array $models) + { + // To load relation's data, we act normally on MorphToMany relation, + // But on MorphedByMany relation, we collect related ids from pivot column + // and add to a whereIn condition + if ($this->getInverse()) { + $ids = $this->getKeys($models, $this->table); + $ids = $this->extractIds($ids[0] ?? []); + $this->query->whereIn($this->relatedKey, $ids); + } else { + parent::addEagerConstraints($models); + + $this->query->where($this->qualifyPivotColumn($this->morphType), $this->morphClass); + } + } + + /** + * Set the where clause for the relation query. + * + * @return $this + */ + protected function setWhere() + { + if ($this->getInverse()) { + $ids = $this->extractIds((array) $this->parent->{$this->table}); + + $this->query->whereIn($this->relatedKey, $ids); + } else { + $this->query->whereIn($this->relatedKey, (array) $this->parent->{$this->relatedPivotKey}); + } + + return $this; + } + + /** @inheritdoc */ + public function save(Model $model, array $joining = [], $touch = true) + { + $model->save(['touch' => false]); + + $this->attach($model, $joining, $touch); + + return $model; + } + + /** @inheritdoc */ + public function create(array $attributes = [], array $joining = [], $touch = true) + { + $instance = $this->related->newInstance($attributes); + + // Once we save the related model, we need to attach it to the base model via + // through intermediate table so we'll use the existing "attach" method to + // accomplish this which will insert the record and any more attributes. + $instance->save(['touch' => false]); + + $this->attach($instance, $joining, $touch); + + return $instance; + } + + /** @inheritdoc */ + public function sync($ids, $detaching = true) + { + $changes = [ + 'attached' => [], + 'detached' => [], + 'updated' => [], + ]; + + if ($ids instanceof Collection) { + $ids = $this->parseIds($ids); + } elseif ($ids instanceof Model) { + $ids = $this->parseIds($ids); + } + + // First we need to attach any of the associated models that are not currently + // in this joining table. We'll spin through the given IDs, checking to see + // if they exist in the array of current ones, and if not we will insert. + if ($this->getInverse()) { + $current = $this->extractIds($this->parent->{$this->table} ?: []); + } else { + $current = $this->parent->{$this->relatedPivotKey} ?: []; + } + + // See issue #256. + if ($current instanceof Collection) { + $current = $this->parseIds($current); + } + + $records = $this->formatRecordsList($ids); + + $current = Arr::wrap($current); + + $detach = array_diff($current, array_keys($records)); + + // We need to make sure we pass a clean array, so that it is not interpreted + // as an associative array. + $detach = array_values($detach); + + // Next, we will take the differences of the currents and given IDs and detach + // all of the entities that exist in the "current" array but are not in the + // the array of the IDs given to the method which will complete the sync. + if ($detaching && count($detach) > 0) { + $this->detach($detach); + + $changes['detached'] = array_map(function ($v) { + return is_numeric($v) ? (int) $v : (string) $v; + }, $detach); + } + + // Now we are finally ready to attach the new records. Note that we'll disable + // touching until after the entire operation is complete so we don't fire a + // ton of touch operations until we are totally done syncing the records. + $changes = array_merge( + $changes, + $this->attachNew($records, $current, false), + ); + + if (count($changes['attached']) || count($changes['updated'])) { + $this->touchIfTouching(); + } + + return $changes; + } + + /** @inheritdoc */ + public function updateExistingPivot($id, array $attributes, $touch = true) + { + // Do nothing, we have no pivot table. + } + + /** @inheritdoc */ + public function attach($id, array $attributes = [], $touch = true) + { + if ($id instanceof Model) { + $model = $id; + + $id = $this->parseId($model); + + if ($this->getInverse()) { + // Attach the new ids to the parent model. + $this->parent->push($this->table, [ + [ + $this->relatedPivotKey => $model->{$this->relatedKey}, + $this->morphType => $model->getMorphClass(), + ], + ], true); + + // Attach the new parent id to the related model. + $model->push($this->foreignPivotKey, $this->parseIds($this->parent), true); + } else { + // Attach the new parent id to the related model. + $model->push($this->table, [ + [ + $this->foreignPivotKey => $this->parent->{$this->parentKey}, + $this->morphType => $this->parent instanceof Model ? $this->parent->getMorphClass() : null, + ], + ], true); + + // Attach the new ids to the parent model. + $this->parent->push($this->relatedPivotKey, (array) $id, true); + } + } else { + if ($id instanceof Collection) { + $id = $this->parseIds($id); + } + + $id = (array) $id; + + $query = $this->newRelatedQuery(); + $query->whereIn($this->relatedKey, $id); + + if ($this->getInverse()) { + // Attach the new parent id to the related model. + $query->push($this->foreignPivotKey, $this->parent->{$this->parentKey}); + + // Attach the new ids to the parent model. + foreach ($id as $item) { + $this->parent->push($this->table, [ + [ + $this->relatedPivotKey => $item, + $this->morphType => $this->related instanceof Model ? $this->related->getMorphClass() : null, + ], + ], true); + } + } else { + // Attach the new parent id to the related model. + $query->push($this->table, [ + [ + $this->foreignPivotKey => $this->parent->{$this->parentKey}, + $this->morphType => $this->parent instanceof Model ? $this->parent->getMorphClass() : null, + ], + ], true); + + // Attach the new ids to the parent model. + $this->parent->push($this->relatedPivotKey, $id, true); + } + } + + if ($touch) { + $this->touchIfTouching(); + } + } + + /** @inheritdoc */ + public function detach($ids = [], $touch = true) + { + if ($ids instanceof Model) { + $ids = $this->parseIds($ids); + } + + $query = $this->newRelatedQuery(); + + // If associated IDs were passed to the method we will only delete those + // associations, otherwise all the association ties will be broken. + // We'll return the numbers of affected rows when we do the deletes. + $ids = (array) $ids; + + // Detach all ids from the parent model. + if ($this->getInverse()) { + // Remove the relation from the parent. + $data = []; + foreach ($ids as $item) { + $data = array_merge($data, [ + [ + $this->relatedPivotKey => $item, + $this->morphType => $this->related->getMorphClass(), + ], + ]); + } + + $this->parent->pull($this->table, $data); + + // Prepare the query to select all related objects. + if (count($ids) > 0) { + $query->whereIn($this->relatedKey, $ids); + } + + // Remove the relation from the related. + $query->pull($this->foreignPivotKey, $this->parent->{$this->parentKey}); + } else { + // Remove the relation from the parent. + $this->parent->pull($this->relatedPivotKey, $ids); + + // Prepare the query to select all related objects. + if (count($ids) > 0) { + $query->whereIn($this->relatedKey, $ids); + } + + // Remove the relation to the related. + $query->pull($this->table, [ + [ + $this->foreignPivotKey => $this->parent->{$this->parentKey}, + $this->morphType => $this->parent->getMorphClass(), + ], + ]); + } + + if ($touch) { + $this->touchIfTouching(); + } + + return count($ids); + } + + /** @inheritdoc */ + protected function buildDictionary(Collection $results) + { + $foreign = $this->foreignPivotKey; + + // First we will build a dictionary of child models keyed by the foreign key + // of the relation so that we will easily and quickly match them to their + // parents without having a possibly slow inner loops for every models. + $dictionary = []; + + foreach ($results as $result) { + if ($this->getInverse()) { + foreach ($result->$foreign as $item) { + $dictionary[$item][] = $result; + } + } else { + // Collect $foreign value from pivot column of result model + $items = $this->extractIds($result->{$this->table} ?? [], $foreign); + foreach ($items as $item) { + $dictionary[$item][] = $result; + } + } + } + + return $dictionary; + } + + /** @inheritdoc */ + public function newPivotQuery() + { + return $this->newRelatedQuery(); + } + + /** + * Create a new query builder for the related model. + * + * @return \Illuminate\Database\Query\Builder + */ + public function newRelatedQuery() + { + return $this->related->newQuery(); + } + + /** @inheritdoc */ + public function getQualifiedRelatedPivotKeyName() + { + return $this->relatedPivotKey; + } + + /** + * Get the name of the "where in" method for eager loading. + * + * @param string $key + * + * @return string + */ + protected function whereInMethod(Model $model, $key) + { + return 'whereIn'; + } + + /** + * Extract ids from given pivot table data + * + * @param array $data + * @param string|null $relatedPivotKey + * + * @return mixed + */ + public function extractIds(array $data, ?string $relatedPivotKey = null) + { + $relatedPivotKey = $relatedPivotKey ?: $this->relatedPivotKey; + return array_reduce($data, function ($carry, $item) use ($relatedPivotKey) { + if (is_array($item) && array_key_exists($relatedPivotKey, $item)) { + $carry[] = $item[$relatedPivotKey]; + } + + return $carry; + }, []); + } +} diff --git a/tests/Models/Client.php b/tests/Models/Client.php index 7ee8cec4a..2ab4f5e33 100644 --- a/tests/Models/Client.php +++ b/tests/Models/Client.php @@ -29,4 +29,22 @@ public function addresses(): HasMany { return $this->hasMany(Address::class, 'data.client_id', 'data.client_id'); } + + public function labels() + { + return $this->morphToMany(Label::class, 'labelled'); + } + + public function labelsWithCustomKeys() + { + return $this->morphToMany( + Label::class, + 'clabelled', + 'clabelleds', + 'cclabelled_id', + 'clabel_ids', + 'cclient_id', + 'clabel_id', + ); + } } diff --git a/tests/Models/Label.php b/tests/Models/Label.php new file mode 100644 index 000000000..179503ce1 --- /dev/null +++ b/tests/Models/Label.php @@ -0,0 +1,51 @@ +morphedByMany(User::class, 'labelled'); + } + + public function clients() + { + return $this->morphedByMany(Client::class, 'labelled'); + } + + public function clientsWithCustomKeys() + { + return $this->morphedByMany( + Client::class, + 'clabelled', + 'clabelleds', + 'clabel_ids', + 'cclabelled_id', + 'clabel_id', + 'cclient_id', + ); + } +} diff --git a/tests/Models/User.php b/tests/Models/User.php index 4e0d7294c..f2d2cf7cc 100644 --- a/tests/Models/User.php +++ b/tests/Models/User.php @@ -38,12 +38,22 @@ class User extends Eloquent implements AuthenticatableContract, CanResetPassword use Notifiable; use MassPrunable; - protected $connection = 'mongodb'; - protected $casts = [ + protected $connection = 'mongodb'; + protected $casts = [ 'birthday' => 'datetime', 'entry.date' => 'datetime', 'member_status' => MemberStatus::class, ]; + + protected $fillable = [ + 'name', + 'email', + 'title', + 'age', + 'birthday', + 'username', + 'member_status', + ]; protected static $unguarded = true; public function books() @@ -96,6 +106,11 @@ public function photos() return $this->morphMany(Photo::class, 'has_image'); } + public function labels() + { + return $this->morphToMany(Label::class, 'labelled'); + } + public function addresses() { return $this->embedsMany(Address::class); diff --git a/tests/RelationsTest.php b/tests/RelationsTest.php index a4a1c7a84..652f3d7bf 100644 --- a/tests/RelationsTest.php +++ b/tests/RelationsTest.php @@ -13,6 +13,7 @@ use MongoDB\Laravel\Tests\Models\Experience; use MongoDB\Laravel\Tests\Models\Group; use MongoDB\Laravel\Tests\Models\Item; +use MongoDB\Laravel\Tests\Models\Label; use MongoDB\Laravel\Tests\Models\Photo; use MongoDB\Laravel\Tests\Models\Role; use MongoDB\Laravel\Tests\Models\Skill; @@ -33,6 +34,7 @@ public function tearDown(): void Role::truncate(); Group::truncate(); Photo::truncate(); + Label::truncate(); Skill::truncate(); Experience::truncate(); } @@ -491,6 +493,450 @@ public function testMorph(): void $this->assertEquals($client->_id, $photo->hasImageWithCustomOwnerKey->_id); } + public function testMorphToMany(): void + { + $user = User::query()->create(['name' => 'Young Gerald']); + $client = Client::query()->create(['name' => 'Hans Thomas']); + + $label = Label::query()->create(['name' => 'Had the world in my palms, I gave it to you']); + + $user->labels()->attach($label); + $client->labels()->attach($label); + + $this->assertEquals(1, $user->labels->count()); + $this->assertContains($label->_id, $user->labels->pluck('_id')); + + $this->assertEquals(1, $client->labels->count()); + $this->assertContains($label->_id, $user->labels->pluck('_id')); + } + + public function testMorphToManyAttachEloquentCollection(): void + { + $client = Client::query()->create(['name' => 'Young Gerald']); + + $label1 = Label::query()->create(['name' => "Make no mistake, it's the life that I was chosen for"]); + $label2 = Label::query()->create(['name' => 'All I prayed for was an open door']); + + $client->labels()->attach(new Collection([$label1, $label2])); + + $this->assertEquals(2, $client->labels->count()); + $this->assertContains($label1->_id, $client->labels->pluck('_id')); + $this->assertContains($label2->_id, $client->labels->pluck('_id')); + } + + public function testMorphToManyAttachMultipleIds(): void + { + $client = Client::query()->create(['name' => 'Young Gerald']); + + $label1 = Label::query()->create(['name' => 'stayed solid i never fled']); + $label2 = Label::query()->create(['name' => "I've got a lane and I'm in gear"]); + + $client->labels()->attach([$label1->_id, $label2->_id]); + + $this->assertEquals(2, $client->labels->count()); + $this->assertContains($label1->_id, $client->labels->pluck('_id')); + $this->assertContains($label2->_id, $client->labels->pluck('_id')); + } + + public function testMorphToManyDetaching(): void + { + $client = Client::query()->create(['name' => 'Marshall Mathers']); + + $label1 = Label::query()->create(['name' => "I'll never love again"]); + $label2 = Label::query()->create(['name' => 'The way I loved you']); + + $client->labels()->attach([$label1->_id, $label2->_id]); + + $this->assertEquals(2, $client->labels->count()); + + $client->labels()->detach($label1); + $check = $client->withoutRelations(); + + $this->assertEquals(1, $check->labels->count()); + $this->assertContains($label2->_id, $client->labels->pluck('_id')); + } + + public function testMorphToManyDetachingMultipleIds(): void + { + $client = Client::query()->create(['name' => 'Young Gerald']); + + $label1 = Label::query()->create(['name' => "I make what I wanna make, but I won't make everyone happy"]); + $label2 = Label::query()->create(['name' => "My skin's thick, but I'm not bulletproof"]); + $label3 = Label::query()->create(['name' => 'All I can be is myself, go, and tell the truth']); + + $client->labels()->attach([$label1->_id, $label2->_id, $label3->_id]); + + $this->assertEquals(3, $client->labels->count()); + + $client->labels()->detach([$label1->_id, $label2->_id]); + $client->refresh(); + + $this->assertEquals(1, $client->labels->count()); + $this->assertContains($label3->_id, $client->labels->pluck('_id')); + } + + public function testMorphToManySyncing(): void + { + $user = User::query()->create(['name' => 'Young Gerald']); + $client = Client::query()->create(['name' => 'Hans Thomas']); + + $label = Label::query()->create(['name' => "Lesson learned, we weren't the perfect match"]); + $label2 = Label::query()->create(['name' => 'Future ref, not keeping personal and work attached']); + + $user->labels()->sync($label); + $client->labels()->sync($label); + $client->labels()->sync($label2, false); + + $this->assertEquals(1, $user->labels->count()); + $this->assertContains($label->_id, $user->labels->pluck('_id')); + $this->assertNotContains($label2->_id, $user->labels->pluck('_id')); + + $this->assertEquals(2, $client->labels->count()); + $this->assertContains($label->_id, $client->labels->pluck('_id')); + $this->assertContains($label2->_id, $client->labels->pluck('_id')); + } + + public function testMorphToManySyncingEloquentCollection(): void + { + $client = Client::query()->create(['name' => 'Young Gerald']); + + $label = Label::query()->create(['name' => 'Why the ones who love me most, the people I push away?']); + $label2 = Label::query()->create(['name' => 'Look in a mirror, this is you']); + + $client->labels()->sync(new Collection([$label, $label2])); + + $this->assertEquals(2, $client->labels->count()); + $this->assertContains($label->_id, $client->labels->pluck('_id')); + $this->assertContains($label2->_id, $client->labels->pluck('_id')); + } + + public function testMorphToManySyncingMultipleIds(): void + { + $client = Client::query()->create(['name' => 'Young Gerald']); + + $label = Label::query()->create(['name' => 'They all talk about karma, how it slowly comes']); + $label2 = Label::query()->create(['name' => "But life is short, enjoy it while you're young"]); + + $client->labels()->sync([$label->_id, $label2->_id]); + + $this->assertEquals(2, $client->labels->count()); + $this->assertContains($label->_id, $client->labels->pluck('_id')); + $this->assertContains($label2->_id, $client->labels->pluck('_id')); + } + + public function testMorphToManySyncingWithCustomKeys(): void + { + $client = Client::query()->create(['cclient_id' => (string) (new ObjectId()), 'name' => 'Young Gerald']); + + $label = Label::query()->create(['clabel_id' => (string) (new ObjectId()), 'name' => "Why do people do things that be bad for 'em?"]); + $label2 = Label::query()->create(['clabel_id' => (string) (new ObjectId()), 'name' => "Say we done with these things, then we ask for 'em"]); + + $client->labelsWithCustomKeys()->sync([$label->clabel_id, $label2->clabel_id]); + + $this->assertEquals(2, $client->labelsWithCustomKeys->count()); + $this->assertContains($label->_id, $client->labelsWithCustomKeys->pluck('_id')); + $this->assertContains($label2->_id, $client->labelsWithCustomKeys->pluck('_id')); + + $client->labelsWithCustomKeys()->sync($label); + $client->load('labelsWithCustomKeys'); + + $this->assertEquals(1, $client->labelsWithCustomKeys->count()); + $this->assertContains($label->_id, $client->labelsWithCustomKeys->pluck('_id')); + $this->assertNotContains($label2->_id, $client->labelsWithCustomKeys->pluck('_id')); + } + + public function testMorphToManyLoadAndRefreshing(): void + { + $user = User::query()->create(['name' => 'The Pretty Reckless']); + + $client = Client::query()->create(['name' => 'Young Gerald']); + + $label = Label::query()->create(['name' => 'The greatest gift is knowledge itself']); + $label2 = Label::query()->create(['name' => "I made it here all by my lonely, no askin' for help"]); + + $client->labels()->sync([$label->_id, $label2->_id]); + $client->users()->sync($user); + + $this->assertEquals(2, $client->labels->count()); + + $client->load('labels'); + + $this->assertEquals(2, $client->labels->count()); + + $client->refresh(); + + $this->assertEquals(2, $client->labels->count()); + + $check = Client::query()->find($client->_id); + + $this->assertEquals(2, $check->labels->count()); + + $check = Client::query()->with('labels')->find($client->_id); + + $this->assertEquals(2, $check->labels->count()); + } + + public function testMorphToManyHasQuery(): void + { + $client = Client::query()->create(['name' => 'Ashley']); + $client2 = Client::query()->create(['name' => 'Halsey']); + $client3 = Client::query()->create(['name' => 'John Doe 2']); + + $label = Label::query()->create(['name' => "I've been digging myself down deeper"]); + $label2 = Label::query()->create(['name' => "I won't stop 'til I get where you are"]); + + $client->labels()->sync([$label->_id, $label2->_id]); + $client2->labels()->sync($label); + + $this->assertEquals(2, $client->labels->count()); + $this->assertEquals(1, $client2->labels->count()); + + $check = Client::query()->has('labels')->get(); + $this->assertCount(2, $check); + + $check = Client::query()->has('labels', '>', 1)->get(); + $this->assertCount(1, $check); + $this->assertContains($client->_id, $check->pluck('_id')); + + $check = Client::query()->has('labels', '<', 2)->get(); + $this->assertCount(2, $check); + $this->assertContains($client2->_id, $check->pluck('_id')); + $this->assertContains($client3->_id, $check->pluck('_id')); + } + + public function testMorphedByMany(): void + { + $user = User::query()->create(['name' => 'Young Gerald']); + $client = Client::query()->create(['name' => 'Hans Thomas']); + $extra = Client::query()->create(['name' => 'John Doe']); + + $label = Label::query()->create(['name' => 'Never finished, tryna search for more']); + + $label->users()->attach($user); + $label->clients()->attach($client); + + $this->assertEquals(1, $label->users->count()); + $this->assertContains($user->_id, $label->users->pluck('_id')); + + $this->assertEquals(1, $label->clients->count()); + $this->assertContains($client->_id, $label->clients->pluck('_id')); + } + + public function testMorphedByManyAttachEloquentCollection(): void + { + $client1 = Client::query()->create(['name' => 'Young Gerald']); + $client2 = Client::query()->create(['name' => 'Hans Thomas']); + $extra = Client::query()->create(['name' => 'John Doe']); + + $label = Label::query()->create(['name' => 'They want me to architect Rome, in a day']); + + $label->clients()->attach(new Collection([$client1, $client2])); + + $this->assertEquals(2, $label->clients->count()); + $this->assertContains($client1->_id, $label->clients->pluck('_id')); + $this->assertContains($client2->_id, $label->clients->pluck('_id')); + + $client1->refresh(); + $this->assertEquals(1, $client1->labels->count()); + } + + public function testMorphedByManyAttachMultipleIds(): void + { + $client1 = Client::query()->create(['name' => 'Austin Richard Post']); + $client2 = Client::query()->create(['name' => 'Hans Thomas']); + $extra = Client::query()->create(['name' => 'John Doe']); + + $label = Label::query()->create(['name' => 'Always in the game and never played by the rules']); + + $label->clients()->attach([$client1->_id, $client2->_id]); + + $this->assertEquals(2, $label->clients->count()); + $this->assertContains($client1->_id, $label->clients->pluck('_id')); + $this->assertContains($client2->_id, $label->clients->pluck('_id')); + + $client1->refresh(); + $this->assertEquals(1, $client1->labels->count()); + } + + public function testMorphedByManyDetaching(): void + { + $client1 = Client::query()->create(['name' => 'Austin Richard Post']); + $client2 = Client::query()->create(['name' => 'Hans Thomas']); + $extra = Client::query()->create(['name' => 'John Doe']); + + $label = Label::query()->create(['name' => 'Seasons change and our love went cold']); + + $label->clients()->attach([$client1->_id, $client2->_id]); + + $this->assertEquals(2, $label->clients->count()); + + $label->clients()->detach($client1->_id); + $check = $label->withoutRelations(); + + $this->assertEquals(1, $check->clients->count()); + $this->assertContains($client2->_id, $check->clients->pluck('_id')); + } + + public function testMorphedByManyDetachingMultipleIds(): void + { + $client1 = Client::query()->create(['name' => 'Austin Richard Post']); + $client2 = Client::query()->create(['name' => 'Hans Thomas']); + $client3 = Client::query()->create(['name' => 'John Doe']); + + $label = Label::query()->create(['name' => "Run away, but we're running in circles"]); + + $label->clients()->attach([$client1->_id, $client2->_id, $client3->_id]); + + $this->assertEquals(3, $label->clients->count()); + + $label->clients()->detach([$client1->_id, $client2->_id]); + $label->load('clients'); + + $this->assertEquals(1, $label->clients->count()); + $this->assertContains($client3->_id, $label->clients->pluck('_id')); + } + + public function testMorphedByManySyncing(): void + { + $client1 = Client::query()->create(['name' => 'Austin Richard Post']); + $client2 = Client::query()->create(['name' => 'Hans Thomas']); + $client3 = Client::query()->create(['name' => 'John Doe']); + + $label = Label::query()->create(['name' => "Was scared of losin' somethin' that we never found"]); + + $label->clients()->sync($client1); + $label->clients()->sync($client2, false); + $label->clients()->sync($client3, false); + + $this->assertEquals(3, $label->clients->count()); + $this->assertContains($client1->_id, $label->clients->pluck('_id')); + $this->assertContains($client2->_id, $label->clients->pluck('_id')); + $this->assertContains($client3->_id, $label->clients->pluck('_id')); + } + + public function testMorphedByManySyncingEloquentCollection(): void + { + $client1 = Client::query()->create(['name' => 'Austin Richard Post']); + $client2 = Client::query()->create(['name' => 'Hans Thomas']); + $extra = Client::query()->create(['name' => 'John Doe']); + + $label = Label::query()->create(['name' => "I'm goin' hard 'til I'm gone. Can you feel it?"]); + + $label->clients()->sync(new Collection([$client1, $client2])); + + $this->assertEquals(2, $label->clients->count()); + $this->assertContains($client1->_id, $label->clients->pluck('_id')); + $this->assertContains($client2->_id, $label->clients->pluck('_id')); + + $this->assertNotContains($extra->_id, $label->clients->pluck('_id')); + } + + public function testMorphedByManySyncingMultipleIds(): void + { + $client1 = Client::query()->create(['name' => 'Dorothy']); + $client2 = Client::query()->create(['name' => 'Hans Thomas']); + $extra = Client::query()->create(['name' => 'John Doe']); + + $label = Label::query()->create(['name' => "Love ain't patient, it's not kind. true love waits to rob you blind"]); + + $label->clients()->sync([$client1->_id, $client2->_id]); + + $this->assertEquals(2, $label->clients->count()); + $this->assertContains($client1->_id, $label->clients->pluck('_id')); + $this->assertContains($client2->_id, $label->clients->pluck('_id')); + + $this->assertNotContains($extra->_id, $label->clients->pluck('_id')); + } + + public function testMorphedByManySyncingWithCustomKeys(): void + { + $client1 = Client::query()->create(['cclient_id' => (string) (new ObjectId()), 'name' => 'Young Gerald']); + $client2 = Client::query()->create(['cclient_id' => (string) (new ObjectId()), 'name' => 'Hans Thomas']); + $client3 = Client::query()->create(['cclient_id' => (string) (new ObjectId()), 'name' => 'John Doe']); + + $label = Label::query()->create(['clabel_id' => (string) (new ObjectId()), 'name' => "I'm in my own lane, so what do I have to hurry for?"]); + + $label->clientsWithCustomKeys()->sync([$client1->cclient_id, $client2->cclient_id]); + + $this->assertEquals(2, $label->clientsWithCustomKeys->count()); + $this->assertContains($client1->_id, $label->clientsWithCustomKeys->pluck('_id')); + $this->assertContains($client2->_id, $label->clientsWithCustomKeys->pluck('_id')); + + $this->assertNotContains($client3->_id, $label->clientsWithCustomKeys->pluck('_id')); + + $label->clientsWithCustomKeys()->sync($client3); + $label->load('clientsWithCustomKeys'); + + $this->assertEquals(1, $label->clientsWithCustomKeys->count()); + $this->assertNotContains($client1->_id, $label->clientsWithCustomKeys->pluck('_id')); + $this->assertNotContains($client2->_id, $label->clientsWithCustomKeys->pluck('_id')); + + $this->assertContains($client3->_id, $label->clientsWithCustomKeys->pluck('_id')); + } + + public function testMorphedByManyLoadAndRefreshing(): void + { + $user = User::query()->create(['name' => 'Abel Tesfaye']); + + $client1 = Client::query()->create(['name' => 'Young Gerald']); + $client2 = Client::query()->create(['name' => 'Hans Thomas']); + $client3 = Client::query()->create(['name' => 'John Doe']); + + $label = Label::query()->create(['name' => "but don't think I don't think about you just cause I ain't spoken about you"]); + + $label->clients()->sync(new Collection([$client1, $client2, $client3])); + $label->users()->sync($user); + + $this->assertEquals(3, $label->clients->count()); + + $label->load('clients'); + + $this->assertEquals(3, $label->clients->count()); + + $label->refresh(); + + $this->assertEquals(3, $label->clients->count()); + + $check = Label::query()->find($label->_id); + + $this->assertEquals(3, $check->clients->count()); + + $check = Label::query()->with('clients')->find($label->_id); + + $this->assertEquals(3, $check->clients->count()); + } + + public function testMorphedByManyHasQuery(): void + { + $user = User::query()->create(['name' => 'Austin Richard Post']); + + $client1 = Client::query()->create(['name' => 'Young Gerald']); + $client2 = Client::query()->create(['name' => 'John Doe']); + + $label = Label::query()->create(['name' => "My star's back shining bright, I just polished it"]); + $label2 = Label::query()->create(['name' => "Somethin' in my spirit woke back up like I just sat up"]); + $label3 = Label::query()->create(['name' => 'How can I beam when you blocking my light?']); + + $label->clients()->sync(new Collection([$client1, $client2])); + $label2->clients()->sync($client1); + $label3->users()->sync($user); + + $this->assertEquals(2, $label->clients->count()); + + $check = Label::query()->has('clients')->get(); + $this->assertCount(2, $check); + $this->assertContains($label->_id, $check->pluck('_id')); + $this->assertContains($label2->_id, $check->pluck('_id')); + + $check = Label::query()->has('users')->get(); + $this->assertCount(1, $check); + $this->assertContains($label3->_id, $check->pluck('_id')); + + $check = Label::query()->has('clients', '>', 1)->get(); + $this->assertCount(1, $check); + $this->assertContains($label->_id, $check->pluck('_id')); + } + public function testHasManyHas(): void { $author1 = User::create(['name' => 'George R. R. Martin']); From ae0a535b2d79ffe8b27d3b39bb3327e8395670bd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 22 Nov 2023 16:28:26 +0100 Subject: [PATCH 132/446] PHPORM-6 Fix doc Builder::timeout applies to find query, not the cursor (#2681) --- src/Query/Builder.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 82ba9d09a..3fc9c1b33 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -80,7 +80,7 @@ class Builder extends BaseBuilder public $projections; /** - * The cursor timeout value. + * The maximum amount of seconds to allow the query to run. * * @var int */ @@ -189,7 +189,7 @@ public function project($columns) } /** - * Set the cursor timeout in seconds. + * The maximum amount of seconds to allow the query to run. * * @param int $seconds * From 3ffc75934068337f5da703c73308e75432f46135 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Thu, 23 Nov 2023 11:02:31 +0100 Subject: [PATCH 133/446] Add PR template (#2684) --- .github/PULL_REQUEST_TEMPLATE.md | 10 ++++++++++ CHANGELOG.md | 10 ++++++++++ CONTRIBUTING.md | 8 ++++---- 3 files changed, 24 insertions(+), 4 deletions(-) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 000000000..c3aad8477 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,10 @@ + + +### Checklist + +- [ ] Add tests and ensure they pass +- [ ] Add an entry to the CHANGELOG.md file +- [ ] Update documentation for new features diff --git a/CHANGELOG.md b/CHANGELOG.md index 5f897386a..27ab3d4d3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,16 @@ # Changelog All notable changes to this project will be documented in this file. +## [4.0.3] - unreleased + + +## [4.0.2] - 2023-11-03 + +- Fix compatibility with Laravel 10.30 [#2661](https://github.com/mongodb/laravel-mongodb/pull/2661) by [@Treggats](https://github.com/Treggats) +- PHPORM-101 Allow empty insert batch for consistency with Eloquent SQL [#2661](https://github.com/mongodb/laravel-mongodb/pull/2645) by [@GromNaN](https://github.com/GromNaN) + +*4.0.1 skipped due to a mistake in the release process.* + ## [4.0.0] - 2023-09-28 - Rename package to `mongodb/laravel-mongodb` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4de5b27bd..a6e6a8f1e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,7 +38,8 @@ Before submitting a pull request: ## Run Tests -The full test suite requires PHP cli with mongodb extension, a running MongoDB server and a running MySQL server. +The full test suite requires PHP cli with mongodb extension and a running MongoDB server. A replica set is required for +testing transactions. Duplicate the `phpunit.xml.dist` file to `phpunit.xml` and edit the environment variables to match your setup. ```bash @@ -69,14 +70,13 @@ If the project maintainer has any additional requirements, you will find them li - **Add tests!** - Your patch won't be accepted if it doesn't have tests. -- **Document any change in behaviour** - Make sure the documentation is kept up-to-date. +- **Document any change in behaviour** - Make sure the documentation is kept up-to-date, and update the changelog for +new features and bug fixes. - **Consider our release cycle** - We try to follow [SemVer v2.0.0](https://semver.org/). Randomly breaking public APIs is not an option. - **One pull request per feature** - If you want to do more than one thing, send multiple pull requests. -- **Send coherent history** - Make sure each individual commit in your pull request is meaningful. If you had to make multiple intermediate commits while developing, please [squash them](https://www.git-scm.com/book/en/v2/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages) before submitting. - Happy coding! ## Releasing From 973b6b90f7916916bf252ebd707fe4f4b5eaaeb1 Mon Sep 17 00:00:00 2001 From: Tonko Mulder Date: Thu, 23 Nov 2023 20:04:07 +0100 Subject: [PATCH 134/446] [feature] add static analysis tool (#2664) --- .editorconfig | 5 +- .github/workflows/build-ci.yml | 14 ++---- .github/workflows/coding-standards.yml | 68 +++++++++++++++++++++++++- .gitignore | 4 +- composer.json | 3 +- phpcs.xml.dist | 2 +- phpstan-baseline.neon | 16 ++++++ phpstan.neon.dist | 16 ++++++ phpunit.xml.dist | 23 +++++---- src/Eloquent/Builder.php | 14 +++--- src/Eloquent/Model.php | 4 +- src/Relations/BelongsToMany.php | 40 +++------------ src/Relations/EmbedsMany.php | 25 ++++++---- src/Relations/EmbedsOne.php | 16 ++++-- src/Relations/EmbedsOneOrMany.php | 34 ++++++++----- src/Relations/MorphToMany.php | 22 ++++----- src/Schema/Blueprint.php | 14 ++++-- src/Schema/Builder.php | 26 +++++----- 18 files changed, 221 insertions(+), 125 deletions(-) create mode 100644 phpstan-baseline.neon create mode 100644 phpstan.neon.dist diff --git a/.editorconfig b/.editorconfig index fcdf61edc..80ce1de38 100644 --- a/.editorconfig +++ b/.editorconfig @@ -6,4 +6,7 @@ end_of_line = lf insert_final_newline = true indent_style = space indent_size = 4 -trim_trailing_whitespace = true \ No newline at end of file +trim_trailing_whitespace = true + +[*.yml] +indent_size = 2 diff --git a/.github/workflows/build-ci.yml b/.github/workflows/build-ci.yml index 97b1e8a32..3664d752e 100644 --- a/.github/workflows/build-ci.yml +++ b/.github/workflows/build-ci.yml @@ -2,8 +2,6 @@ name: CI on: push: - branches: - tags: pull_request: jobs: @@ -55,7 +53,7 @@ jobs: - name: Show Docker version run: if [[ "$DEBUG" == "true" ]]; then docker version && env; fi env: - DEBUG: ${{secrets.DEBUG}} + DEBUG: ${{ secrets.DEBUG }} - name: Download Composer cache dependencies from cache id: composer-cache run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT @@ -66,14 +64,8 @@ jobs: key: ${{ matrix.os }}-composer-${{ hashFiles('**/composer.json') }} restore-keys: ${{ matrix.os }}-composer- - name: Install dependencies - run: | - composer update --no-interaction $([[ "${{ matrix.mode }}" == low-deps ]] && echo ' --prefer-lowest --prefer-stable') + run: composer update --no-interaction $([[ "${{ matrix.mode }}" == low-deps ]] && echo ' --prefer-lowest --prefer-stable') - name: Run tests - run: | - ./vendor/bin/phpunit --coverage-clover coverage.xml + run: ./vendor/bin/phpunit --coverage-clover coverage.xml env: MONGODB_URI: 'mongodb://127.0.0.1/?replicaSet=rs' - - uses: codecov/codecov-action@v3 - with: - token: ${{ secrets.CODECOV_TOKEN }} - fail_ci_if_error: false diff --git a/.github/workflows/coding-standards.yml b/.github/workflows/coding-standards.yml index e75ca3c53..c6f730d33 100644 --- a/.github/workflows/coding-standards.yml +++ b/.github/workflows/coding-standards.yml @@ -2,8 +2,6 @@ name: "Coding Standards" on: push: - branches: - tags: pull_request: env: @@ -15,6 +13,11 @@ jobs: name: "phpcs" runs-on: "ubuntu-22.04" + permissions: + # Give the default GITHUB_TOKEN write permission to commit and push the + # added or changed files to the repository. + contents: write + steps: - name: "Checkout" uses: "actions/checkout@v4" @@ -50,6 +53,67 @@ jobs: with: composer-options: "--no-suggest" + - name: "Format the code" + continue-on-error: true + run: | + mkdir .cache + ./vendor/bin/phpcbf + # The -q option is required until phpcs v4 is released - name: "Run PHP_CodeSniffer" run: "vendor/bin/phpcs -q --no-colors --report=checkstyle | cs2pr" + + - name: "Commit the changes" + uses: stefanzweifel/git-auto-commit-action@v5 + with: + commit_message: "apply phpcbf formatting" + + analysis: + runs-on: "ubuntu-22.04" + continue-on-error: true + strategy: + matrix: + php: + - '8.1' + - '8.2' + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup PHP + uses: shivammathur/setup-php@v2 + with: + php-version: ${{ matrix.php }} + extensions: curl, mbstring + tools: composer:v2 + coverage: none + + - name: Cache dependencies + id: composer-cache + uses: actions/cache@v3 + with: + path: ./vendor + key: composer-${{ hashFiles('**/composer.lock') }} + + - name: Install dependencies + run: composer install + + - name: Restore cache PHPStan results + id: phpstan-cache-restore + uses: actions/cache/restore@v3 + with: + path: .cache + key: "phpstan-result-cache-${{ github.run_id }}" + restore-keys: | + phpstan-result-cache- + + - name: Run PHPStan + run: ./vendor/bin/phpstan analyse --no-interaction --no-progress --ansi + + - name: Save cache PHPStan results + id: phpstan-cache-save + if: always() + uses: actions/cache/save@v3 + with: + path: .cache + key: ${{ steps.phpstan-cache-restore.outputs.cache-primary-key }} diff --git a/.gitignore b/.gitignore index d69c89d6f..80f343333 100644 --- a/.gitignore +++ b/.gitignore @@ -3,9 +3,9 @@ *.sublime-workspace .DS_Store .idea/ -.phpunit.cache/ -.phpcs-cache /vendor composer.lock composer.phar phpunit.xml +phpstan.neon +/.cache/ diff --git a/composer.json b/composer.json index 9f605c667..b04425751 100644 --- a/composer.json +++ b/composer.json @@ -35,7 +35,8 @@ "orchestra/testbench": "^8.0", "mockery/mockery": "^1.4.4", "doctrine/coding-standard": "12.0.x-dev", - "spatie/laravel-query-builder": "^5.6" + "spatie/laravel-query-builder": "^5.6", + "phpstan/phpstan": "^1.10" }, "replace": { "jenssegers/mongodb": "self.version" diff --git a/phpcs.xml.dist b/phpcs.xml.dist index 23bc44ab7..5f402d4ce 100644 --- a/phpcs.xml.dist +++ b/phpcs.xml.dist @@ -3,7 +3,7 @@ - + diff --git a/phpstan-baseline.neon b/phpstan-baseline.neon new file mode 100644 index 000000000..71a44a395 --- /dev/null +++ b/phpstan-baseline.neon @@ -0,0 +1,16 @@ +parameters: + ignoreErrors: + - + message: "#^Method Illuminate\\\\Database\\\\Eloquent\\\\Model\\:\\:push\\(\\) invoked with 3 parameters, 0 required\\.$#" + count: 3 + path: src/Relations/BelongsToMany.php + + - + message: "#^Method Illuminate\\\\Database\\\\Eloquent\\\\Model\\:\\:push\\(\\) invoked with 3 parameters, 0 required\\.$#" + count: 6 + path: src/Relations/MorphToMany.php + + - + message: "#^Method Illuminate\\\\Database\\\\Schema\\\\Blueprint\\:\\:create\\(\\) invoked with 1 parameter, 0 required\\.$#" + count: 1 + path: src/Schema/Builder.php diff --git a/phpstan.neon.dist b/phpstan.neon.dist new file mode 100644 index 000000000..518fe9ab8 --- /dev/null +++ b/phpstan.neon.dist @@ -0,0 +1,16 @@ +includes: + - ./phpstan-baseline.neon + +parameters: + tmpDir: .cache/phpstan + + paths: + - src + + level: 2 + + editorUrl: 'phpstorm://open?file=%%file%%&line=%%line%%' + + ignoreErrors: + - '#Unsafe usage of new static#' + - '#Call to an undefined method [a-zA-Z0-9\\_\<\>]+::[a-zA-Z]+\(\)#' diff --git a/phpunit.xml.dist b/phpunit.xml.dist index 7a38678eb..8e5e9d3d6 100644 --- a/phpunit.xml.dist +++ b/phpunit.xml.dist @@ -1,15 +1,13 @@ - + cacheDirectory=".cache/phpunit" + executionOrder="depends,defects" + beStrictAboutCoverageMetadata="true" + beStrictAboutOutputDuringTests="true" + failOnRisky="true" + failOnWarning="true"> tests/ @@ -20,10 +18,15 @@ + + - + + - ./src + ./src diff --git a/src/Eloquent/Builder.php b/src/Eloquent/Builder.php index 948182ad3..b9005c442 100644 --- a/src/Eloquent/Builder.php +++ b/src/Eloquent/Builder.php @@ -16,6 +16,7 @@ use function is_array; use function iterator_to_array; +/** @method \MongoDB\Laravel\Query\Builder toBase() */ class Builder extends EloquentBuilder { use QueriesRelationships; @@ -219,16 +220,15 @@ protected function ensureOrderForCursorPagination($shouldReverse = false) } if ($shouldReverse) { - $this->query->orders = collect($this->query->orders)->map(function ($direction) { - return $direction === 1 ? -1 : 1; - })->toArray(); + $this->query->orders = collect($this->query->orders) + ->map(static fn (int $direction) => $direction === 1 ? -1 : 1) + ->toArray(); } - return collect($this->query->orders)->map(function ($direction, $column) { - return [ + return collect($this->query->orders) + ->map(static fn ($direction, $column) => [ 'column' => $column, 'direction' => $direction === 1 ? 'asc' : 'desc', - ]; - })->values(); + ])->values(); } } diff --git a/src/Eloquent/Model.php b/src/Eloquent/Model.php index bbd45a32b..bcb672a3c 100644 --- a/src/Eloquent/Model.php +++ b/src/Eloquent/Model.php @@ -297,10 +297,10 @@ protected function asDecimal($value, $decimals) public function fromJson($value, $asObject = false) { if (! is_string($value)) { - $value = Json::encode($value ?? ''); + $value = Json::encode($value); } - return Json::decode($value ?? '', ! $asObject); + return Json::decode($value, ! $asObject); } /** @inheritdoc */ diff --git a/src/Relations/BelongsToMany.php b/src/Relations/BelongsToMany.php index a1b028c9f..1d6b84ba8 100644 --- a/src/Relations/BelongsToMany.php +++ b/src/Relations/BelongsToMany.php @@ -15,8 +15,8 @@ use function array_map; use function array_merge; use function array_values; +use function assert; use function count; -use function is_array; use function is_numeric; class BelongsToMany extends EloquentBelongsToMany @@ -82,11 +82,11 @@ protected function setWhere() } /** @inheritdoc */ - public function save(Model $model, array $joining = [], $touch = true) + public function save(Model $model, array $pivotAttributes = [], $touch = true) { $model->save(['touch' => false]); - $this->attach($model, $joining, $touch); + $this->attach($model, $pivotAttributes, $touch); return $model; } @@ -126,12 +126,7 @@ public function sync($ids, $detaching = true) // if they exist in the array of current ones, and if not we will insert. $current = $this->parent->{$this->relatedPivotKey} ?: []; - // See issue #256. - if ($current instanceof Collection) { - $current = $ids->modelKeys(); - } - - $records = $this->formatSyncList($ids); + $records = $this->formatRecordsList($ids); $current = Arr::wrap($current); @@ -171,6 +166,7 @@ public function sync($ids, $detaching = true) public function updateExistingPivot($id, array $attributes, $touch = true) { // Do nothing, we have no pivot table. + return $this; } /** @inheritdoc */ @@ -229,6 +225,8 @@ public function detach($ids = [], $touch = true) } // Remove the relation to the parent. + assert($this->parent instanceof \MongoDB\Laravel\Eloquent\Model); + assert($query instanceof \MongoDB\Laravel\Eloquent\Builder); $query->pull($this->foreignPivotKey, $this->parent->getKey()); if ($touch) { @@ -266,7 +264,7 @@ public function newPivotQuery() /** * Create a new query builder for the related model. * - * @return \Illuminate\Database\Query\Builder + * @return Builder|Model */ public function newRelatedQuery() { @@ -295,28 +293,6 @@ public function getQualifiedRelatedPivotKeyName() return $this->relatedPivotKey; } - /** - * Format the sync list so that it is keyed by ID. (Legacy Support) - * The original function has been renamed to formatRecordsList since Laravel 5.3. - * - * @deprecated - * - * @return array - */ - protected function formatSyncList(array $records) - { - $results = []; - foreach ($records as $id => $attributes) { - if (! is_array($attributes)) { - [$id, $attributes] = [$attributes, []]; - } - - $results[$id] = $attributes; - } - - return $results; - } - /** * Get the name of the "where in" method for eager loading. * diff --git a/src/Relations/EmbedsMany.php b/src/Relations/EmbedsMany.php index b97849f24..2d68af70b 100644 --- a/src/Relations/EmbedsMany.php +++ b/src/Relations/EmbedsMany.php @@ -9,6 +9,8 @@ use Illuminate\Pagination\LengthAwarePaginator; use Illuminate\Pagination\Paginator; use MongoDB\BSON\ObjectID; +use MongoDB\Driver\Exception\LogicException; +use MongoDB\Laravel\Eloquent\Model as MongoDBModel; use function array_key_exists; use function array_values; @@ -16,6 +18,7 @@ use function in_array; use function is_array; use function method_exists; +use function throw_if; class EmbedsMany extends EmbedsOneOrMany { @@ -82,7 +85,7 @@ public function performUpdate(Model $model) // Get the correct foreign key value. $foreignKey = $this->getForeignKeyValue($model); - $values = $this->getUpdateValues($model->getDirty(), $this->localKey . '.$.'); + $values = self::getUpdateValues($model->getDirty(), $this->localKey . '.$.'); // Update document in database. $result = $this->toBase()->where($this->localKey . '.' . $model->getKeyName(), $foreignKey) @@ -195,10 +198,14 @@ public function destroy($ids = []) /** * Delete all embedded models. * - * @return int + * @param null $id + * + * @note The $id is not used to delete embedded models. */ - public function delete() + public function delete($id = null): int { + throw_if($id !== null, new LogicException('The id parameter should not be used.')); + // Overwrite the local key with an empty array. $result = $this->query->update([$this->localKey => []]); @@ -224,9 +231,9 @@ public function detach($ids = []) /** * Save alias. * - * @return Model + * @return MongoDBModel */ - public function attach(Model $model) + public function attach(MongoDBModel $model) { return $this->save($model); } @@ -322,13 +329,13 @@ protected function getEmbedded() } /** @inheritdoc */ - protected function setEmbedded($models) + protected function setEmbedded($records) { - if (! is_array($models)) { - $models = [$models]; + if (! is_array($records)) { + $records = [$records]; } - return parent::setEmbedded(array_values($models)); + return parent::setEmbedded(array_values($records)); } /** @inheritdoc */ diff --git a/src/Relations/EmbedsOne.php b/src/Relations/EmbedsOne.php index 196415a55..678141cf1 100644 --- a/src/Relations/EmbedsOne.php +++ b/src/Relations/EmbedsOne.php @@ -6,6 +6,10 @@ use Illuminate\Database\Eloquent\Model; use MongoDB\BSON\ObjectID; +use MongoDB\Driver\Exception\LogicException; +use Throwable; + +use function throw_if; class EmbedsOne extends EmbedsOneOrMany { @@ -73,7 +77,7 @@ public function performUpdate(Model $model) return $this->parent->save(); } - $values = $this->getUpdateValues($model->getDirty(), $this->localKey . '.'); + $values = self::getUpdateValues($model->getDirty(), $this->localKey . '.'); $result = $this->toBase()->update($values); @@ -133,10 +137,16 @@ public function dissociate() /** * Delete all embedded models. * - * @return int + * @param ?string $id + * + * @throws LogicException|Throwable + * + * @note The $id is not used to delete embedded models. */ - public function delete() + public function delete($id = null): int { + throw_if($id !== null, new LogicException('The id parameter should not be used.')); + return $this->performDelete(); } diff --git a/src/Relations/EmbedsOneOrMany.php b/src/Relations/EmbedsOneOrMany.php index 46f4f1e72..56fc62041 100644 --- a/src/Relations/EmbedsOneOrMany.php +++ b/src/Relations/EmbedsOneOrMany.php @@ -8,11 +8,15 @@ use Illuminate\Database\Eloquent\Collection; use Illuminate\Database\Eloquent\Model as EloquentModel; use Illuminate\Database\Eloquent\Relations\Relation; +use Illuminate\Database\Query\Expression; +use MongoDB\Driver\Exception\LogicException; use MongoDB\Laravel\Eloquent\Model; +use Throwable; use function array_merge; use function count; use function is_array; +use function throw_if; abstract class EmbedsOneOrMany extends Relation { @@ -42,8 +46,8 @@ abstract class EmbedsOneOrMany extends Relation */ public function __construct(Builder $query, Model $parent, Model $related, string $localKey, string $foreignKey, string $relation) { - $this->query = $query; - $this->parent = $parent; + parent::__construct($query, $parent); + $this->related = $related; $this->localKey = $localKey; $this->foreignKey = $foreignKey; @@ -54,8 +58,6 @@ public function __construct(Builder $query, Model $parent, Model $related, strin if ($parentRelation) { $this->query = $parentRelation->getQuery(); } - - $this->addConstraints(); } /** @inheritdoc */ @@ -101,10 +103,16 @@ public function get($columns = ['*']) /** * Get the number of embedded models. * - * @return int + * @param Expression|string $columns + * + * @throws LogicException|Throwable + * + * @note The $column parameter is not used to count embedded models. */ - public function count() + public function count($columns = '*'): int { + throw_if($columns !== '*', new LogicException('The columns parameter should not be used.')); + return count($this->getEmbedded()); } @@ -261,21 +269,21 @@ protected function toCollection(array $records = []) /** * Create a related model instanced. * - * @param array $attributes + * @param mixed $attributes * - * @return Model + * @return Model | null */ - protected function toModel($attributes = []) + protected function toModel(mixed $attributes = []): Model|null { if ($attributes === null) { - return; + return null; } $connection = $this->related->getConnection(); $model = $this->related->newFromBuilder( (array) $attributes, - $connection ? $connection->getName() : null, + $connection?->getName(), ); $model->setParentRelation($this); @@ -394,8 +402,8 @@ public function getQualifiedForeignKeyName() /** * Get the name of the "where in" method for eager loading. * - * @param \Illuminate\Database\Eloquent\Model $model - * @param string $key + * @param EloquentModel $model + * @param string $key * * @return string */ diff --git a/src/Relations/MorphToMany.php b/src/Relations/MorphToMany.php index 9c9576d90..a2c55969f 100644 --- a/src/Relations/MorphToMany.php +++ b/src/Relations/MorphToMany.php @@ -85,11 +85,11 @@ protected function setWhere() } /** @inheritdoc */ - public function save(Model $model, array $joining = [], $touch = true) + public function save(Model $model, array $pivotAttributes = [], $touch = true) { $model->save(['touch' => false]); - $this->attach($model, $joining, $touch); + $this->attach($model, $pivotAttributes, $touch); return $model; } @@ -133,11 +133,6 @@ public function sync($ids, $detaching = true) $current = $this->parent->{$this->relatedPivotKey} ?: []; } - // See issue #256. - if ($current instanceof Collection) { - $current = $this->parseIds($current); - } - $records = $this->formatRecordsList($ids); $current = Arr::wrap($current); @@ -175,7 +170,7 @@ public function sync($ids, $detaching = true) } /** @inheritdoc */ - public function updateExistingPivot($id, array $attributes, $touch = true) + public function updateExistingPivot($id, array $attributes, $touch = true): void { // Do nothing, we have no pivot table. } @@ -272,12 +267,13 @@ public function detach($ids = [], $touch = true) // Remove the relation from the parent. $data = []; foreach ($ids as $item) { - $data = array_merge($data, [ + $data = [ + ...$data, [ $this->relatedPivotKey => $item, - $this->morphType => $this->related->getMorphClass(), + $this->morphType => $this->related->getMorphClass(), ], - ]); + ]; } $this->parent->pull($this->table, $data); @@ -378,8 +374,8 @@ protected function whereInMethod(Model $model, $key) /** * Extract ids from given pivot table data * - * @param array $data - * @param string|null $relatedPivotKey + * @param array $data + * @param string|null $relatedPivotKey * * @return mixed */ diff --git a/src/Schema/Blueprint.php b/src/Schema/Blueprint.php index 6dd28d3b2..52a5762f5 100644 --- a/src/Schema/Blueprint.php +++ b/src/Schema/Blueprint.php @@ -44,6 +44,8 @@ class Blueprint extends SchemaBlueprint */ public function __construct(Connection $connection, string $collection) { + parent::__construct($collection); + $this->connection = $connection; $this->collection = $this->connection->getCollection($collection); @@ -82,11 +84,11 @@ public function primary($columns = null, $name = null, $algorithm = null, $optio } /** @inheritdoc */ - public function dropIndex($indexOrColumns = null) + public function dropIndex($index = null) { - $indexOrColumns = $this->transformColumns($indexOrColumns); + $index = $this->transformColumns($index); - $this->collection->dropIndex($indexOrColumns); + $this->collection->dropIndex($index); return $this; } @@ -275,6 +277,8 @@ public function create($options = []) public function drop() { $this->collection->drop(); + + return $this; } /** @inheritdoc */ @@ -339,11 +343,11 @@ protected function fluent($columns = null) * Allows the use of unsupported schema methods. * * @param string $method - * @param array $args + * @param array $parameters * * @return Blueprint */ - public function __call($method, $args) + public function __call($method, $parameters) { // Dummy. return $this; diff --git a/src/Schema/Builder.php b/src/Schema/Builder.php index af311df6c..bfa0e4715 100644 --- a/src/Schema/Builder.php +++ b/src/Schema/Builder.php @@ -44,9 +44,9 @@ public function hasCollection($name) } /** @inheritdoc */ - public function hasTable($collection) + public function hasTable($table) { - return $this->hasCollection($collection); + return $this->hasCollection($table); } /** @@ -66,15 +66,15 @@ public function collection($collection, Closure $callback) } /** @inheritdoc */ - public function table($collection, Closure $callback) + public function table($table, Closure $callback) { - $this->collection($collection, $callback); + $this->collection($table, $callback); } /** @inheritdoc */ - public function create($collection, ?Closure $callback = null, array $options = []) + public function create($table, ?Closure $callback = null, array $options = []) { - $blueprint = $this->createBlueprint($collection); + $blueprint = $this->createBlueprint($table); $blueprint->create($options); @@ -84,17 +84,17 @@ public function create($collection, ?Closure $callback = null, array $options = } /** @inheritdoc */ - public function dropIfExists($collection) + public function dropIfExists($table) { - if ($this->hasCollection($collection)) { - $this->drop($collection); + if ($this->hasCollection($table)) { + $this->drop($table); } } /** @inheritdoc */ - public function drop($collection) + public function drop($table) { - $blueprint = $this->createBlueprint($collection); + $blueprint = $this->createBlueprint($table); $blueprint->drop(); } @@ -108,9 +108,9 @@ public function dropAllTables() } /** @inheritdoc */ - protected function createBlueprint($collection, ?Closure $callback = null) + protected function createBlueprint($table, ?Closure $callback = null) { - return new Blueprint($this->connection, $collection); + return new Blueprint($this->connection, $table); } /** From 1fb3e9e443a331adfe71cc3293afff2e46a0606a Mon Sep 17 00:00:00 2001 From: Tonko Mulder Date: Thu, 30 Nov 2023 11:27:49 +0100 Subject: [PATCH 135/446] Add test for the `$hidden` property (#2687) --- tests/Models/HiddenAnimal.php | 28 ++++++++++++++++++++++++++ tests/PropertyTest.php | 38 +++++++++++++++++++++++++++++++++++ 2 files changed, 66 insertions(+) create mode 100644 tests/Models/HiddenAnimal.php create mode 100644 tests/PropertyTest.php diff --git a/tests/Models/HiddenAnimal.php b/tests/Models/HiddenAnimal.php new file mode 100644 index 000000000..81e666d37 --- /dev/null +++ b/tests/Models/HiddenAnimal.php @@ -0,0 +1,28 @@ + 'Sheep', + 'country' => 'Ireland', + 'can_be_eaten' => true, + ]); + + $hiddenAnimal = HiddenAnimal::sole(); + assert($hiddenAnimal instanceof HiddenAnimal); + self::assertSame('Ireland', $hiddenAnimal->country); + self::assertTrue($hiddenAnimal->can_be_eaten); + + self::assertArrayHasKey('name', $hiddenAnimal->toArray()); + self::assertArrayNotHasKey('country', $hiddenAnimal->toArray(), 'the country column should be hidden'); + self::assertArrayHasKey('can_be_eaten', $hiddenAnimal->toArray()); + } +} From 4d65ca77117bf3ee77581cf6c12c504b4fc27f4a Mon Sep 17 00:00:00 2001 From: Mohammad Mortazavi <39920372+hans-thomas@users.noreply.github.com> Date: Thu, 30 Nov 2023 13:58:30 +0330 Subject: [PATCH 136/446] Update .gitattributes (#2686) --- .gitattributes | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/.gitattributes b/.gitattributes index 64657992f..2c18f5570 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,3 +1,12 @@ -/tests export-ignore -/.* export-ignore -/phpunit.xml.dist export-ignore +/.github export-ignore +/.phpunit.cache export-ignore +/docs export-ignore +/tests export-ignore +*.md export-ignore +*.dist export-ignore +.editorconfig export-ignore +.gitattributes export-ignore +.gitignore export-ignore +docker-compose.yml export-ignore +Dockerfile export-ignore +phpstan-baseline.neon export-ignore From fc1f9cc0b96d5d7d25fcb0eff7306d87c1a1efbc Mon Sep 17 00:00:00 2001 From: Mohammad Mortazavi <39920372+hans-thomas@users.noreply.github.com> Date: Mon, 4 Dec 2023 14:21:10 +0330 Subject: [PATCH 137/446] Update docker and test configs (#2678) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Tonko Mulder Co-authored-by: Jérôme Tamarelle --- .github/workflows/build-ci.yml | 83 +++++++++++++++----------- .github/workflows/coding-standards.yml | 12 ++-- CONTRIBUTING.md | 14 ++--- Dockerfile | 13 ++-- composer.json | 6 ++ docker-compose.yml | 14 ++--- phpunit.xml.dist | 2 +- 7 files changed, 78 insertions(+), 66 deletions(-) diff --git a/.github/workflows/build-ci.yml b/.github/workflows/build-ci.yml index 3664d752e..e69b2bfb9 100644 --- a/.github/workflows/build-ci.yml +++ b/.github/workflows/build-ci.yml @@ -1,4 +1,4 @@ -name: CI +name: "CI" on: push: @@ -6,29 +6,32 @@ on: jobs: build: - runs-on: ${{ matrix.os }} - name: PHP v${{ matrix.php }} with MongoDB ${{ matrix.mongodb }} ${{ matrix.mode }} + runs-on: "${{ matrix.os }}" + + name: "PHP v${{ matrix.php }} with MongoDB ${{ matrix.mongodb }} ${{ matrix.mode }}" + strategy: matrix: os: - - ubuntu-latest + - "ubuntu-latest" mongodb: - - '4.4' - - '5.0' - - '6.0' - - '7.0' + - "4.4" + - "5.0" + - "6.0" + - "7.0" php: - - '8.1' - - '8.2' - - '8.3' + - "8.1" + - "8.2" + - "8.3" include: - - php: '8.1' - mongodb: '5.0' - mode: 'low-deps' + - php: "8.1" + mongodb: "5.0" + mode: "low-deps" steps: - - uses: actions/checkout@v4 - - name: Create MongoDB Replica Set + - uses: "actions/checkout@v4" + + - name: "Create MongoDB Replica Set" run: | docker run --name mongodb -p 27017:27017 -e MONGO_INITDB_DATABASE=unittest --detach mongo:${{ matrix.mongodb }} mongod --replSet rs --setParameter transactionLifetimeLimitSeconds=5 @@ -37,35 +40,43 @@ jobs: sleep 1 done sudo docker exec --tty mongodb $MONGOSH_BIN 127.0.0.1:27017 --eval "rs.initiate({\"_id\":\"rs\",\"members\":[{\"_id\":0,\"host\":\"127.0.0.1:27017\" }]})" - - name: Show MongoDB server status + + - name: "Show MongoDB server status" run: | if [ "${{ matrix.mongodb }}" = "4.4" ]; then MONGOSH_BIN="mongo"; else MONGOSH_BIN="mongosh"; fi docker exec --tty mongodb $MONGOSH_BIN 127.0.0.1:27017 --eval "db.runCommand({ serverStatus: 1 })" + - name: "Installing php" - uses: shivammathur/setup-php@v2 + uses: "shivammathur/setup-php@v2" with: php-version: ${{ matrix.php }} - extensions: curl,mbstring,xdebug - coverage: xdebug - tools: composer - - name: Show PHP version - run: php -v && composer -V - - name: Show Docker version - run: if [[ "$DEBUG" == "true" ]]; then docker version && env; fi - env: - DEBUG: ${{ secrets.DEBUG }} - - name: Download Composer cache dependencies from cache - id: composer-cache + extensions: "curl,mbstring,xdebug" + coverage: "xdebug" + tools: "composer" + + - name: "Show PHP version" + if: ${{ secrets.DEBUG == 'true' }} + run: "php -v && composer -V" + + - name: "Show Docker version" + if: ${{ secrets.DEBUG == 'true' }} + run: "docker version && env" + + - name: "Download Composer cache dependencies from cache" + id: "composer-cache" run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT - - name: Cache Composer dependencies - uses: actions/cache@v3 + + - name: "Cache Composer dependencies" + uses: "actions/cache@v3" with: path: ${{ steps.composer-cache.outputs.dir }} - key: ${{ matrix.os }}-composer-${{ hashFiles('**/composer.json') }} - restore-keys: ${{ matrix.os }}-composer- - - name: Install dependencies + key: "${{ matrix.os }}-composer-${{ hashFiles('**/composer.json') }}" + restore-keys: "${{ matrix.os }}-composer-" + + - name: "Install dependencies" run: composer update --no-interaction $([[ "${{ matrix.mode }}" == low-deps ]] && echo ' --prefer-lowest --prefer-stable') - - name: Run tests - run: ./vendor/bin/phpunit --coverage-clover coverage.xml + + - name: "Run tests" + run: "./vendor/bin/phpunit --coverage-clover coverage.xml" env: MONGODB_URI: 'mongodb://127.0.0.1/?replicaSet=rs' diff --git a/.github/workflows/coding-standards.yml b/.github/workflows/coding-standards.yml index c6f730d33..aa359be3d 100644 --- a/.github/workflows/coding-standards.yml +++ b/.github/workflows/coding-standards.yml @@ -22,16 +22,16 @@ jobs: - name: "Checkout" uses: "actions/checkout@v4" - - name: Setup cache environment - id: extcache - uses: shivammathur/cache-extensions@v1 + - name: "Setup cache environment" + id: "extcache" + uses: "shivammathur/cache-extensions@v1" with: php-version: ${{ env.PHP_VERSION }} extensions: "mongodb-${{ env.DRIVER_VERSION }}" key: "extcache-v1" - - name: Cache extensions - uses: actions/cache@v3 + - name: "Cache extensions" + uses: "actions/cache@v3" with: path: ${{ steps.extcache.outputs.dir }} key: ${{ steps.extcache.outputs.key }} @@ -42,7 +42,7 @@ jobs: with: coverage: "none" extensions: "mongodb-${{ env.DRIVER_VERSION }}" - php-version: "${{ env.PHP_VERSION }}" + php-version: ${{ env.PHP_VERSION }} tools: "cs2pr" - name: "Show driver information" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4de5b27bd..419828755 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,27 +38,27 @@ Before submitting a pull request: ## Run Tests -The full test suite requires PHP cli with mongodb extension, a running MongoDB server and a running MySQL server. +The full test suite requires PHP cli with mongodb extension, a running MongoDB server. Duplicate the `phpunit.xml.dist` file to `phpunit.xml` and edit the environment variables to match your setup. ```bash -$ docker-compose up -d mongodb -$ docker-compose run tests +$ docker-compose run app ``` -Docker can be slow to start. You can run the command `php vendor/bin/phpunit --testdox` locally or in a docker container. +Docker can be slow to start. You can run the command `composer run test` locally or in a docker container. ```bash $ docker-compose run -it tests bash # Inside the container $ composer install -$ vendor/bin/phpunit --testdox +$ composer run test ``` -For fixing style issues, you can run the PHP Code Beautifier and Fixer: +For fixing style issues, you can run the PHP Code Beautifier and Fixer, some issues can't be fixed automatically: ```bash -$ php vendor/bin/phpcbf +$ composer run cs:fix +$ composer run cs ``` ## Requirements diff --git a/Dockerfile b/Dockerfile index 5d22eb513..43529d9e4 100644 --- a/Dockerfile +++ b/Dockerfile @@ -2,18 +2,15 @@ ARG PHP_VERSION=8.1 FROM php:${PHP_VERSION}-cli +# Install extensions RUN apt-get update && \ apt-get install -y autoconf pkg-config libssl-dev git unzip libzip-dev zlib1g-dev && \ pecl install mongodb && docker-php-ext-enable mongodb && \ pecl install xdebug && docker-php-ext-enable xdebug && \ docker-php-ext-install -j$(nproc) zip -COPY --from=composer:2.6.2 /usr/bin/composer /usr/local/bin/composer +# Create php.ini +RUN cp "$PHP_INI_DIR/php.ini-development" "$PHP_INI_DIR/php.ini" -ENV COMPOSER_ALLOW_SUPERUSER=1 - -WORKDIR /code - -COPY ./ ./ - -CMD ["bash", "-c", "composer install && ./vendor/bin/phpunit --testdox"] +# Install Composer +COPY --from=composer:2 /usr/bin/composer /usr/local/bin/composer diff --git a/composer.json b/composer.json index b04425751..22b75f58f 100644 --- a/composer.json +++ b/composer.json @@ -59,6 +59,12 @@ ] } }, + "scripts": { + "test": "phpunit", + "test:coverage": "phpunit --coverage-clover ./coverage.xml", + "cs": "phpcs", + "cs:fix": "phpcbf" + }, "config": { "platform": { "php": "8.1" diff --git a/docker-compose.yml b/docker-compose.yml index fec4aa191..f757ec3cd 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,17 +1,15 @@ version: '3.5' services: - tests: - container_name: tests + app: tty: true - build: - context: . - dockerfile: Dockerfile - volumes: - - .:/code - working_dir: /code + build: . + working_dir: /var/www/laravel-mongodb + command: "bash -c 'composer install && composer run test'" environment: MONGODB_URI: 'mongodb://mongodb/' + volumes: + - .:/var/www/laravel-mongodb depends_on: mongodb: condition: service_healthy diff --git a/phpunit.xml.dist b/phpunit.xml.dist index 8e5e9d3d6..b1aa3a8eb 100644 --- a/phpunit.xml.dist +++ b/phpunit.xml.dist @@ -18,7 +18,7 @@ - + From 24c359283588e16d1469c5835ef8ea2d44bacca6 Mon Sep 17 00:00:00 2001 From: Mohammad Mortazavi <39920372+hans-thomas@users.noreply.github.com> Date: Mon, 4 Dec 2023 22:49:01 +0330 Subject: [PATCH 138/446] Update `push` and `pull` docs (#2685) Co-Authored-By: Jeremy Mikola --- docs/query-builder.md | 122 +++++++++++++++++++++++++++++++++--------- 1 file changed, 97 insertions(+), 25 deletions(-) diff --git a/docs/query-builder.md b/docs/query-builder.md index 9672e21ef..4438e889c 100644 --- a/docs/query-builder.md +++ b/docs/query-builder.md @@ -448,64 +448,136 @@ DB::collection('items') **Push** -Add items to an array. +Add one or multiple values to the `items` array. ```php +// Push the value to the matched documents DB::collection('users') - ->where('name', 'John') - ->push('items', 'boots'); + ->where('name', 'John') + // Push a single value to the items array + ->push('items', 'boots'); +// Result: +// items: ['boots'] + +DB::collection('users') + ->where('name', 'John') + // Push multiple values to the items array + ->push('items', ['hat', 'jeans']); +// Result: +// items: ['boots', 'hat', 'jeans'] +// Or + +// Push the values directly to a model object $user->push('items', 'boots'); +$user->push('items', ['hat', 'jeans']); ``` +To add embedded document or array values to the `messages` array, those values must be specified within a list array. + ```php DB::collection('users') - ->where('name', 'John') - ->push('messages', [ - 'from' => 'Jane Doe', - 'message' => 'Hi John', - ]); + ->where('name', 'John') + // Push an embedded document as a value to the messages array + ->push('messages', [ + [ 'from' => 'Jane Doe', 'message' => 'Hi John' ] + ]); +// Result: +// messages: [ +// { from: "Jane Doe", message: "Hi John" } +// ] + +// Or $user->push('messages', [ - 'from' => 'Jane Doe', - 'message' => 'Hi John', + [ 'from' => 'Jane Doe', 'message' => 'Hi John' ] ]); ``` -If you **DON'T** want duplicate items, set the third parameter to `true`: +If you **DON'T** want duplicate values, set the third parameter to `true`: ```php DB::collection('users') - ->where('name', 'John') - ->push('items', 'boots', true); + ->where('name', 'John') + ->push('items', 'boots'); +// Result: +// items: ['boots'] + +DB::collection('users') + ->where('name', 'John') + ->push('items', ['hat', 'boots', 'jeans'], true); +// Result: +// items: ['boots', 'hat', 'jeans'] + +// Or -$user->push('items', 'boots', true); +$user->push('messages', [ + [ 'from' => 'Jane Doe', 'message' => 'Hi John' ] +]); +// Result: +// messages: [ +// { from: "Jane Doe", message: "Hi John" } +// ] + +$user->push('messages', [ + [ 'from' => 'Jess Doe', 'message' => 'Hi' ], + [ 'from' => 'Jane Doe', 'message' => 'Hi John' ], +], true); +// Result: +// messages: [ +// { from: "Jane Doe", message: "Hi John" } +// { from: "Jess Doe", message: "Hi" } +// ] ``` **Pull** -Remove an item from an array. +Remove one or multiple values from the `items` array. ```php +// items: ['boots', 'hat', 'jeans'] + DB::collection('users') - ->where('name', 'John') - ->pull('items', 'boots'); + ->where('name', 'John') + ->pull('items', 'boots'); // Pull a single value +// Result: +// items: ['hat', 'jeans'] -$user->pull('items', 'boots'); +// Or pull multiple values + +$user->pull('items', ['boots', 'jeans']); +// Result: +// items: ['hat'] ``` +Embedded document and arrays values can also be removed from the `messages` array. + ```php +// Latest state: +// messages: [ +// { from: "Jane Doe", message: "Hi John" } +// { from: "Jess Doe", message: "Hi" } +// ] + DB::collection('users') - ->where('name', 'John') - ->pull('messages', [ - 'from' => 'Jane Doe', - 'message' => 'Hi John', - ]); + ->where('name', 'John') + // Pull an embedded document from the array + ->pull('messages', [ + [ 'from' => 'Jane Doe', 'message' => 'Hi John' ] + ]); +// Result: +// messages: [ +// { from: "Jess Doe", message: "Hi" } +// ] + +// Or pull multiple embedded documents $user->pull('messages', [ - 'from' => 'Jane Doe', - 'message' => 'Hi John', + [ 'from' => 'Jane Doe', 'message' => 'Hi John' ], + [ 'from' => 'Jess Doe', 'message' => 'Hi' ] ]); +// Result: +// messages: [ ] ``` **Unset** From 57060eba510b5d24b6f88771ddff37679db838cf Mon Sep 17 00:00:00 2001 From: Tonko Mulder Date: Tue, 5 Dec 2023 13:16:14 +0100 Subject: [PATCH 139/446] fix CI workflow (#2691) * use `runner.debug` as conditional * remove redundant debug step --- .github/workflows/build-ci.yml | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/.github/workflows/build-ci.yml b/.github/workflows/build-ci.yml index e69b2bfb9..c6cc2588b 100644 --- a/.github/workflows/build-ci.yml +++ b/.github/workflows/build-ci.yml @@ -54,12 +54,8 @@ jobs: coverage: "xdebug" tools: "composer" - - name: "Show PHP version" - if: ${{ secrets.DEBUG == 'true' }} - run: "php -v && composer -V" - - name: "Show Docker version" - if: ${{ secrets.DEBUG == 'true' }} + if: ${{ runner.debug }} run: "docker version && env" - name: "Download Composer cache dependencies from cache" From 2adbf87c5eeac99f622a5e10949b22734dbf4aff Mon Sep 17 00:00:00 2001 From: Mohammad Mortazavi <39920372+hans-thomas@users.noreply.github.com> Date: Mon, 11 Dec 2023 12:13:54 +0330 Subject: [PATCH 140/446] Hybrid support for BelongsToMany relationship (#2688) Co-authored-by: Junio Hyago <35033754+juniohyago@users.noreply.github.com> --- phpstan-baseline.neon | 2 +- src/Relations/BelongsToMany.php | 29 ++++++++++++++++--- tests/HybridRelationsTest.php | 51 +++++++++++++++++++++++++++++++++ tests/Models/Skill.php | 6 ++++ tests/Models/SqlUser.php | 13 +++++++++ 5 files changed, 96 insertions(+), 5 deletions(-) diff --git a/phpstan-baseline.neon b/phpstan-baseline.neon index 71a44a395..4869c6ca0 100644 --- a/phpstan-baseline.neon +++ b/phpstan-baseline.neon @@ -2,7 +2,7 @@ parameters: ignoreErrors: - message: "#^Method Illuminate\\\\Database\\\\Eloquent\\\\Model\\:\\:push\\(\\) invoked with 3 parameters, 0 required\\.$#" - count: 3 + count: 2 path: src/Relations/BelongsToMany.php - diff --git a/src/Relations/BelongsToMany.php b/src/Relations/BelongsToMany.php index 1d6b84ba8..082f95e06 100644 --- a/src/Relations/BelongsToMany.php +++ b/src/Relations/BelongsToMany.php @@ -17,6 +17,7 @@ use function array_values; use function assert; use function count; +use function in_array; use function is_numeric; class BelongsToMany extends EloquentBelongsToMany @@ -124,7 +125,14 @@ public function sync($ids, $detaching = true) // First we need to attach any of the associated models that are not currently // in this joining table. We'll spin through the given IDs, checking to see // if they exist in the array of current ones, and if not we will insert. - $current = $this->parent->{$this->relatedPivotKey} ?: []; + $current = match ($this->parent instanceof \MongoDB\Laravel\Eloquent\Model) { + true => $this->parent->{$this->relatedPivotKey} ?: [], + false => $this->parent->{$this->relationName} ?: [], + }; + + if ($current instanceof Collection) { + $current = $this->parseIds($current); + } $records = $this->formatRecordsList($ids); @@ -193,7 +201,14 @@ public function attach($id, array $attributes = [], $touch = true) } // Attach the new ids to the parent model. - $this->parent->push($this->relatedPivotKey, (array) $id, true); + if ($this->parent instanceof \MongoDB\Laravel\Eloquent\Model) { + $this->parent->push($this->relatedPivotKey, (array) $id, true); + } else { + $instance = new $this->related(); + $instance->forceFill([$this->relatedKey => $id]); + $relationData = $this->parent->{$this->relationName}->push($instance)->unique($this->relatedKey); + $this->parent->setRelation($this->relationName, $relationData); + } if (! $touch) { return; @@ -217,7 +232,13 @@ public function detach($ids = [], $touch = true) $ids = (array) $ids; // Detach all ids from the parent model. - $this->parent->pull($this->relatedPivotKey, $ids); + if ($this->parent instanceof \MongoDB\Laravel\Eloquent\Model) { + $this->parent->pull($this->relatedPivotKey, $ids); + } else { + $value = $this->parent->{$this->relationName} + ->filter(fn ($rel) => ! in_array($rel->{$this->relatedKey}, $ids)); + $this->parent->setRelation($this->relationName, $value); + } // Prepare the query to select all related objects. if (count($ids) > 0) { @@ -225,7 +246,7 @@ public function detach($ids = [], $touch = true) } // Remove the relation to the parent. - assert($this->parent instanceof \MongoDB\Laravel\Eloquent\Model); + assert($this->parent instanceof Model); assert($query instanceof \MongoDB\Laravel\Eloquent\Builder); $query->pull($this->foreignPivotKey, $this->parent->getKey()); diff --git a/tests/HybridRelationsTest.php b/tests/HybridRelationsTest.php index 9ff6264e5..0080a3a47 100644 --- a/tests/HybridRelationsTest.php +++ b/tests/HybridRelationsTest.php @@ -8,6 +8,7 @@ use Illuminate\Support\Facades\DB; use MongoDB\Laravel\Tests\Models\Book; use MongoDB\Laravel\Tests\Models\Role; +use MongoDB\Laravel\Tests\Models\Skill; use MongoDB\Laravel\Tests\Models\SqlBook; use MongoDB\Laravel\Tests\Models\SqlRole; use MongoDB\Laravel\Tests\Models\SqlUser; @@ -36,6 +37,7 @@ public function tearDown(): void SqlUser::truncate(); SqlBook::truncate(); SqlRole::truncate(); + Skill::truncate(); } public function testSqlRelations() @@ -210,4 +212,53 @@ public function testHybridWith() $this->assertEquals($user->id, $user->books->count()); }); } + + public function testHybridBelongsToMany() + { + $user = new SqlUser(); + $user2 = new SqlUser(); + $this->assertInstanceOf(SqlUser::class, $user); + $this->assertInstanceOf(SQLiteConnection::class, $user->getConnection()); + $this->assertInstanceOf(SqlUser::class, $user2); + $this->assertInstanceOf(SQLiteConnection::class, $user2->getConnection()); + + // Create Mysql Users + $user->fill(['name' => 'John Doe'])->save(); + $user = SqlUser::query()->find($user->id); + + $user2->fill(['name' => 'Maria Doe'])->save(); + $user2 = SqlUser::query()->find($user2->id); + + // Create Mongodb Skills + $skill = Skill::query()->create(['name' => 'Laravel']); + $skill2 = Skill::query()->create(['name' => 'MongoDB']); + + // sync (pivot is empty) + $skill->sqlUsers()->sync([$user->id, $user2->id]); + $check = Skill::query()->find($skill->_id); + $this->assertEquals(2, $check->sqlUsers->count()); + + // sync (pivot is not empty) + $skill->sqlUsers()->sync($user); + $check = Skill::query()->find($skill->_id); + $this->assertEquals(1, $check->sqlUsers->count()); + + // Inverse sync (pivot is empty) + $user->skills()->sync([$skill->_id, $skill2->_id]); + $check = SqlUser::find($user->id); + $this->assertEquals(2, $check->skills->count()); + + // Inverse sync (pivot is not empty) + $user->skills()->sync($skill); + $check = SqlUser::find($user->id); + $this->assertEquals(1, $check->skills->count()); + + // Inverse attach + $user->skills()->sync([]); + $check = SqlUser::find($user->id); + $this->assertEquals(0, $check->skills->count()); + $user->skills()->attach($skill); + $check = SqlUser::find($user->id); + $this->assertEquals(1, $check->skills->count()); + } } diff --git a/tests/Models/Skill.php b/tests/Models/Skill.php index c4c1dbd0a..3b9a434ee 100644 --- a/tests/Models/Skill.php +++ b/tests/Models/Skill.php @@ -4,6 +4,7 @@ namespace MongoDB\Laravel\Tests\Models; +use Illuminate\Database\Eloquent\Relations\BelongsToMany; use MongoDB\Laravel\Eloquent\Model as Eloquent; class Skill extends Eloquent @@ -11,4 +12,9 @@ class Skill extends Eloquent protected $connection = 'mongodb'; protected $collection = 'skills'; protected static $unguarded = true; + + public function sqlUsers(): BelongsToMany + { + return $this->belongsToMany(SqlUser::class); + } } diff --git a/tests/Models/SqlUser.php b/tests/Models/SqlUser.php index 1fe11276a..34c65f42e 100644 --- a/tests/Models/SqlUser.php +++ b/tests/Models/SqlUser.php @@ -5,6 +5,7 @@ namespace MongoDB\Laravel\Tests\Models; use Illuminate\Database\Eloquent\Model as EloquentModel; +use Illuminate\Database\Eloquent\Relations\BelongsToMany; use Illuminate\Database\Eloquent\Relations\HasMany; use Illuminate\Database\Eloquent\Relations\HasOne; use Illuminate\Database\Schema\Blueprint; @@ -32,6 +33,11 @@ public function role(): HasOne return $this->hasOne(Role::class); } + public function skills(): BelongsToMany + { + return $this->belongsToMany(Skill::class, relatedPivotKey: 'skills'); + } + public function sqlBooks(): HasMany { return $this->hasMany(SqlBook::class); @@ -51,5 +57,12 @@ public static function executeSchema(): void $table->string('name'); $table->timestamps(); }); + if (! $schema->hasTable('skill_sql_user')) { + $schema->create('skill_sql_user', function (Blueprint $table) { + $table->foreignIdFor(self::class)->constrained()->cascadeOnDelete(); + $table->string((new Skill())->getForeignKey()); + $table->primary([(new self())->getForeignKey(), (new Skill())->getForeignKey()]); + }); + } } } From b3779a13e8ac4cb442b230aa7f2bde3c56d4c64f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Anderson=20Luiz=20Silv=C3=A9rio?= Date: Mon, 11 Dec 2023 06:23:53 -0300 Subject: [PATCH 141/446] Avoid unnecessary data fetch for exists method (#2692) --- src/Query/Builder.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 60d6b01da..36a4c7497 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -545,7 +545,7 @@ public function aggregate($function, $columns = []) /** @inheritdoc */ public function exists() { - return $this->first() !== null; + return $this->first(['_id']) !== null; } /** @inheritdoc */ From 1a4a972bab046f5ab1d3f35225fcd197f7794249 Mon Sep 17 00:00:00 2001 From: Mohammad Mortazavi <39920372+hans-thomas@users.noreply.github.com> Date: Mon, 11 Dec 2023 16:47:35 +0330 Subject: [PATCH 142/446] Hybrid support for MorphToMany relationship (#2690) --- phpstan-baseline.neon | 2 +- src/Eloquent/HybridRelations.php | 16 ++-- src/Relations/MorphToMany.php | 122 +++++++++++++++++++++++++------ tests/HybridRelationsTest.php | 106 +++++++++++++++++++++++++++ tests/Models/Experience.php | 6 ++ tests/Models/Label.php | 9 ++- tests/Models/SqlUser.php | 29 ++++++++ 7 files changed, 257 insertions(+), 33 deletions(-) diff --git a/phpstan-baseline.neon b/phpstan-baseline.neon index 4869c6ca0..99579fa0a 100644 --- a/phpstan-baseline.neon +++ b/phpstan-baseline.neon @@ -7,7 +7,7 @@ parameters: - message: "#^Method Illuminate\\\\Database\\\\Eloquent\\\\Model\\:\\:push\\(\\) invoked with 3 parameters, 0 required\\.$#" - count: 6 + count: 2 path: src/Relations/MorphToMany.php - diff --git a/src/Eloquent/HybridRelations.php b/src/Eloquent/HybridRelations.php index 9551a6c43..5c058f50f 100644 --- a/src/Eloquent/HybridRelations.php +++ b/src/Eloquent/HybridRelations.php @@ -432,12 +432,16 @@ public function morphedByMany( $relatedKey = null, $relation = null, ) { - $foreignPivotKey = $foreignPivotKey ?: Str::plural($this->getForeignKey()); - - // For the inverse of the polymorphic many-to-many relations, we will change - // the way we determine the foreign and other keys, as it is the opposite - // of the morph-to-many method since we're figuring out these inverses. - $relatedPivotKey = $relatedPivotKey ?: $name . '_id'; + // If the related model is an instance of eloquent model class, leave pivot keys + // as default. It's necessary for supporting hybrid relationship + if (is_subclass_of($related, Model::class)) { + // For the inverse of the polymorphic many-to-many relations, we will change + // the way we determine the foreign and other keys, as it is the opposite + // of the morph-to-many method since we're figuring out these inverses. + $foreignPivotKey = $foreignPivotKey ?: Str::plural($this->getForeignKey()); + + $relatedPivotKey = $relatedPivotKey ?: $name . '_id'; + } return $this->morphToMany( $related, diff --git a/src/Relations/MorphToMany.php b/src/Relations/MorphToMany.php index a2c55969f..163e7e67f 100644 --- a/src/Relations/MorphToMany.php +++ b/src/Relations/MorphToMany.php @@ -9,6 +9,7 @@ use Illuminate\Database\Eloquent\Model; use Illuminate\Database\Eloquent\Relations\MorphToMany as EloquentMorphToMany; use Illuminate\Support\Arr; +use MongoDB\BSON\ObjectId; use function array_diff; use function array_key_exists; @@ -17,7 +18,9 @@ use function array_merge; use function array_reduce; use function array_values; +use function collect; use function count; +use function in_array; use function is_array; use function is_numeric; @@ -74,11 +77,20 @@ public function addEagerConstraints(array $models) protected function setWhere() { if ($this->getInverse()) { - $ids = $this->extractIds((array) $this->parent->{$this->table}); + if ($this->parent instanceof \MongoDB\Laravel\Eloquent\Model) { + $ids = $this->extractIds((array) $this->parent->{$this->table}); - $this->query->whereIn($this->relatedKey, $ids); + $this->query->whereIn($this->relatedKey, $ids); + } else { + $this->query + ->whereIn($this->foreignPivotKey, (array) $this->parent->{$this->parentKey}); + } } else { - $this->query->whereIn($this->relatedKey, (array) $this->parent->{$this->relatedPivotKey}); + match ($this->parent instanceof \MongoDB\Laravel\Eloquent\Model) { + true => $this->query->whereIn($this->relatedKey, (array) $this->parent->{$this->relatedPivotKey}), + false => $this->query + ->whereIn($this->getQualifiedForeignPivotKeyName(), (array) $this->parent->{$this->parentKey}), + }; } return $this; @@ -128,9 +140,25 @@ public function sync($ids, $detaching = true) // in this joining table. We'll spin through the given IDs, checking to see // if they exist in the array of current ones, and if not we will insert. if ($this->getInverse()) { - $current = $this->extractIds($this->parent->{$this->table} ?: []); + $current = match ($this->parent instanceof \MongoDB\Laravel\Eloquent\Model) { + true => $this->parent->{$this->table} ?: [], + false => $this->parent->{$this->relationName} ?: [], + }; + + if ($current instanceof Collection) { + $current = collect($this->parseIds($current))->flatten()->toArray(); + } else { + $current = $this->extractIds($current); + } } else { - $current = $this->parent->{$this->relatedPivotKey} ?: []; + $current = match ($this->parent instanceof \MongoDB\Laravel\Eloquent\Model) { + true => $this->parent->{$this->relatedPivotKey} ?: [], + false => $this->parent->{$this->relationName} ?: [], + }; + + if ($current instanceof Collection) { + $current = $this->parseIds($current); + } } $records = $this->formatRecordsList($ids); @@ -185,15 +213,19 @@ public function attach($id, array $attributes = [], $touch = true) if ($this->getInverse()) { // Attach the new ids to the parent model. - $this->parent->push($this->table, [ - [ - $this->relatedPivotKey => $model->{$this->relatedKey}, - $this->morphType => $model->getMorphClass(), - ], - ], true); + if ($this->parent instanceof \MongoDB\Laravel\Eloquent\Model) { + $this->parent->push($this->table, [ + [ + $this->relatedPivotKey => $model->{$this->relatedKey}, + $this->morphType => $model->getMorphClass(), + ], + ], true); + } else { + $this->addIdToParentRelationData($id); + } // Attach the new parent id to the related model. - $model->push($this->foreignPivotKey, $this->parseIds($this->parent), true); + $model->push($this->foreignPivotKey, (array) $this->parent->{$this->parentKey}, true); } else { // Attach the new parent id to the related model. $model->push($this->table, [ @@ -204,7 +236,11 @@ public function attach($id, array $attributes = [], $touch = true) ], true); // Attach the new ids to the parent model. - $this->parent->push($this->relatedPivotKey, (array) $id, true); + if ($this->parent instanceof \MongoDB\Laravel\Eloquent\Model) { + $this->parent->push($this->relatedPivotKey, (array) $id, true); + } else { + $this->addIdToParentRelationData($id); + } } } else { if ($id instanceof Collection) { @@ -221,13 +257,19 @@ public function attach($id, array $attributes = [], $touch = true) $query->push($this->foreignPivotKey, $this->parent->{$this->parentKey}); // Attach the new ids to the parent model. - foreach ($id as $item) { - $this->parent->push($this->table, [ - [ - $this->relatedPivotKey => $item, - $this->morphType => $this->related instanceof Model ? $this->related->getMorphClass() : null, - ], - ], true); + if ($this->parent instanceof \MongoDB\Laravel\Eloquent\Model) { + foreach ($id as $item) { + $this->parent->push($this->table, [ + [ + $this->relatedPivotKey => $item, + $this->morphType => $this->related instanceof Model ? $this->related->getMorphClass() : null, + ], + ], true); + } + } else { + foreach ($id as $item) { + $this->addIdToParentRelationData($item); + } } } else { // Attach the new parent id to the related model. @@ -239,7 +281,13 @@ public function attach($id, array $attributes = [], $touch = true) ], true); // Attach the new ids to the parent model. - $this->parent->push($this->relatedPivotKey, $id, true); + if ($this->parent instanceof \MongoDB\Laravel\Eloquent\Model) { + $this->parent->push($this->relatedPivotKey, $id, true); + } else { + foreach ($id as $item) { + $this->addIdToParentRelationData($item); + } + } } } @@ -276,7 +324,13 @@ public function detach($ids = [], $touch = true) ]; } - $this->parent->pull($this->table, $data); + if ($this->parent instanceof \MongoDB\Laravel\Eloquent\Model) { + $this->parent->pull($this->table, $data); + } else { + $value = $this->parent->{$this->relationName} + ->filter(fn ($rel) => ! in_array($rel->{$this->relatedKey}, $this->extractIds($data))); + $this->parent->setRelation($this->relationName, $value); + } // Prepare the query to select all related objects. if (count($ids) > 0) { @@ -287,7 +341,13 @@ public function detach($ids = [], $touch = true) $query->pull($this->foreignPivotKey, $this->parent->{$this->parentKey}); } else { // Remove the relation from the parent. - $this->parent->pull($this->relatedPivotKey, $ids); + if ($this->parent instanceof \MongoDB\Laravel\Eloquent\Model) { + $this->parent->pull($this->relatedPivotKey, $ids); + } else { + $value = $this->parent->{$this->relationName} + ->filter(fn ($rel) => ! in_array($rel->{$this->relatedKey}, $ids)); + $this->parent->setRelation($this->relationName, $value); + } // Prepare the query to select all related objects. if (count($ids) > 0) { @@ -390,4 +450,20 @@ public function extractIds(array $data, ?string $relatedPivotKey = null) return $carry; }, []); } + + /** + * Add the given id to the relation's data of the current parent instance. + * It helps to keep up-to-date the sql model instances in hybrid relationships. + * + * @param ObjectId|string|int $id + * + * @return void + */ + private function addIdToParentRelationData($id) + { + $instance = new $this->related(); + $instance->forceFill([$this->relatedKey => $id]); + $relationData = $this->parent->{$this->relationName}->push($instance)->unique($this->relatedKey); + $this->parent->setRelation($this->relationName, $relationData); + } } diff --git a/tests/HybridRelationsTest.php b/tests/HybridRelationsTest.php index 0080a3a47..5253784c9 100644 --- a/tests/HybridRelationsTest.php +++ b/tests/HybridRelationsTest.php @@ -7,6 +7,8 @@ use Illuminate\Database\SQLiteConnection; use Illuminate\Support\Facades\DB; use MongoDB\Laravel\Tests\Models\Book; +use MongoDB\Laravel\Tests\Models\Experience; +use MongoDB\Laravel\Tests\Models\Label; use MongoDB\Laravel\Tests\Models\Role; use MongoDB\Laravel\Tests\Models\Skill; use MongoDB\Laravel\Tests\Models\SqlBook; @@ -38,6 +40,8 @@ public function tearDown(): void SqlBook::truncate(); SqlRole::truncate(); Skill::truncate(); + Experience::truncate(); + Label::truncate(); } public function testSqlRelations() @@ -261,4 +265,106 @@ public function testHybridBelongsToMany() $check = SqlUser::find($user->id); $this->assertEquals(1, $check->skills->count()); } + + public function testHybridMorphToManySqlModelToMongoModel() + { + // SqlModel -> MorphToMany -> MongoModel + $user = new SqlUser(); + $user2 = new SqlUser(); + $this->assertInstanceOf(SqlUser::class, $user); + $this->assertInstanceOf(SQLiteConnection::class, $user->getConnection()); + $this->assertInstanceOf(SqlUser::class, $user2); + $this->assertInstanceOf(SQLiteConnection::class, $user2->getConnection()); + + // Create Mysql Users + $user->fill(['name' => 'John Doe'])->save(); + $user = SqlUser::query()->find($user->id); + + $user2->fill(['name' => 'Maria Doe'])->save(); + $user2 = SqlUser::query()->find($user2->id); + + // Create Mongodb skills + $label = Label::query()->create(['name' => 'Laravel']); + $label2 = Label::query()->create(['name' => 'MongoDB']); + + // MorphToMany (pivot is empty) + $user->labels()->sync([$label->_id, $label2->_id]); + $check = SqlUser::query()->find($user->id); + $this->assertEquals(2, $check->labels->count()); + + // MorphToMany (pivot is not empty) + $user->labels()->sync($label); + $check = SqlUser::query()->find($user->id); + $this->assertEquals(1, $check->labels->count()); + + // Attach MorphToMany + $user->labels()->sync([]); + $check = SqlUser::query()->find($user->id); + $this->assertEquals(0, $check->labels->count()); + $user->labels()->attach($label); + $user->labels()->attach($label); // ignore duplicates + $check = SqlUser::query()->find($user->id); + $this->assertEquals(1, $check->labels->count()); + + // Inverse MorphToMany (pivot is empty) + $label->sqlUsers()->sync([$user->id, $user2->id]); + $check = Label::query()->find($label->_id); + $this->assertEquals(2, $check->sqlUsers->count()); + + // Inverse MorphToMany (pivot is empty) + $label->sqlUsers()->sync([$user->id, $user2->id]); + $check = Label::query()->find($label->_id); + $this->assertEquals(2, $check->sqlUsers->count()); + } + + public function testHybridMorphToManyMongoModelToSqlModel() + { + // MongoModel -> MorphToMany -> SqlModel + $user = new SqlUser(); + $user2 = new SqlUser(); + $this->assertInstanceOf(SqlUser::class, $user); + $this->assertInstanceOf(SQLiteConnection::class, $user->getConnection()); + $this->assertInstanceOf(SqlUser::class, $user2); + $this->assertInstanceOf(SQLiteConnection::class, $user2->getConnection()); + + // Create Mysql Users + $user->fill(['name' => 'John Doe'])->save(); + $user = SqlUser::query()->find($user->id); + + $user2->fill(['name' => 'Maria Doe'])->save(); + $user2 = SqlUser::query()->find($user2->id); + + // Create Mongodb experiences + $experience = Experience::query()->create(['title' => 'DB expert']); + $experience2 = Experience::query()->create(['title' => 'MongoDB']); + + // MorphToMany (pivot is empty) + $experience->sqlUsers()->sync([$user->id, $user2->id]); + $check = Experience::query()->find($experience->_id); + $this->assertEquals(2, $check->sqlUsers->count()); + + // MorphToMany (pivot is not empty) + $experience->sqlUsers()->sync([$user->id]); + $check = Experience::query()->find($experience->_id); + $this->assertEquals(1, $check->sqlUsers->count()); + + // Inverse MorphToMany (pivot is empty) + $user->experiences()->sync([$experience->_id, $experience2->_id]); + $check = SqlUser::query()->find($user->id); + $this->assertEquals(2, $check->experiences->count()); + + // Inverse MorphToMany (pivot is not empty) + $user->experiences()->sync([$experience->_id]); + $check = SqlUser::query()->find($user->id); + $this->assertEquals(1, $check->experiences->count()); + + // Inverse MorphToMany (pivot is not empty) + $user->experiences()->sync([]); + $check = SqlUser::query()->find($user->id); + $this->assertEquals(0, $check->experiences->count()); + $user->experiences()->attach($experience); + $user->experiences()->attach($experience); // ignore duplicates + $check = SqlUser::query()->find($user->id); + $this->assertEquals(1, $check->experiences->count()); + } } diff --git a/tests/Models/Experience.php b/tests/Models/Experience.php index 617073c79..4c2869d9e 100644 --- a/tests/Models/Experience.php +++ b/tests/Models/Experience.php @@ -4,6 +4,7 @@ namespace MongoDB\Laravel\Tests\Models; +use Illuminate\Database\Eloquent\Relations\MorphToMany; use MongoDB\Laravel\Eloquent\Model as Eloquent; class Experience extends Eloquent @@ -23,4 +24,9 @@ public function skillsWithCustomParentKey() { return $this->belongsToMany(Skill::class, parentKey: 'cexperience_id'); } + + public function sqlUsers(): MorphToMany + { + return $this->morphToMany(SqlUser::class, 'experienced'); + } } diff --git a/tests/Models/Label.php b/tests/Models/Label.php index 179503ce1..5bd1cf4da 100644 --- a/tests/Models/Label.php +++ b/tests/Models/Label.php @@ -4,6 +4,7 @@ namespace MongoDB\Laravel\Tests\Models; +use Illuminate\Database\Eloquent\Relations\MorphToMany; use MongoDB\Laravel\Eloquent\Model as Eloquent; /** @@ -23,14 +24,16 @@ class Label extends Eloquent 'chapters', ]; - /** - * Get all the posts that are assigned this tag. - */ public function users() { return $this->morphedByMany(User::class, 'labelled'); } + public function sqlUsers(): MorphToMany + { + return $this->morphedByMany(SqlUser::class, 'labeled'); + } + public function clients() { return $this->morphedByMany(Client::class, 'labelled'); diff --git a/tests/Models/SqlUser.php b/tests/Models/SqlUser.php index 34c65f42e..4cb77faa5 100644 --- a/tests/Models/SqlUser.php +++ b/tests/Models/SqlUser.php @@ -12,6 +12,7 @@ use Illuminate\Database\Schema\SQLiteBuilder; use Illuminate\Support\Facades\Schema; use MongoDB\Laravel\Eloquent\HybridRelations; +use MongoDB\Laravel\Relations\MorphToMany; use function assert; @@ -43,6 +44,16 @@ public function sqlBooks(): HasMany return $this->hasMany(SqlBook::class); } + public function labels(): MorphToMany + { + return $this->morphToMany(Label::class, 'labeled'); + } + + public function experiences(): MorphToMany + { + return $this->morphedByMany(Experience::class, 'experienced'); + } + /** * Check if we need to run the schema. */ @@ -57,6 +68,8 @@ public static function executeSchema(): void $table->string('name'); $table->timestamps(); }); + + // Pivot table for BelongsToMany relationship with Skill if (! $schema->hasTable('skill_sql_user')) { $schema->create('skill_sql_user', function (Blueprint $table) { $table->foreignIdFor(self::class)->constrained()->cascadeOnDelete(); @@ -64,5 +77,21 @@ public static function executeSchema(): void $table->primary([(new self())->getForeignKey(), (new Skill())->getForeignKey()]); }); } + + // Pivot table for MorphToMany relationship with Label + if (! $schema->hasTable('labeleds')) { + $schema->create('labeleds', function (Blueprint $table) { + $table->foreignIdFor(self::class)->constrained()->cascadeOnDelete(); + $table->morphs('labeled'); + }); + } + + // Pivot table for MorphedByMany relationship with Experience + if (! $schema->hasTable('experienceds')) { + $schema->create('experienceds', function (Blueprint $table) { + $table->foreignIdFor(self::class)->constrained()->cascadeOnDelete(); + $table->morphs('experienced'); + }); + } } } From 563a49fc6595087ba85c1607648dc027604da8ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 11 Dec 2023 15:39:14 +0100 Subject: [PATCH 143/446] Update changelog --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 27ab3d4d3..a6086cd60 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,7 +1,7 @@ # Changelog All notable changes to this project will be documented in this file. -## [4.0.3] - unreleased +## [4.1.0] - unreleased ## [4.0.2] - 2023-11-03 From f0eed1a306de3688591706d04c0bf701a0ea3422 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 11 Dec 2023 16:55:22 +0100 Subject: [PATCH 144/446] Update changelog for release 4.1.0 (#2694) Co-authored-by: Jeremy Mikola --- CHANGELOG.md | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a6086cd60..ec3ed4e4d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,26 @@ # Changelog All notable changes to this project will be documented in this file. -## [4.1.0] - unreleased - +## [4.1.0] - 2023-12-11 + +* PHPORM-100 Support query on numerical field names by [@GromNaN](https://github.com/GromNaN) in [#2642](https://github.com/mongodb/laravel-mongodb/pull/2642) +* Fix casting issue by [@hans-thomas](https://github.com/hans-thomas) in [#2653](https://github.com/mongodb/laravel-mongodb/pull/2653) +* Upgrade minimum Laravel version to 10.30 by [@GromNaN](https://github.com/GromNaN) in [#2665](https://github.com/mongodb/laravel-mongodb/pull/2665) +* Handling single model in sync method by [@hans-thomas](https://github.com/hans-thomas) in [#2648](https://github.com/mongodb/laravel-mongodb/pull/2648) +* BelongsToMany sync does't use configured keys by [@hans-thomas](https://github.com/hans-thomas) in [#2667](https://github.com/mongodb/laravel-mongodb/pull/2667) +* morphTo relationship by [@hans-thomas](https://github.com/hans-thomas) in [#2669](https://github.com/mongodb/laravel-mongodb/pull/2669) +* Datetime casting with custom format by [@hans-thomas](https://github.com/hans-thomas) in [#2658](https://github.com/mongodb/laravel-mongodb/pull/2658) +* PHPORM-106 Implement pagination for groupBy queries by [@GromNaN](https://github.com/GromNaN) in [#2672](https://github.com/mongodb/laravel-mongodb/pull/2672) +* Add method `Connection::ping()` to check server connection by [@hans-thomas](https://github.com/hans-thomas) in [#2677](https://github.com/mongodb/laravel-mongodb/pull/2677) +* PHPORM-119 Fix integration with Spatie Query Builder - Don't qualify field names in document models by [@GromNaN](https://github.com/GromNaN) in [#2676](https://github.com/mongodb/laravel-mongodb/pull/2676) +* Support renaming columns in migrations by [@hans-thomas](https://github.com/hans-thomas) in [#2682](https://github.com/mongodb/laravel-mongodb/pull/2682) +* Add MorphToMany support by [@hans-thomas](https://github.com/hans-thomas) in [#2670](https://github.com/mongodb/laravel-mongodb/pull/2670) +* PHPORM-6 Fix doc Builder::timeout applies to find query, not the cursor by [@GromNaN](https://github.com/GromNaN) in [#2681](https://github.com/mongodb/laravel-mongodb/pull/2681) +* Add test for the `$hidden` property by [@Treggats](https://github.com/Treggats) in [#2687](https://github.com/mongodb/laravel-mongodb/pull/2687) +* Update `push` and `pull` docs by [@hans-thomas](https://github.com/hans-thomas) in [#2685](https://github.com/mongodb/laravel-mongodb/pull/2685) +* Hybrid support for BelongsToMany relationship by [@hans-thomas](https://github.com/hans-thomas) in [#2688](https://github.com/mongodb/laravel-mongodb/pull/2688) +* Avoid unnecessary data fetch for exists method by [@andersonls](https://github.com/andersonls) in [#2692](https://github.com/mongodb/laravel-mongodb/pull/2692) +* Hybrid support for MorphToMany relationship by [@hans-thomas](https://github.com/hans-thomas) in [#2690](https://github.com/mongodb/laravel-mongodb/pull/2690) ## [4.0.2] - 2023-11-03 From 99e10287070a0d74c1aa3ad4457b2e69c59fc392 Mon Sep 17 00:00:00 2001 From: Mohammad Mortazavi <39920372+hans-thomas@users.noreply.github.com> Date: Wed, 13 Dec 2023 12:27:18 +0330 Subject: [PATCH 145/446] Fix BelongsToMany relationship bugs when using custom keys (#2695) --- src/Relations/BelongsToMany.php | 12 +- tests/Models/Client.php | 11 ++ tests/Models/Experience.php | 10 -- tests/RelationsTest.php | 228 ++++++++++++++++++++++++++++---- 4 files changed, 219 insertions(+), 42 deletions(-) diff --git a/src/Relations/BelongsToMany.php b/src/Relations/BelongsToMany.php index 082f95e06..8ff311f3f 100644 --- a/src/Relations/BelongsToMany.php +++ b/src/Relations/BelongsToMany.php @@ -183,13 +183,13 @@ public function attach($id, array $attributes = [], $touch = true) if ($id instanceof Model) { $model = $id; - $id = $model->getKey(); + $id = $this->parseId($model); // Attach the new parent id to the related model. - $model->push($this->foreignPivotKey, $this->parent->getKey(), true); + $model->push($this->foreignPivotKey, $this->parent->{$this->parentKey}, true); } else { if ($id instanceof Collection) { - $id = $id->modelKeys(); + $id = $this->parseIds($id); } $query = $this->newRelatedQuery(); @@ -221,7 +221,7 @@ public function attach($id, array $attributes = [], $touch = true) public function detach($ids = [], $touch = true) { if ($ids instanceof Model) { - $ids = (array) $ids->getKey(); + $ids = $this->parseIds($ids); } $query = $this->newRelatedQuery(); @@ -242,13 +242,13 @@ public function detach($ids = [], $touch = true) // Prepare the query to select all related objects. if (count($ids) > 0) { - $query->whereIn($this->related->getKeyName(), $ids); + $query->whereIn($this->relatedKey, $ids); } // Remove the relation to the parent. assert($this->parent instanceof Model); assert($query instanceof \MongoDB\Laravel\Eloquent\Builder); - $query->pull($this->foreignPivotKey, $this->parent->getKey()); + $query->pull($this->foreignPivotKey, $this->parent->{$this->parentKey}); if ($touch) { $this->touchIfTouching(); diff --git a/tests/Models/Client.php b/tests/Models/Client.php index 2ab4f5e33..4e7e7ecc9 100644 --- a/tests/Models/Client.php +++ b/tests/Models/Client.php @@ -20,6 +20,17 @@ public function users(): BelongsToMany return $this->belongsToMany(User::class); } + public function skillsWithCustomKeys() + { + return $this->belongsToMany( + Skill::class, + foreignPivotKey: 'cclient_ids', + relatedPivotKey: 'cskill_ids', + parentKey: 'cclient_id', + relatedKey: 'cskill_id', + ); + } + public function photo(): MorphOne { return $this->morphOne(Photo::class, 'has_image'); diff --git a/tests/Models/Experience.php b/tests/Models/Experience.php index 4c2869d9e..2852ece5f 100644 --- a/tests/Models/Experience.php +++ b/tests/Models/Experience.php @@ -15,16 +15,6 @@ class Experience extends Eloquent protected $casts = ['years' => 'int']; - public function skillsWithCustomRelatedKey() - { - return $this->belongsToMany(Skill::class, relatedKey: 'cskill_id'); - } - - public function skillsWithCustomParentKey() - { - return $this->belongsToMany(Skill::class, parentKey: 'cexperience_id'); - } - public function sqlUsers(): MorphToMany { return $this->morphToMany(SqlUser::class, 'experienced'); diff --git a/tests/RelationsTest.php b/tests/RelationsTest.php index 652f3d7bf..8c0a7a4a7 100644 --- a/tests/RelationsTest.php +++ b/tests/RelationsTest.php @@ -10,7 +10,6 @@ use MongoDB\Laravel\Tests\Models\Address; use MongoDB\Laravel\Tests\Models\Book; use MongoDB\Laravel\Tests\Models\Client; -use MongoDB\Laravel\Tests\Models\Experience; use MongoDB\Laravel\Tests\Models\Group; use MongoDB\Laravel\Tests\Models\Item; use MongoDB\Laravel\Tests\Models\Label; @@ -36,7 +35,6 @@ public function tearDown(): void Photo::truncate(); Label::truncate(); Skill::truncate(); - Experience::truncate(); } public function testHasMany(): void @@ -350,48 +348,226 @@ public function testBelongsToManyAttachEloquentCollection(): void $this->assertCount(2, $user->clients); } - public function testBelongsToManySyncEloquentCollectionWithCustomRelatedKey(): void + public function testBelongsToManySyncWithCustomKeys(): void { - $experience = Experience::create(['years' => '5']); + $client = Client::create(['cclient_id' => (string) (new ObjectId()), 'years' => '5']); + $skill1 = Skill::create(['cskill_id' => (string) (new ObjectId()), 'name' => 'PHP']); + $skill2 = Skill::create(['cskill_id' => (string) (new ObjectId()), 'name' => 'Laravel']); + + $client = Client::query()->find($client->_id); + $client->skillsWithCustomKeys()->sync([$skill1->cskill_id, $skill2->cskill_id]); + $this->assertCount(2, $client->skillsWithCustomKeys); + + self::assertIsString($skill1->cskill_id); + self::assertContains($skill1->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($skill1->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + + self::assertIsString($skill2->cskill_id); + self::assertContains($skill2->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($skill2->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + + $check = Skill::query()->find($skill1->_id); + self::assertIsString($check->cskill_id); + self::assertContains($check->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($check->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + + $check = Skill::query()->find($skill2->_id); + self::assertIsString($check->cskill_id); + self::assertContains($check->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($check->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + } + + public function testBelongsToManySyncModelWithCustomKeys(): void + { + $client = Client::create(['cclient_id' => (string) (new ObjectId()), 'years' => '5']); + $skill1 = Skill::create(['cskill_id' => (string) (new ObjectId()), 'name' => 'PHP']); + + $client = Client::query()->find($client->_id); + $client->skillsWithCustomKeys()->sync($skill1); + $this->assertCount(1, $client->skillsWithCustomKeys); + + self::assertIsString($skill1->cskill_id); + self::assertContains($skill1->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($skill1->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + + $check = Skill::query()->find($skill1->_id); + self::assertIsString($check->_id); + self::assertContains($check->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($check->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + } + + public function testBelongsToManySyncEloquentCollectionWithCustomKeys(): void + { + $client = Client::create(['cclient_id' => (string) (new ObjectId()), 'years' => '5']); $skill1 = Skill::create(['cskill_id' => (string) (new ObjectId()), 'name' => 'PHP']); $skill2 = Skill::create(['cskill_id' => (string) (new ObjectId()), 'name' => 'Laravel']); $collection = new Collection([$skill1, $skill2]); - $experience = Experience::query()->find($experience->id); - $experience->skillsWithCustomRelatedKey()->sync($collection); - $this->assertCount(2, $experience->skillsWithCustomRelatedKey); + $client = Client::query()->find($client->_id); + $client->skillsWithCustomKeys()->sync($collection); + $this->assertCount(2, $client->skillsWithCustomKeys); self::assertIsString($skill1->cskill_id); - self::assertContains($skill1->cskill_id, $experience->skillsWithCustomRelatedKey->pluck('cskill_id')); + self::assertContains($skill1->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($skill1->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); self::assertIsString($skill2->cskill_id); - self::assertContains($skill2->cskill_id, $experience->skillsWithCustomRelatedKey->pluck('cskill_id')); + self::assertContains($skill2->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($skill2->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + + $check = Skill::query()->find($skill1->_id); + self::assertIsString($check->cskill_id); + self::assertContains($check->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($check->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + + $check = Skill::query()->find($skill2->_id); + self::assertIsString($check->cskill_id); + self::assertContains($check->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($check->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + } + + public function testBelongsToManyAttachWithCustomKeys(): void + { + $client = Client::create(['cclient_id' => (string) (new ObjectId()), 'years' => '5']); + $skill1 = Skill::create(['cskill_id' => (string) (new ObjectId()), 'name' => 'PHP']); + $skill2 = Skill::create(['cskill_id' => (string) (new ObjectId()), 'name' => 'Laravel']); + + $client = Client::query()->find($client->_id); + $client->skillsWithCustomKeys()->attach([$skill1->cskill_id, $skill2->cskill_id]); + $this->assertCount(2, $client->skillsWithCustomKeys); + + self::assertIsString($skill1->cskill_id); + self::assertContains($skill1->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($skill1->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + + self::assertIsString($skill2->cskill_id); + self::assertContains($skill2->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($skill2->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + + $check = Skill::query()->find($skill1->_id); + self::assertIsString($check->cskill_id); + self::assertContains($check->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($check->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + + $check = Skill::query()->find($skill2->_id); + self::assertIsString($check->cskill_id); + self::assertContains($check->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($check->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + } + + public function testBelongsToManyAttachModelWithCustomKeys(): void + { + $client = Client::create(['cclient_id' => (string) (new ObjectId()), 'years' => '5']); + $skill1 = Skill::create(['cskill_id' => (string) (new ObjectId()), 'name' => 'PHP']); - $skill1->refresh(); - self::assertIsString($skill1->_id); - self::assertNotContains($skill1->_id, $experience->skillsWithCustomRelatedKey->pluck('cskill_id')); + $client = Client::query()->find($client->_id); + $client->skillsWithCustomKeys()->attach($skill1); + $this->assertCount(1, $client->skillsWithCustomKeys); + + self::assertIsString($skill1->cskill_id); + self::assertContains($skill1->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($skill1->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); - $skill2->refresh(); - self::assertIsString($skill2->_id); - self::assertNotContains($skill2->_id, $experience->skillsWithCustomRelatedKey->pluck('cskill_id')); + $check = Skill::query()->find($skill1->_id); + self::assertIsString($check->_id); + self::assertContains($check->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($check->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); } - public function testBelongsToManySyncEloquentCollectionWithCustomParentKey(): void + public function testBelongsToManyAttachEloquentCollectionWithCustomKeys(): void { - $experience = Experience::create(['cexperience_id' => (string) (new ObjectId()), 'years' => '5']); - $skill1 = Skill::create(['name' => 'PHP']); - $skill2 = Skill::create(['name' => 'Laravel']); + $client = Client::create(['cclient_id' => (string) (new ObjectId()), 'years' => '5']); + $skill1 = Skill::create(['cskill_id' => (string) (new ObjectId()), 'name' => 'PHP']); + $skill2 = Skill::create(['cskill_id' => (string) (new ObjectId()), 'name' => 'Laravel']); $collection = new Collection([$skill1, $skill2]); - $experience = Experience::query()->find($experience->id); - $experience->skillsWithCustomParentKey()->sync($collection); - $this->assertCount(2, $experience->skillsWithCustomParentKey); + $client = Client::query()->find($client->_id); + $client->skillsWithCustomKeys()->attach($collection); + $this->assertCount(2, $client->skillsWithCustomKeys); + + self::assertIsString($skill1->cskill_id); + self::assertContains($skill1->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($skill1->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + + self::assertIsString($skill2->cskill_id); + self::assertContains($skill2->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($skill2->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + + $check = Skill::query()->find($skill1->_id); + self::assertIsString($check->cskill_id); + self::assertContains($check->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($check->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + + $check = Skill::query()->find($skill2->_id); + self::assertIsString($check->cskill_id); + self::assertContains($check->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($check->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + } + + public function testBelongsToManyDetachWithCustomKeys(): void + { + $client = Client::create(['cclient_id' => (string) (new ObjectId()), 'years' => '5']); + $skill1 = Skill::create(['cskill_id' => (string) (new ObjectId()), 'name' => 'PHP']); + $skill2 = Skill::create(['cskill_id' => (string) (new ObjectId()), 'name' => 'Laravel']); + + $client = Client::query()->find($client->_id); + $client->skillsWithCustomKeys()->sync([$skill1->cskill_id, $skill2->cskill_id]); + $this->assertCount(2, $client->skillsWithCustomKeys); + + $client->skillsWithCustomKeys()->detach($skill1->cskill_id); + $client->load('skillsWithCustomKeys'); // Reload the relationship based on the latest pivot column's data + $this->assertCount(1, $client->skillsWithCustomKeys); + + self::assertIsString($skill1->cskill_id); + self::assertNotContains($skill1->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($skill1->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); - self::assertIsString($skill1->_id); - self::assertContains($skill1->_id, $experience->skillsWithCustomParentKey->pluck('_id')); + self::assertIsString($skill2->cskill_id); + self::assertContains($skill2->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($skill2->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + + $check = Skill::query()->find($skill1->_id); + self::assertIsString($check->cskill_id); + self::assertNotContains($check->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($check->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + + $check = Skill::query()->find($skill2->_id); + self::assertIsString($check->cskill_id); + self::assertContains($check->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($check->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + } - self::assertIsString($skill2->_id); - self::assertContains($skill2->_id, $experience->skillsWithCustomParentKey->pluck('_id')); + public function testBelongsToManyDetachModelWithCustomKeys(): void + { + $client = Client::create(['cclient_id' => (string) (new ObjectId()), 'years' => '5']); + $skill1 = Skill::create(['cskill_id' => (string) (new ObjectId()), 'name' => 'PHP']); + $skill2 = Skill::create(['cskill_id' => (string) (new ObjectId()), 'name' => 'Laravel']); + + $client = Client::query()->find($client->_id); + $client->skillsWithCustomKeys()->sync([$skill1->cskill_id, $skill2->cskill_id]); + $this->assertCount(2, $client->skillsWithCustomKeys); + + $client->skillsWithCustomKeys()->detach($skill1); + $client->load('skillsWithCustomKeys'); // Reload the relationship based on the latest pivot column's data + $this->assertCount(1, $client->skillsWithCustomKeys); + + self::assertIsString($skill1->cskill_id); + self::assertNotContains($skill1->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($skill1->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + + self::assertIsString($skill2->cskill_id); + self::assertContains($skill2->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($skill2->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + + $check = Skill::query()->find($skill1->_id); + self::assertIsString($check->cskill_id); + self::assertNotContains($check->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($check->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + + $check = Skill::query()->find($skill2->_id); + self::assertIsString($check->cskill_id); + self::assertContains($check->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($check->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); } public function testBelongsToManySyncAlreadyPresent(): void From f708c908ea3d0bedb45095b83008179fd76eb064 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Thu, 14 Dec 2023 13:53:13 +0100 Subject: [PATCH 146/446] Change release date --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ec3ed4e4d..66690e932 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,7 +1,7 @@ # Changelog All notable changes to this project will be documented in this file. -## [4.1.0] - 2023-12-11 +## [4.1.0] - 2023-12-14 * PHPORM-100 Support query on numerical field names by [@GromNaN](https://github.com/GromNaN) in [#2642](https://github.com/mongodb/laravel-mongodb/pull/2642) * Fix casting issue by [@hans-thomas](https://github.com/hans-thomas) in [#2653](https://github.com/mongodb/laravel-mongodb/pull/2653) From 634ea509a604da21d9fb2e5cfb49d9339d9b8ab3 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Fri, 12 Jan 2024 06:04:17 -0500 Subject: [PATCH 147/446] DOCSP-35148: Convert docs to Snooty RST (#2704) --- CHANGELOG.md | 2 + README.md | 14 +- docs/eloquent-models.md | 464 --------------------------- docs/eloquent-models.txt | 522 ++++++++++++++++++++++++++++++ docs/index.txt | 70 ++++ docs/install.md | 64 ---- docs/install.txt | 82 +++++ docs/query-builder.md | 602 ----------------------------------- docs/query-builder.txt | 568 +++++++++++++++++++++++++++++++++ docs/queues.md | 34 -- docs/queues.txt | 46 +++ docs/transactions.md | 56 ---- docs/transactions.txt | 79 +++++ docs/upgrade.md | 19 -- docs/upgrade.txt | 49 +++ docs/user-authentication.md | 15 - docs/user-authentication.txt | 24 ++ 17 files changed, 1449 insertions(+), 1261 deletions(-) delete mode 100644 docs/eloquent-models.md create mode 100644 docs/eloquent-models.txt create mode 100644 docs/index.txt delete mode 100644 docs/install.md create mode 100644 docs/install.txt delete mode 100644 docs/query-builder.md create mode 100644 docs/query-builder.txt delete mode 100644 docs/queues.md create mode 100644 docs/queues.txt delete mode 100644 docs/transactions.md create mode 100644 docs/transactions.txt delete mode 100644 docs/upgrade.md create mode 100644 docs/upgrade.txt delete mode 100644 docs/user-authentication.md create mode 100644 docs/user-authentication.txt diff --git a/CHANGELOG.md b/CHANGELOG.md index 66690e932..8e4d01e25 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,8 @@ # Changelog All notable changes to this project will be documented in this file. +* Move documentation to the mongodb.com domain at [https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/) + ## [4.1.0] - 2023-12-14 * PHPORM-100 Support query on numerical field names by [@GromNaN](https://github.com/GromNaN) in [#2642](https://github.com/mongodb/laravel-mongodb/pull/2642) diff --git a/README.md b/README.md index 60a48f725..71074ee62 100644 --- a/README.md +++ b/README.md @@ -12,13 +12,13 @@ This package was renamed to `mongodb/laravel-mongodb` because of a transfer of o It is compatible with Laravel 10.x. For older versions of Laravel, please refer to the [old versions](https://github.com/mongodb/laravel-mongodb/tree/3.9#laravel-version-compatibility). -- [Installation](docs/install.md) -- [Eloquent Models](docs/eloquent-models.md) -- [Query Builder](docs/query-builder.md) -- [Transactions](docs/transactions.md) -- [User Authentication](docs/user-authentication.md) -- [Queues](docs/queues.md) -- [Upgrading](docs/upgrade.md) +- [Installation](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/install/) +- [Eloquent Models](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/eloquent-models/) +- [Query Builder](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/query-builder/) +- [Transactions](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/transactions/) +- [User Authentication](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/user-authentication/) +- [Queues](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/queues/) +- [Upgrading](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/upgrade/) ## Reporting Issues diff --git a/docs/eloquent-models.md b/docs/eloquent-models.md deleted file mode 100644 index c64bb76b6..000000000 --- a/docs/eloquent-models.md +++ /dev/null @@ -1,464 +0,0 @@ -Eloquent Models -=============== - -Previous: [Installation and configuration](install.md) - -This package includes a MongoDB enabled Eloquent class that you can use to define models for corresponding collections. - -### Extending the base model - -To get started, create a new model class in your `app\Models\` directory. - -```php -namespace App\Models; - -use MongoDB\Laravel\Eloquent\Model; - -class Book extends Model -{ - // -} -``` - -Just like a normal model, the MongoDB model class will know which collection to use based on the model name. For `Book`, the collection `books` will be used. - -To change the collection, pass the `$collection` property: - -```php -use MongoDB\Laravel\Eloquent\Model; - -class Book extends Model -{ - protected $collection = 'my_books_collection'; -} -``` - -**NOTE:** MongoDB documents are automatically stored with a unique ID that is stored in the `_id` property. If you wish to use your own ID, substitute the `$primaryKey` property and set it to your own primary key attribute name. - -```php -use MongoDB\Laravel\Eloquent\Model; - -class Book extends Model -{ - protected $primaryKey = 'id'; -} - -// MongoDB will also create _id, but the 'id' property will be used for primary key actions like find(). -Book::create(['id' => 1, 'title' => 'The Fault in Our Stars']); -``` - -Likewise, you may define a `connection` property to override the name of the database connection that should be used when utilizing the model. - -```php -use MongoDB\Laravel\Eloquent\Model; - -class Book extends Model -{ - protected $connection = 'mongodb'; -} -``` - -### Soft Deletes - -When soft deleting a model, it is not actually removed from your database. Instead, a `deleted_at` timestamp is set on the record. - -To enable soft delete for a model, apply the `MongoDB\Laravel\Eloquent\SoftDeletes` Trait to the model: - -```php -use MongoDB\Laravel\Eloquent\SoftDeletes; - -class User extends Model -{ - use SoftDeletes; -} -``` - -For more information check [Laravel Docs about Soft Deleting](http://laravel.com/docs/eloquent#soft-deleting). - -### Prunable - -`Prunable` and `MassPrunable` traits are Laravel features to automatically remove models from your database. You can use -`Illuminate\Database\Eloquent\Prunable` trait to remove models one by one. If you want to remove models in bulk, you need -to use the `MongoDB\Laravel\Eloquent\MassPrunable` trait instead: it will be more performant but can break links with -other documents as it does not load the models. - -```php -use MongoDB\Laravel\Eloquent\Model; -use MongoDB\Laravel\Eloquent\MassPrunable; - -class Book extends Model -{ - use MassPrunable; -} -``` - -For more information check [Laravel Docs about Pruning Models](http://laravel.com/docs/eloquent#pruning-models). - -### Dates - -Eloquent allows you to work with Carbon or DateTime objects instead of MongoDate objects. Internally, these dates will be converted to MongoDate objects when saved to the database. - -```php -use MongoDB\Laravel\Eloquent\Model; - -class User extends Model -{ - protected $casts = ['birthday' => 'datetime']; -} -``` - -This allows you to execute queries like this: - -```php -$users = User::where( - 'birthday', '>', - new DateTime('-18 years') -)->get(); -``` - -### Extending the Authenticatable base model - -This package includes a MongoDB Authenticatable Eloquent class `MongoDB\Laravel\Auth\User` that you can use to replace the default Authenticatable class `Illuminate\Foundation\Auth\User` for your `User` model. - -```php -use MongoDB\Laravel\Auth\User as Authenticatable; - -class User extends Authenticatable -{ - -} -``` - -### Guarding attributes - -When choosing between guarding attributes or marking some as fillable, Taylor Otwell prefers the fillable route. -This is in light of [recent security issues described here](https://blog.laravel.com/security-release-laravel-61835-7240). - -Keep in mind guarding still works, but you may experience unexpected behavior. - -Schema ------- - -The database driver also has (limited) schema builder support. You can easily manipulate collections and set indexes. - -### Basic Usage - -```php -Schema::create('users', function ($collection) { - $collection->index('name'); - $collection->unique('email'); -}); -``` - -You can also pass all the parameters specified [in the MongoDB docs](https://docs.mongodb.com/manual/reference/method/db.collection.createIndex/#options-for-all-index-types) to the `$options` parameter: - -```php -Schema::create('users', function ($collection) { - $collection->index( - 'username', - null, - null, - [ - 'sparse' => true, - 'unique' => true, - 'background' => true, - ] - ); -}); -``` - -Inherited operations: - -- create and drop -- collection -- hasCollection -- index and dropIndex (compound indexes supported as well) -- unique - -MongoDB specific operations: - -- background -- sparse -- expire -- geospatial - -All other (unsupported) operations are implemented as dummy pass-through methods because MongoDB does not use a predefined schema. - -Read more about the schema builder on [Laravel Docs](https://laravel.com/docs/10.x/migrations#tables) - -### Geospatial indexes - -Geospatial indexes are handy for querying location-based documents. - -They come in two forms: `2d` and `2dsphere`. Use the schema builder to add these to a collection. - -```php -Schema::create('bars', function ($collection) { - $collection->geospatial('location', '2d'); -}); -``` - -To add a `2dsphere` index: - -```php -Schema::create('bars', function ($collection) { - $collection->geospatial('location', '2dsphere'); -}); -``` - -Relationships -------------- - -### Basic Usage - -The only available relationships are: - -- hasOne -- hasMany -- belongsTo -- belongsToMany - -The MongoDB-specific relationships are: - -- embedsOne -- embedsMany - -Here is a small example: - -```php -use MongoDB\Laravel\Eloquent\Model; - -class User extends Model -{ - public function items() - { - return $this->hasMany(Item::class); - } -} -``` - -The inverse relation of `hasMany` is `belongsTo`: - -```php -use MongoDB\Laravel\Eloquent\Model; - -class Item extends Model -{ - public function user() - { - return $this->belongsTo(User::class); - } -} -``` - -### belongsToMany and pivots - -The belongsToMany relation will not use a pivot "table" but will push id's to a __related_ids__ attribute instead. This makes the second parameter for the belongsToMany method useless. - -If you want to define custom keys for your relation, set it to `null`: - -```php -use MongoDB\Laravel\Eloquent\Model; - -class User extends Model -{ - public function groups() - { - return $this->belongsToMany( - Group::class, null, 'user_ids', 'group_ids' - ); - } -} -``` - -### EmbedsMany Relationship - -If you want to embed models, rather than referencing them, you can use the `embedsMany` relation. This relation is similar to the `hasMany` relation but embeds the models inside the parent object. - -**REMEMBER**: These relations return Eloquent collections, they don't return query builder objects! - -```php -use MongoDB\Laravel\Eloquent\Model; - -class User extends Model -{ - public function books() - { - return $this->embedsMany(Book::class); - } -} -``` - -You can access the embedded models through the dynamic property: - -```php -$user = User::first(); - -foreach ($user->books as $book) { - // -} -``` - -The inverse relation is auto*magically* available. You don't need to define this reverse relation. - -```php -$book = Book::first(); - -$user = $book->user; -``` - -Inserting and updating embedded models works similar to the `hasMany` relation: - -```php -$book = $user->books()->save( - new Book(['title' => 'A Game of Thrones']) -); - -// or -$book = - $user->books() - ->create(['title' => 'A Game of Thrones']); -``` - -You can update embedded models using their `save` method (available since release 2.0.0): - -```php -$book = $user->books()->first(); - -$book->title = 'A Game of Thrones'; -$book->save(); -``` - -You can remove an embedded model by using the `destroy` method on the relation, or the `delete` method on the model (available since release 2.0.0): - -```php -$book->delete(); - -// Similar operation -$user->books()->destroy($book); -``` - -If you want to add or remove an embedded model, without touching the database, you can use the `associate` and `dissociate` methods. - -To eventually write the changes to the database, save the parent object: - -```php -$user->books()->associate($book); -$user->save(); -``` - -Like other relations, embedsMany assumes the local key of the relationship based on the model name. You can override the default local key by passing a second argument to the embedsMany method: - -```php -use MongoDB\Laravel\Eloquent\Model; - -class User extends Model -{ - public function books() - { - return $this->embedsMany(Book::class, 'local_key'); - } -} -``` - -Embedded relations will return a Collection of embedded items instead of a query builder. Check out the available operations here: https://laravel.com/docs/master/collections - -### EmbedsOne Relationship - -The embedsOne relation is similar to the embedsMany relation, but only embeds a single model. - -```php -use MongoDB\Laravel\Eloquent\Model; - -class Book extends Model -{ - public function author() - { - return $this->embedsOne(Author::class); - } -} -``` - -You can access the embedded models through the dynamic property: - -```php -$book = Book::first(); -$author = $book->author; -``` - -Inserting and updating embedded models works similar to the `hasOne` relation: - -```php -$author = $book->author()->save( - new Author(['name' => 'John Doe']) -); - -// Similar -$author = - $book->author() - ->create(['name' => 'John Doe']); -``` - -You can update the embedded model using the `save` method (available since release 2.0.0): - -```php -$author = $book->author; - -$author->name = 'Jane Doe'; -$author->save(); -``` - -You can replace the embedded model with a new model like this: - -```php -$newAuthor = new Author(['name' => 'Jane Doe']); - -$book->author()->save($newAuthor); -``` - -Cross-Database Relationships ----------------------------- - -If you're using a hybrid MongoDB and SQL setup, you can define relationships across them. - -The model will automatically return a MongoDB-related or SQL-related relation based on the type of the related model. - -If you want this functionality to work both ways, your SQL-models will need to use the `MongoDB\Laravel\Eloquent\HybridRelations` trait. - -**This functionality only works for `hasOne`, `hasMany` and `belongsTo`.** - -The SQL model should use the `HybridRelations` trait: - -```php -use MongoDB\Laravel\Eloquent\HybridRelations; - -class User extends Model -{ - use HybridRelations; - - protected $connection = 'mysql'; - - public function messages() - { - return $this->hasMany(Message::class); - } -} -``` - -Within your MongoDB model, you should define the relationship: - -```php -use MongoDB\Laravel\Eloquent\Model; - -class Message extends Model -{ - protected $connection = 'mongodb'; - - public function user() - { - return $this->belongsTo(User::class); - } -} -``` - - diff --git a/docs/eloquent-models.txt b/docs/eloquent-models.txt new file mode 100644 index 000000000..d10822c37 --- /dev/null +++ b/docs/eloquent-models.txt @@ -0,0 +1,522 @@ +.. _laravel-eloquent-models: + +=============== +Eloquent Models +=============== + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :keywords: php framework, odm, code example + +This package includes a MongoDB enabled Eloquent class that you can use to +define models for corresponding collections. + +Extending the base model +~~~~~~~~~~~~~~~~~~~~~~~~ + +To get started, create a new model class in your ``app\Models\`` directory. + +.. code-block:: php + + namespace App\Models; + + use MongoDB\Laravel\Eloquent\Model; + + class Book extends Model + { + // + } + +Just like a regular model, the MongoDB model class will know which collection +to use based on the model name. For ``Book``, the collection ``books`` will +be used. + +To change the collection, pass the ``$collection`` property: + +.. code-block:: php + + use MongoDB\Laravel\Eloquent\Model; + + class Book extends Model + { + protected $collection = 'my_books_collection'; + } + +.. note:: + + MongoDB documents are automatically stored with a unique ID that is stored + in the ``_id`` property. If you wish to use your own ID, substitute the + ``$primaryKey`` property and set it to your own primary key attribute name. + +.. code-block:: php + + use MongoDB\Laravel\Eloquent\Model; + + class Book extends Model + { + protected $primaryKey = 'id'; + } + + // MongoDB will also create _id, but the 'id' property will be used for primary key actions like find(). + Book::create(['id' => 1, 'title' => 'The Fault in Our Stars']); + +Likewise, you may define a ``connection`` property to override the name of the +database connection to reference the model. + +.. code-block:: php + + use MongoDB\Laravel\Eloquent\Model; + + class Book extends Model + { + protected $connection = 'mongodb'; + } + +Soft Deletes +~~~~~~~~~~~~ + +When soft deleting a model, it is not actually removed from your database. +Instead, a ``deleted_at`` timestamp is set on the record. + +To enable soft delete for a model, apply the ``MongoDB\Laravel\Eloquent\SoftDeletes`` +Trait to the model: + +.. code-block:: php + + use MongoDB\Laravel\Eloquent\SoftDeletes; + + class User extends Model + { + use SoftDeletes; + } + +For more information check `Laravel Docs about Soft Deleting `__. + +Prunable +~~~~~~~~ + +``Prunable`` and ``MassPrunable`` traits are Laravel features to automatically +remove models from your database. You can use ``Illuminate\Database\Eloquent\Prunable`` +trait to remove models one by one. If you want to remove models in bulk, you +must use the ``MongoDB\Laravel\Eloquent\MassPrunable`` trait instead: it +will be more performant but can break links with other documents as it does +not load the models. + +.. code-block:: php + + use MongoDB\Laravel\Eloquent\Model; + use MongoDB\Laravel\Eloquent\MassPrunable; + + class Book extends Model + { + use MassPrunable; + } + +For more information check `Laravel Docs about Pruning Models `__. + +Dates +~~~~~ + +Eloquent allows you to work with Carbon or DateTime objects instead of MongoDate objects. Internally, these dates will be converted to MongoDate objects when saved to the database. + +.. code-block:: php + + use MongoDB\Laravel\Eloquent\Model; + + class User extends Model + { + protected $casts = ['birthday' => 'datetime']; + } + +This allows you to execute queries like this: + +.. code-block:: php + + $users = User::where( + 'birthday', '>', + new DateTime('-18 years') + )->get(); + +Extending the Authenticatable base model +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This package includes a MongoDB Authenticatable Eloquent class ``MongoDB\Laravel\Auth\User`` +that you can use to replace the default Authenticatable class ``Illuminate\Foundation\Auth\User`` +for your ``User`` model. + +.. code-block:: php + + use MongoDB\Laravel\Auth\User as Authenticatable; + + class User extends Authenticatable + { + + } + +Guarding attributes +~~~~~~~~~~~~~~~~~~~ + +When choosing between guarding attributes or marking some as fillable, Taylor +Otwell prefers the fillable route. This is in light of +`recent security issues described here `__. + +Keep in mind guarding still works, but you may experience unexpected behavior. + +Schema +------ + +The database driver also has (limited) schema builder support. You can +conveniently manipulate collections and set indexes. + +Basic Usage +~~~~~~~~~~~ + +.. code-block:: php + + Schema::create('users', function ($collection) { + $collection->index('name'); + $collection->unique('email'); + }); + +You can also pass all the parameters specified :manual:`in the MongoDB docs ` +to the ``$options`` parameter: + +.. code-block:: php + + Schema::create('users', function ($collection) { + $collection->index( + 'username', + null, + null, + [ + 'sparse' => true, + 'unique' => true, + 'background' => true, + ] + ); + }); + +Inherited operations: + + +* create and drop +* collection +* hasCollection +* index and dropIndex (compound indexes supported as well) +* unique + +MongoDB specific operations: + + +* background +* sparse +* expire +* geospatial + +All other (unsupported) operations are implemented as dummy pass-through +methods because MongoDB does not use a predefined schema. + +Read more about the schema builder on `Laravel Docs `__ + +Geospatial indexes +~~~~~~~~~~~~~~~~~~ + +Geospatial indexes can improve query performance of location-based documents. + +They come in two forms: ``2d`` and ``2dsphere``. Use the schema builder to add +these to a collection. + +.. code-block:: php + + Schema::create('bars', function ($collection) { + $collection->geospatial('location', '2d'); + }); + +To add a ``2dsphere`` index: + +.. code-block:: php + + Schema::create('bars', function ($collection) { + $collection->geospatial('location', '2dsphere'); + }); + +Relationships +------------- + +Basic Usage +~~~~~~~~~~~ + +The only available relationships are: + + +* hasOne +* hasMany +* belongsTo +* belongsToMany + +The MongoDB-specific relationships are: + + +* embedsOne +* embedsMany + +Here is a small example: + +.. code-block:: php + + use MongoDB\Laravel\Eloquent\Model; + + class User extends Model + { + public function items() + { + return $this->hasMany(Item::class); + } + } + +The inverse relation of ``hasMany`` is ``belongsTo``: + +.. code-block:: php + + use MongoDB\Laravel\Eloquent\Model; + + class Item extends Model + { + public function user() + { + return $this->belongsTo(User::class); + } + } + +belongsToMany and pivots +~~~~~~~~~~~~~~~~~~~~~~~~ + +The belongsToMany relation will not use a pivot "table" but will push id's to +a **related_ids** attribute instead. This makes the second parameter for the +belongsToMany method useless. + +If you want to define custom keys for your relation, set it to ``null``: + +.. code-block:: php + + use MongoDB\Laravel\Eloquent\Model; + + class User extends Model + { + public function groups() + { + return $this->belongsToMany( + Group::class, null, 'user_ids', 'group_ids' + ); + } + } + +EmbedsMany Relationship +~~~~~~~~~~~~~~~~~~~~~~~ + +If you want to embed models, rather than referencing them, you can use the +``embedsMany`` relation. This relation is similar to the ``hasMany`` relation +but embeds the models inside the parent object. + +**REMEMBER**\ : These relations return Eloquent collections, they don't return +query builder objects! + +.. code-block:: php + + use MongoDB\Laravel\Eloquent\Model; + + class User extends Model + { + public function books() + { + return $this->embedsMany(Book::class); + } + } + +You can access the embedded models through the dynamic property: + +.. code-block:: php + + $user = User::first(); + + foreach ($user->books as $book) { + // + } + +The inverse relation is auto *magically* available. You can omit the reverse +relation definition. + +.. code-block:: php + + $book = Book::first(); + + $user = $book->user; + +Inserting and updating embedded models works similar to the ``hasMany`` relation: + +.. code-block:: php + + $book = $user->books()->save( + new Book(['title' => 'A Game of Thrones']) + ); + + // or + $book = + $user->books() + ->create(['title' => 'A Game of Thrones']); + +You can update embedded models using their ``save`` method (available since +release 2.0.0): + +.. code-block:: php + + $book = $user->books()->first(); + + $book->title = 'A Game of Thrones'; + $book->save(); + +You can remove an embedded model by using the ``destroy`` method on the +relation, or the ``delete`` method on the model (available since release 2.0.0): + +.. code-block:: php + + $book->delete(); + + // Similar operation + $user->books()->destroy($book); + +If you want to add or remove an embedded model, without touching the database, +you can use the ``associate`` and ``dissociate`` methods. + +To eventually write the changes to the database, save the parent object: + +.. code-block:: php + + $user->books()->associate($book); + $user->save(); + +Like other relations, embedsMany assumes the local key of the relationship +based on the model name. You can override the default local key by passing a +second argument to the embedsMany method: + +.. code-block:: php + + use MongoDB\Laravel\Eloquent\Model; + + class User extends Model + { + public function books() + { + return $this->embedsMany(Book::class, 'local_key'); + } + } + +Embedded relations will return a Collection of embedded items instead of a +query builder. Check out the available operations here: +`https://laravel.com/docs/master/collections `__ + +EmbedsOne Relationship +~~~~~~~~~~~~~~~~~~~~~~ + +The embedsOne relation is similar to the embedsMany relation, but only embeds a single model. + +.. code-block:: php + + use MongoDB\Laravel\Eloquent\Model; + + class Book extends Model + { + public function author() + { + return $this->embedsOne(Author::class); + } + } + +You can access the embedded models through the dynamic property: + +.. code-block:: php + + $book = Book::first(); + $author = $book->author; + +Inserting and updating embedded models works similar to the ``hasOne`` relation: + +.. code-block:: php + + $author = $book->author()->save( + new Author(['name' => 'John Doe']) + ); + + // Similar + $author = + $book->author() + ->create(['name' => 'John Doe']); + +You can update the embedded model using the ``save`` method (available since +release 2.0.0): + +.. code-block:: php + + $author = $book->author; + + $author->name = 'Jane Doe'; + $author->save(); + +You can replace the embedded model with a new model like this: + +.. code-block:: php + + $newAuthor = new Author(['name' => 'Jane Doe']); + + $book->author()->save($newAuthor); + +Cross-Database Relationships +---------------------------- + +If you're using a hybrid MongoDB and SQL setup, you can define relationships +across them. + +The model will automatically return a MongoDB-related or SQL-related relation +based on the type of the related model. + +If you want this functionality to work both ways, your SQL-models will need +to use the ``MongoDB\Laravel\Eloquent\HybridRelations`` trait. + +**This functionality only works for ``hasOne``, ``hasMany`` and ``belongsTo``.** + +The SQL model must use the ``HybridRelations`` trait: + +.. code-block:: php + + use MongoDB\Laravel\Eloquent\HybridRelations; + + class User extends Model + { + use HybridRelations; + + protected $connection = 'mysql'; + + public function messages() + { + return $this->hasMany(Message::class); + } + } + +Within your MongoDB model, you must define the following relationship: + +.. code-block:: php + + use MongoDB\Laravel\Eloquent\Model; + + class Message extends Model + { + protected $connection = 'mongodb'; + + public function user() + { + return $this->belongsTo(User::class); + } + } diff --git a/docs/index.txt b/docs/index.txt new file mode 100644 index 000000000..e58ba3532 --- /dev/null +++ b/docs/index.txt @@ -0,0 +1,70 @@ +=============== +Laravel MongoDB +=============== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: php framework, odm + +This package adds functionalities to the Eloquent model and Query builder for +MongoDB, using the original Laravel API. +*This library extends the original Laravel classes, so it uses exactly the +same methods.* + +This package was renamed to ``mongodb/laravel-mongodb`` because of a transfer +of ownership to MongoDB, Inc. It is compatible with Laravel 10.x. For older +versions of Laravel, please see the `old versions `__. + +- :ref:`laravel-install` +- :ref:`laravel-eloquent-models` +- :ref:`laravel-query-builder` +- :ref:`laravel-user-authentication` +- :ref:`laravel-queues` +- :ref:`laravel-transactions` +- :ref:`laravel-upgrading` + +Reporting Issues +---------------- + +Think you’ve found a bug in the library? Want to see a new feature? Please open a case in our issue management tool, JIRA: + +- `Create an account and login `__ +- Navigate to the `PHPORM `__ project. +- Click Create +- Please provide as much information as possible about the issue type and how to reproduce it. + +Note: All reported issues in JIRA project are public. + +For general questions and support requests, please use one of MongoDB's +:manual:`Technical Support ` channels. + +Security Vulnerabilities +~~~~~~~~~~~~~~~~~~~~~~~~ + +If you've identified a security vulnerability in a driver or any other MongoDB +project, please report it according to the instructions in +:manual:`Create a Vulnerability Report `. + + +Development +----------- + +Development is tracked in the `PHPORM `__ +project in MongoDB's JIRA. Documentation for contributing to this project may +be found in `CONTRIBUTING.md `__. + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /install + /eloquent-models + /query-builder + /user-authentication + /queues + /transactions + /upgrade + diff --git a/docs/install.md b/docs/install.md deleted file mode 100644 index d09628fec..000000000 --- a/docs/install.md +++ /dev/null @@ -1,64 +0,0 @@ -Getting Started -=============== - -Installation ------------- - -Make sure you have the MongoDB PHP driver installed. You can find installation instructions at https://php.net/manual/en/mongodb.installation.php - -Install the package via Composer: - -```bash -$ composer require mongodb/laravel-mongodb -``` - -In case your Laravel version does NOT autoload the packages, add the service provider to `config/app.php`: - -```php -'providers' => [ - // ... - MongoDB\Laravel\MongoDBServiceProvider::class, -], -``` - -Configuration -------------- - -To configure a new MongoDB connection, add a new connection entry to `config/database.php`: - -```php -'default' => env('DB_CONNECTION', 'mongodb'), - -'connections' => [ - 'mongodb' => [ - 'driver' => 'mongodb', - 'dsn' => env('DB_DSN'), - 'database' => env('DB_DATABASE', 'homestead'), - ], - // ... -], -``` - -The `dsn` key contains the connection string used to connect to your MongoDB deployment. The format and available options are documented in the [MongoDB documentation](https://docs.mongodb.com/manual/reference/connection-string/). - -Instead of using a connection string, you can also use the `host` and `port` configuration options to have the connection string created for you. - -```php -'connections' => [ - 'mongodb' => [ - 'driver' => 'mongodb', - 'host' => env('DB_HOST', '127.0.0.1'), - 'port' => env('DB_PORT', 27017), - 'database' => env('DB_DATABASE', 'homestead'), - 'username' => env('DB_USERNAME', 'homestead'), - 'password' => env('DB_PASSWORD', 'secret'), - 'options' => [ - 'appname' => 'homestead', - ], - ], -], -``` - -The `options` key in the connection configuration corresponds to the [`uriOptions` parameter](https://www.php.net/manual/en/mongodb-driver-manager.construct.php#mongodb-driver-manager.construct-urioptions). - -You are ready to [create your first MongoDB model](eloquent-models.md). diff --git a/docs/install.txt b/docs/install.txt new file mode 100644 index 000000000..795dbcff0 --- /dev/null +++ b/docs/install.txt @@ -0,0 +1,82 @@ +.. _laravel-install: + +=============== +Getting Started +=============== + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :keywords: php framework, odm, code example + +Installation +------------ + +Make sure you have the MongoDB PHP driver installed. You can find installation +instructions at `https://php.net/manual/en/mongodb.installation.php `__. + +Install the package by using Composer: + +.. code-block:: bash + + $ composer require mongodb/laravel-mongodb + +In case your Laravel version does NOT autoload the packages, add the service +provider to ``config/app.php``: + +.. code-block:: php + + 'providers' => [ + // ... + MongoDB\Laravel\MongoDBServiceProvider::class, + ], + +Configuration +------------- + +To configure a new MongoDB connection, add a new connection entry +to ``config/database.php``: + +.. code-block:: php + + 'default' => env('DB_CONNECTION', 'mongodb'), + + 'connections' => [ + 'mongodb' => [ + 'driver' => 'mongodb', + 'dsn' => env('DB_DSN'), + 'database' => env('DB_DATABASE', 'homestead'), + ], + // ... + ], + +The ``dsn`` key contains the connection string used to connect to your MongoDB +deployment. The format and available options are documented in the +:manual:`MongoDB documentation `. + +Instead of using a connection string, you can also use the ``host`` and +``port`` configuration options to have the connection string created for you. + +.. code-block:: php + + 'connections' => [ + 'mongodb' => [ + 'driver' => 'mongodb', + 'host' => env('DB_HOST', '127.0.0.1'), + 'port' => env('DB_PORT', 27017), + 'database' => env('DB_DATABASE', 'homestead'), + 'username' => env('DB_USERNAME', 'homestead'), + 'password' => env('DB_PASSWORD', 'secret'), + 'options' => [ + 'appname' => 'homestead', + ], + ], + ], + +The ``options`` key in the connection configuration corresponds to the +`uriOptions `__ +parameter. + +You are ready to :ref:`create your first MongoDB model `. diff --git a/docs/query-builder.md b/docs/query-builder.md deleted file mode 100644 index 4438e889c..000000000 --- a/docs/query-builder.md +++ /dev/null @@ -1,602 +0,0 @@ -Query Builder -============= - -The database driver plugs right into the original query builder. - -When using MongoDB connections, you will be able to build fluent queries to perform database operations. - -For your convenience, there is a `collection` alias for `table` as well as some additional MongoDB specific operators/operations. - -```php -$books = DB::collection('books')->get(); - -$hungerGames = - DB::collection('books') - ->where('name', 'Hunger Games') - ->first(); -``` - -If you are familiar with [Eloquent Queries](http://laravel.com/docs/queries), there is the same functionality. - -Available operations --------------------- - -**Retrieving all models** - -```php -$users = User::all(); -``` - -**Retrieving a record by primary key** - -```php -$user = User::find('517c43667db388101e00000f'); -``` - -**Where** - -```php -$posts = - Post::where('author.name', 'John') - ->take(10) - ->get(); -``` - -**OR Statements** - -```php -$posts = - Post::where('votes', '>', 0) - ->orWhere('is_approved', true) - ->get(); -``` - -**AND statements** - -```php -$users = - User::where('age', '>', 18) - ->where('name', '!=', 'John') - ->get(); -``` - -**NOT statements** - -```php -$users = User::whereNot('age', '>', 18)->get(); -``` - -**whereIn** - -```php -$users = User::whereIn('age', [16, 18, 20])->get(); -``` - -When using `whereNotIn` objects will be returned if the field is non-existent. Combine with `whereNotNull('age')` to leave out those documents. - -**whereBetween** - -```php -$posts = Post::whereBetween('votes', [1, 100])->get(); -``` - -**whereNull** - -```php -$users = User::whereNull('age')->get(); -``` - -**whereDate** - -```php -$users = User::whereDate('birthday', '2021-5-12')->get(); -``` - -The usage is the same as `whereMonth` / `whereDay` / `whereYear` / `whereTime` - -**Advanced wheres** - -```php -$users = - User::where('name', 'John') - ->orWhere(function ($query) { - return $query - ->where('votes', '>', 100) - ->where('title', '<>', 'Admin'); - })->get(); -``` - -**orderBy** - -```php -$users = User::orderBy('age', 'desc')->get(); -``` - -**Offset & Limit (skip & take)** - -```php -$users = - User::skip(10) - ->take(5) - ->get(); -``` - -**groupBy** - -Selected columns that are not grouped will be aggregated with the `$last` function. - -```php -$users = - Users::groupBy('title') - ->get(['title', 'name']); -``` - -**Distinct** - -Distinct requires a field for which to return the distinct values. - -```php -$users = User::distinct()->get(['name']); - -// Equivalent to: -$users = User::distinct('name')->get(); -``` - -Distinct can be combined with **where**: - -```php -$users = - User::where('active', true) - ->distinct('name') - ->get(); -``` - -**Like** - -```php -$spamComments = Comment::where('body', 'like', '%spam%')->get(); -``` - -**Aggregation** - -**Aggregations are only available for MongoDB versions greater than 2.2.x** - -```php -$total = Product::count(); -$price = Product::max('price'); -$price = Product::min('price'); -$price = Product::avg('price'); -$total = Product::sum('price'); -``` - -Aggregations can be combined with **where**: - -```php -$sold = Orders::where('sold', true)->sum('price'); -``` - -Aggregations can be also used on sub-documents: - -```php -$total = Order::max('suborder.price'); -``` - -**NOTE**: This aggregation only works with single sub-documents (like `EmbedsOne`) not subdocument arrays (like `EmbedsMany`). - -**Incrementing/Decrementing the value of a column** - -Perform increments or decrements (default 1) on specified attributes: - -```php -Cat::where('name', 'Kitty')->increment('age'); - -Car::where('name', 'Toyota')->decrement('weight', 50); -``` - -The number of updated objects is returned: - -```php -$count = User::increment('age'); -``` - -You may also specify additional columns to update: - -```php -Cat::where('age', 3) - ->increment('age', 1, ['group' => 'Kitty Club']); - -Car::where('weight', 300) - ->decrement('weight', 100, ['latest_change' => 'carbon fiber']); -``` - -### MongoDB-specific operators - -In addition to the Laravel Eloquent operators, all available MongoDB query operators can be used with `where`: - -```php -User::where($fieldName, $operator, $value)->get(); -``` - -It generates the following MongoDB filter: -```ts -{ $fieldName: { $operator: $value } } -``` - -**Exists** - -Matches documents that have the specified field. - -```php -User::where('age', 'exists', true)->get(); -``` - -**All** - -Matches arrays that contain all elements specified in the query. - -```php -User::where('roles', 'all', ['moderator', 'author'])->get(); -``` - -**Size** - -Selects documents if the array field is a specified size. - -```php -Post::where('tags', 'size', 3)->get(); -``` - -**Regex** - -Selects documents where values match a specified regular expression. - -```php -use MongoDB\BSON\Regex; - -User::where('name', 'regex', new Regex('.*doe', 'i'))->get(); -``` - -**NOTE:** you can also use the Laravel regexp operations. These will automatically convert your regular expression string to a `MongoDB\BSON\Regex` object. - -```php -User::where('name', 'regexp', '/.*doe/i')->get(); -``` - -The inverse of regexp: - -```php -User::where('name', 'not regexp', '/.*doe/i')->get(); -``` - -**Type** - -Selects documents if a field is of the specified type. For more information check: http://docs.mongodb.org/manual/reference/operator/query/type/#op._S_type - -```php -User::where('age', 'type', 2)->get(); -``` - -**Mod** - -Performs a modulo operation on the value of a field and selects documents with a specified result. - -```php -User::where('age', 'mod', [10, 0])->get(); -``` - -### MongoDB-specific Geo operations - -**Near** - -```php -$bars = Bar::where('location', 'near', [ - '$geometry' => [ - 'type' => 'Point', - 'coordinates' => [ - -0.1367563, // longitude - 51.5100913, // latitude - ], - ], - '$maxDistance' => 50, -])->get(); -``` - -**GeoWithin** - -```php -$bars = Bar::where('location', 'geoWithin', [ - '$geometry' => [ - 'type' => 'Polygon', - 'coordinates' => [ - [ - [-0.1450383, 51.5069158], - [-0.1367563, 51.5100913], - [-0.1270247, 51.5013233], - [-0.1450383, 51.5069158], - ], - ], - ], -])->get(); -``` - -**GeoIntersects** - -```php -$bars = Bar::where('location', 'geoIntersects', [ - '$geometry' => [ - 'type' => 'LineString', - 'coordinates' => [ - [-0.144044, 51.515215], - [-0.129545, 51.507864], - ], - ], -])->get(); -``` - -**GeoNear** - -You are able to make a `geoNear` query on mongoDB. -You don't need to specify the automatic fields on the model. -The returned instance is a collection. So you're able to make the [Collection](https://laravel.com/docs/9.x/collections) operations. -Just make sure that your model has a `location` field, and a [2ndSphereIndex](https://www.mongodb.com/docs/manual/core/2dsphere). -The data in the `location` field must be saved as [GeoJSON](https://www.mongodb.com/docs/manual/reference/geojson/). -The `location` points must be saved as [WGS84](https://www.mongodb.com/docs/manual/reference/glossary/#std-term-WGS84) reference system for geometry calculation. That means, basically, you need to save `longitude and latitude`, in that order specifically, and to find near with calculated distance, you `need to do the same way`. - -``` -Bar::find("63a0cd574d08564f330ceae2")->update( - [ - 'location' => [ - 'type' => 'Point', - 'coordinates' => [ - -0.1367563, - 51.5100913 - ] - ] - ] -); -$bars = Bar::raw(function ($collection) { - return $collection->aggregate([ - [ - '$geoNear' => [ - "near" => [ "type" => "Point", "coordinates" => [-0.132239, 51.511874] ], - "distanceField" => "dist.calculated", - "minDistance" => 0, - "maxDistance" => 6000, - "includeLocs" => "dist.location", - "spherical" => true, - ] - ] - ]); -}); -``` - -### Inserts, updates and deletes - -Inserting, updating and deleting records works just like the original Eloquent. Please check [Laravel Docs' Eloquent section](https://laravel.com/docs/6.x/eloquent). - -Here, only the MongoDB-specific operations are specified. - -### MongoDB specific operations - -**Raw Expressions** - -These expressions will be injected directly into the query. - -```php -User::whereRaw([ - 'age' => ['$gt' => 30, '$lt' => 40], -])->get(); - -User::whereRaw([ - '$where' => '/.*123.*/.test(this.field)', -])->get(); - -User::whereRaw([ - '$where' => '/.*123.*/.test(this["hyphenated-field"])', -])->get(); -``` - -You can also perform raw expressions on the internal MongoCollection object. If this is executed on the model class, it will return a collection of models. - -If this is executed on the query builder, it will return the original response. - -**Cursor timeout** - -To prevent `MongoCursorTimeout` exceptions, you can manually set a timeout value that will be applied to the cursor: - -```php -DB::collection('users')->timeout(-1)->get(); -``` - -**Upsert** - -Update or insert a document. Additional options for the update method are passed directly to the native update method. - -```php -// Query Builder -DB::collection('users') - ->where('name', 'John') - ->update($data, ['upsert' => true]); - -// Eloquent -$user->update($data, ['upsert' => true]); -``` - -**Projections** - -You can apply projections to your queries using the `project` method. - -```php -DB::collection('items') - ->project(['tags' => ['$slice' => 1]]) - ->get(); - -DB::collection('items') - ->project(['tags' => ['$slice' => [3, 7]]]) - ->get(); -``` - -**Projections with Pagination** - -```php -$limit = 25; -$projections = ['id', 'name']; - -DB::collection('items') - ->paginate($limit, $projections); -``` - -**Push** - -Add one or multiple values to the `items` array. - -```php -// Push the value to the matched documents -DB::collection('users') - ->where('name', 'John') - // Push a single value to the items array - ->push('items', 'boots'); -// Result: -// items: ['boots'] - -DB::collection('users') - ->where('name', 'John') - // Push multiple values to the items array - ->push('items', ['hat', 'jeans']); -// Result: -// items: ['boots', 'hat', 'jeans'] - -// Or - -// Push the values directly to a model object -$user->push('items', 'boots'); -$user->push('items', ['hat', 'jeans']); -``` - -To add embedded document or array values to the `messages` array, those values must be specified within a list array. - -```php -DB::collection('users') - ->where('name', 'John') - // Push an embedded document as a value to the messages array - ->push('messages', [ - [ 'from' => 'Jane Doe', 'message' => 'Hi John' ] - ]); -// Result: -// messages: [ -// { from: "Jane Doe", message: "Hi John" } -// ] - -// Or - -$user->push('messages', [ - [ 'from' => 'Jane Doe', 'message' => 'Hi John' ] -]); -``` - -If you **DON'T** want duplicate values, set the third parameter to `true`: - -```php -DB::collection('users') - ->where('name', 'John') - ->push('items', 'boots'); -// Result: -// items: ['boots'] - -DB::collection('users') - ->where('name', 'John') - ->push('items', ['hat', 'boots', 'jeans'], true); -// Result: -// items: ['boots', 'hat', 'jeans'] - -// Or - -$user->push('messages', [ - [ 'from' => 'Jane Doe', 'message' => 'Hi John' ] -]); -// Result: -// messages: [ -// { from: "Jane Doe", message: "Hi John" } -// ] - -$user->push('messages', [ - [ 'from' => 'Jess Doe', 'message' => 'Hi' ], - [ 'from' => 'Jane Doe', 'message' => 'Hi John' ], -], true); -// Result: -// messages: [ -// { from: "Jane Doe", message: "Hi John" } -// { from: "Jess Doe", message: "Hi" } -// ] -``` - -**Pull** - -Remove one or multiple values from the `items` array. - -```php -// items: ['boots', 'hat', 'jeans'] - -DB::collection('users') - ->where('name', 'John') - ->pull('items', 'boots'); // Pull a single value -// Result: -// items: ['hat', 'jeans'] - -// Or pull multiple values - -$user->pull('items', ['boots', 'jeans']); -// Result: -// items: ['hat'] -``` - -Embedded document and arrays values can also be removed from the `messages` array. - -```php -// Latest state: -// messages: [ -// { from: "Jane Doe", message: "Hi John" } -// { from: "Jess Doe", message: "Hi" } -// ] - -DB::collection('users') - ->where('name', 'John') - // Pull an embedded document from the array - ->pull('messages', [ - [ 'from' => 'Jane Doe', 'message' => 'Hi John' ] - ]); -// Result: -// messages: [ -// { from: "Jess Doe", message: "Hi" } -// ] - -// Or pull multiple embedded documents - -$user->pull('messages', [ - [ 'from' => 'Jane Doe', 'message' => 'Hi John' ], - [ 'from' => 'Jess Doe', 'message' => 'Hi' ] -]); -// Result: -// messages: [ ] -``` - -**Unset** - -Remove one or more fields from a document. - -```php -DB::collection('users') - ->where('name', 'John') - ->unset('note'); - -$user->unset('note'); - -$user->save(); -``` - -Using the native `unset` on models will work as well: - -```php -unset($user['note']); -unset($user->node); -``` diff --git a/docs/query-builder.txt b/docs/query-builder.txt new file mode 100644 index 000000000..40d2b9634 --- /dev/null +++ b/docs/query-builder.txt @@ -0,0 +1,568 @@ +.. _laravel-query-builder: + +============= +Query Builder +============= + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :keywords: php framework, odm, code example + +The database driver plugs right into the original query builder. + +When using MongoDB connections, you will be able to build fluent queries to +perform database operations. + +For your convenience, there is a ``collection`` alias for ``table`` and +other MongoDB specific operators/operations. + +.. code-block:: php + + $books = DB::collection('books')->get(); + + $hungerGames = + DB::collection('books') + ->where('name', 'Hunger Games') + ->first(); + +If you are familiar with `Eloquent Queries `__, +there is the same functionality. + +Available operations +-------------------- + +**Retrieving all models** + +.. code-block:: php + + $users = User::all(); + +**Retrieving a record by primary key** + +.. code-block:: php + + $user = User::find('517c43667db388101e00000f'); + +**Where** + +.. code-block:: php + + $posts = + Post::where('author.name', 'John') + ->take(10) + ->get(); + +**OR Statements** + +.. code-block:: php + + $posts = + Post::where('votes', '>', 0) + ->orWhere('is_approved', true) + ->get(); + +**AND statements** + +.. code-block:: php + + $users = + User::where('age', '>', 18) + ->where('name', '!=', 'John') + ->get(); + +**NOT statements** + +.. code-block:: php + + $users = User::whereNot('age', '>', 18)->get(); + +**whereIn** + +.. code-block:: php + + $users = User::whereIn('age', [16, 18, 20])->get(); + +When using ``whereNotIn`` objects will be returned if the field is +non-existent. Combine with ``whereNotNull('age')`` to omit those documents. + +**whereBetween** + +.. code-block:: php + + $posts = Post::whereBetween('votes', [1, 100])->get(); + +**whereNull** + +.. code-block:: php + + $users = User::whereNull('age')->get(); + +**whereDate** + +.. code-block:: php + + $users = User::whereDate('birthday', '2021-5-12')->get(); + +The usage is the same as ``whereMonth`` / ``whereDay`` / ``whereYear`` / ``whereTime`` + +**Advanced wheres** + +.. code-block:: php + + $users = + User::where('name', 'John') + ->orWhere(function ($query) { + return $query + ->where('votes', '>', 100) + ->where('title', '<>', 'Admin'); + })->get(); + +**orderBy** + +.. code-block:: php + + $users = User::orderBy('age', 'desc')->get(); + +**Offset & Limit (skip & take)** + +.. code-block:: php + + $users = + User::skip(10) + ->take(5) + ->get(); + +**groupBy** + +Selected columns that are not grouped will be aggregated with the ``$last`` +function. + +.. code-block:: php + + $users = + Users::groupBy('title') + ->get(['title', 'name']); + +**Distinct** + +Distinct requires a field for which to return the distinct values. + +.. code-block:: php + + $users = User::distinct()->get(['name']); + + // Equivalent to: + $users = User::distinct('name')->get(); + +Distinct can be combined with **where**: + +.. code-block:: php + + $users = + User::where('active', true) + ->distinct('name') + ->get(); + +**Like** + +.. code-block:: php + + $spamComments = Comment::where('body', 'like', '%spam%')->get(); + +**Aggregation** + +**Aggregations are only available for MongoDB versions greater than 2.2.x** + +.. code-block:: php + + $total = Product::count(); + $price = Product::max('price'); + $price = Product::min('price'); + $price = Product::avg('price'); + $total = Product::sum('price'); + +Aggregations can be combined with **where**: + +.. code-block:: php + + $sold = Orders::where('sold', true)->sum('price'); + +Aggregations can be also used on sub-documents: + +.. code-block:: php + + $total = Order::max('suborder.price'); + +.. note:: + + This aggregation only works with single sub-documents (like ``EmbedsOne``) + not subdocument arrays (like ``EmbedsMany``). + +**Incrementing/Decrementing the value of a column** + +Perform increments or decrements (default 1) on specified attributes: + +.. code-block:: php + + Cat::where('name', 'Kitty')->increment('age'); + + Car::where('name', 'Toyota')->decrement('weight', 50); + +The number of updated objects is returned: + +.. code-block:: php + + $count = User::increment('age'); + +You may also specify more columns to update: + +.. code-block:: php + + Cat::where('age', 3) + ->increment('age', 1, ['group' => 'Kitty Club']); + + Car::where('weight', 300) + ->decrement('weight', 100, ['latest_change' => 'carbon fiber']); + +MongoDB-specific operators +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In addition to the Laravel Eloquent operators, all available MongoDB query +operators can be used with ``where``: + +.. code-block:: php + + User::where($fieldName, $operator, $value)->get(); + +It generates the following MongoDB filter: + +.. code-block:: ts + + { $fieldName: { $operator: $value } } + +**Exists** + +Matches documents that have the specified field. + +.. code-block:: php + + User::where('age', 'exists', true)->get(); + +**All** + +Matches arrays that contain all elements specified in the query. + +.. code-block:: php + + User::where('roles', 'all', ['moderator', 'author'])->get(); + +**Size** + +Selects documents if the array field is a specified size. + +.. code-block:: php + + Post::where('tags', 'size', 3)->get(); + +**Regex** + +Selects documents where values match a specified regular expression. + +.. code-block:: php + + use MongoDB\BSON\Regex; + + User::where('name', 'regex', new Regex('.*doe', 'i'))->get(); + +.. note:: + + You can also use the Laravel regexp operations. These will automatically + convert your regular expression string to a ``MongoDB\BSON\Regex`` object. + +.. code-block:: php + + User::where('name', 'regexp', '/.*doe/i')->get(); + +The inverse of regexp: + +.. code-block:: php + + User::where('name', 'not regexp', '/.*doe/i')->get(); + +**Type** + +Selects documents if a field is of the specified type. For more information +check: :manual:`$type ` in the +MongoDB Server documentation. + +.. code-block:: php + + User::where('age', 'type', 2)->get(); + +**Mod** + +Performs a modulo operation on the value of a field and selects documents with +a specified result. + +.. code-block:: php + + User::where('age', 'mod', [10, 0])->get(); + +MongoDB-specific Geo operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Near** + +.. code-block:: php + + $bars = Bar::where('location', 'near', [ + '$geometry' => [ + 'type' => 'Point', + 'coordinates' => [ + -0.1367563, // longitude + 51.5100913, // latitude + ], + ], + '$maxDistance' => 50, + ])->get(); + +**GeoWithin** + +.. code-block:: php + + $bars = Bar::where('location', 'geoWithin', [ + '$geometry' => [ + 'type' => 'Polygon', + 'coordinates' => [ + [ + [-0.1450383, 51.5069158], + [-0.1367563, 51.5100913], + [-0.1270247, 51.5013233], + [-0.1450383, 51.5069158], + ], + ], + ], + ])->get(); + +**GeoIntersects** + +.. code-block:: php + + $bars = Bar::where('location', 'geoIntersects', [ + '$geometry' => [ + 'type' => 'LineString', + 'coordinates' => [ + [-0.144044, 51.515215], + [-0.129545, 51.507864], + ], + ], + ])->get(); + +**GeoNear** + +You can make a ``geoNear`` query on MongoDB. +You can omit specifying the automatic fields on the model. +The returned instance is a collection, so you can call the `Collection `__ operations. +Make sure that your model has a ``location`` field, and a +`2ndSphereIndex `__. +The data in the ``location`` field must be saved as `GeoJSON `__. +The ``location`` points must be saved as `WGS84 `__ +reference system for geometry calculation. That means that you must +save ``longitude and latitude``, in that order specifically, and to find near +with calculated distance, you ``must do the same way``. + +.. code-block:: + + Bar::find("63a0cd574d08564f330ceae2")->update( + [ + 'location' => [ + 'type' => 'Point', + 'coordinates' => [ + -0.1367563, + 51.5100913 + ] + ] + ] + ); + $bars = Bar::raw(function ($collection) { + return $collection->aggregate([ + [ + '$geoNear' => [ + "near" => [ "type" => "Point", "coordinates" => [-0.132239, 51.511874] ], + "distanceField" => "dist.calculated", + "minDistance" => 0, + "maxDistance" => 6000, + "includeLocs" => "dist.location", + "spherical" => true, + ] + ] + ]); + }); + +Inserts, updates and deletes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Inserting, updating and deleting records works just like the original Eloquent. +Please check `Laravel Docs' Eloquent section `__. + +Here, only the MongoDB-specific operations are specified. + +MongoDB specific operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Raw Expressions** + +These expressions will be injected directly into the query. + +.. code-block:: php + + User::whereRaw([ + 'age' => ['$gt' => 30, '$lt' => 40], + ])->get(); + + User::whereRaw([ + '$where' => '/.*123.*/.test(this.field)', + ])->get(); + + User::whereRaw([ + '$where' => '/.*123.*/.test(this["hyphenated-field"])', + ])->get(); + +You can also perform raw expressions on the internal MongoCollection object. +If this is executed on the model class, it will return a collection of models. + +If this is executed on the query builder, it will return the original response. + +**Cursor timeout** + +To prevent ``MongoCursorTimeout`` exceptions, you can manually set a timeout +value that will be applied to the cursor: + +.. code-block:: php + + DB::collection('users')->timeout(-1)->get(); + +**Upsert** + +Update or insert a document. Other options for the update method can be +passed directly to the native update method. + +.. code-block:: php + + // Query Builder + DB::collection('users') + ->where('name', 'John') + ->update($data, ['upsert' => true]); + + // Eloquent + $user->update($data, ['upsert' => true]); + +**Projections** + +You can apply projections to your queries using the ``project`` method. + +.. code-block:: php + + DB::collection('items') + ->project(['tags' => ['$slice' => 1]]) + ->get(); + + DB::collection('items') + ->project(['tags' => ['$slice' => [3, 7]]]) + ->get(); + +**Projections with Pagination** + +.. code-block:: php + + $limit = 25; + $projections = ['id', 'name']; + + DB::collection('items') + ->paginate($limit, $projections); + +**Push** + +Add items to an array. + +.. code-block:: php + + DB::collection('users') + ->where('name', 'John') + ->push('items', 'boots'); + + $user->push('items', 'boots'); + +.. code-block:: php + + DB::collection('users') + ->where('name', 'John') + ->push('messages', [ + 'from' => 'Jane Doe', + 'message' => 'Hi John', + ]); + + $user->push('messages', [ + 'from' => 'Jane Doe', + 'message' => 'Hi John', + ]); + +If you **DON'T** want duplicate items, set the third parameter to ``true``: + +.. code-block:: php + + DB::collection('users') + ->where('name', 'John') + ->push('items', 'boots', true); + + $user->push('items', 'boots', true); + +**Pull** + +Remove an item from an array. + +.. code-block:: php + + DB::collection('users') + ->where('name', 'John') + ->pull('items', 'boots'); + + $user->pull('items', 'boots'); + +.. code-block:: php + + DB::collection('users') + ->where('name', 'John') + ->pull('messages', [ + 'from' => 'Jane Doe', + 'message' => 'Hi John', + ]); + + $user->pull('messages', [ + 'from' => 'Jane Doe', + 'message' => 'Hi John', + ]); + +**Unset** + +Remove one or more fields from a document. + +.. code-block:: php + + DB::collection('users') + ->where('name', 'John') + ->unset('note'); + + $user->unset('note'); + + $user->save(); + +Using the native ``unset`` on models will work as well: + +.. code-block:: php + + unset($user['note']); + unset($user->node); diff --git a/docs/queues.md b/docs/queues.md deleted file mode 100644 index 0645a3d9e..000000000 --- a/docs/queues.md +++ /dev/null @@ -1,34 +0,0 @@ -Queues -====== - -If you want to use MongoDB as your database backend for Laravel Queue, change the driver in `config/queue.php`: - -```php -'connections' => [ - 'database' => [ - 'driver' => 'mongodb', - // You can also specify your jobs specific database created on config/database.php - 'connection' => 'mongodb-job', - 'table' => 'jobs', - 'queue' => 'default', - 'expire' => 60, - ], -], -``` - -If you want to use MongoDB to handle failed jobs, change the database in `config/queue.php`: - -```php -'failed' => [ - 'driver' => 'mongodb', - // You can also specify your jobs specific database created on config/database.php - 'database' => 'mongodb-job', - 'table' => 'failed_jobs', -], -``` - -Add the service provider in `config/app.php`: - -```php -MongoDB\Laravel\MongoDBQueueServiceProvider::class, -``` diff --git a/docs/queues.txt b/docs/queues.txt new file mode 100644 index 000000000..330662913 --- /dev/null +++ b/docs/queues.txt @@ -0,0 +1,46 @@ +.. _laravel-queues: + +====== +Queues +====== + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :keywords: php framework, odm, code example + +If you want to use MongoDB as your database backend for Laravel Queue, change +the driver in ``config/queue.php``: + +.. code-block:: php + + 'connections' => [ + 'database' => [ + 'driver' => 'mongodb', + // You can also specify your jobs specific database created on config/database.php + 'connection' => 'mongodb-job', + 'table' => 'jobs', + 'queue' => 'default', + 'expire' => 60, + ], + ], + +If you want to use MongoDB to handle failed jobs, change the database in +``config/queue.php``: + +.. code-block:: php + + 'failed' => [ + 'driver' => 'mongodb', + // You can also specify your jobs specific database created on config/database.php + 'database' => 'mongodb-job', + 'table' => 'failed_jobs', + ], + +Add the service provider in ``config/app.php``: + +.. code-block:: php + + MongoDB\Laravel\MongoDBQueueServiceProvider::class, diff --git a/docs/transactions.md b/docs/transactions.md deleted file mode 100644 index fad0df803..000000000 --- a/docs/transactions.md +++ /dev/null @@ -1,56 +0,0 @@ -Transactions -============ - -Transactions require MongoDB version ^4.0 as well as deployment of replica set or sharded clusters. You can find more information [in the MongoDB docs](https://docs.mongodb.com/manual/core/transactions/) - -```php -DB::transaction(function () { - User::create(['name' => 'john', 'age' => 19, 'title' => 'admin', 'email' => 'john@example.com']); - DB::collection('users')->where('name', 'john')->update(['age' => 20]); - DB::collection('users')->where('name', 'john')->delete(); -}); -``` - -```php -// begin a transaction -DB::beginTransaction(); -User::create(['name' => 'john', 'age' => 19, 'title' => 'admin', 'email' => 'john@example.com']); -DB::collection('users')->where('name', 'john')->update(['age' => 20]); -DB::collection('users')->where('name', 'john')->delete(); - -// commit changes -DB::commit(); -``` - -To abort a transaction, call the `rollBack` method at any point during the transaction: - -```php -DB::beginTransaction(); -User::create(['name' => 'john', 'age' => 19, 'title' => 'admin', 'email' => 'john@example.com']); - -// Abort the transaction, discarding any data created as part of it -DB::rollBack(); -``` - -**NOTE:** Transactions in MongoDB cannot be nested. DB::beginTransaction() function will start new transactions in a new created or existing session and will raise the RuntimeException when transactions already exist. See more in MongoDB official docs [Transactions and Sessions](https://www.mongodb.com/docs/manual/core/transactions/#transactions-and-sessions) - -```php -DB::beginTransaction(); -User::create(['name' => 'john', 'age' => 20, 'title' => 'admin']); - -// This call to start a nested transaction will raise a RuntimeException -DB::beginTransaction(); -DB::collection('users')->where('name', 'john')->update(['age' => 20]); -DB::commit(); -DB::rollBack(); -``` - -Database Testing ----------------- - -For testing, the traits `Illuminate\Foundation\Testing\DatabaseTransactions` and `Illuminate\Foundation\Testing\RefreshDatabase` are not yet supported. -Instead, create migrations and use the `DatabaseMigrations` trait to reset the database after each test: - -```php -use Illuminate\Foundation\Testing\DatabaseMigrations; -``` diff --git a/docs/transactions.txt b/docs/transactions.txt new file mode 100644 index 000000000..ee70f8c8b --- /dev/null +++ b/docs/transactions.txt @@ -0,0 +1,79 @@ +.. _laravel-transactions: + +============ +Transactions +============ + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :keywords: php framework, odm, code example + +MongoDB transactions require the following software and topology: + +- MongoDB version 4.0 or later +- A replica set deployment or sharded cluster + +You can find more information :manual:`in the MongoDB docs ` + +.. code-block:: php + + DB::transaction(function () { + User::create(['name' => 'john', 'age' => 19, 'title' => 'admin', 'email' => 'john@example.com']); + DB::collection('users')->where('name', 'john')->update(['age' => 20]); + DB::collection('users')->where('name', 'john')->delete(); + }); + +.. code-block:: php + + // begin a transaction + DB::beginTransaction(); + User::create(['name' => 'john', 'age' => 19, 'title' => 'admin', 'email' => 'john@example.com']); + DB::collection('users')->where('name', 'john')->update(['age' => 20]); + DB::collection('users')->where('name', 'john')->delete(); + + // commit changes + DB::commit(); + +To abort a transaction, call the ``rollBack`` method at any point during the transaction: + +.. code-block:: php + + DB::beginTransaction(); + User::create(['name' => 'john', 'age' => 19, 'title' => 'admin', 'email' => 'john@example.com']); + + // Abort the transaction, discarding any data created as part of it + DB::rollBack(); + + +.. note:: + + Transactions in MongoDB cannot be nested. DB::beginTransaction() function + will start new transactions in a new created or existing session and will + raise the RuntimeException when transactions already exist. See more in + MongoDB official docs :manual:`Transactions and Sessions `. + +.. code-block:: php + + DB::beginTransaction(); + User::create(['name' => 'john', 'age' => 20, 'title' => 'admin']); + + // This call to start a nested transaction will raise a RuntimeException + DB::beginTransaction(); + DB::collection('users')->where('name', 'john')->update(['age' => 20]); + DB::commit(); + DB::rollBack(); + +Database Testing +---------------- + +For testing, the traits ``Illuminate\Foundation\Testing\DatabaseTransactions`` +and ``Illuminate\Foundation\Testing\RefreshDatabase`` are not yet supported. +Instead, create migrations and use the ``DatabaseMigrations`` trait to reset +the database after each test: + +.. code-block:: php + + use Illuminate\Foundation\Testing\DatabaseMigrations; diff --git a/docs/upgrade.md b/docs/upgrade.md deleted file mode 100644 index 612dd27af..000000000 --- a/docs/upgrade.md +++ /dev/null @@ -1,19 +0,0 @@ -Upgrading -========= - -The PHP library uses [semantic versioning](https://semver.org/). Upgrading to a new major version may require changes to your application. - -Upgrading from version 3 to 4 ------------------------------ - -- Laravel 10.x is required -- Change dependency name in your composer.json to `"mongodb/laravel-mongodb": "^4.0"` and run `composer update` -- Change namespace from `Jenssegers\Mongodb\` to `MongoDB\Laravel\` in your models and config -- Remove support for non-Laravel projects -- Replace `$dates` with `$casts` in your models -- Call `$model->save()` after `$model->unset('field')` to persist the change -- Replace calls to `Query\Builder::whereAll($column, $values)` with `Query\Builder::where($column, 'all', $values)` -- `Query\Builder::delete()` doesn't accept `limit()` other than `1` or `null`. -- `whereDate`, `whereDay`, `whereMonth`, `whereYear`, `whereTime` now use MongoDB operators on date fields -- Replace `Illuminate\Database\Eloquent\MassPrunable` with `MongoDB\Laravel\Eloquent\MassPrunable` in your models -- Remove calls to not-supported methods of `Query\Builder`: `toSql`, `toRawSql`, `whereColumn`, `whereFullText`, `groupByRaw`, `orderByRaw`, `unionAll`, `union`, `having`, `havingRaw`, `havingBetween`, `whereIntegerInRaw`, `orWhereIntegerInRaw`, `whereIntegerNotInRaw`, `orWhereIntegerNotInRaw`. diff --git a/docs/upgrade.txt b/docs/upgrade.txt new file mode 100644 index 000000000..8148fbdfc --- /dev/null +++ b/docs/upgrade.txt @@ -0,0 +1,49 @@ +.. _laravel-upgrading: + +========= +Upgrading +========= + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :keywords: php framework, odm, code example + +The PHP library uses `semantic versioning `__. Upgrading +to a new major version may require changes to your application. + +Upgrading from version 3 to 4 +----------------------------- + +- Laravel 10.x is required + +- Change dependency name in your composer.json to ``"mongodb/laravel-mongodb": "^4.0"`` + and run ``composer update`` + +- Change namespace from ``Jenssegers\Mongodb\`` to ``MongoDB\Laravel\`` + in your models and config + +- Remove support for non-Laravel projects + +- Replace ``$dates`` with ``$casts`` in your models + +- Call ``$model->save()`` after ``$model->unset('field')`` to persist the change + +- Replace calls to ``Query\Builder::whereAll($column, $values)`` with + ``Query\Builder::where($column, 'all', $values)`` + +- ``Query\Builder::delete()`` doesn't accept ``limit()`` other than ``1`` or ``null``. + +- ``whereDate``, ``whereDay``, ``whereMonth``, ``whereYear``, ``whereTime`` + now use MongoDB operators on date fields + +- Replace ``Illuminate\Database\Eloquent\MassPrunable`` with ``MongoDB\Laravel\Eloquent\MassPrunable`` + in your models + +- Remove calls to not-supported methods of ``Query\Builder``: ``toSql``, + ``toRawSql``, ``whereColumn``, ``whereFullText``, ``groupByRaw``, + ``orderByRaw``, ``unionAll``, ``union``, ``having``, ``havingRaw``, + ``havingBetween``, ``whereIntegerInRaw``, ``orWhereIntegerInRaw``, + ``whereIntegerNotInRaw``, ``orWhereIntegerNotInRaw``. diff --git a/docs/user-authentication.md b/docs/user-authentication.md deleted file mode 100644 index 72341ceae..000000000 --- a/docs/user-authentication.md +++ /dev/null @@ -1,15 +0,0 @@ -User authentication -================== - -If you want to use Laravel's native Auth functionality, register this included service provider: - -```php -MongoDB\Laravel\Auth\PasswordResetServiceProvider::class, -``` - -This service provider will slightly modify the internal `DatabaseReminderRepository` to add support for MongoDB based password reminders. - -If you don't use password reminders, you don't have to register this service provider and everything else should work just fine. - - - diff --git a/docs/user-authentication.txt b/docs/user-authentication.txt new file mode 100644 index 000000000..8755c7c6a --- /dev/null +++ b/docs/user-authentication.txt @@ -0,0 +1,24 @@ +.. _laravel-user-authentication: + +=================== +User authentication +=================== + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :keywords: php framework, odm, code example + +If you want to use Laravel's native Auth functionality, register this included +service provider: + +.. code-block:: php + + MongoDB\Laravel\Auth\PasswordResetServiceProvider::class, + +This service provider will slightly modify the internal ``DatabaseReminderRepository`` +to add support for MongoDB based password reminders. + +If you don't use password reminders, you can omit this service provider. From a5cf5cba823f5a1d79fb23ce8c9a55e2f27f0ce7 Mon Sep 17 00:00:00 2001 From: George Stubbs Date: Tue, 16 Jan 2024 17:06:06 +0000 Subject: [PATCH 148/446] Fix casting issues (issue: #2703) (#2705) --- src/Eloquent/Model.php | 83 +++++++++++++++++---------- tests/Casts/BooleanTest.php | 37 ++++++++++++ tests/Casts/CollectionTest.php | 8 +++ tests/Casts/DateTest.php | 10 ++++ tests/Casts/DatetimeTest.php | 6 ++ tests/Casts/DecimalTest.php | 94 ++++++++++++++++++++++++++++-- tests/Casts/EncryptionTest.php | 102 +++++++++++++++++++++++++++++++++ tests/Casts/IntegerTest.php | 18 ++++++ tests/Casts/JsonTest.php | 10 +++- tests/Casts/ObjectTest.php | 2 + tests/Casts/StringTest.php | 8 +++ tests/Models/Casting.php | 8 +++ tests/QueueTest.php | 3 +- 13 files changed, 352 insertions(+), 37 deletions(-) create mode 100644 tests/Casts/EncryptionTest.php diff --git a/src/Eloquent/Model.php b/src/Eloquent/Model.php index bcb672a3c..8928c78e1 100644 --- a/src/Eloquent/Model.php +++ b/src/Eloquent/Model.php @@ -4,15 +4,11 @@ namespace MongoDB\Laravel\Eloquent; -use Brick\Math\BigDecimal; -use Brick\Math\Exception\MathException as BrickMathException; -use Brick\Math\RoundingMode; use Carbon\CarbonInterface; use DateTimeInterface; use Illuminate\Contracts\Queue\QueueableCollection; use Illuminate\Contracts\Queue\QueueableEntity; use Illuminate\Contracts\Support\Arrayable; -use Illuminate\Database\Eloquent\Casts\Json; use Illuminate\Database\Eloquent\Model as BaseModel; use Illuminate\Database\Eloquent\Relations\Relation; use Illuminate\Support\Arr; @@ -22,10 +18,11 @@ use MongoDB\BSON\Binary; use MongoDB\BSON\Decimal128; use MongoDB\BSON\ObjectID; +use MongoDB\BSON\Type; use MongoDB\BSON\UTCDateTime; use MongoDB\Laravel\Query\Builder as QueryBuilder; +use Stringable; -use function abs; use function array_key_exists; use function array_keys; use function array_merge; @@ -41,7 +38,6 @@ use function is_string; use function ltrim; use function method_exists; -use function sprintf; use function str_contains; use function str_starts_with; use function strcmp; @@ -139,15 +135,9 @@ public function fromDateTime($value) /** @inheritdoc */ protected function asDateTime($value) { - // Convert UTCDateTime instances. + // Convert UTCDateTime instances to Carbon. if ($value instanceof UTCDateTime) { - $date = $value->toDateTime(); - - $seconds = $date->format('U'); - $milliseconds = abs((int) $date->format('v')); - $timestampMs = sprintf('%d%03d', $seconds, $milliseconds); - - return Date::createFromTimestampMs($timestampMs); + return Date::instance($value->toDateTime()); } return parent::asDateTime($value); @@ -250,9 +240,16 @@ public function setAttribute($key, $value) { $key = (string) $key; - // Add casts - if ($this->hasCast($key)) { - $value = $this->castAttribute($key, $value); + $casts = $this->getCasts(); + if (array_key_exists($key, $casts)) { + $castType = $this->getCastType($key); + $castOptions = Str::after($casts[$key], ':'); + + // Can add more native mongo type casts here. + $value = match ($castType) { + 'decimal' => $this->fromDecimal($value, $castOptions), + default => $value, + }; } // Convert _id to ObjectID. @@ -281,26 +278,38 @@ public function setAttribute($key, $value) return parent::setAttribute($key, $value); } - /** @inheritdoc */ + /** + * @param mixed $value + * + * @inheritdoc + */ protected function asDecimal($value, $decimals) { - try { - $value = (string) BigDecimal::of((string) $value)->toScale((int) $decimals, RoundingMode::HALF_UP); - - return new Decimal128($value); - } catch (BrickMathException $e) { - throw new MathException('Unable to cast value to a decimal.', previous: $e); + // Convert BSON to string. + if ($this->isBSON($value)) { + if ($value instanceof Binary) { + $value = $value->getData(); + } elseif ($value instanceof Stringable) { + $value = (string) $value; + } else { + throw new MathException('BSON type ' . $value::class . ' cannot be converted to string'); + } } + + return parent::asDecimal($value, $decimals); } - /** @inheritdoc */ - public function fromJson($value, $asObject = false) + /** + * Change to mongo native for decimal cast. + * + * @param mixed $value + * @param int $decimals + * + * @return Decimal128 + */ + protected function fromDecimal($value, $decimals) { - if (! is_string($value)) { - $value = Json::encode($value); - } - - return Json::decode($value, ! $asObject); + return new Decimal128($this->asDecimal($value, $decimals)); } /** @inheritdoc */ @@ -707,4 +716,16 @@ protected function addCastAttributesToArray(array $attributes, array $mutatedAtt return $attributes; } + + /** + * Is a value a BSON type? + * + * @param mixed $value + * + * @return bool + */ + protected function isBSON(mixed $value): bool + { + return $value instanceof Type; + } } diff --git a/tests/Casts/BooleanTest.php b/tests/Casts/BooleanTest.php index 8be2a4def..a4812ddec 100644 --- a/tests/Casts/BooleanTest.php +++ b/tests/Casts/BooleanTest.php @@ -50,5 +50,42 @@ public function testBoolAsString(): void self::assertIsBool($model->booleanValue); self::assertSame(false, $model->booleanValue); + + $model->update(['booleanValue' => 'false']); + + self::assertIsBool($model->booleanValue); + self::assertSame(true, $model->booleanValue); + + $model->update(['booleanValue' => '0.0']); + + self::assertIsBool($model->booleanValue); + self::assertSame(true, $model->booleanValue); + + $model->update(['booleanValue' => 'true']); + + self::assertIsBool($model->booleanValue); + self::assertSame(true, $model->booleanValue); + } + + public function testBoolAsNumber(): void + { + $model = Casting::query()->create(['booleanValue' => 1]); + + self::assertIsBool($model->booleanValue); + self::assertSame(true, $model->booleanValue); + + $model->update(['booleanValue' => 0]); + + self::assertIsBool($model->booleanValue); + self::assertSame(false, $model->booleanValue); + + $model->update(['booleanValue' => 1.79]); + + self::assertIsBool($model->booleanValue); + self::assertSame(true, $model->booleanValue); + + $model->update(['booleanValue' => 0.0]); + self::assertIsBool($model->booleanValue); + self::assertSame(false, $model->booleanValue); } } diff --git a/tests/Casts/CollectionTest.php b/tests/Casts/CollectionTest.php index 67498c092..4c2400ecb 100644 --- a/tests/Casts/CollectionTest.php +++ b/tests/Casts/CollectionTest.php @@ -24,11 +24,19 @@ public function testCollection(): void $model = Casting::query()->create(['collectionValue' => ['g' => 'G-Eazy']]); self::assertInstanceOf(Collection::class, $model->collectionValue); + self::assertIsString($model->getRawOriginal('collectionValue')); self::assertEquals(collect(['g' => 'G-Eazy']), $model->collectionValue); $model->update(['collectionValue' => ['Dont let me go' => 'Even the longest of nights turn days']]); self::assertInstanceOf(Collection::class, $model->collectionValue); + self::assertIsString($model->getRawOriginal('collectionValue')); self::assertEquals(collect(['Dont let me go' => 'Even the longest of nights turn days']), $model->collectionValue); + + $model->update(['collectionValue' => [['Dont let me go' => 'Even the longest of nights turn days']]]); + + self::assertInstanceOf(Collection::class, $model->collectionValue); + self::assertIsString($model->getRawOriginal('collectionValue')); + self::assertEquals(collect([['Dont let me go' => 'Even the longest of nights turn days']]), $model->collectionValue); } } diff --git a/tests/Casts/DateTest.php b/tests/Casts/DateTest.php index bd4b76424..20ce5dd9a 100644 --- a/tests/Casts/DateTest.php +++ b/tests/Casts/DateTest.php @@ -7,6 +7,7 @@ use Carbon\CarbonImmutable; use DateTime; use Illuminate\Support\Carbon; +use MongoDB\BSON\UTCDateTime; use MongoDB\Laravel\Tests\Models\Casting; use MongoDB\Laravel\Tests\TestCase; @@ -31,17 +32,26 @@ public function testDate(): void $model->update(['dateField' => now()->subDay()]); self::assertInstanceOf(Carbon::class, $model->dateField); + self::assertInstanceOf(UTCDateTime::class, $model->getRawOriginal('dateField')); self::assertEquals(now()->subDay()->startOfDay()->format('Y-m-d H:i:s'), (string) $model->dateField); $model->update(['dateField' => new DateTime()]); self::assertInstanceOf(Carbon::class, $model->dateField); + self::assertInstanceOf(UTCDateTime::class, $model->getRawOriginal('dateField')); self::assertEquals(now()->startOfDay()->format('Y-m-d H:i:s'), (string) $model->dateField); $model->update(['dateField' => (new DateTime())->modify('-1 day')]); self::assertInstanceOf(Carbon::class, $model->dateField); + self::assertInstanceOf(UTCDateTime::class, $model->getRawOriginal('dateField')); self::assertEquals(now()->subDay()->startOfDay()->format('Y-m-d H:i:s'), (string) $model->dateField); + + $refetchedModel = Casting::query()->find($model->getKey()); + + self::assertInstanceOf(Carbon::class, $refetchedModel->dateField); + self::assertInstanceOf(UTCDateTime::class, $model->getRawOriginal('dateField')); + self::assertEquals(now()->subDay()->startOfDay()->format('Y-m-d H:i:s'), (string) $refetchedModel->dateField); } public function testDateAsString(): void diff --git a/tests/Casts/DatetimeTest.php b/tests/Casts/DatetimeTest.php index dc2bdd877..022ed3535 100644 --- a/tests/Casts/DatetimeTest.php +++ b/tests/Casts/DatetimeTest.php @@ -7,6 +7,7 @@ use Carbon\CarbonImmutable; use DateTime; use Illuminate\Support\Carbon; +use MongoDB\BSON\UTCDateTime; use MongoDB\Laravel\Tests\Models\Casting; use MongoDB\Laravel\Tests\TestCase; @@ -27,11 +28,13 @@ public function testDatetime(): void $model = Casting::query()->create(['datetimeField' => now()]); self::assertInstanceOf(Carbon::class, $model->datetimeField); + self::assertInstanceOf(UTCDateTime::class, $model->getRawOriginal('datetimeField')); self::assertEquals(now()->format('Y-m-d H:i:s'), (string) $model->datetimeField); $model->update(['datetimeField' => now()->subDay()]); self::assertInstanceOf(Carbon::class, $model->datetimeField); + self::assertInstanceOf(UTCDateTime::class, $model->getRawOriginal('datetimeField')); self::assertEquals(now()->subDay()->format('Y-m-d H:i:s'), (string) $model->datetimeField); } @@ -40,6 +43,7 @@ public function testDatetimeAsString(): void $model = Casting::query()->create(['datetimeField' => '2023-10-29']); self::assertInstanceOf(Carbon::class, $model->datetimeField); + self::assertInstanceOf(UTCDateTime::class, $model->getRawOriginal('datetimeField')); self::assertEquals( Carbon::createFromTimestamp(1698577443)->startOfDay()->format('Y-m-d H:i:s'), (string) $model->datetimeField, @@ -48,6 +52,7 @@ public function testDatetimeAsString(): void $model->update(['datetimeField' => '2023-10-28 11:04:03']); self::assertInstanceOf(Carbon::class, $model->datetimeField); + self::assertInstanceOf(UTCDateTime::class, $model->getRawOriginal('datetimeField')); self::assertEquals( Carbon::createFromTimestamp(1698577443)->subDay()->format('Y-m-d H:i:s'), (string) $model->datetimeField, @@ -82,6 +87,7 @@ public function testImmutableDatetime(): void $model->update(['immutableDatetimeField' => '2023-10-28 11:04:03']); self::assertInstanceOf(CarbonImmutable::class, $model->immutableDatetimeField); + self::assertInstanceOf(UTCDateTime::class, $model->getRawOriginal('immutableDatetimeField')); self::assertEquals( Carbon::createFromTimestamp(1698577443)->subDay()->format('Y-m-d H:i:s'), (string) $model->immutableDatetimeField, diff --git a/tests/Casts/DecimalTest.php b/tests/Casts/DecimalTest.php index 535328fe4..f69d24d62 100644 --- a/tests/Casts/DecimalTest.php +++ b/tests/Casts/DecimalTest.php @@ -4,10 +4,18 @@ namespace MongoDB\Laravel\Tests\Casts; +use Illuminate\Support\Exceptions\MathException; +use MongoDB\BSON\Binary; use MongoDB\BSON\Decimal128; +use MongoDB\BSON\Int64; +use MongoDB\BSON\Javascript; +use MongoDB\BSON\UTCDateTime; +use MongoDB\Laravel\Collection; use MongoDB\Laravel\Tests\Models\Casting; use MongoDB\Laravel\Tests\TestCase; +use function now; + class DecimalTest extends TestCase { protected function setUp(): void @@ -21,25 +29,103 @@ public function testDecimal(): void { $model = Casting::query()->create(['decimalNumber' => 100.99]); - self::assertInstanceOf(Decimal128::class, $model->decimalNumber); + self::assertIsString($model->decimalNumber); + self::assertInstanceOf(Decimal128::class, $model->getRawOriginal('decimalNumber')); self::assertEquals('100.99', $model->decimalNumber); $model->update(['decimalNumber' => 9999.9]); - self::assertInstanceOf(Decimal128::class, $model->decimalNumber); + self::assertIsString($model->decimalNumber); + self::assertInstanceOf(Decimal128::class, $model->getRawOriginal('decimalNumber')); self::assertEquals('9999.90', $model->decimalNumber); + + $model->update(['decimalNumber' => 9999.00000009]); + + self::assertIsString($model->decimalNumber); + self::assertInstanceOf(Decimal128::class, $model->getRawOriginal('decimalNumber')); + self::assertEquals('9999.00', $model->decimalNumber); } public function testDecimalAsString(): void { $model = Casting::query()->create(['decimalNumber' => '120.79']); - self::assertInstanceOf(Decimal128::class, $model->decimalNumber); + self::assertIsString($model->decimalNumber); + self::assertInstanceOf(Decimal128::class, $model->getRawOriginal('decimalNumber')); self::assertEquals('120.79', $model->decimalNumber); $model->update(['decimalNumber' => '795']); - self::assertInstanceOf(Decimal128::class, $model->decimalNumber); + self::assertIsString($model->decimalNumber); + self::assertInstanceOf(Decimal128::class, $model->getRawOriginal('decimalNumber')); self::assertEquals('795.00', $model->decimalNumber); + + $model->update(['decimalNumber' => '1234.99999999999']); + + self::assertIsString($model->decimalNumber); + self::assertInstanceOf(Decimal128::class, $model->getRawOriginal('decimalNumber')); + self::assertEquals('1235.00', $model->decimalNumber); + } + + public function testDecimalAsDecimal128(): void + { + $model = Casting::query()->create(['decimalNumber' => new Decimal128('100.99')]); + + self::assertIsString($model->decimalNumber); + self::assertInstanceOf(Decimal128::class, $model->getRawOriginal('decimalNumber')); + self::assertEquals('100.99', $model->decimalNumber); + + $model->update(['decimalNumber' => new Decimal128('9999.9')]); + + self::assertIsString($model->decimalNumber); + self::assertInstanceOf(Decimal128::class, $model->getRawOriginal('decimalNumber')); + self::assertEquals('9999.90', $model->decimalNumber); + } + + public function testOtherBSONTypes(): void + { + $modelId = $this->setBSONType(new Int64(100)); + $model = Casting::query()->find($modelId); + + self::assertIsString($model->decimalNumber); + self::assertIsInt($model->getRawOriginal('decimalNumber')); + self::assertEquals('100.00', $model->decimalNumber); + + // Update decimalNumber to a Binary type + $this->setBSONType(new Binary('100.1234', Binary::TYPE_GENERIC), $modelId); + $model->refresh(); + + self::assertIsString($model->decimalNumber); + self::assertInstanceOf(Binary::class, $model->getRawOriginal('decimalNumber')); + self::assertEquals('100.12', $model->decimalNumber); + + $this->setBSONType(new Javascript('function() { return 100; }'), $modelId); + $model->refresh(); + self::expectException(MathException::class); + self::expectExceptionMessage('Unable to cast value to a decimal.'); + $model->decimalNumber; + self::assertInstanceOf(Javascript::class, $model->getRawOriginal('decimalNumber')); + + $this->setBSONType(new UTCDateTime(now()), $modelId); + $model->refresh(); + self::expectException(MathException::class); + self::expectExceptionMessage('Unable to cast value to a decimal.'); + $model->decimalNumber; + self::assertInstanceOf(UTCDateTime::class, $model->getRawOriginal('decimalNumber')); + } + + private function setBSONType($value, $id = null) + { + // Do a raw insert/update, so we can enforce the type we want + return Casting::raw(function (Collection $collection) use ($id, $value) { + if (! empty($id)) { + return $collection->updateOne( + ['_id' => $id], + ['$set' => ['decimalNumber' => $value]], + ); + } + + return $collection->insertOne(['decimalNumber' => $value])->getInsertedId(); + }); } } diff --git a/tests/Casts/EncryptionTest.php b/tests/Casts/EncryptionTest.php new file mode 100644 index 000000000..0c40254f1 --- /dev/null +++ b/tests/Casts/EncryptionTest.php @@ -0,0 +1,102 @@ +make(Encrypter::class) + ->decryptString( + $model->getRawOriginal($key), + ); + } + + public function testEncryptedString(): void + { + $model = Casting::query()->create(['encryptedString' => 'encrypted']); + + self::assertIsString($model->encryptedString); + self::assertEquals('encrypted', $model->encryptedString); + self::assertNotEquals('encrypted', $model->getRawOriginal('encryptedString')); + self::assertEquals('encrypted', $this->decryptRaw($model, 'encryptedString')); + + $model->update(['encryptedString' => 'updated']); + self::assertIsString($model->encryptedString); + self::assertEquals('updated', $model->encryptedString); + self::assertNotEquals('updated', $model->getRawOriginal('encryptedString')); + self::assertEquals('updated', $this->decryptRaw($model, 'encryptedString')); + } + + public function testEncryptedArray(): void + { + $expected = ['foo' => 'bar']; + $model = Casting::query()->create(['encryptedArray' => $expected]); + + self::assertIsArray($model->encryptedArray); + self::assertEquals($expected, $model->encryptedArray); + self::assertNotEquals($expected, $model->getRawOriginal('encryptedArray')); + self::assertEquals($expected, Json::decode($this->decryptRaw($model, 'encryptedArray'))); + + $updated = ['updated' => 'array']; + $model->update(['encryptedArray' => $updated]); + self::assertIsArray($model->encryptedArray); + self::assertEquals($updated, $model->encryptedArray); + self::assertNotEquals($updated, $model->getRawOriginal('encryptedArray')); + self::assertEquals($updated, Json::decode($this->decryptRaw($model, 'encryptedArray'))); + } + + public function testEncryptedObject(): void + { + $expected = (object) ['foo' => 'bar']; + $model = Casting::query()->create(['encryptedObject' => $expected]); + + self::assertIsObject($model->encryptedObject); + self::assertEquals($expected, $model->encryptedObject); + self::assertNotEquals($expected, $model->getRawOriginal('encryptedObject')); + self::assertEquals($expected, Json::decode($this->decryptRaw($model, 'encryptedObject'), false)); + + $updated = (object) ['updated' => 'object']; + $model->update(['encryptedObject' => $updated]); + self::assertIsObject($model->encryptedObject); + self::assertEquals($updated, $model->encryptedObject); + self::assertNotEquals($updated, $model->getRawOriginal('encryptedObject')); + self::assertEquals($updated, Json::decode($this->decryptRaw($model, 'encryptedObject'), false)); + } + + public function testEncryptedCollection(): void + { + $expected = collect(['foo' => 'bar']); + $model = Casting::query()->create(['encryptedCollection' => $expected]); + + self::assertInstanceOf(Collection::class, $model->encryptedCollection); + self::assertEquals($expected, $model->encryptedCollection); + self::assertNotEquals($expected, $model->getRawOriginal('encryptedCollection')); + self::assertEquals($expected, collect(Json::decode($this->decryptRaw($model, 'encryptedCollection'), false))); + + $updated = collect(['updated' => 'object']); + $model->update(['encryptedCollection' => $updated]); + self::assertIsObject($model->encryptedCollection); + self::assertEquals($updated, $model->encryptedCollection); + self::assertNotEquals($updated, $model->getRawOriginal('encryptedCollection')); + self::assertEquals($updated, collect(Json::decode($this->decryptRaw($model, 'encryptedCollection'), false))); + } +} diff --git a/tests/Casts/IntegerTest.php b/tests/Casts/IntegerTest.php index f1a11dba5..99cb0cd14 100644 --- a/tests/Casts/IntegerTest.php +++ b/tests/Casts/IntegerTest.php @@ -51,4 +51,22 @@ public function testIntAsString(): void self::assertIsInt($model->intNumber); self::assertEquals(9, $model->intNumber); } + + public function testIntAsFloat(): void + { + $model = Casting::query()->create(['intNumber' => 1.0]); + + self::assertIsInt($model->intNumber); + self::assertEquals(1, $model->intNumber); + + $model->update(['intNumber' => 2.0]); + + self::assertIsInt($model->intNumber); + self::assertEquals(2, $model->intNumber); + + $model->update(['intNumber' => 9.6]); + + self::assertIsInt($model->intNumber); + self::assertEquals(9, $model->intNumber); + } } diff --git a/tests/Casts/JsonTest.php b/tests/Casts/JsonTest.php index 99473c5d8..2b8759dd6 100644 --- a/tests/Casts/JsonTest.php +++ b/tests/Casts/JsonTest.php @@ -25,9 +25,17 @@ public function testJson(): void self::assertIsArray($model->jsonValue); self::assertEquals(['g' => 'G-Eazy'], $model->jsonValue); - $model->update(['jsonValue' => json_encode(['Dont let me go' => 'Even the longest of nights turn days'])]); + $model->update(['jsonValue' => ['Dont let me go' => 'Even the longest of nights turn days']]); self::assertIsArray($model->jsonValue); + self::assertIsString($model->getRawOriginal('jsonValue')); self::assertEquals(['Dont let me go' => 'Even the longest of nights turn days'], $model->jsonValue); + + $json = json_encode(['it will encode json' => 'even if it is already json']); + $model->update(['jsonValue' => $json]); + + self::assertIsString($model->jsonValue); + self::assertIsString($model->getRawOriginal('jsonValue')); + self::assertEquals($json, $model->jsonValue); } } diff --git a/tests/Casts/ObjectTest.php b/tests/Casts/ObjectTest.php index 3217b23fc..e45b736e0 100644 --- a/tests/Casts/ObjectTest.php +++ b/tests/Casts/ObjectTest.php @@ -21,11 +21,13 @@ public function testObject(): void $model = Casting::query()->create(['objectValue' => ['g' => 'G-Eazy']]); self::assertIsObject($model->objectValue); + self::assertIsString($model->getRawOriginal('objectValue')); self::assertEquals((object) ['g' => 'G-Eazy'], $model->objectValue); $model->update(['objectValue' => ['Dont let me go' => 'Even the brightest of colors turn greys']]); self::assertIsObject($model->objectValue); + self::assertIsString($model->getRawOriginal('objectValue')); self::assertEquals((object) ['Dont let me go' => 'Even the brightest of colors turn greys'], $model->objectValue); } } diff --git a/tests/Casts/StringTest.php b/tests/Casts/StringTest.php index 120fb9b19..67ed7227d 100644 --- a/tests/Casts/StringTest.php +++ b/tests/Casts/StringTest.php @@ -7,6 +7,8 @@ use MongoDB\Laravel\Tests\Models\Casting; use MongoDB\Laravel\Tests\TestCase; +use function now; + class StringTest extends TestCase { protected function setUp(): void @@ -27,5 +29,11 @@ public function testString(): void self::assertIsString($model->stringContent); self::assertEquals("Losing hope, don't mean I'm hopeless And maybe all I need is time", $model->stringContent); + + $now = now(); + $model->update(['stringContent' => $now]); + + self::assertIsString($model->stringContent); + self::assertEquals((string) $now, $model->stringContent); } } diff --git a/tests/Models/Casting.php b/tests/Models/Casting.php index 9e232cf15..f44f08a62 100644 --- a/tests/Models/Casting.php +++ b/tests/Models/Casting.php @@ -32,6 +32,10 @@ class Casting extends Eloquent 'datetimeWithFormatField', 'immutableDatetimeField', 'immutableDatetimeWithFormatField', + 'encryptedString', + 'encryptedArray', + 'encryptedObject', + 'encryptedCollection', ]; protected $casts = [ @@ -52,5 +56,9 @@ class Casting extends Eloquent 'datetimeWithFormatField' => 'datetime:j.n.Y H:i', 'immutableDatetimeField' => 'immutable_datetime', 'immutableDatetimeWithFormatField' => 'immutable_datetime:j.n.Y H:i', + 'encryptedString' => 'encrypted', + 'encryptedArray' => 'encrypted:array', + 'encryptedObject' => 'encrypted:object', + 'encryptedCollection' => 'encrypted:collection', ]; } diff --git a/tests/QueueTest.php b/tests/QueueTest.php index c23e711ab..2236fba1b 100644 --- a/tests/QueueTest.php +++ b/tests/QueueTest.php @@ -27,6 +27,8 @@ public function setUp(): void // Always start with a clean slate Queue::getDatabase()->table(Config::get('queue.connections.database.table'))->truncate(); Queue::getDatabase()->table(Config::get('queue.failed.table'))->truncate(); + + Carbon::setTestNow(Carbon::now()); } public function testQueueJobLifeCycle(): void @@ -147,7 +149,6 @@ public function testQueueDeleteReserved(): void public function testQueueRelease(): void { - Carbon::setTestNow(); $queue = 'test'; $delay = 123; Queue::push($queue, ['action' => 'QueueRelease'], 'test'); From 749a2d082526706a60240d2fd712d97bb7a84b1e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 16 Jan 2024 18:06:53 +0100 Subject: [PATCH 149/446] Update changelog --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8e4d01e25..6f9454df8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,10 @@ All notable changes to this project will be documented in this file. * Move documentation to the mongodb.com domain at [https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/) +## [4.1.1] + +* Fix casting issues by [@stubbo](https://github.com/stubbo) in [#2705](https://github.com/mongodb/laravel-mongodb/pull/2705) + ## [4.1.0] - 2023-12-14 * PHPORM-100 Support query on numerical field names by [@GromNaN](https://github.com/GromNaN) in [#2642](https://github.com/mongodb/laravel-mongodb/pull/2642) From da11d4d120cd864c1b3a833a989f1cf212dbd372 Mon Sep 17 00:00:00 2001 From: Richard Fila Date: Wed, 17 Jan 2024 09:52:40 +0000 Subject: [PATCH 150/446] Reset `Model::$unset` when a model is saved or refreshed (#2709) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Override save() and refresh() functions to clear $this->unset * Add tests reset Model::$unset when a model is saved or refreshed --------- Co-authored-by: Richard Fila <“richardfila@capuk.org”> Co-authored-by: Jérôme Tamarelle --- CHANGELOG.md | 3 ++- src/Eloquent/Model.php | 26 ++++++++++++++++++++++++++ tests/ModelTest.php | 15 +++++++++++++++ 3 files changed, 43 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 27ab3d4d3..99b7bab08 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,9 @@ # Changelog All notable changes to this project will be documented in this file. -## [4.0.3] - unreleased +## [4.0.3] - 2024-01-17 +- Reset `Model::$unset` when a model is saved or refreshed [#2709](https://github.com/mongodb/laravel-mongodb/pull/2709) by [@richardfila](https://github.com/richardfila) ## [4.0.2] - 2023-11-03 diff --git a/src/Eloquent/Model.php b/src/Eloquent/Model.php index 05a20bb31..a4797f16d 100644 --- a/src/Eloquent/Model.php +++ b/src/Eloquent/Model.php @@ -614,4 +614,30 @@ protected function addCastAttributesToArray(array $attributes, array $mutatedAtt return $attributes; } + + /** + * {@inheritDoc} + */ + public function save(array $options = []) + { + $saved = parent::save($options); + + // Clear list of unset fields + $this->unset = []; + + return $saved; + } + + /** + * {@inheritDoc} + */ + public function refresh() + { + parent::refresh(); + + // Clear list of unset fields + $this->unset = []; + + return $this; + } } diff --git a/tests/ModelTest.php b/tests/ModelTest.php index afa95c203..b979be1a8 100644 --- a/tests/ModelTest.php +++ b/tests/ModelTest.php @@ -496,8 +496,10 @@ public function testUnset(): void $user1->unset('note1'); $this->assertFalse(isset($user1->note1)); + $this->assertTrue($user1->isDirty()); $user1->save(); + $this->assertFalse($user1->isDirty()); $this->assertFalse(isset($user1->note1)); $this->assertTrue(isset($user1->note2)); @@ -526,6 +528,19 @@ public function testUnset(): void $this->assertFalse(isset($user2->note2)); } + public function testUnsetRefresh(): void + { + $user = User::create(['name' => 'John Doe', 'note' => 'ABC']); + $user->save(); + $user->unset('note'); + $this->assertTrue($user->isDirty()); + + $user->refresh(); + + $this->assertSame('ABC', $user->note); + $this->assertFalse($user->isDirty()); + } + public function testUnsetAndSet(): void { $user = User::create(['name' => 'John Doe', 'note1' => 'ABC', 'note2' => 'DEF']); From 8a66967c6292f8cb880baab6f4ecc630425ddcc8 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 23 Jan 2024 08:42:18 +0100 Subject: [PATCH 151/446] Bump actions/cache from 3 to 4 (#2711) Bumps [actions/cache](https://github.com/actions/cache) from 3 to 4. - [Release notes](https://github.com/actions/cache/releases) - [Changelog](https://github.com/actions/cache/blob/main/RELEASES.md) - [Commits](https://github.com/actions/cache/compare/v3...v4) --- updated-dependencies: - dependency-name: actions/cache dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/build-ci.yml | 2 +- .github/workflows/coding-standards.yml | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/build-ci.yml b/.github/workflows/build-ci.yml index c6cc2588b..55cf0f773 100644 --- a/.github/workflows/build-ci.yml +++ b/.github/workflows/build-ci.yml @@ -63,7 +63,7 @@ jobs: run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT - name: "Cache Composer dependencies" - uses: "actions/cache@v3" + uses: "actions/cache@v4" with: path: ${{ steps.composer-cache.outputs.dir }} key: "${{ matrix.os }}-composer-${{ hashFiles('**/composer.json') }}" diff --git a/.github/workflows/coding-standards.yml b/.github/workflows/coding-standards.yml index aa359be3d..14202e858 100644 --- a/.github/workflows/coding-standards.yml +++ b/.github/workflows/coding-standards.yml @@ -31,7 +31,7 @@ jobs: key: "extcache-v1" - name: "Cache extensions" - uses: "actions/cache@v3" + uses: "actions/cache@v4" with: path: ${{ steps.extcache.outputs.dir }} key: ${{ steps.extcache.outputs.key }} @@ -90,7 +90,7 @@ jobs: - name: Cache dependencies id: composer-cache - uses: actions/cache@v3 + uses: actions/cache@v4 with: path: ./vendor key: composer-${{ hashFiles('**/composer.lock') }} @@ -100,7 +100,7 @@ jobs: - name: Restore cache PHPStan results id: phpstan-cache-restore - uses: actions/cache/restore@v3 + uses: actions/cache/restore@v4 with: path: .cache key: "phpstan-result-cache-${{ github.run_id }}" @@ -113,7 +113,7 @@ jobs: - name: Save cache PHPStan results id: phpstan-cache-save if: always() - uses: actions/cache/save@v3 + uses: actions/cache/save@v4 with: path: .cache key: ${{ steps.phpstan-cache-restore.outputs.cache-primary-key }} From 1251a2db4a5915c6d108ab2d4c5302e0afa882e3 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 24 Jan 2024 04:08:37 -0500 Subject: [PATCH 152/446] DOCSP-35401: docs landing page (#2710) --- docs/index.txt | 126 ++++++++++++++++++++++++++++++++++--------------- 1 file changed, 88 insertions(+), 38 deletions(-) diff --git a/docs/index.txt b/docs/index.txt index e58ba3532..a6fcb8038 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -7,64 +7,114 @@ Laravel MongoDB :values: reference .. meta:: - :keywords: php framework, odm + :keywords: php framework, odm, eloquent, query builder -This package adds functionalities to the Eloquent model and Query builder for -MongoDB, using the original Laravel API. -*This library extends the original Laravel classes, so it uses exactly the -same methods.* +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /install + /eloquent-models + /query-builder + /user-authentication + /queues + /transactions + /upgrade + +Introduction +------------ + +Welcome to the documentation site for the official {+odm-long+}. +This package extends methods in the PHP Laravel API to work with MongoDB as +a datastore in your Laravel application. {+odm-short+} allows you to use +Laravel Eloquent and Query Builder syntax to work with your MongoDB data. + +.. note:: + + This documentation describes the ``mongodb/laravel-mongodb`` package, + formerly named ``jenssegers/mongodb``. This package is now owned and + maintained by MongoDB, Inc. and is compatible with Laravel 10.x and + later. + + To find versions of the package compatible with older versions of Laravel, + see the `Laravel Version Compatibility `__ + table. + +Getting Started +--------------- + +Learn how to install and configure your app to MongoDB by using the +{+odm-short+} in the :ref:`laravel-install` section. + +Fundamentals +------------ -This package was renamed to ``mongodb/laravel-mongodb`` because of a transfer -of ownership to MongoDB, Inc. It is compatible with Laravel 10.x. For older -versions of Laravel, please see the `old versions `__. +To learn how to perform the following tasks by using the {+odm-short+}, +see the following content: -- :ref:`laravel-install` - :ref:`laravel-eloquent-models` - :ref:`laravel-query-builder` - :ref:`laravel-user-authentication` - :ref:`laravel-queues` - :ref:`laravel-transactions` -- :ref:`laravel-upgrading` + +Upgrade Versions +---------------- + +Learn what changes you might need to make to your application to upgrade +versions in the :ref:`laravel-upgrading` section. Reporting Issues ---------------- -Think you’ve found a bug in the library? Want to see a new feature? Please open a case in our issue management tool, JIRA: +We are lucky to have a vibrant PHP community that includes users of varying +experience with MongoDB PHP Library and {+odm-short+}. To get support for +general questions, search or post in the +`MongoDB Community Forums `__. -- `Create an account and login `__ -- Navigate to the `PHPORM `__ project. -- Click Create -- Please provide as much information as possible about the issue type and how to reproduce it. +To learn more about MongoDB support options, see the +`Technical Support `__ page. -Note: All reported issues in JIRA project are public. -For general questions and support requests, please use one of MongoDB's -:manual:`Technical Support ` channels. +Bugs / Feature Requests +----------------------- -Security Vulnerabilities -~~~~~~~~~~~~~~~~~~~~~~~~ +If you've found a bug or want to see a new feature in {+odm-short+}, +please report it in the GitHub issues section of the +`mongodb/laravel-mongodb `__ +repository. -If you've identified a security vulnerability in a driver or any other MongoDB -project, please report it according to the instructions in -:manual:`Create a Vulnerability Report `. +If you want to contribute code, see the following section for instructions on +submitting pull requests. +To report a bug or request a new feature, perform the following steps: -Development ------------ +1. Visit the `GitHub issues `__ + section and search for any similar issues or bugs. +#. If you find a matching issue, you can reply to the thread to report that + you have a similar issue or request. +#. If you cannot find a matching issue, click :guilabel:`New issue` and select + the appropriate issue type. +#. If you selected "Bug report" or "Feature request", please provide as much + information as possible about the issue. Click :guilabel:`Submit new issue` + to complete your submission. -Development is tracked in the `PHPORM `__ -project in MongoDB's JIRA. Documentation for contributing to this project may -be found in `CONTRIBUTING.md `__. +If you've identified a security vulnerability in any official MongoDB +product, please report it according to the instructions found in the +:manual:`Create a Vulnerability Report page `. -.. toctree:: - :titlesonly: - :maxdepth: 1 +For general questions and support requests, please use one of MongoDB's +:manual:`Technical Support ` channels. - /install - /eloquent-models - /query-builder - /user-authentication - /queues - /transactions - /upgrade +Pull Requests +------------- + +We are happy to accept contributions to help improve the {+odm-short+}. + +We track current development in `PHPORM `__ +MongoDB JIRA project. + +To learn more about contributing to this project, see the +`CONTRIBUTING.md `__ +guide on GitHub. From 90ff337d2f13706ecc492b6e239ac07cd523e39b Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 24 Jan 2024 15:15:44 -0500 Subject: [PATCH 153/446] DOCSP-35866: update the link to the compatibility table for older versions --- docs/index.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.txt b/docs/index.txt index a6fcb8038..3a6a42fd3 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -37,8 +37,8 @@ Laravel Eloquent and Query Builder syntax to work with your MongoDB data. later. To find versions of the package compatible with older versions of Laravel, - see the `Laravel Version Compatibility `__ - table. + see `Laravel Version Compatibility `__ + on GitHub. Getting Started --------------- From 0f3d8409b57fd0c1514e56167851306e426f6eea Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Fri, 26 Jan 2024 09:32:47 -0500 Subject: [PATCH 154/446] DOCSP-35892: quick start docs --- .../atlas_connection_select_cluster.png | Bin 0 -> 35481 bytes docs/includes/quick-start/troubleshoot.rst | 7 ++ docs/index.txt | 10 ++- docs/install.txt | 82 ------------------ docs/quick-start.txt | 51 +++++++++++ docs/quick-start/connect-to-mongodb.txt | 36 ++++++++ .../create-a-connection-string.txt | 61 +++++++++++++ docs/quick-start/create-a-deployment.txt | 37 ++++++++ docs/quick-start/download-and-install.txt | 34 ++++++++ docs/quick-start/next-steps.txt | 26 ++++++ 10 files changed, 261 insertions(+), 83 deletions(-) create mode 100644 docs/includes/figures/atlas_connection_select_cluster.png create mode 100644 docs/includes/quick-start/troubleshoot.rst delete mode 100644 docs/install.txt create mode 100644 docs/quick-start.txt create mode 100644 docs/quick-start/connect-to-mongodb.txt create mode 100644 docs/quick-start/create-a-connection-string.txt create mode 100644 docs/quick-start/create-a-deployment.txt create mode 100644 docs/quick-start/download-and-install.txt create mode 100644 docs/quick-start/next-steps.txt diff --git a/docs/includes/figures/atlas_connection_select_cluster.png b/docs/includes/figures/atlas_connection_select_cluster.png new file mode 100644 index 0000000000000000000000000000000000000000..52d827d67bf9a46e30671df001d144f4538c4695 GIT binary patch literal 35481 zcmV)mK%T#eP)Px#V^B;~MfUdf?(gvF_4VWAoa^z-oY@%8rh z^YZcwSwrCR@899#hKr5p>FUnY)Xnzq8YL<(d1143{NTYuRoMbygnt?jl!5%i&wdO9Ab+W7#LFgx`l zU*N;8-~V?;-|sdeemfLPeeLeYW2S-^w14i>UBBBIcz@OCd6eN(DS&Vvwz&A^Q0yoZ zRb@;ZkN4Vcg!(ZPvD+X1#!UznIoD#Qxy>g8(pWBJmZ z`ZGE0-+ADzio#k?wgNEEo8_O!rYir3_UV9fQyxO0QX%=*6k2%_8-_kLrDAJ}?@=7| z7Z|KRasx}(-znK!=-K5EULP!3*s5G}ED!KP?uY4S@#Q)PtKy7dxrz`h33KaaNhDo52oqfq06s|s<@b7f`vIRz6<6q6k)46tjxy87A-%h{DcE8f7 z4h4OwmbG%BWC6cG!Z%bok(5{RM3re-qC4byF(y8Pn=c1uqqp1K@NZ{d&LYZhcJa+D z;6Hg(6jo|4#)z%jyKBl#QR=q%*O#aCta0@SzjY|EHFg}a2!NiED$}trkaK0V(-#i5 zHPaJvBK9TdOh2+pRjYR~hL}(bo#!?u?KddCAQbf%M$MHvFESQ*^7Ry| zISMV}Llwdk*7;~H)tHo+?5Y%0s@Vs>>_gCNsv&0y{rH`|#WG09l9IJn^(ri?@-9q` zFOtxxUCt1duiI@Pd_WQ8$vpuK$=4P15}u=U7!yt!o^E$laI`~Zr;L-X?yCA03XIN% zo}EK+7U8g@@31oqkxc|x%_{N|-TWTx$6~F-e_oPaiwj>8_d67g!P-SB`S}Hkwk}Li zC~93%@yJlrFWU6@QHoiyP2}jYCyvMDD$6{CLN3SSRV{*ixjBj) z^x8M8@#U^TYgLKX9v@M;U+i**f?y#v9diB~27Zh0hy6nVESHwVUS;3h4#S{S?y%D4 z-;`r@_{XY3U6W`%^vp+rLVTO|t7|QxzCz*7UxkDF^?IRo!sF?3y_`)i&hjik#zH^% z?Dk7xW`7YZg2Uq{ES!MeULE?Uf@{%_YJov*89z#MM|iwucl&#YYqeGz+{W8D#>PXV z=j4acH)+Vp#mh#(Iur;pmzl_HxJvR5wGkA0^M^L1Tz$N=uw0;E&Zd0uWU}_i{(800 z_G-KY5xCeW^%>3WHb8SE-DaOpQ~|;*Rj#wI z1&YUI3J3-76V&G8<$jzl@J-I3K)qcfVLEY+HR{1#?)O^!cTg<$Ny^fK4l%tKLBK~d z5F#2HQtHFT5Wz#dr8$8iK*5zxBL_rq-F<(6`ZJtjOC+Ng z;%PH;1#uu0LF&7{ieR}4-1CtP(+4kT!+GCC@#PO3`|Erfdf@0C?Th_ zyj<^KE{WqXwv1$aCVY$E#niQ6eb6>T6VtrMbavgKn50A;Ziz~Y z)$RC*In6!eJH{-bejaUnbGI5)BE^Ud;?rzOAuSHy9dT7v>UtA$cTDuw33#80Da^4EZ?Dc#1_#Nm@Q> z`Pa7@5T%>oFNTpZ%E-NSY1|{hcipXQACp)N_m~5GMTVlkDHHa5rAA=<-^S!5&3=Ib zyVO8=NeP5wgJQ*96ezNNx;rhIX+qsR)y{Df%ZodNfUqbOFjiCDRDsL@j+!^vy33@# zAXNXtJ{2fZi=am`i(e=hus#5a0de2V5Dy9imOYn|P`HjSDm}fu9iFOzN5!O-p&}t_6|^ZHJM0gfyQebJDv2E z*bZu+@F9&Vh1w@VF+;dUelRV-=APb_f-TvL(Qq|3q+CHj_#*=$>?en_f#s~eicmP2 z?A}4(KxXvOIcp__k2Vj_&Ua9-MnJ^RgSy{aY#HcCo$2PdgixqJ@FiE2q8+kjf|4|N zrOPF%d2)H9-kWjB4bV0FB-)sbe$_s4Tv%hD^bwU6smMjeSzfLgV!G1E+zd%z2-6?U zY%wtXV<7sG^AYpin4)Nl0rAOW0TlQr#p7UmJF=6J3=VEj{0Jxp-eNzN)FX}~Hd!gZ z)=dHoj>@$tMTP==G#z&_jvEIbmK$?fKSSZ{Dm8y=bU7l>-ATiqH3W-?%4ttlKS z$~6VD@on(5;<5EK+iwTR4RLPPN}XJ2vvkqrTKB0gQZZex;DLqq>5{98^9K}O_M_JA zBlZwF&_vgv>Xv=%$JX@?vrF5JSh(D8!f`YdJv>u?*ik8{3^U$AWrz*8!|@=U^f(=j za+KRtEX!tO5A&>t&og|0&bERwwPWTpEg>q>#B*5(ks5vxC(AwYo;xG}Y| zns9JSaMF=H;Cbq?A#rUmrnow@R0kU!-qXKuS?-#!3xl|m0Kf^5LA!qai|n|F_yqB;-`kq$vcR49tFEcpNb^7WBGKyY+deLFMh+4Vrqq`$t>N#mI+ z))b?GWc-M=T^zZr(Yhi{ksoV{(8hb#N zSKN2hW9axEIJ(67=U}|}mjpgK8XaelAqbB9Cltq><~s@R%gAyPXpkWxa7^dJU#yVGRX~Q#v*aLmwqaKb*i6dpfinhaE|Yb6PGhp;fd{IYX^F>^ zgw#NVu9_j630nxj4esT+yKv?o(k?GgBCbvr%qJ94$bJr5j>AY}q|tmz{IUf-rF3v7 zXUzNQwxtnl%OetKDiA2hCT1U7yKiahqE9Fwb-V56^AskUg1`V1P`HF=73Q)zskUd+ zsB+@XjbMqqH!>2J2YsomPXM>!vJ3f;5bj3kG%f{XDc~> zF8PL%TY@HQWg;kU(>&NzBJtl!Mu%i&ke49y1t2{VS~voewxt&H37vB?t5X`kqu+Xl zO_|N&d;5Exb*CqQVn%2?WY#A{y_7b=<(VTrl8|A-Nk$;?pFZs@fZ0fdJo+S$z+#$K-p;*$FE5viOy>QC2OU6z_Huuo`+RyQW#6WMq_m zubV32apiKKqCEeMqwRGCDF9RqgYtl~?=K}O4uhZi9$}#SbBDe|*Y)(Kb=lRp8M+Gv zr@Fqzt+QlQCzA6&>CDW!MCx}a_l;U%W#qg~@C58;@EjzQf#Eb^@1qF=NDd61eU{&D(n|c1F`}#&; zcvUpcI*RluO~Jyjzf32&WHJdj8AN98zCk{$OYSGXi=C5?Gs64@5)ME<-I>E|{(Lfv z^mU-f*X~Mgc;d?5G2c{B_U1i3VaG*If(mHwv+EzkK4a~CFPZ~(gMp< zCwx^;sHs+apZzpU%#95Dp^&Wq;Fo#|YyzcjIbd2LZ&EYwZF2JeZ=`UU{x8-^i1Z^s z;RfsGpjhU|u((55S9QA5%a3cN6;MPD`k~$J(_L7!*-c{31{UAyuWm)(+t)(invKv7needSsbj0*VhD z6DiV<21TSu5fqUk{VGsIiWDj4DMX4CHO0RqfMP3r1KLE26lp@ye2Nq)MxSE)Mv9&G zKRIiI(-s>ef+A7`Lj*;nND&l~B1KR{`eUDBW>UrWj-dGEprEDPV1kL*-Vqf4jMJ+^ z`8{LJoB6hX%e%wjCNqaaqP3s?u7X)7>WTA2`evZ`cjRBDR@g|**m1`E%bcZoFSUX+Vd2)}l`P!Q~=r1wMy`4}-Pa z0=)qq6aW)Y01V9gltbVz2U;^6Qum?_*bxv*@(}}=K9zdw;h$*(CFSmTq30E*;9>&I@m8vAjGQT3Ve%$V1~6OZL_N+G zuyds&$69&2X+1uGdrda6=z?YHUgA@|#cBKU)ZZu0puWKwAGaA6DoGH7vM~cvdWI-X z^+4m+8R7O+!?Oq%_7K}?Hw6Wv0z_|(UPWNOh3*WDCfp0!biRPmn=tWJ70TZMisffi zZ)1J6Y8_aqW|%D$vLF_So_Om1GPY%y0Q>|K}&4DY!jke!kxmefn_VVjUIyx?HA|57Eq@JNLRn@y&u<{;19=eHn-< zpzeG@U@6|Mp1Mnr>&Zpr!g58Ja{u7J+_tC+mmPWz6ye{(!glxfe;yScc(9^9zTphd z7X{=$hKlu{tD?#l>?fAE6PdjW5Hb{v9{{tP7LjkXfv20qgTkM0IJcQbm;lx=F<)0p zy{I3b=&(n5S^Z_deKSy01yV&7LB%S`oDpoKw!2jFwPT5MS-zYL)wz<-Aa$vH0rZ4F zNzqd^9{(WaHow=p9p392D4L-jyyO3)uZ1l%LSq-Y$MkLgY?W#DUFL=ppBw!Q8RX`8 zQqJDaSRhJ)_wMmY6FZUGj}$RdQr2Es-}rgXs>lwZH*nR`oDNYzEyB#Y$}q~c^HWX$ z2v-PO*vuE0p?X%nG?_1E58oXW1yiN@S*RQ;wIh^exi=msNm1mUW99J^SD$TDG99d| zg@-MayVlRZ6;OS$T-DtgUl~GpztV{ailczy*j`$G#}AkGcx*0A_^oO#J?+$98rj&0 z_Gnz_=W$RpZQBy6*k~GKP^2l?aaTs;E-4HPTf6u#^Hx=thU-G%rbJm4mQ}m200?WP ziwsZ!!p!q4bqCn8s{BZd3JT9E+ttFU+3+&fo_tVKi0`ATs-z0KD4Y0HEt z_~x1-_n>f8`K?!?PKyzLxL(8Zc7vSCZO8jv<*DD10BCS(ub zcd`-P=%utJ)J6>)SVA&%Ui;?R>?)ayZHnYP!!5twQ21vgJm~sb0cy(*Rpz0q@TaOuOjUFUk+MTg&23D3 zLfO&phWy~FJLs;eiV~`>G}6Zpmpv`zF1l5gzze{AP#}9=w#4-*vpymK%^c#`BZGpK z#2GO|pcn=i8vP_FQr0*GI5yEPErRdd;|cpq-}c1vEg=T28BLpz|N9>I>RSy>-_m>9 z_LmkEXgVGtfqOOZrLqFpotW>jFRHrO19ebQlnj^6sRY>IwacPL=G_-%Q5AGhSC$o` zpsTT0XgmFiHe6kr2aO#iAk>5jghE~5zpAeAQU>qhP#oxXx~@K9_uz)j&+sWOQ&51g z`V}AkT3-)!jqiK>UPE!M87sKCppKwDO?9QOfIAWGOMas-C0IMFLVA~yF0kU3c%q^o z7iTd9pg?v+)=&Fw>jXJNAr(*{Vu)Xl4ck9nQ)mtL2~dDWP^AB{cP&bat3WiO5ZJ_b z%9^q)_y7O$p3@B^&O}FN-B~l2j^;ryiJ=eOO*bG|qgaC2c+<=6R8a#50yaCK!$61I z{puEGw*wR*ISgdg8`L)W!O}v@;t6hkoto=`iFqQb<;kA6*0^rlEjyrKx!qz5o(I!{ zDO<>#{dP$OZ4F(D0CMXsaA3{pBpKJ+?!4`6%S>~7pB#@4$o*C&le2Pr=y9gwWwvV^ zpU&sgw%hNw`|dP-P@EMK$EZGuf-9hCPXxnq-E@CG}dx#aCO|KG3y_qJ{_}7Av`Cb*o&lqB8<0cx{er$mURno zsL4S1tfRSoh6n+2+BN~@)OkM|mT^;o+TS|gw%4MGA}BVowg&6%L}voWEe7fnt#FzG znzVTU6hlkgW=Ww^=eSsKhfI&v!3G8kQl(ORUS!C|8XyNKfRrE@7PKyou@T_+FAA2c zmTyivZ}Fy4(K}kY4qUoqNi|aEt0fF}7h10g7ie28<%xoUq-RmZZBKjay}i!~5!k%7 zrZvOR0b{`$X1%p)MGzFcIziDuhWr#zL~_xrB1^ZZ{8NPlh4iFq)4qj*YOsw~mVjc( zL?T5bM$0#bbev0`iu)gQe-1Yd?eXC8(1Su*pX_<0Fko#xv?-|X{H8h1lgDUjA0%$} z0soW{n_@?1-(|ynLm|b~gYnfKJT8)i_WT%G9|6MZ%1lT*9@kV zXrZ9MVpA?Od$qK_S9_Z@2r#m=*R{FqMN+rts3TZcj8Fz~dAWPTuDV)`hY2 zQwP?>}4ZlT$ z*$gDbLPW)ZK_J>BI{?M)_jCb@irmeMZv=S+2lXQu3zGb1r1c5AJBWfK9z#LlVSZCW z?0HNjZ+AHCcE69XIe?wxFBs&v8-~GztgBHfhW5l-D*Uruu?}-`2vY&YWss~4Yg)(* zQEaG9L57?2sfBU{-Imq8yR&TKL+v32%({cl6hUFAu5}3%(Al6-5F{b_cYlDNVwsxo zXef7Ua7x!fZlJC~Mrcgl!DfKv;0X#aJF=7U=S)Oyob1G=ShAcbMWm7ZLEqhtVhUnt zf0PzvT62j0>lBzrRqD_?*fzc6dDA2}cZ|+xKLN#Me5^(=)A4ya=qx?(9585fje1PIqSO6coFb z8M2pqlIoMyFpu7O7oDSQ%UDH?Q<*}OK1Oet82Qwgcaf}v-VZV4V{UIc8dF%S?G*_VVb#ZwYy@nQv@l+y zKr}XeA>Fqj1w!SF!K+0gzI5{i&kf8r*c%#Pds|Y(4O{&nAgrn^&P3m-_3cW07H$>2 zNop7;cisy3c9tb*xoQ19TI0J1Fl{b+!Kamy57BXgk0pbAQn|gjq_D9Ej#hBGr&Mb%g8vSqVci!ArfFhA z+t@p-iPT|_A%1=k`Xtu6_N$QCTsg|`)Wr@?;Kmr;6rwN9NT{GAe}>pW>eEo901IAy zcA~EcC?s-NeWw`)dE5l6<;UmfqmqKgFvUWC1QK!~$C!>VaB-wCUAdL`%_lHjXmvBa z9yoAV*c3Sy`UchGf5Z+1!e-MWU^51Y zVaWI5(AX<2p&vy>#8%G@Y z`x>>^6Ix^Kr?Jn2iNrNqun82yAoV6|Zwu)Tt5CA)e@G4f8a*4^{v}Q|x>E}POU+9$878sGp+xzzP$cBQI6NY0!dXX4pQI^9K1(K`}TJ4FKQw^n0(DZH5Y($-_eR zef|V5{I#^edOPe>k@|OEM@4nplkrV2eELJU-5Q?evZL)pUs@c&X*iD4qXTr@0}4o@ zi#|nvPK!}8_L?{St991s+;Ox{I}J2S6u$0$FsjK{yxsvcn2t= z&EXcu-FMK@+-B}Cydle0tNiVUoO=DT{WqYP{)oWUP&$l{K5{vV#f8~?$B>n=*@>X| z^$p8)P<)jX4chF*rSkv#p`bq>t7r0{7{&J0e|9kh(*r|@NnfBvbWv=cMR%xA&*FpX zZjJGO4vOgyO8zh?zN$yp(xe%*38_ha?((*8k6mPk_aZyJ^X_2uG>&y(2Hy1Wot*l2 zZe@Q4D5hpXeAOr%YifIhfmq^o9{bNWX+)`Uw|SEt=8N3u#2@HzI87dYM@BjrJV&U$ zi_@!TRvN>Wjh_gLsbKvpMfWwHu!Es4W1}e~MdJF+NEAsk;zRG<0NNm+;JjpPn84oylve+)={fN%}>NFMWPh8Y}K;gJ}NN1aT zFn~l8KYC;fj}}SsBP4|x`ly?CuxQ3bLo=G#6i^gUOx13`pxQL6=1EjQ@ejDHE%a=f zmsc=ts^;x{5+AZ!-h1Wcxv0>8U6yZMCMGH7^VO>_D}MQ$jUIiK^7ZCr`R1jXPl{Hr zPr}9@j=%6J^slIz(6i3)Q3|iSQZiWbjxmGHr-v8I`~O?MfA_1aYBm*G@e`D0ue++l ztgh=BmO4J_mlxe!T)uq&?pIe;tj}J1g|(BdboL!CueK6$x?y}^T0LQ@LRr3P0ka9e zz3__bSpRyTyAaFAzRt=A-CTH7p5V#Pqom;SA@{g0-@o4{dKGJ}Q{d#ctZnq%fH9!%jLNk6! zs8*qG0!2NARRKkz?^B;a^_O-_zxsRRi9e3l|I`#BnTF#PkgCs|-N!ZVM*o~CuYB|o?pA3rkQ`7a6KlVx9 zUrv>9Wp>>U1DjVLa#wkp>0!#pD_!jMlZFirsaY;AowIme-|FL&1I+Ef@5WId-XnMT#l!egI_5Xi)5s@}kGuLx>xR z4rl9%BCD!*K$dr<|XR0-O5Np#V! z?i^PPT^t9Q(X%@qU^8VK2ric0hAmMw@Hf4i6cdd$*0@*Tr`qq%Vb>s>POjtENfAj1 zoA1B#5W1z)^h9zlHPs;-svA-1FpgMuc4lhC84ak1toX}r#V4c~WW0oOzk>n(e!qLS z-+Am_b^P?+s_vL}`$cCpy|oXCGVIbJ;aS@6fM8Vt;#|GoYio{*3OK4@eV|a#RtFlD z-lsYTP4NL+$~4Xtd>crxR)wNC=FCp4kJ>Kf*c!LKAWOYRC&3!kMT#>>foU{$yZ`VD zVr*KVIopQu^mMqNjzu@5UJR|n>gse+$$ak9HHBIDM32xX*w(T))b53_tSsPTJuVi{ zYGMf(#5ZT=-coF`(jlvpf+vzG@wHSTo~)zJfG9sW<5ML>tM9${q3tA134E z!=ZlOW9~w8O{|41vUa_jStd>LSG{q)0CcU>Z|b3(dhT6s z5k?X+L2acNf`8Ez4S-dq40X@0^F|8Ywu_e%*LoT{J%s*3w}eEXH_kr%b0Cz`goqeT z!_Y9J_f1j+GqtL-@$cS0M|F|nBuD!QutsOblx&~a!%G5lhc!u&Of|Ug!cb1Wv|7Yt zX(Dzr%HmH=rJPC%#_OjB^Sw4w1lLMJ3+HCKtOig3vECo0&9DR&uYd(s)iHgLLO~xv z&qz^CBDD^k-Dd4{pTikNObzKny@y7MDqo{8gi1@uNuh`o)fnTWMA^7`d+URj!qi9+ z)k&3|w;SX4HmZvhXRT8Zv`#TZz75@tdQvu@NG?q4dGNzD4gh6}c}#IkDU5NnNNq-= zJmGX2j>W!XA#j@D2985x4w{T@B_vJ%LvZ#dK1G{{tC<_!y%s4n)sh;elxCS1^T6o| z)P7CVFWZ;qW}wloMy;e)X53W&PAk8fY16D7Isu_JXWFK5FUS6e-mA>5!j+XGV@EAY z8%PJZb29zH;MsrIBZWaLFCTpGeVgAcjy^Q1ixlUPA|+qeWx3sMkIlOz7z4t?7^nio z5SS4-0~Po;vY6N=%+X%P0PY0b0`QO18#t6;#Gs*@Lm;WrTL`GMh*TI)Bn5|)Cm#>l0(jI-1t#2N*NFipKi_sO& zAw;0nfan}-;L$J~1Mx<=yE7L=VWmMAKbqgOffN~1U9_Os!}_YCaisxxk>WH`$ZK#b z8DYm7L<#^KkcR%4(~#nfqK=s{ef-<>o(s%$ut%t8zzHsMjnSoHVoWQ54!kAIGZ+)K zdZslea3_V+NFiDT|Lsc%ipB&BtR6L*k9YsRRq(^D_|o$p#l2A z^H!QfriUzDsDuy0V2;Y6h{UFVG$`W(wqUgU3a$p)t-=-<8`2Ujtw-w`E;1eJ%^Yy@(XUh?}-r zA2WUjFM)VLr*0qQmsxKZbmI5^cUp<|vDHxU|e3dlUvjLS;C#+h!9&`E#(nt?U zV0}p(w3NYM$$a@p)9Y)4dT+$2Tq@o>B;^9Oo2R2w$+vg3gd=$`^PL)mDkE^YXY@t3 z8Va3&XOdAR6Z_-!K}tuHzJ+g7%XuTcZWQKc|%G zPfxKB&}CVmDS&4`lN5k_At_*5pi)|31xuENIs$s(w(_GoRMQGkO#vyKguwe4WA1By zXXHLj${FQ+{Ytk;hV(u?Q>KTU9 za3z$V=V(vvwr!=XnA@QkW`>Den2Z!edY#Fa586u)pq!*|(NQ-*&66RZ03CEPVOb!n zn@^(5vaBRUBq?Ut-f29I6oVyWw=D3XZ!?%QlegJ5%1X)1%syDrxR9Hz)U=7EZ%+-{ z4PfCXZ?2;m6lKkrk~-ubN(Kmy#-U_VWYn?3>YvHq(|3}awrbRnN(lDDB!^a%8D>V9 z;f2Z98$3?(DTq(=85TulZ@#5^kQAK$mt~%B%LcDmPQ+5l12@6rASvKbte*CjkMPG~ zGXeTW3i#C`1=UE?6yC*n`r_Tse%rtK*`Mzv`uv(+KKXrpgM9-aB7aoZk;PZ79o7sot8Q-CEKbVF$&*>C@FFmY!KuhyAMe#`3Kra-{Y&VBi_ zy3v6UUtJ5yez}=8@$@Oa%@--I<99Hh0to3j2g)5Ga?aO)WNV1%d*7+jNMuAp)Wqt@son>iy= z5o3rKDX!zUAcZzSDA|wMJhQXCK%)R3xTY{LR|!)+-3(^OqQr!9@<2P2U{|36x*=um zp^!=#?ePX&XJs~RQhIH?NO2v%iKA_sfL!we;_D9V{@AnBo?*}*=Olzj?ZYsr>j5}Z zf5KCL?1!Bn&jm@p@_?I*6xZ>WIocin+Fu%ur`Yt(b5U?_JLcj)*}E3q#&I3$Xhd7C zcQ=Mp7>04N{{O$cI)|hrXVNJagLxrwryV;{EV<xG7a##l?Q}g_7r8_9_d2z|U zjz7bvaItoSX)Ls8rW*J%Bw9HOERWkPB4<2sAStm&@7dj<&}Bko+UdNvjeJadmMGL6iH1suSWZbeU+`V(6SpceptNNitbcf2OIW`oV z-*f!8tRRKl<$FM;${iNEdpT>R<`hnwwpc)GD=i zO~Rpa)SM%cluk*fdcvG(trT&8oP?AO#?*G?r<#kJhK{@m%Fb^EG}xqPj_Mf{OhB?5 zh~_$hRKaqSER9J{BHz`ds^nR--n*t2`h(fC-eX$iG(!j|7c5&mSq+S*gbd3g=t>+y zu0c0!=oje#gTE8ZH^9CPx%A~2np0cg8+`4$X=KvfH=q3cu*T?_Bsu-VzfzX4aJ_A} zZ98ta+m%Ai`XyCUG%|iMoTSH~kZoVyLzR~DISAw^AI!0y2;NmtAR{|{$%ERqe{aWj zn}RVZXmZ^62o&NeMx<2WNbI`mA~}QNYtq-e|WH zFlj8b1)e-DniyKzk9RhUp-p=n)2$iSvZKU==6stwXCpY>V^q*|Hj>n4x>g9cMpRQj z%#nO9c2-kdTT9QiXtIJyomE}3_R>8qE({d$H$FH#9pm)C$Y$boh$M5{wskueCd>+W zGzJ<2#Xc|0Hzk?6N{C4dN#XV&V`Gy`V<4FwQ***o12>=Vc{U6%p4LP2wzfR&Bc~B8 ze_7uRsUa%ps%chBjCDyz(g=3*(^|KBVpnkTze=bEI}92j9Kp70y+COM*6`r zVcJAmP?+{?^iPQIQTq0`(luVpvw~B!g8eM4hrZm6;l7OI;BnCu|aAZ>_ME64+1PmPzTF zlJRa7aV@B=(i+TsN(DA@2a2xhry6Z*ts^C7GxXGAmkQv%fw%-@5ch?VA<2`QPiIr5 zwWjX;jbCd-JvN_=bu7uIW)G-s`Zeo{xnac+DS?>mzvlT`+CR84?O8L3BIa}H&*CPo z0jk|Y2D1Vjr=e+BZg6jE3iV@26&FNlYC4BwYuAuX(De{OQS^}nM?$sZPGJJ2?HSw$ z8Qt;shb$kqM-hgb{CBWo9x1dw*`=UG_@vRNdr>#vI>zE#Hy(D>m;J|2_&2qVMVub4 z9t@mE35tukjR!79Hv*NLA@%5xd7YYcTZr>C!=5aWT)7qbUE!^-B?1L~V5nfO{z|EGciH@A00*$_hk zvXw*?tFXE%cV}4Fsf5>XjnP~2)KV8V=0^5u@^(cHkn!#|j^_l$NlAQaCr$O|&w+)j zh;M;H=h&`W~+I9Uo;nexn*ZMThjiv$hJ%n0)m2WF(?~? zsAW{z!DX3>OP*gjxCYVQ$znQONSJt)QUSi79ylJuwWa9ig8EWp_s|lw2LUZve3%Pce_EA zWVzc}1%6e@^LW2&3iZh$=Wjt>?rf|?#>}?Rb$PeF%qY_ygZ&KvU1-gf*F&>1=ZZA2k=xPr-x&$`N! zgCb5J2Ys|k!t|>#5vPaGFcKA;Ti^tRUIhXHY_EaSE6zdEhO$3GXGh(d3rsEbJ&2p`TH+qXh*gby2+$386zPYM^;UDJF_C`TF4< zz0>5^WyC<~rmIAl1_kpBR%blJ!m{%q=2}q@11G>4Cj>0l=-5US+kiKn6(10gZw-!J z;A@j)=;SYQ*uY!|CG@6 zI&yZ+py(VF`E%1s(GV7iI4JBWD*2}3fk=>{VKuiMGN`xlU>C&vCPcyNqy7%^`eA7;1WpT1aVw@uh|x9hQ+%3gYAXzcr0dswpVqSaSs|rbnUBc>`yxMWx)$ z{yAUTUjc?ZUb=(yZ4L?&jN>ZGzdC8MV8nU?1^)P)B}2zW1WvFKUV5a!s7c02T2xAO zQ-t0|EiW1wu+cH8E^}m1h;loZy>tyI;O@}F2s(F*5~x6!n_jVz>ri)GqfZ<|Oj>b6 z@tHrl5W?s=KMVq3aj})Yf;gVobi711s0}x(sc@(j&;+} zT&L%CyZQt@XQ%8qP1rx#&8|>PAFXH`D7f7Y@s@*u)m=>@O#8uSP!$?fX;I^<)7nHd zY%nhd>X>}PFd_23^_em@p~I4>Ma4LSfxe?Y3LNm=*t$e$aW4y&&7pH>K5?7J zkVtsCLvM}G42pSHrevUE)?)+B_)NYUgS=b&Ox!OHAC=U%m7OIXaL7bxKjJDmFxy;1x1SYW6O^IN-f6fRsrXir)isiRt$QIiNIin0l{?Z?Jg9a*C^)x5_`_n_!I zGoR9c*-_1$k)T+DZKO@beA0I6&?0`sT@$)DH&4fAa@CTNmy*{LO;cbsjt1MNpokKz z#N@^F(*jU1&1X|hp&J6#qtT*drXdgp!4Pr2LEo594hqwUx=k3N=+seD z2)2zWD0&T=>E2+@GJ%4yKQAbvYYNmLf&sc@IM94Tp~pi(fLGUiy&Wu6bZiIKh^Sre zLGgojdVHWMIxTJ2H|rFg78}#O3!>7b9x|+VE;OK&Dc{y|aug1{tRdNG8!gP9_uF*V zZcT;?%4U8qsK1h!x)$X2msdem4YcZByb%k2030xgiw|I|6i`}!}hg9+GwZkN*kDITEIM#_;BCnV&np>omaLg2ox(~VTqtX zeQE+wfF|{}#C7;`SC${p(}=`P-=|dDzD^4Hm#>x7*#ZUUTRXN+qyGfmJ2aorYlMa| znAPNzK~SJ?iOMcSz zA$8-^tpETZ07*naR1>dbDGvY$l+<}Fs)1y3#<#sbj%dfyn`l#ba-@P6(mGb?<0BoP z<~-32d2E9E0rn>CZX4$s4BoY<-*X5MZ4;=8a2*~3Gd4V757@GsWXVVlT8mkNAJ>@a zYQ1Aa+jD8fV%Ss0f58L!Ozu~5KPBtPaOyaDj#1%r$;aeS4TKmr6{K^V!l~qPcC0>; z!gr%&`5>yU@XkqnLO($GI&Vg?kIVI-{GIXM@Vfd{y-zTgF`)WJQ-8wrnHf`gsJj>F zm-u^`Xnn=>AV{59u?e2UK|PUwSW>WEp$Q3)iUDbL(}>mu#qfGV5ip#-_^=IDW_vgr zMvsoWX9QAsujsHesJD;cb3Mm%r*RPU8p-pIDIpjmo^=qFH)z*{9sp(N9FRYuDMtg0 z14|P++)TKOnXZMPpzK_-7U1Sbb{&|B0(+RJG0mv(brf7*Qm!l=WmWX4IrhCV1hM|A zy-gGJSzx0E5Y$HZFK!B|+{M_K2LmvB+2Ea~IK?!<^hV7HR3c1%3ojF@PndSrQew>n zUkilc=pro zCG7^C0{WBz=ttNJ`F9)+pQ!a2jdKpSKv)wV^d2V_rkO$=k%@hV*^7g>#Z|JfcvMYz zI0yv;ar70ginj{b@tDr^whlp7^kMXR!)(KF3d+GXC<$6F(j))ydJgzq*_(==2!z{7 zbEGa+Q;X^u=Fkob)G@kj-@c!$mb4xDcPAPd`hC_yH8?Oop>x#J; zt_HkTadg-Pm4+VGu^YwN(I>!18bfz+G3G!=V8mj`_Xg=LbVp~{lj16r9ER=*ybr># zdu33>*&hRP(PnN%jGN|u8YD9XWt`$0CB>ZrwFL^5YHfJ2mb{Og8mMRBz0p*dLs7JL zSq3T&g53-5c6m3Vg~)PDqCJ4qz)@78Lp2r%r09unDb+&3<(D><5P}q%D0-3$gUBNcb?SyoiSQ2$+)#)j7a6r&nnWKN zh(j2HLJr<+_)zB7IQPPa_GY4NoawpJqJK!Y(HF;lmrc=E+S9g6wx~+ZoEk2%5*SNv zORU!Rn22gq!9V8sWXh(@BLLX2kvs;o>3}%^X*lR=*3fzQ+%PjO(6xzDZb6M888;Ni z0V$~$ovj#?0FRXs^PZ2Qi5jkjd98e>pyiy2F-H(3#9aE4I44}AGuoC+QJGjR#d|2E z4)g_%h~-|iNL!T;y(u}a&iDl^NJ^aAO2T;%jH9MSHq$mS9>Hu*i$4S*E^ z7KPs?>CAA9WCl))51_sq!i~qf@@}WnR5e9GOiLwDND(j=u;^>5gFfy4&N#)Fk|I4D z3yvniYGEoi56h_`PTkKWG3|MuPmCE#QryINwPb$EEI4-#x7)hWq%A?Q77COyMSLt>q+$C`?dPt4J0 zB*#+ZrgY)~uc}#FGt?UBJMPGl3XZ5qzLDuGUH$a;Kz(RMona>ONf4LGttM-4#15B< z-6SZS5gcen@U*>b?o%BjOO!Ga3_>RKrJ7U`

4N?~)Xc)h9V|#8Xnx^ocodOvO(h zXH!0&&gY#g6&x42HKRI};Zjhv3V^!O=y%et$#)G^r625mwXP(K&FA%r5gGI+d&UBy zDA+1`&%#{bcR~iV_^kLvb}A?s0g=^Ky)r27jp)8skm@XsZTovOeS8CSPgoP}y+C?Y zWaRF3mdrz+d@T|bzCNG?h0x$t&44U?UMACvxy0})ePTk{FF_$F(*S_;B3!1~=2wNx z;hRT7X+6*EFL0$~D*ap~up|_>TzJX}DSHR>7qls!qOI)PPk0VSDJwpw$mv^A*(xQ2 zba+WcZe-u^Hka(iw#v%*`iM`)sRyU7+M;YXaoJeEPk(o@vBvZFXC4xjRiG{|sUCe^ zd+(M)QanL`U#?fKs;xun?XCQa_vr_hYx`rL235yvvwvgz^7Ek3sY#304gT2jU$v@r z7yjcCSL+dQ8XRSDDD_*RMv~P01^c908brThdl=l?bod7~4x=MzXw&Rp*uMM%D7d#> zM=go!MqObdm)*83Y@k;3o$q2(`rOQmI&VWKum+oYahue}=Ju)7o;dYeO>MSqZjLww z3k~(QYvL=nVePnIG2R`WZP$JG1FHo`47H%6)YiUcuhmGy%)70;T7DfHF zQ$zaLliS9Itu}!q-QoU)?aQx#BDXfBIbXLZrH%Nn%dJms8cBOPHcqrnlblRsY^-f< zudPp~Cc_$yc<$H zzMcPKd7s~p){u#wK(Q?;>OQ(Ju@t$y`|{0_0%m`AG!4`^;!3oj*&&tJz5jzCBHI8! z(%d_!*nI?;C?eS-li>71M)a~A2_tk`#IM`A?Tsyk&^98}c1FhkdhwjJxKH7q@jm$@ zR3ln*?40kCKIA|iI5{E1u&yD$sW***@eO;Q(ywS`TYaA}GL|VEeU^L)RHFHb{2~^FKhMGpIaS(^!3U zgq&(2Uu>t__uTMhY$Mk}kIc2>9bQHWj0B2VcV*<{(e!ZY_&&Vc^5?k2;>T=?U{Va{ z^AK>69ZSLNwlMdjnQP8Ru*Jg&@Vx5b5)Ab2Na5=gcD7`Z2UKW1)5Km@v}^9 zov^;%#ud2z$J;tDVJ~i5!;o;yg2&7e6v}({6{G#KZE=Rp@550s5C7}f*~j-k`wadO zP(V{Pqd!hzIiPoxJV@sJ2V%`>{dhW?6p}E_aDq%E8NbNR(-IWK%-vEi&~YRpBqHQQ z22NxngoXGBC-`}riDhTjIYxol*cKGZ9S2z^@FEJ7a?Os49|1*};6POIan=3#bTK*x zC-mv8Np#S1JPj6=dyBjl0Tdc`(g0y+WAF~b4iOY@(5Mr7iUM&MGI2uBBu}J+N$YcvEW_b)wK@i;lcbQKxZ%V{P)r1hk%R7N z2o5s811O5H`a>0Zz=Bg^gNX*H;vh!h*!NQBdT_eR*O^w8IR0zL(4E=io|k0m=`q7T zg@4BT)CHp=ND6Jt<)W_v45!m|xSYbu5LP};7tpEz6hUJ;o<0tj(+NOvJq;(IyH8`oixIi%<`%($tj1t54Gx?Pk2E#P1*f1=-t{@12yZLR2pqPR+ z4nP6A|9{xK5+1jC9Vp4x6)RE_ErK8@lK=lNABU2U9J_Vjw{03!Ds~;8*#aDMD3QZM z(QF1Tj_L*#UwVqNNFgf#^!%3p^d0#cnMq$WxSNTJ$;RZO-md-p)^aNlXiV;aQ`8jMB`A1{nJ1z~$0C`(8_+)CI0fQ7CEEiv zAW_$G<(oiZ*MowFCOCwk2^rxI6f)BAHqFmqww0dJr!G9axfvF6g$>g4lYC%9$%~cA zN}~R2pm?FDK$vYJ)+s)+HY!jU{ecMMvfp=P^!pzl9~K&ROq4!!#(Kt{Hky966kdQw zIeoLF&1vJus`0_e9VPRrG-92WwkKKhrTqV_dd`8iT@4D@o+0YwbRb}C^BsXonMQXH ziY`C3>y&04j3`IP;$6%?H&!o1j`uJTS&H=;e4THgc&(>E3ZLc*2dqDk`4byrg>95V zDAOrJ1PdAjh%Ahes>4+V+Vc3Ph;B)}T*NCmvgSBvai~cGq+(+hu&J3Jce+xey7SuE zC$bGbMW8@C2e);3%i4GgJMa87fizFD%KVf*g@vu9RC|cgZ<$w-{Vbih<5OAswVm(=DH&;5qhYoSY*i#3vKd6*3)p)>Say_91{Yu zb~pUO>=Vy9ZMUpunTbG!+eL~L7&pXhy4cYUn||O|Karg-B_E0@`;a1lU};N)3!G8n zV32`41M;6$dVAkxEW6MW)TXLt%3QYRdUl zghSEUlv8pyksoeA?X`@C9%j`?pVy8$ApGvro5zn#)wc856tv z&&;LzhP=q3V1#yvuG*pfrQMbQO{V{+iURot7%Ep#{&e7!*ueR4QN)}9EhE_a?U#1B{* zzSC;njS&~hZ0YC~FrWe6?@QaS{OB%LYxA?JvA{BxM(WeL# zjxy8hp4^7ZLHG!|L(f3QaXmpGh=PDY`*cd+LORqjGost*3~?-aHvQN{z=LA~#0XgU zyogEe1eqHs{?IzbC{;5#iaR?m>K*gW%`a;|L4~XZ*W74wKzK6Mog#kWGE~&6@+D){ zkt#>5;*CMw-TIgU%M^(xV|75l&2vuE|1*c;N+P|gIhMd18>Z~Rqc97ap|yq}**X|1 zwjo&$s+9r(EhaMeLixK?;sgQ}u_c+|d)Sh@1PVo-0uanV55AnBlqFC@*i0aD?5HSk zU^46sEOqQJGCF*>xX!Pk%2iiX!e!;8!DB2-!B|e_rMe)hN3V}5WQAMGE z^9NbIpf55uJdF#Hwc@7$2G5EH1PU+K&pvTfk++v^##%*k`sNLrN?Jbv$FqJL3abiD?qW(s4>&3^@_ntP8AQ5dDbZN zQAE#Vd0>$_lc?ykwG_O7#!91+t?1Y0K6#eorgt}%?ux6hvpw+(-!n4-JSk!GXJ75GRe3#T6U?V+GeBmLqjTG6W_;tUn28!PS3UjAwb018YY5J+8HO*B; z^)A?pRhxkB0TKuhO5W*E{VeyXM%w`uBKd+` z4{O>M{`VpsUl)8S@NnlQiM5{sM`o))PddrNVtg{gykD7KcnNlT(Yeq zRztG28n?%KLnKf{>&hW~u`Te_6%_b-L@V?_rgC%--7n}b>T>7nQbz;Dp9Do^Fr${t zXQ1%Yr>SDq*w38D6up~TVo{;s3p28#ax4Rf(Z!$2A7MraA#horC0p8=_}W6(!dKiX z3VL!KbxNlsY6D&c9t0jY? zgbD?p{wBp;f?L%;!MZt7R{SIrv4P?>F~y_-C|7eQ`#8T_eSx1>Kc@PN@w(Adm>QEj zgz)l{a#T(TyeAnFsCZ@3k*J`!KN|D5XmFHV_y&rXg2MhfB))q*1qEl&CGTtJ#_=!( zB)PoRUkM7I9{=2_boM`ELNrhDYEam}6BKM5N!%xbix&&ujIHV(Pe}JYrQ~I@teJ2F z#Z&S$vWS~jcF_KKamn^mhakkaxi11<14RSHbCTj*hz}pXpQrvWR*TJdktlJy}r6Kg0ww?EOQUa{XIDU}^ zKGo(eYV=G4MH_Diim@WDR4~BywKUS9-Ce1YljzP;>Oy^Ov{kBzBwx=Bz{(yVz{PUW zl@dGepUdJjP_*&)gQ64waq*}}y*;;?m!&F5IK{=)LQfrpC4<5l=xsP@P=gJTKyH$U zp7dyBG1b*IP_*%OpfJ@_6n#K%xMj9w6EF3sk{i5p2UQJeBbLPTLPnz$J{nDzk$dq1 zZbLg;1UYKw;6|U?c)yr}V&vjhS=aX{L$uh;tC;>1aYpK=HtAUJP39lj8&s~E- zqy|M;(5#9%K*Jvz{k4^F14SF}2MTT{(Qg)`H+AaC4E^9MI`$ND9(MR_x$zJpEoK} z*Z?0gpwIjHkbCqrJsuTyubV4coGKh+P@K@;@pRZ^h2Ge76)rv;ddS1d7HGHehM!TYk2gYH^&Vbd_SP+U{KhU<==3UY&ZoW~ zwD6dmZJ=o5-9RBNYkPw}!Bh0`0E6&C^BNuP5G-(Pv)L;qN{7RdJDb8u5GXG6xi^@U z(u(O*kF&U`u2?iswDESH!eH^u4-^wzE|)~{GkFSM7O}nF?M~+dd4luieBKVAPXq_P z=6X2nfD-tJBU%cpVZ4f>jPvHO)8uZPZ1ky(_XCAS%7zDhD!qmfQ+R74=lq?{C+13^ zNIgR8>j^=&qL_g~X{Amhm+DVHE=-^35ts9hNY?+@yB6j~bscPzm2KSwxGb63-ARVi z|Nkqm9)6LgE$P`pIv2MIc@S`jKTDq^OC&0s---6#zN7jiZfN-Le|{!E1*tW``N(Pp49GUC2^QsFZ=O_Rx>0K6IDD23}75*KMN zvFS5`h3>)o1Ox#7h~q;Vu6n#DciKQwu$vB=AOFlj!9+v6cd|5MUJlZE_i9a@wWZJ< zt6qPVUq1*6N!W^Or3#C3qRj0`QZ{9i1&k6x!0_j`MQ~(+;e7rA0*V0p0NsdF@Xr>S zQuLjzt3tD-hAAwl)`HbO3?V=dTY(}e9T-RES7!_aC~A=0IX*jGHyY569-~NyjDuhN z_lxf+tn*4BY>o*A;Hx?u&oEO;1q;GRE--io&;TMUC2PB2&FE(*d0Zrat zbjSao*vLscZQxK!0H+e-B7peyP7`3Tz$ifD!#eZDo!{@?`cYN78>2s^9T#3W0I0OvZbSxUT`xpgcD9P4C9rm%=oyavfypooe`K!${^8OB#b zB0gjSmQtUis!cNuDOsGPnP`dnGuw;VMQ}6o)!w!M1v<&X;Znw?MwVhroQG>t;sFaE zh>2U3$*v8GsEZry4h#u18?Rpv3N~(g=GY)&f+0~MA{m)Xk|zO^RZ3N?87xfLv+ZvS z3Xu<*#0I0fBrAg|S@AtG1ag@#qPd4|RkwG+gz-+SsD#T(N+c2;ZAtk9VjvUUb%qO7 zqSPGAb?bLnY~;}vHsNsAzI4L>5>Ui?Mu)XSLE;d{;<%ncLd{A66a;fnFmH$iP;bNt)cIKB!LGIj(LSVr7>4N7S-yoH1~wF^UVt_qBr zmn18&P*j8l!VZe9K%p!mF^ZHFEy|5=!71XvVoaEoF`*Gk5S{4NbgxXpvK4lus} zrj#|NkC#s)0=2Urd2nl8sG_a?yu zXQn0bTze7Ggu-$&>spzt}fCDZMqNy#X5-+^drIK(EHDC{5@oT)!3qu)W% zmLSC7a{hxGtE)!K7F;nZcAM;0plDLiD<{4zs#Brb-vAUr{1aVB!*j) z9=nxIPHYEOhh3HvFL5;2wZVwJzpJ+b>3Vb?H0EfSKYIa%&6c`;4(H&P~BAJ`O{2N+P zC<+IB>=Co;ONz(Zma!lAKoJE+x1Q-q#(Z%=(D^Glq3>$g5`K>O3+OV?7!_g1#LAq) z=}J_$v^?FDfr6C{c4n_8C`3nd6(}$h0F04Myuw=i?4O{=;^7Y2oW(~~uip-eRZX(8 zprU~etnUKdfs{v;nvUSLPOz7{UA%&O%YgFNpopd?c2cZ(%}mH^PaR-16^WdP;T(|Q z@EP+{5`UMZKuNGiW$;?(OJZ$$)_?mHBbMF&p%|!_UKg{Ra~itf7F<6{Yk90{N}+}u~X7N+SuIN1@avih5;GuZ0O)R zNb7ll_PM7QtW>iL&VnZT01_e81wsVSJ#CzO5=jA^c;R5yo2aUQZ=w!G_b26_n1rh= zw#+OZJ-!d>4hOG?7FH4R!tE6?Q66vycoUu?m#;B6?<6kimhQ9+(}o6`4Gn3*!`RS< zlV5U~Q>QlvT=mpSW&;4ri}M>B_!a*opa8QnD5^+T4)3@`k}ai@!MWPCCjlCtIzA@{ z@$uL%`A1)sSbz*VQ3)}^6`mnwq2W$p2&rrE0LuL`RB%R{09?$JK{1Wf)U>Cj8PDf_ z>VdYcZ2R^+HBHm@?Z~ekBvY(=3Q2)$ONwZXmFY9nVND4e%s91wq0uGhoSX6B7yLU% zeY6u}HOJDe-=Y)udWA_wFe1kB!LPFj6jI!aL2%YRhI%a>a19My^97ptxR1 zg(7Cbj}OCmuI&%r!qAd5xgMI4b*m@g6#RwP1%+6ii2ORdm8nO%mLz+F z=R(XbCFEV+yzjgr@-|L9Uu9N-9C?8B=iOROI{^^G9;XoqA{O1o&2z7kRtnTBqPsMW zgpWQ4*74U_C@DDJiS;Lu6fHmK`+-2xTqoU<;-oZuQm~wdbN^)O(;`sRM77kD2q{O@ zU3qY8)2l!MF2%EoCz~2g@G_S>wqqmakQlabzj>n{%UQ8<(^H2o$^tiz*(}STP&i2N z!Fxyh@J#Nl_g#D+V`l^wZ9rcepV`)~m@f2^~=*pR~UzTyvq)1pI+Cbx<^rE3Z3|#wen2vEvU^pHR2YT2u z`{>WZ0k((@d<6tPC#swmQkRHVCy*PEXdae8s#l}3+;O6M{ty(>H z=N9MF6b;S)mO2q6kS0tg$%ltIRiv(02Iu{|=kzj1$FD6$8-7u3H>l@IYG%G1^UITZ zox1MulxO_uRIU4&xuEN##Rgu#&O%VgPSG{tAGYkB1oB>kz0dqiQ8N`X{~;onHUQj)TKkSm*=v^EbgFB3d< zA~yPJP({AQay*h?_1*9Xkw1Awr;F>Gt)!$Zf!77taTu5Ha@%WXP3#r$1+NRIl-unR zIXw=Rud@UcjCqn2?m7{GY2+Wz!_ZzwR+VH+418eF480@LO?2D3Zv+a7y$(=k)iA;2 zGFrY`N1b3%bgbf;j)?{!FF`HVAJZHnNA!D;@E`&r-N&p|2Ck|1ql%#=&E%P zg;&(Yh++Z`lh{V`V&`1oG1*@lv1$1!gcdB8X>Or<`G%wrP?#i(F0Ra?H^KWeJr+L? ziaT%d@Ke8CXfcKUWDwcXqYqXZ%;FU|k;+2d84>*enCk~fQO)O6_@E&rn6Eqxt) z02ExY$Z5K98!V|!<9NQ3IyLYXI>$~uU}^+TMBgU9yU&243Xlm^4yH8zK?9i}l+X>6 z3p$z`ifvN4q6mvxP{{6W6IFL#Qp_!gFUEVIXj&mXmzR_Vsly*{h-g= zLzGWhV?l-=)2~(|;B3l$v=o4t=~YQp{7SW}ds?q#sMmaI=LHltg5rPFT@7=iIuZm0 z2`D2l1)<(mF!%odue|Oa35a9oHrcJ(UGD}P4AK~;=SwpZq|n);`actG02K9C%_mZ# zRHwR!2^H6Met~}AdnXM+58pE*q-NUSACeIG1E9DMHWkeyQ265PV&4}qyr1N9_b~E+ z^PcJyT~j7dJa{@Mu6Xx#`w$c%D(O(O7$_*a8)nIX3GY$%9supb2_7FVP4yfUp6r(f zw_~p1-$Mv>nH}Iy|7E2qFNAK(>9@DJ+s9Z*mdKsOAy70a{`6*wBF|VCl68J&h4yZ> z9IZ+9b@SG!(GphZ@o=;`m1KEzm!Rv`YZ4CL~DVrk4_SJvyC~h znn2OoJ*-9allp3X6^pNdA}ErriyIk9HN_r32{1A!+q$6mz{jTiOF&_apO;iT=YDg* z(s9+gYFV7H6T&H6~5*S12fad=~rGC2e+nZX-P0Ip(1LFbhd&Er-$BLtr{#fjzc z)A-}KibGSv^B@V9|6$5WfD$cQdKc|V{Llz#WQ;UiCJ2T&%?{m-hS}FF-Z6hw;o(HL z)%BRwmF8S(52^%Cv8JpTIu5N2KXgJP{{twRFM?t>`PwH@3j0_7zWMpTWj+}uhBuqX zvM`6)RbX$uDtF^XCY0CW?o1i>%kAb=U5AIC15$3$6*t$kO*mw@C3dsjcu49%t5$hTevads}vpfxo)hLBSA9aSY#qLp|L1VG8tryXj?{(S|Q-CX|31 z0(hXbj3wnd`)Q!%Tc*(mv>%!o)`k+CL7l7u2358hfDjY0BA_?t5q&%b1zgHung-`o zN>Jbs-WnpB9B(!Ri7}I$yz2Y~SM&}acpK2i9Nn~bwAIx!e>q{v452?%`)akweu_K#|S7-?);?H#CLjiy8DkMTt~CElk{Q6#Um4 zHHBoE^8^7A;?hCyu?IE6PrlMMudjrJ^8#qPAQoiZka26{*aUt0sv{DGuTR z56%Q;@L~*xy2`@jcL13l+!pt`}lbr=CN0zKe#4Xf(BW#EIHPS4ySSU zl*Uc&7cU$lR)_)9HXhf`BLnWS^B;i%B7IQO&*EDyGEJ@5P%VMmYvQRE zL#k$z3yKzj#Ecr}V%N&ZUS}K|JaZ>WMlT=M5zizNSV_rOjol#p@O=vKdr)M1l{tJR z8szO2B0O(${qvxxO%1fq0^02lAbfz)sb&!p`2Y>AK3QZjnPVGu<5N^ zktSS_5KqYXy0@ITkD#FO)s1lg==3|(G6~S7!8Jsxv#K2G9j?y~Vy0nQ$0_#)P$)ry z`?}Uka%`i~Yd0y~ub^USUnYz011OFF7(+r3V0Qb}Qh&F6^*2HBi5@6_|5{()@hOUy znBdrO`(~5*VM9ac>gYIEGNepf`~!c%tg0%RR>@wfw12~1WjcfrsP^9!kTp=y{)*WT z!`o$MG8ts;*m<|jv4fP3gWk7kQgw=|Rlq!5oVORZtz)#&KXW(lKv9$qJV70S=Ef;Z z5lo|Y2NuBKy^j-oV1Q!1xK*IIyzAF((-6ls4kvnIH$^ls#F-4P(7%;rcb-a-OnSyO6XHcXYprgHRz=oTH@6UAW zqA5-OUEhNur;N2Ax?w>OXz$QyaMPwh>8}CBAN=~3rf6+l(pCy1&0{7%LXla>mc>9p z=Yq=MrhRIPTg5#plWR7%D(|^v%Wr$^X)isEdmaV^-MS`04IUU*mio@JBE+%eS?tdc zpA@7x(#^89{64DtK~n?(91N+l7Ftl$Mbrxr+?Q#Dl|D`YD6lxr+W5=6ew`oZiCs^2 zeDXXFRdzA!W}uZLFoiuj@IX^QF?DE&nQ^>sGwQ|Tv;J6g18OcJ4lWfwG54DK!`sQ1 z42qejoNoY*qyGtHDw$8`wv6^7olOI z!P)<5B5{{W#@;|L$7|Fp^^ia@sf1_00X~jqS>4fHS%blnf**pSRX)4N*<(k!FuSss z6BGQ;YKm}|cljW7ZO6}Fr74pA^cGYc1Wt3}a`5Z&`rm5;#g*QIybJD;^u8RS2eY*CO+Adx@CQ!tD1Lpk(c%$1Tx}Ey626H*d z1M|tKErE)TQ*Jn#WWMisJL;bR#q%I*+n%%bPa{$7-{Mmc6!@Fotn2~&YpUXQ6$0E2 z3IgROd+8=n@W_Ib;A&$pG>+FSipj!O%9`R-p%g90NAd%1{2WO_2S9^;Z09TC_Inw(&sFT4!L8d?TyMy95 z?oCq+K8g6sgu7y-e8BJGJSo=f=~GnL;5vr1oH_#}R$`Mb0^p8zyQKqhz6`Ut@M^5Q~|9PLAByQEC;XCsX78R)B^c$PV`=k3?$ z$W!~rfZ}saA2~Uas}^md~LdQMy|m+Ti+h|DI~@ z&d3k(2E~Q^x`ALeRB z*}w_8+@!WOupfklewm}4w0Zp}tRMV6O`%D=ZAiQ33cg+uK#Mco7Mf6Vm7-3!>SAwB z07yf8ix(&wZ>YFdnrZxVP(Yye(W3KI3(2we<%={0t>4b6GKG;NI;_wZ;AOpI?5B# z9>L;5lhTnMfPypU$uJ^{hcX!TQaK&NVx)!#Qs*Tn6;Kdi9Yi&MY8t1oQ@Z^qJ%7J` zq+1Q{Ci}hl^pzBrUkHk4dCGsuIE7}LRmnr!gq#%%TvV`+oNs(Z=fYKRTC0kOm;bSM zEzF7IOi*%GuSzhNGF4YsNm2X%f90p{89i)FmL>VXyTNyx5bz7oXl69sJ^!#$_v4@Z z{EzzAkdJlTYj7-%uNg(HfD&Y%=jZ1f(U6V8DnQJ60W0PRfV0OMo}Q$T@WRy@6bmZ% zE$y`1SHnIDR20R9h$;t!PO;|68UqUeAcwPfz}gjWzzMDs>MJo%ws9DqvGXYVk3e8p z9`3M+IXp8*a5kM9g$_y-3Z>qVPnSJPe(>a^%#qJDpeR1%yBh4X%K<*17JzxUy%a|s z?ugg3eBx>3!~8zH7B~bE^5R+OE+&N>RI3 zjc~;W4$-)53LeTF_;v^ZbbMKskpPvJ|p#vS-1df4@G^G9AqQ8E<{#Xu_#yvZx~T1JQzqM<5G^*jX#tW_c}pg$UHEk?R_(z*B0%M8WGqN!W5sLgxrG ze2#wrSY7iJIwrX=g{c8&7rYg&$IBpogScKK`YDH*mZL^(D8cseq2#NNK>%QoHW1Pp z3@HC0B#@*hgwk>TU_uA%yO~k=k6TnI?5WY8I`zA)dy1;D2#1hV1~!^b^Ob7UjaH|f zfZK~g$iNYWyXQ-=uWX9WC~ER$1-UKYX=@c$O-ex&Y<7})l%vlHj>g!+Vol&vRK1Y5 zG-zOkQDhXQO^7B=f+vtQArNCElSh=Xh)N3Ah^}7o&G|QFl8EpI#tAosIbY(q!caQn zDT38kX-F_=UAUCX%W%dZmi+=aI2ieY!3I@{pju~T7a<1WpFrvhYTVZQRy6OYjUxHq zFbbz4BmznZKwWa=$9gN6QGhjzh#EyCNytkRt_?Jhy(Vdl8hD1_|d z0Ff7Y0=V43sl=0l;h5UEl#_)BmY8cGkD>|Y zm6lQd6K|w}5znr3tpR`a}^7tOu)y9-xmOlyOQ$NOQ-M)6!0WZ#l6avq_|XZpU9YAXYFsSe_+u3#g3{&IcY z6H1rB^cR1+vm;sh#TSL%Q>;*LPB_v%_h6=7u*T$U(jBvV6)oA63+1%EFxXd%caQ+6{&|T zob#5!C*>r?t{AbZUclHzr)nz%JpHkV`Tc+z!?dpEiH7 zJOwcCd7#5xpd|$;W5luS-d_)SFru{cWB-a;CHw_2mIu#odHXrVNf)5LJ$(6Hs}N;j zcBTOpe4I-{b#&AuX?*q+@i-;#RNS!%@hjjyw2{-ztkTEASIK^IRO7He+ENSo@8=Y) z$W~C!qaGK^bNQnogRL5e7rxry=Q3go3(!)*%6yOW=Ol7E#-JLb{@=;HxclX(X{2sH?7)fdU+m()m|5=gc+oy_Gd%^`OFwp zUJMOqndCH6h1h_p;#p|g5?UXKEBa)F%MJ_S!=3Qa)USbEazvZ#{6+PAdp2#k&?vIU z&)?%aLH&nAZAmd8ry!hdcOVTvXV+v+WuwTuVPALa)-Bg~3RhEvsG=N2V!8DF?X;e{ z{VZXCIW9#rPb4&(7+O~c`D~{|6hsm$BvrpzEj~`Is19XM9zWVe2+KKjc33RSCF6^g%jDfeX+m9@}l^0}<+Boq{3^z`h@lVH`m_-+@eyjC%J9;HX0v zylfOyCjT>5pT7F@sy0#EG`>aO#QQ&gdeN>;U7MuXuZ}&2>@B`zRuDykCk{x`pGGIW zu^Navl67L(<`AvVDr&u?N)-L!>a8WC6SM5~WPt=Z~zN^KjV`dNpt4%Zw zo%k?{+l5c428v7@(2LnBC^smgp!uf}5GSFY!2l3E0-hXH7cqQKPtm2?|1zsE@iQ}d zcN767gvS;M9pCyeJ#6AOUovEI34gUCF}(!%N5Sp_sUHZmX#6v{IHilqt&Q9Hk zr*Ng|MRgS>oiuv6)+pHNqT0mIqzWYNa~F7Qzh@MRNemIlcXCaD5EeKio&XReiW)lM z@Z3Wz#@YDYa*C)-J^tuBL0&tPyG1hMJ(U(p@FaynU)oQ)$B4a&QS{)(-z5#*xL3ty za*C)0aB&s7LIkytt0!_9{Q4-dsaLIm7~@^+DYcL7W=0{sCw|K&ZX7|~-&1tW<-yPD zmWa%iGkG~8HL#(cRdDH4Bk>ASe2mwddy2CN-17*>`;&}r?-X~%u^5Fo24DJ@3Np}Nb2g)nf+o@Ygd`Nc8O~!t_D)9OPmH2iLe(+}_wyH9 zs8hrlSrypWvM$TH-CuC@>Jt!{n#E3?Us%A~AKPt=Vojf@vf-Nu|4Jd_M6hR_^ZO;f z<&39Dw>64-;lkFdzCwCxSKUq5Q=FDrL4D*a*iXw7r8)N_gSfX*u=&B-T2eELUJ|gg zj#ELc6+hy?#J6n70nrIA_9)szNaXca;me43UUh8aEGbI>U%vnV38YCxK~&H@p%TM` zDM)m66K&n;VH6w7Df)n_N&KYVR?75me?z_GFENVQEujB}Mm-qLse(RIuR0hP9-<-$ zT`V0R+ew;y+hd4s(I~t&ocDeq!|1-sdp=nZKFo9^b}QjYZf5QGKXL3ss0_FqV$8AS%vgqW!kObk_oYCgP2Z)szy#4 zI$_yK1w0?A^;V6dC?1AIs(j)n{PLM^VH7&F(>(l<^0sM-He5tIpi8->_gFIt#9!W- zCa3e*Hfj{(aJ3$PlB18Xqv)H1iaO|YjCk0{_Z!9agE+?PKnwRlj0;jHu zozsb6TEg+z?qn3_wLm*L#vT#X>J=%?1F92q`a)l^MWdh>i1S>zc#G7h52izbt0FBe zq8uY`BA60&JrIC*G>TvJrw|qG|Fw4|x{d2FFj5|Mz_tv-28u-kWB>mvABU22G}$)0 zO=CMIyNz=w!2;D}NJ^T4vooX(oX9&z_=N0mAeFK%yDv)1u&Tk4R{03@qe%3g#fe7F zBYkhL`7KaHEZ&(q?Pra;#_f3?lAf0Hj(hwm z$S31%kEn||mG>c<79uxL-An{?oZusL2_fqld^)sZ_9T-z(R8-Y_#Xg;VWx=leXV3! zCQ<7@tC$5Cf{W6n-DUft_?~Ys5HZ!~rHM;f`d_JHu0QFW{uEAZDY_oso3Lw!2Vvj2 z>>?Ok*1!=%HA|^?E)A^_Szxi46_3Mw()%ZvBF&mUg()wZ5~6ch@NCb>c#ravYH0|HeT{_0whnIer4sMuu!czv@2aR-%=fyq#6cB}~x{=EcJ9bUOX;yVO zj6>JisvGz!@|puN82GuCLBSZvDzpvA2Oovhi~^a5gF+moXHB0@Hmcc~o5HmAa54R_ zW6G`Mz@0l|hx0ul`n^3z_vs#g3RkS|M!fuA-&NzmigQbYD^K`_fzk3W1EIAd=g(Js z6vSr-9yE3o5-dJ`3KVmFspS7fk)VlLCSGcb(r&$ti(kj~RD_qhn2*IHKkQ_)Eh$UP z6<_&NQ1Pb_10%RpAld=LdF&t$2Oh)o{$R!Yi=UUPT!5>gkvao4yfZ&kQ_T8}dMu5z zbb*_WAiYmLrjj?k{W_HxxhoZ}tc#CJdo=lJXw1@m`pln#9O%N}F%PS|y5h(b(!=8m z4=Z9&5SJKa(}^i+d=$`zf}-uj3(Wk);@!;Y(*-obR1btuj?%@c-&CSBpmL-3R)%z5 zVJjx)0mWVZ6i#M)t~!u5aY@d<9bm-Qk(mN`XsT-9VRhG6oPF^}?Ky3#X&4<3%1d|; z?>^CDKykZOD=KDXouaH%Om39gUs`NS_6~oFkkcouYu z&V%+C+uOnv6X8R{@K3rr{L$UcyG#LoN*~(EV-KU zYDAqZmL#xR;rOkxh>@V}&-`Qgj>jO_;G!M-J?Z|HF@=OUauq1}(;C>nF z6r!RWa6crM)%lah5;Yd61EHNO5HeWWqshVojV7t90R`MpkTr@|t|`9Aqog_Ik9Nfh ziY2E{U-(ln8jR1o{2&O=!&BMX7v*ao2~mJpKbozf2$ai)ad}%LNzY)p?%=#mTVsmL z_ALe7ys?ILim&`Bj2IWCyusDPgf(!uRp3q(^9t`%5E8-mYkL$!+HYh&#rw|Ro_&ZA^D1kK$@^MUrZs}%@BJz6I*D!Kxw7B}nIZ%w zhV?Rq`IkdL`TX_q5+^ZclW%>z)Wz9k_vyU2&?&dF^yyFj6xW_!XFu1nndS%yG-RWB zmUQ9xg* zh(BK9Y$G*AP&=ZPg5qlS`@h!xD~ohd{^fqwql${PcAvt>Q>8lZ*2NS@ucAxQvl%Lg zS7Qo|)qvvTmwo(LS2(RHG&T+je@9bx!|tdWTLr~ZQK3ws@pMppvUf?DLSw6i_B8!Z zM6q;GC{t+sG$?NQwJ1|)Y!DQu)w$d0lhza(TLOiNo;)O!MH$@S)G3bOMI17M_@3;5 zm7}RRRrkH)q{2)CZI)G`7GL!5bPx{nAhn zABhMJ59SYm#3k`zA<@z#r%a*o@}Pk3ig9(<6IB1;;057*rUcLeGei)T59mS-&|tR8 z6dJFeK0&X8YN-Cz6;Yq?vuvrGev-Fg!oJh zw%T9VPl%n7W0b({&K;U1fokXQ)sLM6xb6hdik718PVg1H?{1N4Pr47LyBTp5zQ_dWeSbg2Zihihdh(a z_b5yu?iAU#MIPa1m!DLo(AYrwba|r4FF2GbG@cHMn@WE3sbnfsXe67sLe zkWZmZp|QF2srXA2j|s8)&62RwjWUJCwm`A)P^QpOP$*Mq%mIqH@Q#x*g~nn)VWKjH lhNe%-6dD=|3Js0x_#cuE@z*ejqV50y002ovPDHLkV1jmgud@IE literal 0 HcmV?d00001 diff --git a/docs/includes/quick-start/troubleshoot.rst b/docs/includes/quick-start/troubleshoot.rst new file mode 100644 index 000000000..46deeb9eb --- /dev/null +++ b/docs/includes/quick-start/troubleshoot.rst @@ -0,0 +1,7 @@ +.. note:: + + If you run into issues on this step, ask for help in the + :community-forum:`MongoDB Community Forums <>` or submit feedback by using + the :guilabel:`Share Feedback` tab on the right or bottom right side of the + page. + diff --git a/docs/index.txt b/docs/index.txt index 3a6a42fd3..f5fa80f6d 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -13,6 +13,7 @@ Laravel MongoDB :titlesonly: :maxdepth: 1 + /quick-start /install /eloquent-models /query-builder @@ -40,6 +41,13 @@ Laravel Eloquent and Query Builder syntax to work with your MongoDB data. see `Laravel Version Compatibility `__ on GitHub. +Quick Start +----------- + +Learn how to create and configure a Laravel web application to connect to +MongoDB hosted on MongoDB Atlas by using {+odm-short+} and begin working +with data in the :ref:`laravel-quck-start` section. + Getting Started --------------- @@ -70,7 +78,7 @@ Reporting Issues We are lucky to have a vibrant PHP community that includes users of varying experience with MongoDB PHP Library and {+odm-short+}. To get support for general questions, search or post in the -`MongoDB Community Forums `__. +:community-forum:`MongoDB Community Forums <>`__. To learn more about MongoDB support options, see the `Technical Support `__ page. diff --git a/docs/install.txt b/docs/install.txt deleted file mode 100644 index 795dbcff0..000000000 --- a/docs/install.txt +++ /dev/null @@ -1,82 +0,0 @@ -.. _laravel-install: - -=============== -Getting Started -=============== - -.. facet:: - :name: genre - :values: tutorial - -.. meta:: - :keywords: php framework, odm, code example - -Installation ------------- - -Make sure you have the MongoDB PHP driver installed. You can find installation -instructions at `https://php.net/manual/en/mongodb.installation.php `__. - -Install the package by using Composer: - -.. code-block:: bash - - $ composer require mongodb/laravel-mongodb - -In case your Laravel version does NOT autoload the packages, add the service -provider to ``config/app.php``: - -.. code-block:: php - - 'providers' => [ - // ... - MongoDB\Laravel\MongoDBServiceProvider::class, - ], - -Configuration -------------- - -To configure a new MongoDB connection, add a new connection entry -to ``config/database.php``: - -.. code-block:: php - - 'default' => env('DB_CONNECTION', 'mongodb'), - - 'connections' => [ - 'mongodb' => [ - 'driver' => 'mongodb', - 'dsn' => env('DB_DSN'), - 'database' => env('DB_DATABASE', 'homestead'), - ], - // ... - ], - -The ``dsn`` key contains the connection string used to connect to your MongoDB -deployment. The format and available options are documented in the -:manual:`MongoDB documentation `. - -Instead of using a connection string, you can also use the ``host`` and -``port`` configuration options to have the connection string created for you. - -.. code-block:: php - - 'connections' => [ - 'mongodb' => [ - 'driver' => 'mongodb', - 'host' => env('DB_HOST', '127.0.0.1'), - 'port' => env('DB_PORT', 27017), - 'database' => env('DB_DATABASE', 'homestead'), - 'username' => env('DB_USERNAME', 'homestead'), - 'password' => env('DB_PASSWORD', 'secret'), - 'options' => [ - 'appname' => 'homestead', - ], - ], - ], - -The ``options`` key in the connection configuration corresponds to the -`uriOptions `__ -parameter. - -You are ready to :ref:`create your first MongoDB model `. diff --git a/docs/quick-start.txt b/docs/quick-start.txt new file mode 100644 index 000000000..f3ee42b6c --- /dev/null +++ b/docs/quick-start.txt @@ -0,0 +1,51 @@ +.. _laravel-quickstart: + +=========== +Quick Start +=========== + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :keywords: php framework, odm + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Overview +-------- + +This guide shows you how to create and configure Laravel web application +and the {+odm-long+} to use a MongoDB cluster hosted on MongoDB Atlas as the +database. + +If you prefer to connect to MongoDB by using the PHP Library, see +`Connecting to MongoDB `__ +in the PHP Library documentation. + +{+odm-short+} extends the Laravel Eloquent and Query Builder syntax to +store and retrieve data from MongoDB. + +MongoDB Atlas is a fully managed cloud database service that hosts your +MongoDB deployments. You can create your own free (no credit card +required) MongoDB Atlas deployment by following the steps in this guide. + +Follow the steps in this guide to create a sample Laravel web application +that connects to a MongoDB deployment. + +.. button:: Next: Download and Install + :uri: /quick-start/download-and-install/ + +.. toctree:: + + /quick-start/download-and-install/ + /quick-start/create-a-deployment/ + /quick-start/create-a-connection-string/ + /quick-start/connect-to-mongodb/ + /quick-start/next-steps/ + diff --git a/docs/quick-start/connect-to-mongodb.txt b/docs/quick-start/connect-to-mongodb.txt new file mode 100644 index 000000000..f7e1a7c7d --- /dev/null +++ b/docs/quick-start/connect-to-mongodb.txt @@ -0,0 +1,36 @@ +.. _laravelt-quick-start-connect-to-mongodb: + +================== +Connect to MongoDB +================== + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :keywords: test connection, runnable, code example + +.. procedure:: + :style: connected + + .. step:: Create your Laravel Application + + .. step:: Assign the Connection String + + Replace the ```` placeholder with the connection + string that you copied from the :ref:`laravel-quick-start-connection-string` + step of this guide. + + .. step:: Run your Laravel Application + + TODO + +After you complete these steps, you have a Laravel web application that +uses the {+odm-long+} to connect to your MongoDB deployment, run a query on +the sample data, and render a retrieved result. + +.. include:: /includes/quick-start/troubleshoot.rst + +.. button:: Next Steps + :uri: /quick-start/next-steps/ diff --git a/docs/quick-start/create-a-connection-string.txt b/docs/quick-start/create-a-connection-string.txt new file mode 100644 index 000000000..a61a333f5 --- /dev/null +++ b/docs/quick-start/create-a-connection-string.txt @@ -0,0 +1,61 @@ +.. _laravel-quick-start-connection-string: + +========================== +Create a Connection String +========================== + +You can connect to your MongoDB deployment by providing a +**connection URI**, also called a *connection string*, which +instructs the driver on how to connect to a MongoDB deployment +and how to behave while connected. + +The connection string includes the hostname or IP address and +port of your deployment, the authentication mechanism, user credentials +when applicable, and connection options. + +To connect to an instance or deployment not hosted on Atlas, see TODO + +.. procedure:: + :style: connected + + .. step:: Find your MongoDB Atlas Connection String + + To retrieve your connection string for the deployment that + you created in the :ref:`previous step `, + log in to your Atlas account and navigate to the + :guilabel:`Database` section and click the :guilabel:`Connect` button + for your new deployment. + + .. figure:: /includes/figures/atlas_connection_select_cluster.png + :alt: The connect button in the clusters section of the Atlas UI + + Proceed to the :guilabel:`Connect your application` section and select + "PHP" from the :guilabel:`Driver` selection menu and the version + that best matches the version you installed from the :guilabel:`Version` + selection menu. + + Select the :guilabel:`Password (SCRAM)` authentication mechanism. + + Deselect the :guilabel:`Include full driver code example` to view + the connection string. + + .. step:: Copy your Connection String + + Click the button on the right of the connection string to copy it + to your clipboard. + + .. step:: Update the Placeholders + + Paste this connection string into a a file in your preferred text editor + and replace the ```` and ```` placeholders with + your database user's username and password. + + Save this file to a safe location for use in the next step. + +After completing these steps, you have a connection string that +contains your database username and password. + +.. include:: /includes/quick-start/troubleshoot.rst + +.. button:: Next: Connect to MongoDB + :uri: /quick-start/connect-to-mongodb/ diff --git a/docs/quick-start/create-a-deployment.txt b/docs/quick-start/create-a-deployment.txt new file mode 100644 index 000000000..a54d97764 --- /dev/null +++ b/docs/quick-start/create-a-deployment.txt @@ -0,0 +1,37 @@ +.. _laravel-quick-start-create-deployment: + +=========================== +Create a MongoDB Deployment +=========================== + +You can create a free tier MongoDB deployment on MongoDB Atlas +to store and manage your data. MongoDB Atlas hosts and manages +your MongoDB database in the cloud. + +.. procedure:: + :style: connected + + .. step:: Create a Free MongoDB deployment on Atlas + + Complete the :atlas:`Get Started with Atlas ` + guide to set up a new Atlas account and load sample data into a new free + tier MongoDB deployment. + + .. step:: Save your Credentials + + After you create your database user, save that user's + username and password to a safe location for use in an upcoming step. + +After you complete these steps, you have a new free tier MongoDB +deployment on Atlas, database user credentials, and sample data loaded +into your database. + +.. note:: + + If you run into issues on this step, ask for help in the + :community-forum:`MongoDB Community Forums <>` + or submit feedback by using the :guilabel:`Share Feedback` + tab on the right or bottom right side of this page. + +.. button:: Next: Create a Connection String + :uri: /quick-start/create-a-connection-string/ diff --git a/docs/quick-start/download-and-install.txt b/docs/quick-start/download-and-install.txt new file mode 100644 index 000000000..6b4d35143 --- /dev/null +++ b/docs/quick-start/download-and-install.txt @@ -0,0 +1,34 @@ +.. _laravel-quick-start-download-and-install: + +==================== +Download and Install +===================== + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :keywords: php framework, odm, code example + +Prerequisites +------------- + +This guide assumes that you have the following software installed: + +- `PHP `__ +- `Composer `__ + +.. procedure:: + :style: connected + + .. step:: Install the MongoDB PHP Driver + + .. step:: Install Laravel + + .. step:: Add the {+odm-short+} Dependency + +.. include:: /includes/quick-start/troubleshoot.rst + +.. button:: Create a Deployment + :uri: /quick-start/create-a-deployment/ diff --git a/docs/quick-start/next-steps.txt b/docs/quick-start/next-steps.txt new file mode 100644 index 000000000..a9f9730f5 --- /dev/null +++ b/docs/quick-start/next-steps.txt @@ -0,0 +1,26 @@ +.. _laravel-quick-start-next-steps: + +========== +Next Steps +========== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: learn more + +Congratulations on completing the quick start tutorial! + +In this tutorial, you created a Laravel web application that performs +read and write database operations on a MongoDB deployment hostted on +MongoDB Atlas. + +Learn more about {+odm-short+} features from the following resources: + +- :ref:`laravel-eloquent-models`: use Eloquent model classes to work + with MongoDB data. + +- :ref:`laravel-query-builder`: use the query builder to specify MongoDB + queries and aggregations. From 45770388b295e4959f6e7424c351af987ea9c5af Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Fri, 26 Jan 2024 11:40:48 -0500 Subject: [PATCH 155/446] added steps, fixed rst --- docs/quick-start/connect-to-mongodb.txt | 23 +++++++++++++++++++---- docs/quick-start/download-and-install.txt | 11 ++++++++++- docs/quick-start/next-steps.txt | 2 +- 3 files changed, 30 insertions(+), 6 deletions(-) diff --git a/docs/quick-start/connect-to-mongodb.txt b/docs/quick-start/connect-to-mongodb.txt index f7e1a7c7d..4826aa61f 100644 --- a/docs/quick-start/connect-to-mongodb.txt +++ b/docs/quick-start/connect-to-mongodb.txt @@ -14,18 +14,33 @@ Connect to MongoDB .. procedure:: :style: connected - .. step:: Create your Laravel Application - - .. step:: Assign the Connection String + .. step:: Set the Connection String in the Database Configuration Replace the ```` placeholder with the connection string that you copied from the :ref:`laravel-quick-start-connection-string` step of this guide. - .. step:: Run your Laravel Application + .. step:: Create a Sample Model, View, and Controller TODO + .. step:: Create a Sample API Controller to Store Data + + TODO: + + .. step:: Start your Laravel Application + + TODO + + .. step:: Write Sample Data to the API Controller + + TODO + + .. step:: Render Database Data in a View + + TODO + + After you complete these steps, you have a Laravel web application that uses the {+odm-long+} to connect to your MongoDB deployment, run a query on the sample data, and render a retrieved result. diff --git a/docs/quick-start/download-and-install.txt b/docs/quick-start/download-and-install.txt index 6b4d35143..8b5509dc9 100644 --- a/docs/quick-start/download-and-install.txt +++ b/docs/quick-start/download-and-install.txt @@ -2,7 +2,7 @@ ==================== Download and Install -===================== +==================== .. facet:: :name: genre @@ -19,15 +19,24 @@ This guide assumes that you have the following software installed: - `PHP `__ - `Composer `__ +Complete the following steps to download and install the components you +need to create a Laravel web application and set up {+odm-short+}. + .. procedure:: :style: connected .. step:: Install the MongoDB PHP Driver + TODO + .. step:: Install Laravel + TODO + .. step:: Add the {+odm-short+} Dependency + TODO + .. include:: /includes/quick-start/troubleshoot.rst .. button:: Create a Deployment diff --git a/docs/quick-start/next-steps.txt b/docs/quick-start/next-steps.txt index a9f9730f5..0296dbb91 100644 --- a/docs/quick-start/next-steps.txt +++ b/docs/quick-start/next-steps.txt @@ -14,7 +14,7 @@ Next Steps Congratulations on completing the quick start tutorial! In this tutorial, you created a Laravel web application that performs -read and write database operations on a MongoDB deployment hostted on +read and write database operations on a MongoDB deployment hosted on MongoDB Atlas. Learn more about {+odm-short+} features from the following resources: From 47fdb6c8337fea1cf4411669ad0fedbc9e797e34 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Fri, 26 Jan 2024 15:15:39 -0500 Subject: [PATCH 156/446] add link to the devcenter article --- docs/quick-start.txt | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/quick-start.txt b/docs/quick-start.txt index f3ee42b6c..967cb549e 100644 --- a/docs/quick-start.txt +++ b/docs/quick-start.txt @@ -22,11 +22,18 @@ Overview This guide shows you how to create and configure Laravel web application and the {+odm-long+} to use a MongoDB cluster hosted on MongoDB Atlas as the -database. +database from a command line-based development environment. -If you prefer to connect to MongoDB by using the PHP Library, see -`Connecting to MongoDB `__ -in the PHP Library documentation. +.. tip:: + + If you prefer to use GitHub Codespaces or Docker as your development + environment, see the code repository linked in the + `How to Build a Laravel + MongoDB Back End Service `__ + MongoDB Developer Center tutorial. + + If you prefer to connect to MongoDB by using the PHP Library driver without + Laravel, see `Connecting to MongoDB `__ + in the PHP Library documentation. {+odm-short+} extends the Laravel Eloquent and Query Builder syntax to store and retrieve data from MongoDB. From 78f6fe38be40b87342efe3ac2caffcc39fb0af9f Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Fri, 26 Jan 2024 15:24:39 -0500 Subject: [PATCH 157/446] grammar --- docs/quick-start.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/quick-start.txt b/docs/quick-start.txt index 967cb549e..f752bd599 100644 --- a/docs/quick-start.txt +++ b/docs/quick-start.txt @@ -27,7 +27,7 @@ database from a command line-based development environment. .. tip:: If you prefer to use GitHub Codespaces or Docker as your development - environment, see the code repository linked in the + environment, see the linked code repository in the `How to Build a Laravel + MongoDB Back End Service `__ MongoDB Developer Center tutorial. From 2743bcce3fecb97e42207dd52ba3e354de4c821b Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Fri, 26 Jan 2024 17:07:51 -0500 Subject: [PATCH 158/446] DOCSP-35932: compatibility page --- docs/compatibility.txt | 23 +++++++++++++++++++ .../framework-compatibility-laravel.rst | 16 +++++++++++++ docs/index.txt | 11 +++++---- 3 files changed, 46 insertions(+), 4 deletions(-) create mode 100644 docs/compatibility.txt create mode 100644 docs/includes/framework-compatibility-laravel.rst diff --git a/docs/compatibility.txt b/docs/compatibility.txt new file mode 100644 index 000000000..b87fd95e4 --- /dev/null +++ b/docs/compatibility.txt @@ -0,0 +1,23 @@ +.. _laravel-compatibility: + +============= +Compatibility +============= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Laravel Compatibility +--------------------- + +The following compatibility table specifies the versions of Laravel and +{+odm-short+} that you can use together. + +.. include:: /includes/framework-compatibility-laravel.rst + +To find compatibility information for unmaintained versions of {+odm-short+}, +see `Laravel Version Compatibility `__ +on GitHub. diff --git a/docs/includes/framework-compatibility-laravel.rst b/docs/includes/framework-compatibility-laravel.rst new file mode 100644 index 000000000..b9ed88814 --- /dev/null +++ b/docs/includes/framework-compatibility-laravel.rst @@ -0,0 +1,16 @@ +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + + * - {+odm-short+} Version + - Laravel 10.x + - Laravel 9.x + + - 4.1 + - ✓ + - + + - 4.0 + - ✓ + - + diff --git a/docs/index.txt b/docs/index.txt index 3a6a42fd3..32cee5554 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -19,6 +19,7 @@ Laravel MongoDB /user-authentication /queues /transactions + /compatibility /upgrade Introduction @@ -36,10 +37,6 @@ Laravel Eloquent and Query Builder syntax to work with your MongoDB data. maintained by MongoDB, Inc. and is compatible with Laravel 10.x and later. - To find versions of the package compatible with older versions of Laravel, - see `Laravel Version Compatibility `__ - on GitHub. - Getting Started --------------- @@ -58,6 +55,12 @@ see the following content: - :ref:`laravel-queues` - :ref:`laravel-transactions` +Compatibility +------------- + +To learn more about which versions of the {+odm-long+} and Laravel are +compatible, see the :ref:`laravel-compatibility` section. + Upgrade Versions ---------------- From 1f8956ce44e673ed3be48569c810cb2cc5ca5e4f Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Fri, 26 Jan 2024 17:07:51 -0500 Subject: [PATCH 159/446] DOCSP-35932: compatibility page --- docs/includes/framework-compatibility-laravel.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/includes/framework-compatibility-laravel.rst b/docs/includes/framework-compatibility-laravel.rst index b9ed88814..9b39db4ea 100644 --- a/docs/includes/framework-compatibility-laravel.rst +++ b/docs/includes/framework-compatibility-laravel.rst @@ -6,11 +6,11 @@ - Laravel 10.x - Laravel 9.x - - 4.1 + * - 4.1 - ✓ - - - 4.0 + * - 4.0 - ✓ - From 5e6c7ac3eb8d69efaee2217e8fe69eaeb4964271 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Fri, 26 Jan 2024 18:02:57 -0500 Subject: [PATCH 160/446] add facet --- docs/compatibility.txt | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/compatibility.txt b/docs/compatibility.txt index b87fd95e4..40ffef740 100644 --- a/docs/compatibility.txt +++ b/docs/compatibility.txt @@ -4,6 +4,10 @@ Compatibility ============= +.. facet:: + :name: genre + :values: reference + .. contents:: On this page :local: :backlinks: none From 89f5a251aed88becf79e9a74a3b18111b622d010 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Mon, 29 Jan 2024 14:21:29 -0500 Subject: [PATCH 161/446] download and install content --- docs/quick-start/connect-to-mongodb.txt | 6 +- docs/quick-start/download-and-install.txt | 103 +++++++++++++++++++--- 2 files changed, 97 insertions(+), 12 deletions(-) diff --git a/docs/quick-start/connect-to-mongodb.txt b/docs/quick-start/connect-to-mongodb.txt index 4826aa61f..0588263f6 100644 --- a/docs/quick-start/connect-to-mongodb.txt +++ b/docs/quick-start/connect-to-mongodb.txt @@ -1,4 +1,4 @@ -.. _laravelt-quick-start-connect-to-mongodb: +.. _laravel-quick-start-connect-to-mongodb: ================== Connect to MongoDB @@ -22,6 +22,10 @@ Connect to MongoDB .. step:: Create a Sample Model, View, and Controller + .. code-block:: bash + + php artisan make:model User -mcr + TODO .. step:: Create a Sample API Controller to Store Data diff --git a/docs/quick-start/download-and-install.txt b/docs/quick-start/download-and-install.txt index 8b5509dc9..65d2bfaf4 100644 --- a/docs/quick-start/download-and-install.txt +++ b/docs/quick-start/download-and-install.txt @@ -14,30 +14,111 @@ Download and Install Prerequisites ------------- -This guide assumes that you have the following software installed: +- This guide assumes that you have the following software installed: -- `PHP `__ -- `Composer `__ + - `PHP `__ + - `Composer `__ -Complete the following steps to download and install the components you -need to create a Laravel web application and set up {+odm-short+}. +- A terminal app and shell. For MacOS users, use Terminal or a similar app. + For Windows users, use PowerShell. + +Download and Install the Dependencies +------------------------------------- + +Complete the following steps to install and add the {+odm-short+} dependencies +to a Laravel web application. .. procedure:: :style: connected - .. step:: Install the MongoDB PHP Driver + .. step:: Install the {+php-extension} + + The {+odm-short+} requires the {+php-extension+} to manage MongoDB + connections and commands. + + + Use the ``pecl`` extension manager to install {+php-extension+}. + + .. code-block:: bash + + pecl install mongodb + + You can use select the default responses when prompted. + + When the installation successfully completes, you should see the + following output: + + .. code-block:: none + + install ok: channel://pecl.php.net/mongodb- + Extension mongodb enabled in php.ini - TODO .. step:: Install Laravel - TODO + Ensure that the version of Laravel you install is compatible with the + version of {+odm-short+}. + + .. code-block:: bash + + composer global require "laravel/installer" + + When the installation successfully completes, you should see the + following output: + + .. code-block:: none + + Using version ^ for laravel/installer + + .. step:: Create a Laravel App + + Run the following command to generate a new Laravel web application + called {+quickstart-app-name+}: + + .. code-block:: bash + + laravel new {+quickstart-app-name+} + + When the installation successfully completes, you should see the + following output: + + .. code-block:: none + + INFO Application ready in [{+quickstart-app-name+}]. You can start your local development using: + + ➜ cd {+quickstart-app-name+} + ➜ php artisan serve + + New to Laravel? Check out our bootcamp and documentation. Build something amazing! + + .. step:: Add {+odm-short+} to the Dependencies + + + Navigate to the application directory you created in the previous step: + + .. code-block:: bash + + cd {+quickstart-app-name+} + + Run the following command to add the {+odm-short+} dependency to + your application: + + .. code-block:: bash + + composer require "mongodb/laravel-mongodb" + + When the installation successfully completes, you should see the + following in your ``composer.json`` file: - .. step:: Add the {+odm-short+} Dependency + .. code-block:: json - TODO + { + "require": { + "mongodb/laravel-mongodb": "^{+package-version+}" + } + } .. include:: /includes/quick-start/troubleshoot.rst -.. button:: Create a Deployment +.. button:: Create a MongoDB Deployment :uri: /quick-start/create-a-deployment/ From f4487c94988153d1d0433324664a9b8b779501e6 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Mon, 29 Jan 2024 14:42:14 -0500 Subject: [PATCH 162/446] RST fixes, reformat requirements --- docs/quick-start/download-and-install.txt | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/quick-start/download-and-install.txt b/docs/quick-start/download-and-install.txt index 65d2bfaf4..391ac5cb7 100644 --- a/docs/quick-start/download-and-install.txt +++ b/docs/quick-start/download-and-install.txt @@ -14,11 +14,11 @@ Download and Install Prerequisites ------------- -- This guide assumes that you have the following software installed: - - - `PHP `__ - - `Composer `__ +To create the quick start application, you need the following software +installed in your development environment: +- `PHP `__ +- `Composer `__ - A terminal app and shell. For MacOS users, use Terminal or a similar app. For Windows users, use PowerShell. @@ -31,12 +31,11 @@ to a Laravel web application. .. procedure:: :style: connected - .. step:: Install the {+php-extension} + .. step:: Install the {+php-extension+} The {+odm-short+} requires the {+php-extension+} to manage MongoDB connections and commands. - Use the ``pecl`` extension manager to install {+php-extension+}. .. code-block:: bash @@ -49,6 +48,7 @@ to a Laravel web application. following output: .. code-block:: none + :copyable: false install ok: channel://pecl.php.net/mongodb- Extension mongodb enabled in php.ini @@ -67,13 +67,14 @@ to a Laravel web application. following output: .. code-block:: none + :copyable: false Using version ^ for laravel/installer - .. step:: Create a Laravel App + .. step:: Create a Laravel Application Run the following command to generate a new Laravel web application - called {+quickstart-app-name+}: + called ``{+quickstart-app-name+}``: .. code-block:: bash @@ -83,6 +84,7 @@ to a Laravel web application. following output: .. code-block:: none + :copyable: false INFO Application ready in [{+quickstart-app-name+}]. You can start your local development using: @@ -108,7 +110,7 @@ to a Laravel web application. composer require "mongodb/laravel-mongodb" When the installation successfully completes, you should see the - following in your ``composer.json`` file: + following in your ``composer.json`` file in the application directory: .. code-block:: json From d422b8816ca3b63afb1ba434ab91687e3f1d1bd7 Mon Sep 17 00:00:00 2001 From: bisht2050 <108942387+bisht2050@users.noreply.github.com> Date: Thu, 1 Feb 2024 18:33:10 +0530 Subject: [PATCH 163/446] Update readme to include official docs link (#2712) --- README.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 71074ee62..9ecf12af0 100644 --- a/README.md +++ b/README.md @@ -12,13 +12,10 @@ This package was renamed to `mongodb/laravel-mongodb` because of a transfer of o It is compatible with Laravel 10.x. For older versions of Laravel, please refer to the [old versions](https://github.com/mongodb/laravel-mongodb/tree/3.9#laravel-version-compatibility). -- [Installation](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/install/) -- [Eloquent Models](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/eloquent-models/) -- [Query Builder](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/query-builder/) -- [Transactions](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/transactions/) -- [User Authentication](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/user-authentication/) -- [Queues](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/queues/) -- [Upgrading](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/upgrade/) +## Documentation + +- https://www.mongodb.com/docs/drivers/php/laravel-mongodb/ +- https://www.mongodb.com/docs/drivers/php/ ## Reporting Issues From b8482fafa3a3aeb0d980bfa46dafe0c305f43c3b Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Thu, 1 Feb 2024 10:09:09 -0500 Subject: [PATCH 164/446] add Laravel MongoDB v3.9 compatibility --- docs/includes/framework-compatibility-laravel.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/includes/framework-compatibility-laravel.rst b/docs/includes/framework-compatibility-laravel.rst index 9b39db4ea..b373164d2 100644 --- a/docs/includes/framework-compatibility-laravel.rst +++ b/docs/includes/framework-compatibility-laravel.rst @@ -14,3 +14,7 @@ - ✓ - + * - 3.9 + - + - ✓ + From 0126d5380ffd3b444a32be740c09ebd4e851e031 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Fri, 2 Feb 2024 15:39:04 -0500 Subject: [PATCH 165/446] quick start updates --- docs/quick-start.txt | 9 +- docs/quick-start/configure-mongodb.txt | 47 ++++++ docs/quick-start/connect-to-mongodb.txt | 55 ------- docs/quick-start/download-and-install.txt | 22 +-- docs/quick-start/next-steps.txt | 9 +- docs/quick-start/view-data.txt | 174 ++++++++++++++++++++++ docs/quick-start/write-data.txt | 69 +++++++++ 7 files changed, 316 insertions(+), 69 deletions(-) create mode 100644 docs/quick-start/configure-mongodb.txt delete mode 100644 docs/quick-start/connect-to-mongodb.txt create mode 100644 docs/quick-start/view-data.txt create mode 100644 docs/quick-start/write-data.txt diff --git a/docs/quick-start.txt b/docs/quick-start.txt index f752bd599..b0c841bd8 100644 --- a/docs/quick-start.txt +++ b/docs/quick-start.txt @@ -26,8 +26,8 @@ database from a command line-based development environment. .. tip:: - If you prefer to use GitHub Codespaces or Docker as your development - environment, see the linked code repository in the + If you prefer to set up your development environment in GitHub Codespaces + or Docker, see the linked code repository in the `How to Build a Laravel + MongoDB Back End Service `__ MongoDB Developer Center tutorial. @@ -53,6 +53,9 @@ that connects to a MongoDB deployment. /quick-start/download-and-install/ /quick-start/create-a-deployment/ /quick-start/create-a-connection-string/ - /quick-start/connect-to-mongodb/ + /quick-start/configure-mongodb/ + /quick-start/create-a-model-view-controller/ + /quick-start/view-data/ + /quick-start/write-data/ /quick-start/next-steps/ diff --git a/docs/quick-start/configure-mongodb.txt b/docs/quick-start/configure-mongodb.txt new file mode 100644 index 000000000..89e74c27b --- /dev/null +++ b/docs/quick-start/configure-mongodb.txt @@ -0,0 +1,47 @@ +.. _laravel-quick-start-connect-to-mongodb: + +================================== +Confingure Your MongoDB Connection +================================== + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :keywords: test connection, runnable, code example + +.. procedure:: + :style: connected + + .. step:: Set the Connection String in the Database Configuration + + Navigate to the ``config`` directory from your application root directory. + Open the ``database.php`` file and set the default database connection + to ``mongodb`` as shown in the following line: + + .. code-block:: php + + 'default' => env('DB_CONNECTION', 'mongodb'), + + Add the following highlighted ``mongodb`` entry to the ``connections`` array + in the same file. Replace the ```` placeholder with the + connection string that you copied from the :ref:`laravel-quick-start-connection-string` + step of this guide. + + .. code-block:: php + :emphasize-lines: 2-6 + + 'connections' => [ + 'mongodb' => [ + 'driver' => 'mongodb', + 'dsn' => env('DB_URI', ''), + 'database' => 'sample_mflix', + ], + + // ... + +.. include:: /includes/quick-start/troubleshoot.rst + +.. button:: View Sample MongoDB Data + :uri: /quick-start/view-data/ \ No newline at end of file diff --git a/docs/quick-start/connect-to-mongodb.txt b/docs/quick-start/connect-to-mongodb.txt deleted file mode 100644 index 0588263f6..000000000 --- a/docs/quick-start/connect-to-mongodb.txt +++ /dev/null @@ -1,55 +0,0 @@ -.. _laravel-quick-start-connect-to-mongodb: - -================== -Connect to MongoDB -================== - -.. facet:: - :name: genre - :values: tutorial - -.. meta:: - :keywords: test connection, runnable, code example - -.. procedure:: - :style: connected - - .. step:: Set the Connection String in the Database Configuration - - Replace the ```` placeholder with the connection - string that you copied from the :ref:`laravel-quick-start-connection-string` - step of this guide. - - .. step:: Create a Sample Model, View, and Controller - - .. code-block:: bash - - php artisan make:model User -mcr - - TODO - - .. step:: Create a Sample API Controller to Store Data - - TODO: - - .. step:: Start your Laravel Application - - TODO - - .. step:: Write Sample Data to the API Controller - - TODO - - .. step:: Render Database Data in a View - - TODO - - -After you complete these steps, you have a Laravel web application that -uses the {+odm-long+} to connect to your MongoDB deployment, run a query on -the sample data, and render a retrieved result. - -.. include:: /includes/quick-start/troubleshoot.rst - -.. button:: Next Steps - :uri: /quick-start/next-steps/ diff --git a/docs/quick-start/download-and-install.txt b/docs/quick-start/download-and-install.txt index 391ac5cb7..a827f118e 100644 --- a/docs/quick-start/download-and-install.txt +++ b/docs/quick-start/download-and-install.txt @@ -57,11 +57,15 @@ to a Laravel web application. .. step:: Install Laravel Ensure that the version of Laravel you install is compatible with the - version of {+odm-short+}. + version of {+odm-short+}. + + + Then run the following command to install + Laravel. .. code-block:: bash - composer global require "laravel/installer" + composer global require laravel/installer When the installation successfully completes, you should see the following output: @@ -107,18 +111,18 @@ to a Laravel web application. .. code-block:: bash - composer require "mongodb/laravel-mongodb" + composer require mongodb/laravel-mongodb:^{+package-version+} When the installation successfully completes, you should see the - following in your ``composer.json`` file in the application directory: + following line in the ``require`` object in your ``composer.json`` file: .. code-block:: json + :copyable: false + + "mongodb/laravel-mongodb": "^{+package-version+}" - { - "require": { - "mongodb/laravel-mongodb": "^{+package-version+}" - } - } + After you complete these steps, you should have a new Laravel project + with the {+odm-short+} dependencies installed. .. include:: /includes/quick-start/troubleshoot.rst diff --git a/docs/quick-start/next-steps.txt b/docs/quick-start/next-steps.txt index 0296dbb91..60732e896 100644 --- a/docs/quick-start/next-steps.txt +++ b/docs/quick-start/next-steps.txt @@ -13,8 +13,13 @@ Next Steps Congratulations on completing the quick start tutorial! -In this tutorial, you created a Laravel web application that performs -read and write database operations on a MongoDB deployment hosted on +After you complete these steps, you have a Laravel web application that +uses the {+odm-long+} to connect to your MongoDB deployment, run a query on +the sample data, and render a retrieved result. + +In this tutorial, you created a Laravel web application that uses the +{+odm-long+} to connect to your MongoDB deployment, render the result +of a query, and write data to a MongoDB deployment hosted on MongoDB Atlas. Learn more about {+odm-short+} features from the following resources: diff --git a/docs/quick-start/view-data.txt b/docs/quick-start/view-data.txt new file mode 100644 index 000000000..c42c6d431 --- /dev/null +++ b/docs/quick-start/view-data.txt @@ -0,0 +1,174 @@ +.. laravel-quick-start-view-data: + +======================== +View Sample MongoDB Data +======================== + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :keywords: test connection, runnable, code example + +Follow the steps in this section to create the +To create a webpage that displays data from your database, you need +to create a model, view, and controller. + +.. procedure:: + :style: connected + + .. step:: Create a Sample Model and Controller + + Create a model called ``Movie`` to access data from the sample ``movies`` + collection in your MongoDB databse. You can create the model with a + corresponding resource controller by running the following command: + + .. code-block:: bash + + php artisan make:model Movie -cr + + When the command successfully completes, you should see the following + output: + + .. code-block:: none + :copyable: false + + INFO Model [app/Models/Movie.php] created successfully. + + INFO Controller [app/Http/Controllers/MovieController.php] created successfully. + + .. step:: Edit the Model to use {+odm-short+} + + Navigate to the ``app/Models`` directory and open the ``Movie.php`` file. + Edit the following information in the file: + + - Replace the ``Illuminate\Database\Eloquent\Model`` import with ``MongoDB\Laravel\Eloquent\Model`` + - Specify ``mongodb`` in the ``$connection`` field + + + Your ``Movie.php`` file should contain the following code: + + .. code-block:: php + + Movie::where('runtime', '<', 60) + ->where('imdb.rating', '>', 8.5) + ->orderBy('imdb.rating', 'desc') + ->take(10) + ->get() + ]); + } + + .. step:: Add a Web Route + + Navigate to the ``routes`` directory and open the ``web.php`` file. + Add an import for the ``MovieController`` and a route called + ``browse_movies`` as shown in the following code: + + .. code-block:: php + + + + + Browse Movies + + +

Movies

+ + @forelse ($movies as $movie) +

+ Title: {{ $movie->title }}
+ Year: {{ $movie->year }}
+ Runtime: {{ $movie->runtime }}
+ IMDB Rating: {{ $movie->imdb['rating'] }}
+ IMDB Votes: {{ $movie->imdb['votes'] }}
+ Plot: {{ $movie->plot }}
+

+ @empty +

No results

+ @endforelse + + + + + .. step:: Start your Laravel Application + + Navigate to the application root directory and run the following command + to start your PHP built-in web server: + + .. code-block:: bash + + php artisan serve + + If the server starts successfully, you should see the following message: + + .. code-block: none + + INFO Server running on [http://127.0.0.1:8000]. + + Press Ctrl+C to stop the server + +.. step:: View the Movie Data + + Open http://127.0.0.1:8000/browse_movies in your web browser. If it runs + successuflly, you should see a list of movies and details about each of them. + + .. tip:: + + You can run the ``php artisan route:list`` command from your application + root directory to view a list of available routes. + +.. include:: /includes/quick-start/troubleshoot.rst + +.. button:: Write Data + :uri: /quick-start/write-data/ diff --git a/docs/quick-start/write-data.txt b/docs/quick-start/write-data.txt new file mode 100644 index 000000000..1727216ec --- /dev/null +++ b/docs/quick-start/write-data.txt @@ -0,0 +1,69 @@ +.. _laravel-quick-start-write-data: + +================================= +Post an API Request to Write Data +================================= + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :keywords: test connection, runnable, code example + +.. procedure:: + :style: connected + + .. step:: Add a Function to Store Data + + Navigate to your MovieController.php + + .. code-block:: php + + public function store(Request $request) + { + $data = $request->all(); + $movie = new Movie(); + $movie->fill($data); + $movie->save(); + } + + .. step:: Add a Route for the Controller Function + + In routes/api.php + + .. code-block:: php + + use App\Http\Controllers\MovieController; + + // ... + + Route::resource('movies', MovieController::class)->only([ + 'store' + ]); + + + .. step:: Update the Movie Model + + Add the movie detail fields to the ``$fillable`` array + of the ``Movie`` model. + Update the ``Movie`` class at ``app/Models/Movie.php`` + + + .. code-block:: php + :emphasize-lines: 4 + + class Movie extends Model + { + protected $connection = 'mongodb'; + protected $fillable = ['title', 'year', 'runtime', 'imdb', 'plot']; + } + + .. step:: Post a Request to the API + + TODO: + +.. include:: /includes/quick-start/troubleshoot.rst + +.. button:: Next Steps + :uri: /quick-start/next-steps/ From 27f88e0548539c69ff895efd976a58333ba03816 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Fri, 2 Feb 2024 15:41:29 -0500 Subject: [PATCH 166/446] remove last line --- docs/includes/framework-compatibility-laravel.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/includes/framework-compatibility-laravel.rst b/docs/includes/framework-compatibility-laravel.rst index b373164d2..9b39db4ea 100644 --- a/docs/includes/framework-compatibility-laravel.rst +++ b/docs/includes/framework-compatibility-laravel.rst @@ -14,7 +14,3 @@ - ✓ - - * - 3.9 - - - - ✓ - From dcf330faf45f714f404d44e73159b6a43286e54d Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Fri, 2 Feb 2024 17:49:36 -0500 Subject: [PATCH 167/446] shorten download and install and other fixes --- docs/quick-start/configure-mongodb.txt | 19 ++++++++++++++---- .../create-a-connection-string.txt | 4 ++-- docs/quick-start/download-and-install.txt | 20 ++----------------- docs/quick-start/view-data.txt | 19 +++++++++--------- 4 files changed, 29 insertions(+), 33 deletions(-) diff --git a/docs/quick-start/configure-mongodb.txt b/docs/quick-start/configure-mongodb.txt index 89e74c27b..00d35aa80 100644 --- a/docs/quick-start/configure-mongodb.txt +++ b/docs/quick-start/configure-mongodb.txt @@ -1,8 +1,8 @@ .. _laravel-quick-start-connect-to-mongodb: -================================== -Confingure Your MongoDB Connection -================================== +================================= +Configure Your MongoDB Connection +================================= .. facet:: :name: genre @@ -41,7 +41,18 @@ Confingure Your MongoDB Connection // ... + + .. step:: Add the Laravel MongoDB Provider + + + From the ``config`` directory, open the ``app.php`` file and add + the following entry into the ``providers`` array: + + .. code-block:: + + MongoDB\Laravel\MongoDBServiceProvider::class, + .. include:: /includes/quick-start/troubleshoot.rst -.. button:: View Sample MongoDB Data +.. button:: Next: View Sample MongoDB Data :uri: /quick-start/view-data/ \ No newline at end of file diff --git a/docs/quick-start/create-a-connection-string.txt b/docs/quick-start/create-a-connection-string.txt index a61a333f5..775ccba05 100644 --- a/docs/quick-start/create-a-connection-string.txt +++ b/docs/quick-start/create-a-connection-string.txt @@ -57,5 +57,5 @@ contains your database username and password. .. include:: /includes/quick-start/troubleshoot.rst -.. button:: Next: Connect to MongoDB - :uri: /quick-start/connect-to-mongodb/ +.. button:: Next: Configure Your MongoDB Connection + :uri: /quick-start/configure-mongodb/ diff --git a/docs/quick-start/download-and-install.txt b/docs/quick-start/download-and-install.txt index a827f118e..4b6b99f72 100644 --- a/docs/quick-start/download-and-install.txt +++ b/docs/quick-start/download-and-install.txt @@ -35,24 +35,8 @@ to a Laravel web application. The {+odm-short+} requires the {+php-extension+} to manage MongoDB connections and commands. - - Use the ``pecl`` extension manager to install {+php-extension+}. - - .. code-block:: bash - - pecl install mongodb - - You can use select the default responses when prompted. - - When the installation successfully completes, you should see the - following output: - - .. code-block:: none - :copyable: false - - install ok: channel://pecl.php.net/mongodb- - Extension mongodb enabled in php.ini - + Follow the `Installing the MongoDB PHP Driver with PECL `__ + guide to install {+php-extension+}. .. step:: Install Laravel diff --git a/docs/quick-start/view-data.txt b/docs/quick-start/view-data.txt index c42c6d431..fd98f325c 100644 --- a/docs/quick-start/view-data.txt +++ b/docs/quick-start/view-data.txt @@ -153,22 +153,23 @@ to create a model, view, and controller. If the server starts successfully, you should see the following message: .. code-block: none + :copyable: false INFO Server running on [http://127.0.0.1:8000]. Press Ctrl+C to stop the server -.. step:: View the Movie Data + .. step:: View the Movie Data - Open http://127.0.0.1:8000/browse_movies in your web browser. If it runs - successuflly, you should see a list of movies and details about each of them. + Open http://127.0.0.1:8000/browse_movies in your web browser. If it runs + successuflly, you should see a list of movies and details about each of them. - .. tip:: + .. tip:: - You can run the ``php artisan route:list`` command from your application - root directory to view a list of available routes. + You can run the ``php artisan route:list`` command from your application + root directory to view a list of available routes. -.. include:: /includes/quick-start/troubleshoot.rst + .. include:: /includes/quick-start/troubleshoot.rst -.. button:: Write Data - :uri: /quick-start/write-data/ + .. button:: Next: Write Data + :uri: /quick-start/write-data/ From d6397cb37aaaa6ae01d430c0aa1069a51545dbd6 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Fri, 2 Feb 2024 18:23:44 -0500 Subject: [PATCH 168/446] tweaks --- docs/quick-start/view-data.txt | 26 +++++++++------------ docs/quick-start/write-data.txt | 40 ++++++++++++++++++++++++++++----- 2 files changed, 45 insertions(+), 21 deletions(-) diff --git a/docs/quick-start/view-data.txt b/docs/quick-start/view-data.txt index fd98f325c..1ddc98fa2 100644 --- a/docs/quick-start/view-data.txt +++ b/docs/quick-start/view-data.txt @@ -11,10 +11,6 @@ View Sample MongoDB Data .. meta:: :keywords: test connection, runnable, code example -Follow the steps in this section to create the -To create a webpage that displays data from your database, you need -to create a model, view, and controller. - .. procedure:: :style: connected @@ -45,10 +41,10 @@ to create a model, view, and controller. - Replace the ``Illuminate\Database\Eloquent\Model`` import with ``MongoDB\Laravel\Eloquent\Model`` - Specify ``mongodb`` in the ``$connection`` field - - + + Your ``Movie.php`` file should contain the following code: - + .. code-block:: php Date: Mon, 5 Feb 2024 11:43:02 -0500 Subject: [PATCH 169/446] fixes --- docs/quick-start.txt | 6 ++++ docs/quick-start/configure-mongodb.txt | 14 ++++---- .../create-a-connection-string.txt | 4 ++- docs/quick-start/next-steps.txt | 4 +++ docs/quick-start/view-data.txt | 35 +++++++++---------- docs/quick-start/write-data.txt | 6 ++-- 6 files changed, 39 insertions(+), 30 deletions(-) diff --git a/docs/quick-start.txt b/docs/quick-start.txt index b0c841bd8..bf2beffb4 100644 --- a/docs/quick-start.txt +++ b/docs/quick-start.txt @@ -45,6 +45,12 @@ required) MongoDB Atlas deployment by following the steps in this guide. Follow the steps in this guide to create a sample Laravel web application that connects to a MongoDB deployment. +.. tip:: + + You can download the complete web application project by cloning the + `laravel-quickstart `__ + GitHub repository. + .. button:: Next: Download and Install :uri: /quick-start/download-and-install/ diff --git a/docs/quick-start/configure-mongodb.txt b/docs/quick-start/configure-mongodb.txt index 00d35aa80..34c9ac8a4 100644 --- a/docs/quick-start/configure-mongodb.txt +++ b/docs/quick-start/configure-mongodb.txt @@ -16,9 +16,9 @@ Configure Your MongoDB Connection .. step:: Set the Connection String in the Database Configuration - Navigate to the ``config`` directory from your application root directory. - Open the ``database.php`` file and set the default database connection - to ``mongodb`` as shown in the following line: + Open the ``database.php`` file in the ``config`` directory and + set the default database connection to ``mongodb`` as shown + in the following line: .. code-block:: php @@ -27,7 +27,7 @@ Configure Your MongoDB Connection Add the following highlighted ``mongodb`` entry to the ``connections`` array in the same file. Replace the ```` placeholder with the connection string that you copied from the :ref:`laravel-quick-start-connection-string` - step of this guide. + step in the following code example: .. code-block:: php :emphasize-lines: 2-6 @@ -41,12 +41,10 @@ Configure Your MongoDB Connection // ... - .. step:: Add the Laravel MongoDB Provider - - From the ``config`` directory, open the ``app.php`` file and add - the following entry into the ``providers`` array: + Open the ``app.php`` in the ``config`` directory and + add the following entry into the ``providers`` array: .. code-block:: diff --git a/docs/quick-start/create-a-connection-string.txt b/docs/quick-start/create-a-connection-string.txt index 775ccba05..e8366ba62 100644 --- a/docs/quick-start/create-a-connection-string.txt +++ b/docs/quick-start/create-a-connection-string.txt @@ -13,7 +13,9 @@ The connection string includes the hostname or IP address and port of your deployment, the authentication mechanism, user credentials when applicable, and connection options. -To connect to an instance or deployment not hosted on Atlas, see TODO +To connect to an instance or deployment not hosted on Atlas, see the +:manual:`Connection Strings ` in the Server +manual. .. procedure:: :style: connected diff --git a/docs/quick-start/next-steps.txt b/docs/quick-start/next-steps.txt index 60732e896..9b8f644f6 100644 --- a/docs/quick-start/next-steps.txt +++ b/docs/quick-start/next-steps.txt @@ -22,6 +22,10 @@ In this tutorial, you created a Laravel web application that uses the of a query, and write data to a MongoDB deployment hosted on MongoDB Atlas. +You can download the web application project by cloning the +`laravel-quickstart `__ +GitHub repository. + Learn more about {+odm-short+} features from the following resources: - :ref:`laravel-eloquent-models`: use Eloquent model classes to work diff --git a/docs/quick-start/view-data.txt b/docs/quick-start/view-data.txt index 1ddc98fa2..d29d32c19 100644 --- a/docs/quick-start/view-data.txt +++ b/docs/quick-start/view-data.txt @@ -16,9 +16,10 @@ View Sample MongoDB Data .. step:: Create a Sample Model and Controller - Create a model called ``Movie`` to access data from the sample ``movies`` - collection in your MongoDB databse. You can create the model with a - corresponding resource controller by running the following command: + Create a model called ``Movie`` to represent data from the sample + ``movies`` collection in your MongoDB database. You can create the + model with a corresponding resource controller by running the + following command: .. code-block:: bash @@ -36,13 +37,12 @@ View Sample MongoDB Data .. step:: Edit the Model to use {+odm-short+} - Navigate to the ``app/Models`` directory and open the ``Movie.php`` file. - Edit the following information in the file: + Open the ``Movie.php`` model in your ``app/Models`` directory and + make the following edits: - Replace the ``Illuminate\Database\Eloquent\Model`` import with ``MongoDB\Laravel\Eloquent\Model`` - Specify ``mongodb`` in the ``$connection`` field - Your ``Movie.php`` file should contain the following code: .. code-block:: php @@ -55,14 +55,14 @@ View Sample MongoDB Data class Movie extends Model { - protected $connection = 'mongodb'; + protected $connection = 'mongodb'; } .. step:: Add a Controller Function - Navigate to the ``app/Http/Controllers`` directory and open the - ``MovieController.php`` file. Replace the ``show()`` function - with the following code to retrieve results that match a + Open the ``MovieController.php`` file in your ``app/Http/Controllers`` + directory. Replace the ``show()`` function with the + following code to retrieve results that match a database query and render it in the view: .. code-block:: php @@ -80,7 +80,7 @@ View Sample MongoDB Data .. step:: Add a Web Route - Navigate to the ``routes`` directory and open the ``web.php`` file. + Open the ``web.php`` file in the ``routes`` directory. Add an import for the ``MovieController`` and a route called ``browse_movies`` as shown in the following code: @@ -95,8 +95,8 @@ View Sample MongoDB Data .. step:: Generate a View - Navigate to the application root directory and run the following - command to create a view that displays movie data: + Run the following command from the application root directory + to create a view that displays movie data: .. code-block:: bash @@ -107,9 +107,8 @@ View Sample MongoDB Data INFO View [resources/views/browse_movie.blade.php] created successfully. - Navigate to the ``resources/views`` directory and open the - ``browse_movie.blade.php`` file. Replace the contents with the - following code: + Open the ``browse_movie.blade.php`` view file in the ``resources/views`` + directory. Replace the contents with the following code: .. code-block:: bash @@ -139,7 +138,7 @@ View Sample MongoDB Data .. step:: Start your Laravel Application - Navigate to the application root directory and run the following command + Run the following command from the application root directory to start your PHP built-in web server: .. code-block:: bash @@ -158,7 +157,7 @@ View Sample MongoDB Data .. step:: View the Movie Data Open http://127.0.0.1:8000/browse_movies in your web browser. If it runs - successuflly, you should see a list of movies and details about each of them. + successfully, you should see a list of movies and details about each of them. .. tip:: diff --git a/docs/quick-start/write-data.txt b/docs/quick-start/write-data.txt index 38f1507d0..e5a4ed4f4 100644 --- a/docs/quick-start/write-data.txt +++ b/docs/quick-start/write-data.txt @@ -49,9 +49,9 @@ Post an API Request to Write Data .. step:: Update the Movie Model Add the movie detail fields to the ``$fillable`` array - of the ``Movie`` model. - Update the ``Movie`` class at ``app/Models/Movie.php`` - + of the ``Movie`` model. After adding them, the ``Movie`` + class at ``app/Models/Movie.php`` should contain the + following code: .. code-block:: php :emphasize-lines: 4 From d6f7dc520d55a992e2fa97f625d09309eda3b38e Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Mon, 5 Feb 2024 12:23:26 -0500 Subject: [PATCH 170/446] rst fixes --- docs/index.txt | 10 +--- docs/quick-start.txt | 1 - docs/quick-start/view-data.txt | 96 +++++++++++++++++----------------- 3 files changed, 50 insertions(+), 57 deletions(-) diff --git a/docs/index.txt b/docs/index.txt index f5fa80f6d..fcc41ccdc 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -46,13 +46,7 @@ Quick Start Learn how to create and configure a Laravel web application to connect to MongoDB hosted on MongoDB Atlas by using {+odm-short+} and begin working -with data in the :ref:`laravel-quck-start` section. - -Getting Started ---------------- - -Learn how to install and configure your app to MongoDB by using the -{+odm-short+} in the :ref:`laravel-install` section. +with data in the :ref:`laravel-quick-start` section. Fundamentals ------------ @@ -78,7 +72,7 @@ Reporting Issues We are lucky to have a vibrant PHP community that includes users of varying experience with MongoDB PHP Library and {+odm-short+}. To get support for general questions, search or post in the -:community-forum:`MongoDB Community Forums <>`__. +:community-forum:`MongoDB Community Forums <>`. To learn more about MongoDB support options, see the `Technical Support `__ page. diff --git a/docs/quick-start.txt b/docs/quick-start.txt index bf2beffb4..a849081ec 100644 --- a/docs/quick-start.txt +++ b/docs/quick-start.txt @@ -60,7 +60,6 @@ that connects to a MongoDB deployment. /quick-start/create-a-deployment/ /quick-start/create-a-connection-string/ /quick-start/configure-mongodb/ - /quick-start/create-a-model-view-controller/ /quick-start/view-data/ /quick-start/write-data/ /quick-start/next-steps/ diff --git a/docs/quick-start/view-data.txt b/docs/quick-start/view-data.txt index d29d32c19..29dc2c14f 100644 --- a/docs/quick-start/view-data.txt +++ b/docs/quick-start/view-data.txt @@ -45,18 +45,18 @@ View Sample MongoDB Data Your ``Movie.php`` file should contain the following code: - .. code-block:: php + .. code-block:: php - - - - Browse Movies - - -

Movies

- - @forelse ($movies as $movie) -

- Title: {{ $movie->title }}
- Year: {{ $movie->year }}
- Runtime: {{ $movie->runtime }}
- IMDB Rating: {{ $movie->imdb['rating'] }}
- IMDB Votes: {{ $movie->imdb['votes'] }}
- Plot: {{ $movie->plot }}
-

- @empty -

No results

- @endforelse - - - - - .. step:: Start your Laravel Application + Open the ``browse_movie.blade.php`` view file in the ``resources/views`` + directory. Replace the contents with the following code: + + .. code-block:: bash + + + + + Browse Movies + + +

Movies

+ + @forelse ($movies as $movie) +

+ Title: {{ $movie->title }}
+ Year: {{ $movie->year }}
+ Runtime: {{ $movie->runtime }}
+ IMDB Rating: {{ $movie->imdb['rating'] }}
+ IMDB Votes: {{ $movie->imdb['votes'] }}
+ Plot: {{ $movie->plot }}
+

+ @empty +

No results

+ @endforelse + + + + + .. step:: Start your Laravel Application Run the following command from the application root directory to start your PHP built-in web server: @@ -154,17 +154,17 @@ View Sample MongoDB Data Press Ctrl+C to stop the server - .. step:: View the Movie Data + .. step:: View the Movie Data - Open http://127.0.0.1:8000/browse_movies in your web browser. If it runs - successfully, you should see a list of movies and details about each of them. + Open http://127.0.0.1:8000/browse_movies in your web browser. If it runs + successfully, you should see a list of movies and details about each of them. - .. tip:: + .. tip:: - You can run the ``php artisan route:list`` command from your application - root directory to view a list of available routes. + You can run the ``php artisan route:list`` command from your application + root directory to view a list of available routes. - .. include:: /includes/quick-start/troubleshoot.rst +.. include:: /includes/quick-start/troubleshoot.rst - .. button:: Next: Write Data - :uri: /quick-start/write-data/ +.. button:: Next: Write Data + :uri: /quick-start/write-data/ From d6e90432a211d09fd40cedebac22a74048eaa32e Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Mon, 5 Feb 2024 12:29:41 -0500 Subject: [PATCH 171/446] fixes --- docs/index.txt | 7 +++---- docs/quick-start.txt | 2 +- docs/quick-start/view-data.txt | 12 ++++++------ 3 files changed, 10 insertions(+), 11 deletions(-) diff --git a/docs/index.txt b/docs/index.txt index fcc41ccdc..d2098cb0a 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -14,7 +14,6 @@ Laravel MongoDB :maxdepth: 1 /quick-start - /install /eloquent-models /query-builder /user-authentication @@ -44,9 +43,9 @@ Laravel Eloquent and Query Builder syntax to work with your MongoDB data. Quick Start ----------- -Learn how to create and configure a Laravel web application to connect to -MongoDB hosted on MongoDB Atlas by using {+odm-short+} and begin working -with data in the :ref:`laravel-quick-start` section. +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. Fundamentals ------------ diff --git a/docs/quick-start.txt b/docs/quick-start.txt index a849081ec..810abb1c6 100644 --- a/docs/quick-start.txt +++ b/docs/quick-start.txt @@ -1,4 +1,4 @@ -.. _laravel-quickstart: +.. _laravel-quick-start: =========== Quick Start diff --git a/docs/quick-start/view-data.txt b/docs/quick-start/view-data.txt index 29dc2c14f..7b65f3530 100644 --- a/docs/quick-start/view-data.txt +++ b/docs/quick-start/view-data.txt @@ -25,15 +25,15 @@ View Sample MongoDB Data php artisan make:model Movie -cr - When the command successfully completes, you should see the following - output: + When the command successfully completes, you should see the following + output: - .. code-block:: none - :copyable: false + .. code-block:: none + :copyable: false - INFO Model [app/Models/Movie.php] created successfully. + INFO Model [app/Models/Movie.php] created successfully. - INFO Controller [app/Http/Controllers/MovieController.php] created successfully. + INFO Controller [app/Http/Controllers/MovieController.php] created successfully. .. step:: Edit the Model to use {+odm-short+} From c7c93c74867f66211fa35bc89b972cf69709bfa5 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Mon, 5 Feb 2024 13:09:34 -0500 Subject: [PATCH 172/446] reworrd intro --- docs/quick-start.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/quick-start.txt b/docs/quick-start.txt index 810abb1c6..a8861da50 100644 --- a/docs/quick-start.txt +++ b/docs/quick-start.txt @@ -20,13 +20,13 @@ Quick Start Overview -------- -This guide shows you how to create and configure Laravel web application -and the {+odm-long+} to use a MongoDB cluster hosted on MongoDB Atlas as the -database from a command line-based development environment. +This guide shows you how to add {+odm-long+} to a new Laravel web application, +connect to a MongoDB cluster hosted on MongoDB Atlas, and how to perform +read and write operations on the data. .. tip:: - If you prefer to set up your development environment in GitHub Codespaces + If you prefer to set up your development environment in GitHub Codespaces or Docker, see the linked code repository in the `How to Build a Laravel + MongoDB Back End Service `__ MongoDB Developer Center tutorial. From 07b3c8df62880d93ad0f51a4f4e70df0f60ef392 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Mon, 5 Feb 2024 13:20:16 -0500 Subject: [PATCH 173/446] grammar updates --- docs/quick-start/create-a-connection-string.txt | 2 +- docs/quick-start/download-and-install.txt | 8 ++++---- docs/quick-start/view-data.txt | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/quick-start/create-a-connection-string.txt b/docs/quick-start/create-a-connection-string.txt index e8366ba62..ac017a9ad 100644 --- a/docs/quick-start/create-a-connection-string.txt +++ b/docs/quick-start/create-a-connection-string.txt @@ -48,7 +48,7 @@ manual. .. step:: Update the Placeholders - Paste this connection string into a a file in your preferred text editor + Paste this connection string into a file in your preferred text editor and replace the ```` and ```` placeholders with your database user's username and password. diff --git a/docs/quick-start/download-and-install.txt b/docs/quick-start/download-and-install.txt index 4b6b99f72..77e1d5f42 100644 --- a/docs/quick-start/download-and-install.txt +++ b/docs/quick-start/download-and-install.txt @@ -14,7 +14,7 @@ Download and Install Prerequisites ------------- -To create the quick start application, you need the following software +To create the Quick Start application, you need the following software installed in your development environment: - `PHP `__ @@ -51,7 +51,7 @@ to a Laravel web application. composer global require laravel/installer - When the installation successfully completes, you should see the + When the installation completes, you should see the following output: .. code-block:: none @@ -68,7 +68,7 @@ to a Laravel web application. laravel new {+quickstart-app-name+} - When the installation successfully completes, you should see the + When the installation completes, you should see the following output: .. code-block:: none @@ -97,7 +97,7 @@ to a Laravel web application. composer require mongodb/laravel-mongodb:^{+package-version+} - When the installation successfully completes, you should see the + When the installation completes, you should see the following line in the ``require`` object in your ``composer.json`` file: .. code-block:: json diff --git a/docs/quick-start/view-data.txt b/docs/quick-start/view-data.txt index 7b65f3530..ab0b0b934 100644 --- a/docs/quick-start/view-data.txt +++ b/docs/quick-start/view-data.txt @@ -25,7 +25,7 @@ View Sample MongoDB Data php artisan make:model Movie -cr - When the command successfully completes, you should see the following + When the command completes, you should see the following output: .. code-block:: none From c913056ca94c7167932cdd098f2877a63e72f9eb Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Mon, 5 Feb 2024 14:12:24 -0500 Subject: [PATCH 174/446] learning byte --- docs/quick-start.txt | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/quick-start.txt b/docs/quick-start.txt index a8861da50..4ec2e05eb 100644 --- a/docs/quick-start.txt +++ b/docs/quick-start.txt @@ -31,6 +31,11 @@ read and write operations on the data. `How to Build a Laravel + MongoDB Back End Service `__ MongoDB Developer Center tutorial. + You can learn how to set up a local Laravel development environment + and perform CRUD operations by taking the + :mdbu-course:`Getting Started with Laravel and MongoDB ` + MongoDB University Learning Byte. + If you prefer to connect to MongoDB by using the PHP Library driver without Laravel, see `Connecting to MongoDB `__ in the PHP Library documentation. From 38b94c2ad67f9496cf4a570192b0a7452403345c Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Tue, 6 Feb 2024 11:22:41 -0500 Subject: [PATCH 175/446] formatting fixes --- docs/quick-start/view-data.txt | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/quick-start/view-data.txt b/docs/quick-start/view-data.txt index ab0b0b934..f38084475 100644 --- a/docs/quick-start/view-data.txt +++ b/docs/quick-start/view-data.txt @@ -49,14 +49,14 @@ View Sample MongoDB Data Date: Tue, 6 Feb 2024 17:51:28 -0500 Subject: [PATCH 176/446] PRR fixes --- .gitignore | 1 + docs/includes/quick-start/troubleshoot.rst | 2 +- docs/quick-start.txt | 6 +-- docs/quick-start/configure-mongodb.txt | 12 ++--- .../create-a-connection-string.txt | 6 +-- docs/quick-start/download-and-install.txt | 45 +++++++++++-------- docs/quick-start/next-steps.txt | 7 +-- docs/quick-start/view-data.txt | 12 ++--- docs/quick-start/write-data.txt | 23 +++++----- 9 files changed, 58 insertions(+), 56 deletions(-) diff --git a/.gitignore b/.gitignore index 80f343333..9c3e7d494 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,4 @@ composer.phar phpunit.xml phpstan.neon /.cache/ +docs/.vscode diff --git a/docs/includes/quick-start/troubleshoot.rst b/docs/includes/quick-start/troubleshoot.rst index 46deeb9eb..e22d624b6 100644 --- a/docs/includes/quick-start/troubleshoot.rst +++ b/docs/includes/quick-start/troubleshoot.rst @@ -1,6 +1,6 @@ .. note:: - If you run into issues on this step, ask for help in the + If you run into issues, ask for help in the :community-forum:`MongoDB Community Forums <>` or submit feedback by using the :guilabel:`Share Feedback` tab on the right or bottom right side of the page. diff --git a/docs/quick-start.txt b/docs/quick-start.txt index 4ec2e05eb..b5f9166ae 100644 --- a/docs/quick-start.txt +++ b/docs/quick-start.txt @@ -20,8 +20,8 @@ Quick Start Overview -------- -This guide shows you how to add {+odm-long+} to a new Laravel web application, -connect to a MongoDB cluster hosted on MongoDB Atlas, and how to perform +This guide shows you how to add the {+odm-long+} to a new Laravel web +application, connect to a MongoDB cluster hosted on MongoDB Atlas, and perform read and write operations on the data. .. tip:: @@ -32,7 +32,7 @@ read and write operations on the data. MongoDB Developer Center tutorial. You can learn how to set up a local Laravel development environment - and perform CRUD operations by taking the + and perform CRUD operations by viewing the :mdbu-course:`Getting Started with Laravel and MongoDB ` MongoDB University Learning Byte. diff --git a/docs/quick-start/configure-mongodb.txt b/docs/quick-start/configure-mongodb.txt index 34c9ac8a4..9ba3df1a4 100644 --- a/docs/quick-start/configure-mongodb.txt +++ b/docs/quick-start/configure-mongodb.txt @@ -41,16 +41,16 @@ Configure Your MongoDB Connection // ... - .. step:: Add the Laravel MongoDB Provider + .. step:: Add the Laravel MongoDB Provider - Open the ``app.php`` in the ``config`` directory and - add the following entry into the ``providers`` array: + Open the ``app.php`` file in the ``config`` directory and + add the following entry into the ``providers`` array: - .. code-block:: + .. code-block:: - MongoDB\Laravel\MongoDBServiceProvider::class, + MongoDB\Laravel\MongoDBServiceProvider::class, .. include:: /includes/quick-start/troubleshoot.rst .. button:: Next: View Sample MongoDB Data - :uri: /quick-start/view-data/ \ No newline at end of file + :uri: /quick-start/view-data/ diff --git a/docs/quick-start/create-a-connection-string.txt b/docs/quick-start/create-a-connection-string.txt index ac017a9ad..599255426 100644 --- a/docs/quick-start/create-a-connection-string.txt +++ b/docs/quick-start/create-a-connection-string.txt @@ -13,7 +13,7 @@ The connection string includes the hostname or IP address and port of your deployment, the authentication mechanism, user credentials when applicable, and connection options. -To connect to an instance or deployment not hosted on Atlas, see the +To connect to an instance or deployment not hosted on Atlas, see :manual:`Connection Strings ` in the Server manual. @@ -24,7 +24,7 @@ manual. To retrieve your connection string for the deployment that you created in the :ref:`previous step `, - log in to your Atlas account and navigate to the + log in to your Atlas account. Then, navigate to the :guilabel:`Database` section and click the :guilabel:`Connect` button for your new deployment. @@ -38,7 +38,7 @@ manual. Select the :guilabel:`Password (SCRAM)` authentication mechanism. - Deselect the :guilabel:`Include full driver code example` to view + Deselect the :guilabel:`Include full driver code example` option to view the connection string. .. step:: Copy your Connection String diff --git a/docs/quick-start/download-and-install.txt b/docs/quick-start/download-and-install.txt index 77e1d5f42..ee34ca17f 100644 --- a/docs/quick-start/download-and-install.txt +++ b/docs/quick-start/download-and-install.txt @@ -33,19 +33,18 @@ to a Laravel web application. .. step:: Install the {+php-extension+} - The {+odm-short+} requires the {+php-extension+} to manage MongoDB + {+odm-short+} requires the {+php-extension+} to manage MongoDB connections and commands. Follow the `Installing the MongoDB PHP Driver with PECL `__ - guide to install {+php-extension+}. + guide to install the {+php-extension+}. .. step:: Install Laravel Ensure that the version of Laravel you install is compatible with the - version of {+odm-short+}. + version of {+odm-short+}. To learn which versions are compatible, + see the :ref:`laravel-compatibility` page. - - Then run the following command to install - Laravel. + Run the following command to install Laravel: .. code-block:: bash @@ -61,29 +60,37 @@ to a Laravel web application. .. step:: Create a Laravel Application - Run the following command to generate a new Laravel web application - called ``{+quickstart-app-name+}``: + Run the following command to generate a new Laravel web application + called ``{+quickstart-app-name+}``: + + .. code-block:: bash + + laravel new {+quickstart-app-name+} + + When the installation completes, you should see the + following output: + + .. code-block:: none + :copyable: false - .. code-block:: bash + INFO Application ready in [{+quickstart-app-name+}]. You can start your local development using: - laravel new {+quickstart-app-name+} + ➜ cd {+quickstart-app-name+} + ➜ php artisan serve - When the installation completes, you should see the - following output: + New to Laravel? Check out our bootcamp and documentation. Build something amazing! - .. code-block:: none - :copyable: false + .. step:: Add a Laravel Application Encryption Key - INFO Application ready in [{+quickstart-app-name+}]. You can start your local development using: + Run the following command to add the Laravel application encryption + key which is required to encrypt cookies: - ➜ cd {+quickstart-app-name+} - ➜ php artisan serve + .. code-block:: bash - New to Laravel? Check out our bootcamp and documentation. Build something amazing! + php artisan key:generate .. step:: Add {+odm-short+} to the Dependencies - Navigate to the application directory you created in the previous step: .. code-block:: bash diff --git a/docs/quick-start/next-steps.txt b/docs/quick-start/next-steps.txt index 9b8f644f6..0284720a3 100644 --- a/docs/quick-start/next-steps.txt +++ b/docs/quick-start/next-steps.txt @@ -11,17 +11,12 @@ Next Steps .. meta:: :keywords: learn more -Congratulations on completing the quick start tutorial! +Congratulations on completing the Quick Start tutorial! After you complete these steps, you have a Laravel web application that uses the {+odm-long+} to connect to your MongoDB deployment, run a query on the sample data, and render a retrieved result. -In this tutorial, you created a Laravel web application that uses the -{+odm-long+} to connect to your MongoDB deployment, render the result -of a query, and write data to a MongoDB deployment hosted on -MongoDB Atlas. - You can download the web application project by cloning the `laravel-quickstart `__ GitHub repository. diff --git a/docs/quick-start/view-data.txt b/docs/quick-start/view-data.txt index f38084475..27f071177 100644 --- a/docs/quick-start/view-data.txt +++ b/docs/quick-start/view-data.txt @@ -14,12 +14,11 @@ View Sample MongoDB Data .. procedure:: :style: connected - .. step:: Create a Sample Model and Controller + .. step:: Create a Model and Controller Create a model called ``Movie`` to represent data from the sample - ``movies`` collection in your MongoDB database. You can create the - model with a corresponding resource controller by running the - following command: + ``movies`` collection in your MongoDB database and the corresponding + resource controller by running the following command: .. code-block:: bash @@ -110,9 +109,10 @@ View Sample MongoDB Data INFO View [resources/views/browse_movie.blade.php] created successfully. Open the ``browse_movie.blade.php`` view file in the ``resources/views`` - directory. Replace the contents with the following code: + directory. Replace the contents with the following code and save the + changes: - .. code-block:: bash + .. code-block:: html diff --git a/docs/quick-start/write-data.txt b/docs/quick-start/write-data.txt index e5a4ed4f4..deeac6189 100644 --- a/docs/quick-start/write-data.txt +++ b/docs/quick-start/write-data.txt @@ -14,11 +14,11 @@ Post an API Request to Write Data .. procedure:: :style: connected - .. step:: Create the Function to Store Data + .. step:: Create the Function to Insert Data - Add logic to save the data from a request in the ``MovieController.php`` - file in the ``app/Http/Controllers/`` directory. Replace the existing - placeholder ``store()`` method with the following code: + Update the ``store()`` method ``MovieController.php``, located in + the ``app/Http/Controllers`` directory to insert request data + into the database as shown in the following code: .. code-block:: php @@ -32,8 +32,8 @@ Post an API Request to Write Data .. step:: Add a Route for the Controller Function - Add the API route to map to the ``store()`` method in the - ``routes/api.php`` file. + Add the following API route to map to the ``store()`` method and the + corresponding import in the ``routes/api.php`` file: .. code-block:: php @@ -46,11 +46,10 @@ Post an API Request to Write Data ]); - .. step:: Update the Movie Model + .. step:: Update the Model Fields - Add the movie detail fields to the ``$fillable`` array - of the ``Movie`` model. After adding them, the ``Movie`` - class at ``app/Models/Movie.php`` should contain the + Update the ``Movie`` model in the ``app/Models`` directory to + specify fields that the ``fill()`` method populates as shown in the following code: .. code-block:: php @@ -87,8 +86,8 @@ Post an API Request to Write Data .. step:: View the Data - Open ``http://127.0.0.1:8000/browse_movies`` in your web browser to view - the movie information that you submitted. It should appear at the top of + Open ``http://127.0.0.1:8000/browse_movies`` in your web browser to view + the movie information that you submitted. It should appear at the top of the results. .. include:: /includes/quick-start/troubleshoot.rst From 52d3136a1e2cbe5a56394338322400ce203fb158 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Tue, 6 Feb 2024 18:14:44 -0500 Subject: [PATCH 177/446] more edits --- docs/quick-start/configure-mongodb.txt | 3 +++ docs/quick-start/create-a-deployment.txt | 5 ++--- docs/quick-start/download-and-install.txt | 12 +++++------- docs/quick-start/view-data.txt | 6 +++--- docs/quick-start/write-data.txt | 17 +++++++++-------- 5 files changed, 22 insertions(+), 21 deletions(-) diff --git a/docs/quick-start/configure-mongodb.txt b/docs/quick-start/configure-mongodb.txt index 9ba3df1a4..225befaa4 100644 --- a/docs/quick-start/configure-mongodb.txt +++ b/docs/quick-start/configure-mongodb.txt @@ -50,6 +50,9 @@ Configure Your MongoDB Connection MongoDB\Laravel\MongoDBServiceProvider::class, +After completing these steps, your Laravel web application is ready to +connect to MongoDB. + .. include:: /includes/quick-start/troubleshoot.rst .. button:: Next: View Sample MongoDB Data diff --git a/docs/quick-start/create-a-deployment.txt b/docs/quick-start/create-a-deployment.txt index a54d97764..e35ea5293 100644 --- a/docs/quick-start/create-a-deployment.txt +++ b/docs/quick-start/create-a-deployment.txt @@ -22,9 +22,8 @@ your MongoDB database in the cloud. After you create your database user, save that user's username and password to a safe location for use in an upcoming step. -After you complete these steps, you have a new free tier MongoDB -deployment on Atlas, database user credentials, and sample data loaded -into your database. +After completing these steps, you have a new free tier MongoDB deployment on +Atlas, database user credentials, and sample data loaded into your database. .. note:: diff --git a/docs/quick-start/download-and-install.txt b/docs/quick-start/download-and-install.txt index ee34ca17f..7233d70d6 100644 --- a/docs/quick-start/download-and-install.txt +++ b/docs/quick-start/download-and-install.txt @@ -50,8 +50,7 @@ to a Laravel web application. composer global require laravel/installer - When the installation completes, you should see the - following output: + When the installation completes, you should see the following output: .. code-block:: none :copyable: false @@ -67,8 +66,7 @@ to a Laravel web application. laravel new {+quickstart-app-name+} - When the installation completes, you should see the - following output: + When the installation completes, you should see the following output: .. code-block:: none :copyable: false @@ -83,7 +81,7 @@ to a Laravel web application. .. step:: Add a Laravel Application Encryption Key Run the following command to add the Laravel application encryption - key which is required to encrypt cookies: + key, which is required to encrypt cookies: .. code-block:: bash @@ -112,8 +110,8 @@ to a Laravel web application. "mongodb/laravel-mongodb": "^{+package-version+}" - After you complete these steps, you should have a new Laravel project - with the {+odm-short+} dependencies installed. + After completing these steps, you have a new Laravel project with the + {+odm-short+} dependencies installed. .. include:: /includes/quick-start/troubleshoot.rst diff --git a/docs/quick-start/view-data.txt b/docs/quick-start/view-data.txt index 27f071177..8652ccc1a 100644 --- a/docs/quick-start/view-data.txt +++ b/docs/quick-start/view-data.txt @@ -1,8 +1,8 @@ .. laravel-quick-start-view-data: -======================== -View Sample MongoDB Data -======================== +================= +View MongoDB Data +================= .. facet:: :name: genre diff --git a/docs/quick-start/write-data.txt b/docs/quick-start/write-data.txt index deeac6189..6526aa9d5 100644 --- a/docs/quick-start/write-data.txt +++ b/docs/quick-start/write-data.txt @@ -1,8 +1,8 @@ .. _laravel-quick-start-write-data: -================================= -Post an API Request to Write Data -================================= +===================== +Write Data to MongoDB +===================== .. facet:: :name: genre @@ -30,10 +30,10 @@ Post an API Request to Write Data $movie->save(); } - .. step:: Add a Route for the Controller Function + .. step:: Add an API Route that Calls the Controller Function - Add the following API route to map to the ``store()`` method and the - corresponding import in the ``routes/api.php`` file: + Import the controller and add an API route that calls the ``store()`` + method in the ``routes/api.php`` file: .. code-block:: php @@ -49,7 +49,7 @@ Post an API Request to Write Data .. step:: Update the Model Fields Update the ``Movie`` model in the ``app/Models`` directory to - specify fields that the ``fill()`` method populates as shown in the + specify the fields that the ``fill()`` method populates as shown in the following code: .. code-block:: php @@ -78,7 +78,8 @@ Post an API Request to Write Data "plot": "This movie entry was created by running through the Laravel MongoDB Quick Start tutorial." } - Send the payload to the endpoint by running the following command in your shell: + Send the JSON payload to the endpoint as a ``POST`` request by running + the following command in your shell: .. code-block:: bash From da6b2b063c762a972b55d05417c9c425ae0f5097 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Tue, 6 Feb 2024 18:31:28 -0500 Subject: [PATCH 178/446] avoid subjunctive --- docs/quick-start/download-and-install.txt | 8 ++++---- docs/quick-start/view-data.txt | 11 +++++------ docs/quick-start/write-data.txt | 4 ++-- 3 files changed, 11 insertions(+), 12 deletions(-) diff --git a/docs/quick-start/download-and-install.txt b/docs/quick-start/download-and-install.txt index 7233d70d6..9acd0070f 100644 --- a/docs/quick-start/download-and-install.txt +++ b/docs/quick-start/download-and-install.txt @@ -50,7 +50,7 @@ to a Laravel web application. composer global require laravel/installer - When the installation completes, you should see the following output: + When the installation completes, the command outputs the following message: .. code-block:: none :copyable: false @@ -66,7 +66,7 @@ to a Laravel web application. laravel new {+quickstart-app-name+} - When the installation completes, you should see the following output: + When the installation completes, the command outputs the following message: .. code-block:: none :copyable: false @@ -102,8 +102,8 @@ to a Laravel web application. composer require mongodb/laravel-mongodb:^{+package-version+} - When the installation completes, you should see the - following line in the ``require`` object in your ``composer.json`` file: + When the installation completes, verify that the ``composer.json`` file + includes the following line in the ``require`` object: .. code-block:: json :copyable: false diff --git a/docs/quick-start/view-data.txt b/docs/quick-start/view-data.txt index 8652ccc1a..4b0ea63e2 100644 --- a/docs/quick-start/view-data.txt +++ b/docs/quick-start/view-data.txt @@ -24,8 +24,7 @@ View MongoDB Data php artisan make:model Movie -cr - When the command completes, you should see the following - output: + When the command completes, it outputs the following message: .. code-block:: none :copyable: false @@ -42,7 +41,7 @@ View MongoDB Data - Replace the ``Illuminate\Database\Eloquent\Model`` import with ``MongoDB\Laravel\Eloquent\Model`` - Specify ``mongodb`` in the ``$connection`` field - Your ``Movie.php`` file should contain the following code: + The edited ``Movie.php`` file contains the following code: .. code-block:: php @@ -101,7 +100,7 @@ View MongoDB Data php artisan make:view browse_movies - After you run the command, you should see the following message: + After you run the command, it outputs the following message: .. code-block:: none :copyable: false @@ -147,7 +146,7 @@ View MongoDB Data php artisan serve - After the server starts, you should see the following message: + After the server starts, it outputs the following message: .. code-block:: none :copyable: false @@ -159,7 +158,7 @@ View MongoDB Data .. step:: View the Movie Data Open the URL http://127.0.0.1:8000/browse_movies in your web browser. - You should see a list of movies and details about each of them. + The page shows a list of movies and details about each of them. .. tip:: diff --git a/docs/quick-start/write-data.txt b/docs/quick-start/write-data.txt index 6526aa9d5..39c10cf80 100644 --- a/docs/quick-start/write-data.txt +++ b/docs/quick-start/write-data.txt @@ -88,8 +88,8 @@ Write Data to MongoDB .. step:: View the Data Open ``http://127.0.0.1:8000/browse_movies`` in your web browser to view - the movie information that you submitted. It should appear at the top of - the results. + the movie information that you submitted. The inserted movie appears at + the top of the results. .. include:: /includes/quick-start/troubleshoot.rst From 3663a0c0266bf5a7fa0a01b6ee03662182c62a9f Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 7 Feb 2024 14:18:19 -0500 Subject: [PATCH 179/446] PRR fixes --- docs/quick-start/configure-mongodb.txt | 4 ++-- .../quick-start/create-a-connection-string.txt | 8 ++++---- docs/quick-start/create-a-deployment.txt | 11 +++-------- docs/quick-start/download-and-install.txt | 18 +++++++++--------- docs/quick-start/view-data.txt | 14 +++++++------- docs/quick-start/write-data.txt | 2 +- 6 files changed, 26 insertions(+), 31 deletions(-) diff --git a/docs/quick-start/configure-mongodb.txt b/docs/quick-start/configure-mongodb.txt index 225befaa4..66cd2380c 100644 --- a/docs/quick-start/configure-mongodb.txt +++ b/docs/quick-start/configure-mongodb.txt @@ -14,7 +14,7 @@ Configure Your MongoDB Connection .. procedure:: :style: connected - .. step:: Set the Connection String in the Database Configuration + .. step:: Set the connection string in the database configuration Open the ``database.php`` file in the ``config`` directory and set the default database connection to ``mongodb`` as shown @@ -41,7 +41,7 @@ Configure Your MongoDB Connection // ... - .. step:: Add the Laravel MongoDB Provider + .. step:: Add the Laravel MongoDB provider Open the ``app.php`` file in the ``config`` directory and add the following entry into the ``providers`` array: diff --git a/docs/quick-start/create-a-connection-string.txt b/docs/quick-start/create-a-connection-string.txt index 599255426..9851531b6 100644 --- a/docs/quick-start/create-a-connection-string.txt +++ b/docs/quick-start/create-a-connection-string.txt @@ -20,7 +20,7 @@ manual. .. procedure:: :style: connected - .. step:: Find your MongoDB Atlas Connection String + .. step:: Find your MongoDB Atlas connection string To retrieve your connection string for the deployment that you created in the :ref:`previous step `, @@ -31,7 +31,7 @@ manual. .. figure:: /includes/figures/atlas_connection_select_cluster.png :alt: The connect button in the clusters section of the Atlas UI - Proceed to the :guilabel:`Connect your application` section and select + Proceed to the :guilabel:`Connect your application` section. Select "PHP" from the :guilabel:`Driver` selection menu and the version that best matches the version you installed from the :guilabel:`Version` selection menu. @@ -41,12 +41,12 @@ manual. Deselect the :guilabel:`Include full driver code example` option to view the connection string. - .. step:: Copy your Connection String + .. step:: Copy your connection string Click the button on the right of the connection string to copy it to your clipboard. - .. step:: Update the Placeholders + .. step:: Update the placeholders Paste this connection string into a file in your preferred text editor and replace the ```` and ```` placeholders with diff --git a/docs/quick-start/create-a-deployment.txt b/docs/quick-start/create-a-deployment.txt index e35ea5293..a4edb7dc1 100644 --- a/docs/quick-start/create-a-deployment.txt +++ b/docs/quick-start/create-a-deployment.txt @@ -11,13 +11,13 @@ your MongoDB database in the cloud. .. procedure:: :style: connected - .. step:: Create a Free MongoDB deployment on Atlas + .. step:: Create a free MongoDB deployment on Atlas Complete the :atlas:`Get Started with Atlas ` guide to set up a new Atlas account and load sample data into a new free tier MongoDB deployment. - .. step:: Save your Credentials + .. step:: Save your credentials After you create your database user, save that user's username and password to a safe location for use in an upcoming step. @@ -25,12 +25,7 @@ your MongoDB database in the cloud. After completing these steps, you have a new free tier MongoDB deployment on Atlas, database user credentials, and sample data loaded into your database. -.. note:: - - If you run into issues on this step, ask for help in the - :community-forum:`MongoDB Community Forums <>` - or submit feedback by using the :guilabel:`Share Feedback` - tab on the right or bottom right side of this page. +.. include:: /includes/quick-start/troubleshoot.rst .. button:: Next: Create a Connection String :uri: /quick-start/create-a-connection-string/ diff --git a/docs/quick-start/download-and-install.txt b/docs/quick-start/download-and-install.txt index 9acd0070f..f4b4b8aa5 100644 --- a/docs/quick-start/download-and-install.txt +++ b/docs/quick-start/download-and-install.txt @@ -57,7 +57,7 @@ to a Laravel web application. Using version ^ for laravel/installer - .. step:: Create a Laravel Application + .. step:: Create a Laravel application Run the following command to generate a new Laravel web application called ``{+quickstart-app-name+}``: @@ -78,22 +78,22 @@ to a Laravel web application. New to Laravel? Check out our bootcamp and documentation. Build something amazing! - .. step:: Add a Laravel Application Encryption Key + .. step:: Add a Laravel application encryption key - Run the following command to add the Laravel application encryption - key, which is required to encrypt cookies: + Navigate to the application directory you created in the previous step: .. code-block:: bash - php artisan key:generate - - .. step:: Add {+odm-short+} to the Dependencies + cd {+quickstart-app-name+} - Navigate to the application directory you created in the previous step: + Run the following command to add the Laravel application encryption + key, which is required to encrypt cookies: .. code-block:: bash - cd {+quickstart-app-name+} + php artisan key:generate + + .. step:: Add {+odm-short+} to the dependencies Run the following command to add the {+odm-short+} dependency to your application: diff --git a/docs/quick-start/view-data.txt b/docs/quick-start/view-data.txt index 4b0ea63e2..35d53368c 100644 --- a/docs/quick-start/view-data.txt +++ b/docs/quick-start/view-data.txt @@ -14,7 +14,7 @@ View MongoDB Data .. procedure:: :style: connected - .. step:: Create a Model and Controller + .. step:: Create a model and controller Create a model called ``Movie`` to represent data from the sample ``movies`` collection in your MongoDB database and the corresponding @@ -33,7 +33,7 @@ View MongoDB Data INFO Controller [app/Http/Controllers/MovieController.php] created successfully. - .. step:: Edit the Model to use {+odm-short+} + .. step:: Edit the model to use {+odm-short+} Open the ``Movie.php`` model in your ``app/Models`` directory and make the following edits: @@ -56,7 +56,7 @@ View MongoDB Data protected $connection = 'mongodb'; } - .. step:: Add a Controller Function + .. step:: Add a controller function Open the ``MovieController.php`` file in your ``app/Http/Controllers`` directory. Replace the ``show()`` function with the @@ -76,7 +76,7 @@ View MongoDB Data ]); } - .. step:: Add a Web Route + .. step:: Add a web route Open the ``web.php`` file in the ``routes`` directory. Add an import for the ``MovieController`` and a route called @@ -91,7 +91,7 @@ View MongoDB Data Route::get('/browse_movies/', [MovieController::class, 'show']); - .. step:: Generate a View + .. step:: Generate a view Run the following command from the application root directory to create a view that displays movie data: @@ -137,7 +137,7 @@ View MongoDB Data - .. step:: Start your Laravel Application + .. step:: Start your Laravel application Run the following command from the application root directory to start your PHP built-in web server: @@ -155,7 +155,7 @@ View MongoDB Data Press Ctrl+C to stop the server - .. step:: View the Movie Data + .. step:: View the movie data Open the URL http://127.0.0.1:8000/browse_movies in your web browser. The page shows a list of movies and details about each of them. diff --git a/docs/quick-start/write-data.txt b/docs/quick-start/write-data.txt index 39c10cf80..e5e5085f0 100644 --- a/docs/quick-start/write-data.txt +++ b/docs/quick-start/write-data.txt @@ -87,7 +87,7 @@ Write Data to MongoDB .. step:: View the Data - Open ``http://127.0.0.1:8000/browse_movies`` in your web browser to view + Open http://127.0.0.1:8000/browse_movies in your web browser to view the movie information that you submitted. The inserted movie appears at the top of the results. From 650317c041076ced646a21637d39ec4fc669f6fa Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 7 Feb 2024 14:28:39 -0500 Subject: [PATCH 180/446] PRR fixes --- docs/quick-start/write-data.txt | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/quick-start/write-data.txt b/docs/quick-start/write-data.txt index e5e5085f0..31568286a 100644 --- a/docs/quick-start/write-data.txt +++ b/docs/quick-start/write-data.txt @@ -14,11 +14,11 @@ Write Data to MongoDB .. procedure:: :style: connected - .. step:: Create the Function to Insert Data + .. step:: Implement the function to insert data - Update the ``store()`` method ``MovieController.php``, located in - the ``app/Http/Controllers`` directory to insert request data - into the database as shown in the following code: + Replace the ``store()`` method in the ``MovieController.php`` file, + located in the ``app/Http/Controllers`` directory with the following + code: .. code-block:: php @@ -30,7 +30,7 @@ Write Data to MongoDB $movie->save(); } - .. step:: Add an API Route that Calls the Controller Function + .. step:: Add an API route that calls the controller function Import the controller and add an API route that calls the ``store()`` method in the ``routes/api.php`` file: @@ -46,7 +46,7 @@ Write Data to MongoDB ]); - .. step:: Update the Model Fields + .. step:: Update the model fields Update the ``Movie`` model in the ``app/Models`` directory to specify the fields that the ``fill()`` method populates as shown in the @@ -61,7 +61,7 @@ Write Data to MongoDB protected $fillable = ['title', 'year', 'runtime', 'imdb', 'plot']; } - .. step:: Post a Request to the API + .. step:: Post a request to the API Create a file called ``movie.json`` and insert the following data: @@ -85,7 +85,7 @@ Write Data to MongoDB curl -H "Content-Type: application/json" --data @movie.json http://localhost:8000/api/movies - .. step:: View the Data + .. step:: View the data Open http://127.0.0.1:8000/browse_movies in your web browser to view the movie information that you submitted. The inserted movie appears at From 6c5b1f7c5a030b2cf2277b5d5b3f8803f3d6bb58 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Thu, 8 Feb 2024 10:34:56 -0500 Subject: [PATCH 181/446] revert .vscode change --- .gitignore | 1 - 1 file changed, 1 deletion(-) diff --git a/.gitignore b/.gitignore index 9c3e7d494..80f343333 100644 --- a/.gitignore +++ b/.gitignore @@ -9,4 +9,3 @@ composer.phar phpunit.xml phpstan.neon /.cache/ -docs/.vscode From cff277384ca0d8da45663c00a494ea84cafd0459 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Thu, 8 Feb 2024 17:50:05 +0100 Subject: [PATCH 182/446] Fix support for subqueries using the query builder (#2717) --- CHANGELOG.md | 5 +++- docs/query-builder.txt | 52 ++++++++++++++++++++++++++++--------- src/Query/Builder.php | 7 +++++ tests/Query/BuilderTest.php | 25 ++++++++++++++++++ 4 files changed, 76 insertions(+), 13 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 179d81f29..69560cbd9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,11 @@ # Changelog All notable changes to this project will be documented in this file. +## [4.1.2] -## [4.1.1] +* Fix support for subqueries using the query builder by @GromNaN in [#2717](https://github.com/mongodb/laravel-mongodb/pull/2717) + +## [4.1.1] - 2024-01-17 * Fix casting issues by [@stubbo](https://github.com/stubbo) in [#2705](https://github.com/mongodb/laravel-mongodb/pull/2705) * Move documentation to the mongodb.com domain at [https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/) diff --git a/docs/query-builder.txt b/docs/query-builder.txt index 40d2b9634..18f03a2e1 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -13,7 +13,7 @@ Query Builder The database driver plugs right into the original query builder. -When using MongoDB connections, you will be able to build fluent queries to +When using MongoDB connections, you will be able to build fluent queries to perform database operations. For your convenience, there is a ``collection`` alias for ``table`` and @@ -85,7 +85,7 @@ Available operations $users = User::whereIn('age', [16, 18, 20])->get(); -When using ``whereNotIn`` objects will be returned if the field is +When using ``whereNotIn`` objects will be returned if the field is non-existent. Combine with ``whereNotNull('age')`` to omit those documents. **whereBetween** @@ -137,7 +137,7 @@ The usage is the same as ``whereMonth`` / ``whereDay`` / ``whereYear`` / ``where **groupBy** -Selected columns that are not grouped will be aggregated with the ``$last`` +Selected columns that are not grouped will be aggregated with the ``$last`` function. .. code-block:: php @@ -230,7 +230,7 @@ You may also specify more columns to update: MongoDB-specific operators ~~~~~~~~~~~~~~~~~~~~~~~~~~ -In addition to the Laravel Eloquent operators, all available MongoDB query +In addition to the Laravel Eloquent operators, all available MongoDB query operators can be used with ``where``: .. code-block:: php @@ -279,7 +279,7 @@ Selects documents where values match a specified regular expression. .. note:: - You can also use the Laravel regexp operations. These will automatically + You can also use the Laravel regexp operations. These will automatically convert your regular expression string to a ``MongoDB\BSON\Regex`` object. .. code-block:: php @@ -292,9 +292,37 @@ The inverse of regexp: User::where('name', 'not regexp', '/.*doe/i')->get(); +**ElemMatch** + +The :manual:`$elemMatch ` operator +matches documents that contain an array field with at least one element that +matches all the specified query criteria. + +The following query matches only those documents where the results array +contains at least one element that is both greater than or equal to 80 and +is less than 85: + +.. code-block:: php + + User::where('results', 'elemMatch', ['gte' => 80, 'lt' => 85])->get(); + +A closure can be used to create more complex sub-queries. + +The following query matches only those documents where the results array +contains at least one element with both product equal to "xyz" and score +greater than or equal to 8: + +.. code-block:: php + + User::where('results', 'elemMatch', function (Builder $builder) { + $builder + ->where('product', 'xyz') + ->andWhere('score', '>', 50); + })->get(); + **Type** -Selects documents if a field is of the specified type. For more information +Selects documents if a field is of the specified type. For more information check: :manual:`$type ` in the MongoDB Server documentation. @@ -304,7 +332,7 @@ MongoDB Server documentation. **Mod** -Performs a modulo operation on the value of a field and selects documents with +Performs a modulo operation on the value of a field and selects documents with a specified result. .. code-block:: php @@ -366,10 +394,10 @@ MongoDB-specific Geo operations You can make a ``geoNear`` query on MongoDB. You can omit specifying the automatic fields on the model. The returned instance is a collection, so you can call the `Collection `__ operations. -Make sure that your model has a ``location`` field, and a +Make sure that your model has a ``location`` field, and a `2ndSphereIndex `__. The data in the ``location`` field must be saved as `GeoJSON `__. -The ``location`` points must be saved as `WGS84 `__ +The ``location`` points must be saved as `WGS84 `__ reference system for geometry calculation. That means that you must save ``longitude and latitude``, in that order specifically, and to find near with calculated distance, you ``must do the same way``. @@ -405,7 +433,7 @@ with calculated distance, you ``must do the same way``. Inserts, updates and deletes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Inserting, updating and deleting records works just like the original Eloquent. +Inserting, updating and deleting records works just like the original Eloquent. Please check `Laravel Docs' Eloquent section `__. Here, only the MongoDB-specific operations are specified. @@ -431,14 +459,14 @@ These expressions will be injected directly into the query. '$where' => '/.*123.*/.test(this["hyphenated-field"])', ])->get(); -You can also perform raw expressions on the internal MongoCollection object. +You can also perform raw expressions on the internal MongoCollection object. If this is executed on the model class, it will return a collection of models. If this is executed on the query builder, it will return the original response. **Cursor timeout** -To prevent ``MongoCursorTimeout`` exceptions, you can manually set a timeout +To prevent ``MongoCursorTimeout`` exceptions, you can manually set a timeout value that will be applied to the cursor: .. code-block:: php diff --git a/src/Query/Builder.php b/src/Query/Builder.php index e69b93890..42492a1b9 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -1363,6 +1363,13 @@ protected function compileWhereRaw(array $where): mixed return $where['sql']; } + protected function compileWhereSub(array $where): mixed + { + $where['value'] = $where['query']->compileWheres(); + + return $this->compileWhereBasic($where); + } + /** * Set custom options for the query. * diff --git a/tests/Query/BuilderTest.php b/tests/Query/BuilderTest.php index 1b3dcd2ad..8f62583ce 100644 --- a/tests/Query/BuilderTest.php +++ b/tests/Query/BuilderTest.php @@ -1127,6 +1127,31 @@ function (Builder $builder) { ], fn (Builder $builder) => $builder->groupBy('foo'), ]; + + yield 'sub-query' => [ + [ + 'find' => [ + [ + 'filters' => [ + '$elemMatch' => [ + '$and' => [ + ['search_by' => 'by search'], + ['value' => 'foo'], + ], + ], + ], + ], + [], // options + ], + ], + fn (Builder $builder) => $builder->where( + 'filters', + 'elemMatch', + function (Builder $elemMatchQuery): void { + $elemMatchQuery->where([ 'search_by' => 'by search', 'value' => 'foo' ]); + }, + ), + ]; } /** @dataProvider provideExceptions */ From 96642752c014fec61397b99e68c9cf3c0cea7e30 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Thu, 8 Feb 2024 14:32:24 -0500 Subject: [PATCH 183/446] DOCSP-36572: update feedback widget title --- docs/includes/quick-start/troubleshoot.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/includes/quick-start/troubleshoot.rst b/docs/includes/quick-start/troubleshoot.rst index e22d624b6..05bd63f00 100644 --- a/docs/includes/quick-start/troubleshoot.rst +++ b/docs/includes/quick-start/troubleshoot.rst @@ -2,6 +2,6 @@ If you run into issues, ask for help in the :community-forum:`MongoDB Community Forums <>` or submit feedback by using - the :guilabel:`Share Feedback` tab on the right or bottom right side of the - page. + the :guilabel:`{+feedback-widget-title+}` tab on the right or bottom right + side of the page. From 0cef5dca6f256920b3b07caa6cce314580dc1f06 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Thu, 15 Feb 2024 09:35:12 +0100 Subject: [PATCH 184/446] PHPORM-145 Fix Query\Builder::dump and dd methods to dump MongoDB query (#2727) Can't be tested in a simple way. The code is trivial. --- CHANGELOG.md | 4 ++++ src/Query/Builder.php | 27 +++++++++++++++++++++++++++ tests/Eloquent/CallBuilderTest.php | 14 -------------- 3 files changed, 31 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 69560cbd9..83be95b8e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,10 @@ # Changelog All notable changes to this project will be documented in this file. +## [unreleased] + +* Fix `Query\Builder::dump` and `dd` methods to dump the MongoDB query by @GromNaN in [#2727](https://github.com/mongodb/laravel-mongodb/pull/2727) + ## [4.1.2] * Fix support for subqueries using the query builder by @GromNaN in [#2717](https://github.com/mongodb/laravel-mongodb/pull/2717) diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 42492a1b9..6454effbc 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -22,6 +22,7 @@ use MongoDB\BSON\Regex; use MongoDB\BSON\UTCDateTime; use MongoDB\Driver\Cursor; +use Override; use RuntimeException; use function array_fill_keys; @@ -37,6 +38,8 @@ use function call_user_func_array; use function count; use function ctype_xdigit; +use function dd; +use function dump; use function end; use function explode; use function func_get_args; @@ -250,6 +253,30 @@ public function cursor($columns = []) throw new RuntimeException('Query not compatible with cursor'); } + /** + * Die and dump the current MongoDB query + * + * @return never-return + */ + #[Override] + public function dd() + { + dd($this->toMql()); + } + + /** + * Dump the current MongoDB query + * + * @return $this + */ + #[Override] + public function dump() + { + dump($this->toMql()); + + return $this; + } + /** * Return the MongoDB query to be run in the form of an element array like ['method' => [arguments]]. * diff --git a/tests/Eloquent/CallBuilderTest.php b/tests/Eloquent/CallBuilderTest.php index 226fe1f25..fa4cb4580 100644 --- a/tests/Eloquent/CallBuilderTest.php +++ b/tests/Eloquent/CallBuilderTest.php @@ -89,19 +89,5 @@ public static function provideUnsupportedMethods(): Generator 'This method is not supported by MongoDB. Try "toMql()" instead', [[['name' => 'Jane']], fn (QueryBuilder $builder) => $builder], ]; - - yield 'dd' => [ - 'dd', - BadMethodCallException::class, - 'This method is not supported by MongoDB. Try "toMql()" instead', - [[['name' => 'Jane']], fn (QueryBuilder $builder) => $builder], - ]; - - yield 'dump' => [ - 'dump', - BadMethodCallException::class, - 'This method is not supported by MongoDB. Try "toMql()" instead', - [[['name' => 'Jane']], fn (QueryBuilder $builder) => $builder], - ]; } } From 26a682468d1583b7e5cc8cf6a4ddc6676e1ddda0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 21 Feb 2024 11:21:06 +0100 Subject: [PATCH 185/446] PHPORM-151 Update signature of Query\Builder::dump to match parent Dumpable (#2730) Laravel 11 breaking change https://github.com/laravel/framework/commit/4326fc350de2d9e5b1578a0122a8c428895e8391#diff-2ed94a0ea151404a12f3c0d52ae9fb5742348578ec4a8ff79d079fa598ff145dR3878 --- CHANGELOG.md | 2 +- src/Query/Builder.php | 6 ++++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 83be95b8e..d2f745851 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,7 +3,7 @@ All notable changes to this project will be documented in this file. ## [unreleased] -* Fix `Query\Builder::dump` and `dd` methods to dump the MongoDB query by @GromNaN in [#2727](https://github.com/mongodb/laravel-mongodb/pull/2727) +* Fix `Query\Builder::dump` and `dd` methods to dump the MongoDB query by @GromNaN in [#2727](https://github.com/mongodb/laravel-mongodb/pull/2727) and [#2730](https://github.com/mongodb/laravel-mongodb/pull/2730) ## [4.1.2] diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 6454effbc..98e6640df 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -267,12 +267,14 @@ public function dd() /** * Dump the current MongoDB query * + * @param mixed ...$args + * * @return $this */ #[Override] - public function dump() + public function dump(mixed ...$args) { - dump($this->toMql()); + dump($this->toMql(), ...$args); return $this; } From decbd999d8ff71d4dbc7f7c59aef562deb5b1e04 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 21 Feb 2024 15:08:20 +0100 Subject: [PATCH 186/446] PHPORM-152 Fix tests for Carbon 3 (#2733) --- tests/Query/BuilderTest.php | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/tests/Query/BuilderTest.php b/tests/Query/BuilderTest.php index 8f62583ce..6df0b1a42 100644 --- a/tests/Query/BuilderTest.php +++ b/tests/Query/BuilderTest.php @@ -564,7 +564,12 @@ function (Builder $builder) { yield 'whereBetween CarbonPeriod' => [ [ 'find' => [ - ['created_at' => ['$gte' => new UTCDateTime($period->start), '$lte' => new UTCDateTime($period->end)]], + [ + 'created_at' => [ + '$gte' => new UTCDateTime($period->getStartDate()), + '$lte' => new UTCDateTime($period->getEndDate()), + ], + ], [], // options ], ], From 5388dd05aa87477cc0ba249093b4ea7dc3737d60 Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Wed, 21 Feb 2024 15:18:05 +0100 Subject: [PATCH 187/446] PHPORM-140: Fix documentation for inverse embed relationships (#2734) --- docs/eloquent-models.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/eloquent-models.txt b/docs/eloquent-models.txt index d10822c37..3ce32c124 100644 --- a/docs/eloquent-models.txt +++ b/docs/eloquent-models.txt @@ -168,7 +168,7 @@ Keep in mind guarding still works, but you may experience unexpected behavior. Schema ------ -The database driver also has (limited) schema builder support. You can +The database driver also has (limited) schema builder support. You can conveniently manipulate collections and set indexes. Basic Usage @@ -351,7 +351,7 @@ relation definition. .. code-block:: php - $book = Book::first(); + $book = User::first()->books()->first(); $user = $book->user; @@ -455,7 +455,7 @@ Inserting and updating embedded models works similar to the ``hasOne`` relation: $book->author() ->create(['name' => 'John Doe']); -You can update the embedded model using the ``save`` method (available since +You can update the embedded model using the ``save`` method (available since release 2.0.0): .. code-block:: php @@ -476,13 +476,13 @@ You can replace the embedded model with a new model like this: Cross-Database Relationships ---------------------------- -If you're using a hybrid MongoDB and SQL setup, you can define relationships +If you're using a hybrid MongoDB and SQL setup, you can define relationships across them. -The model will automatically return a MongoDB-related or SQL-related relation +The model will automatically return a MongoDB-related or SQL-related relation based on the type of the related model. -If you want this functionality to work both ways, your SQL-models will need +If you want this functionality to work both ways, your SQL-models will need to use the ``MongoDB\Laravel\Eloquent\HybridRelations`` trait. **This functionality only works for ``hasOne``, ``hasMany`` and ``belongsTo``.** From 9b72148d75de75b8a2d44ac759c6c11fa79cddf6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Thu, 22 Feb 2024 11:04:10 +0100 Subject: [PATCH 188/446] PHPORM-150 Run CI on Laravel 11 (#2735) * Run CI on Laravel 11 * Fix inherited param type * Duplicate HasAttributes::getStorableEnumValue() to avoid BC break in method signature in Laravel 11 https://github.com/laravel/framework/commit/8647dcf18e6e315e97daea9ed60ef79b420ad327 --- .github/workflows/build-ci.yml | 11 ++++++++--- CHANGELOG.md | 1 + composer.json | 14 ++++++-------- src/Eloquent/Model.php | 23 ++++++++++++++++++++++- src/Query/Builder.php | 6 +----- 5 files changed, 38 insertions(+), 17 deletions(-) diff --git a/.github/workflows/build-ci.yml b/.github/workflows/build-ci.yml index 55cf0f773..0895d7e8a 100644 --- a/.github/workflows/build-ci.yml +++ b/.github/workflows/build-ci.yml @@ -27,7 +27,10 @@ jobs: - php: "8.1" mongodb: "5.0" mode: "low-deps" - + # Laravel 11 + - php: "8.3" + mongodb: "7.0" + mode: "dev" steps: - uses: "actions/checkout@v4" @@ -70,8 +73,10 @@ jobs: restore-keys: "${{ matrix.os }}-composer-" - name: "Install dependencies" - run: composer update --no-interaction $([[ "${{ matrix.mode }}" == low-deps ]] && echo ' --prefer-lowest --prefer-stable') - + run: | + composer update --no-interaction \ + $([[ "${{ matrix.mode }}" == low-deps ]] && echo ' --prefer-lowest') \ + $([[ "${{ matrix.mode }}" != dev ]] && echo ' --prefer-stable') - name: "Run tests" run: "./vendor/bin/phpunit --coverage-clover coverage.xml" env: diff --git a/CHANGELOG.md b/CHANGELOG.md index d2f745851..f25ab8c77 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,7 @@ All notable changes to this project will be documented in this file. ## [unreleased] +* Add support for Laravel 11 by @GromNaN in [#2735](https://github.com/mongodb/laravel-mongodb/pull/2735) * Fix `Query\Builder::dump` and `dd` methods to dump the MongoDB query by @GromNaN in [#2727](https://github.com/mongodb/laravel-mongodb/pull/2727) and [#2730](https://github.com/mongodb/laravel-mongodb/pull/2730) ## [4.1.2] diff --git a/composer.json b/composer.json index 22b75f58f..d19c1149a 100644 --- a/composer.json +++ b/composer.json @@ -24,20 +24,21 @@ "require": { "php": "^8.1", "ext-mongodb": "^1.15", - "illuminate/support": "^10.0", - "illuminate/container": "^10.0", - "illuminate/database": "^10.30", - "illuminate/events": "^10.0", + "illuminate/support": "^10.0|^11", + "illuminate/container": "^10.0|^11", + "illuminate/database": "^10.30|^11", + "illuminate/events": "^10.0|^11", "mongodb/mongodb": "^1.15" }, "require-dev": { "phpunit/phpunit": "^10.3", - "orchestra/testbench": "^8.0", + "orchestra/testbench": "^8.0|^9.0", "mockery/mockery": "^1.4.4", "doctrine/coding-standard": "12.0.x-dev", "spatie/laravel-query-builder": "^5.6", "phpstan/phpstan": "^1.10" }, + "minimum-stability": "dev", "replace": { "jenssegers/mongodb": "self.version" }, @@ -66,9 +67,6 @@ "cs:fix": "phpcbf" }, "config": { - "platform": { - "php": "8.1" - }, "allow-plugins": { "dealerdirect/phpcodesniffer-composer-installer": true } diff --git a/src/Eloquent/Model.php b/src/Eloquent/Model.php index 80a29e4fa..acf83247d 100644 --- a/src/Eloquent/Model.php +++ b/src/Eloquent/Model.php @@ -4,6 +4,7 @@ namespace MongoDB\Laravel\Eloquent; +use BackedEnum; use Carbon\CarbonInterface; use DateTimeInterface; use Illuminate\Contracts\Queue\QueueableCollection; @@ -22,6 +23,7 @@ use MongoDB\BSON\UTCDateTime; use MongoDB\Laravel\Query\Builder as QueryBuilder; use Stringable; +use ValueError; use function array_key_exists; use function array_keys; @@ -38,10 +40,12 @@ use function is_string; use function ltrim; use function method_exists; +use function sprintf; use function str_contains; use function str_starts_with; use function strcmp; use function uniqid; +use function var_export; abstract class Model extends BaseModel { @@ -704,7 +708,7 @@ protected function addCastAttributesToArray(array $attributes, array $mutatedAtt } if ($this->isEnumCastable($key) && (! $castValue instanceof Arrayable)) { - $castValue = $castValue !== null ? $this->getStorableEnumValue($castValue) : null; + $castValue = $castValue !== null ? $this->getStorableEnumValueFromLaravel11($this->getCasts()[$key], $castValue) : null; } if ($castValue instanceof Arrayable) { @@ -717,6 +721,23 @@ protected function addCastAttributesToArray(array $attributes, array $mutatedAtt return $attributes; } + /** + * Duplicate of {@see HasAttributes::getStorableEnumValue()} for Laravel 11 as the signature of the method has + * changed in a non-backward compatible way. + * + * @todo Remove this method when support for Laravel 10 is dropped. + */ + private function getStorableEnumValueFromLaravel11($expectedEnum, $value) + { + if (! $value instanceof $expectedEnum) { + throw new ValueError(sprintf('Value [%s] is not of the expected enum type [%s].', var_export($value, true), $expectedEnum)); + } + + return $value instanceof BackedEnum + ? $value->value + : $value->name; + } + /** * Is a value a BSON type? * diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 98e6640df..4efa76252 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -614,11 +614,7 @@ public function orderBy($column, $direction = 'asc') return $this; } - /** - * @param list{mixed, mixed}|CarbonPeriod $values - * - * @inheritdoc - */ + /** @inheritdoc */ public function whereBetween($column, iterable $values, $boolean = 'and', $not = false) { $type = 'between'; From b1ab9dcf5b8dcbbbdcd6fb5d019e2493f1f8e2f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Thu, 22 Feb 2024 14:10:42 +0100 Subject: [PATCH 189/446] Update CHANGELOG for 4.1.2 --- CHANGELOG.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d2f745851..269992de8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,13 +1,10 @@ # Changelog All notable changes to this project will be documented in this file. -## [unreleased] - -* Fix `Query\Builder::dump` and `dd` methods to dump the MongoDB query by @GromNaN in [#2727](https://github.com/mongodb/laravel-mongodb/pull/2727) and [#2730](https://github.com/mongodb/laravel-mongodb/pull/2730) - -## [4.1.2] +## [4.1.2] - 2024-02-22 * Fix support for subqueries using the query builder by @GromNaN in [#2717](https://github.com/mongodb/laravel-mongodb/pull/2717) +* Fix `Query\Builder::dump` and `dd` methods to dump the MongoDB query by @GromNaN in [#2727](https://github.com/mongodb/laravel-mongodb/pull/2727) and [#2730](https://github.com/mongodb/laravel-mongodb/pull/2730) ## [4.1.1] - 2024-01-17 From 223597f6ed5986603aa82db0914e125e8ede8202 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 26 Feb 2024 11:54:19 +0100 Subject: [PATCH 190/446] Add codeowners file (#2736) --- .github/CODEOWNERS | 1 + 1 file changed, 1 insertion(+) create mode 100644 .github/CODEOWNERS diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 000000000..067d4a1b3 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1 @@ +* @mongodb/dbx-php From 2829bbc8961042e9533d40483f049bf0940e058f Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Fri, 1 Mar 2024 06:41:30 -0500 Subject: [PATCH 191/446] DOCSP-35957: Retrieve guide (#2722) --- docs/index.txt | 3 + docs/retrieve.txt | 473 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 476 insertions(+) create mode 100644 docs/retrieve.txt diff --git a/docs/index.txt b/docs/index.txt index 35f1eef6f..f22848b57 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -13,7 +13,9 @@ Laravel MongoDB :titlesonly: :maxdepth: 1 + /install /quick-start + /retrieve /eloquent-models /query-builder /user-authentication @@ -50,6 +52,7 @@ Fundamentals To learn how to perform the following tasks by using the {+odm-short+}, see the following content: +- :ref:`laravel-fundamentals-retrieve` - :ref:`laravel-eloquent-models` - :ref:`laravel-query-builder` - :ref:`laravel-user-authentication` diff --git a/docs/retrieve.txt b/docs/retrieve.txt new file mode 100644 index 000000000..b607d3d4f --- /dev/null +++ b/docs/retrieve.txt @@ -0,0 +1,473 @@ +.. _laravel-fundamentals-retrieve: + +============== +Retrieve Data +============== + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :keywords: find one, find many, code example + +.. 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 **find operations** +on your MongoDB collections. Find operations allow you to retrieve documents based on +criteria that you specify. + +This guide shows you how to perform the following tasks: + +- :ref:`laravel-retrieve-matching` +- :ref:`laravel-retrieve-all` +- :ref:`Modify Find Operation Behavior ` + +Before You Get Started +---------------------- + +To run the code examples in this guide, complete the :ref:`Quick Start ` +tutorial. This tutorial provides instructions on setting up a MongoDB Atlas instance with +sample data and creating the following files in your Laravel web application: + +- ``Movie.php`` file, which contains a ``Movie`` model to represent documents in the ``movies`` + collection +- ``MovieController.php`` file, which contains a ``show()`` function to run database operations +- ``browse_movies.blade.php`` file, which contains HTML code to display the results of database + operations + +The following sections describe how to edit the files in your Laravel application to run +the find operation code examples and view the expected output. + +.. _laravel-retrieve-matching: + +Retrieve Documents that Match a Query +------------------------------------- + +You can retrieve documents that match a set of criteria by passing a query filter to the ``where()`` +method. A query filter specifies field value requirements and instructs the find operation +to only return documents that meet these requirements. To run the query, call the ``where()`` +method on an Eloquent model or query builder that represents your collection. + +You can use one of the following ``where()`` method calls to build a query: + +- ``where('', )``: builds a query that matches documents in which the + target field has the exact specified value + +- ``where('', '', )``: builds a query that matches + documents in which the target field's value meets the comparison criteria + +After building your query with the ``where()`` method, use the ``get()`` method to +retrieve the query results. + +To apply multiple sets of criteria to the find operation, you can chain a series +of ``where()`` methods together. + +.. tip:: + + To learn more about other query methods in {+odm-short+}, see the :ref:`laravel-query-builder` + page. + +.. _laravel-retrieve-eloquent: + +Use Eloquent Models to Retrieve Documents +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can use Laravel's Eloquent object-relational mapper (ORM) to create models that represent +MongoDB collections. To retrieve documents from a collection, call the ``where()`` method +on the collection's corresponding Eloquent model. + +This example calls two ``where()`` methods on the ``Movie`` Eloquent model to retrieve +documents that meet the following criteria: + +- ``year`` field has a value of ``2010`` +- ``imdb.rating`` nested field has a value greater than ``8.5`` + +.. tabs:: + + .. tab:: Query Syntax + :tabid: query-syntax + + Use the following syntax to specify the query: + + .. code-block:: php + + $movies = Movie::where('year', 2010) + ->where('imdb.rating', '>', 8.5) + ->get(); + + .. tab:: Controller Method + :tabid: controller + + To see the query results in the ``browse_movies`` view, edit the ``show()`` function + in the ``MovieController.php`` file to resemble the following code: + + .. io-code-block:: + :copyable: true + + .. input:: + :language: php + + class MovieController + { + public function show() + { + $movies = Movie::where('year', 2010) + ->where('imdb.rating', '>', 8.5) + ->get(); + + return view('browse_movies', [ + 'movies' => $movies + ]); + } + } + + .. output:: + :language: none + :visible: false + + Title: Inception + Year: 2010 + Runtime: 148 + IMDB Rating: 8.8 + IMDB Votes: 1294646 + Plot: A thief who steals corporate secrets through use of dream-sharing + technology is given the inverse task of planting an idea into the mind of a CEO. + + Title: Senna + Year: 2010 + Runtime: 106 + IMDB Rating: 8.6 + IMDB Votes: 41904 + Plot: A documentary on Brazilian Formula One racing driver Ayrton Senna, who won the + F1 world championship three times before his death at age 34. + +.. _laravel-retrieve-query-builder: + +Use Laravel Queries to Retrieve Documents +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can use Laravel's database query builder to run find operations instead of using Eloquent +models. To run the database query, import the ``DB`` facade into your controller file and use +Laravel's query builder syntax. + +This example uses Laravel's query builder to retrieve documents in which the value +of the ``imdb.votes`` nested field is ``350``. + +.. tabs:: + + .. tab:: Query Syntax + :tabid: query-syntax + + Use the following syntax to specify the query: + + .. code-block:: php + + $movies = DB::connection('mongodb') + ->collection('movies') + ->where('imdb.votes', 350) + ->get(); + + .. tab:: Controller Method + :tabid: controller + + To see the query results in the ``browse_movies`` view, edit the ``show()`` function + in the ``MovieController.php`` file to resemble the following code: + + .. io-code-block:: + :copyable: true + + .. input:: + :language: php + + class MovieController + { + public function show() + { + $movies = DB::connection('mongodb') + ->collection('movies') + ->where('imdb.votes', 350) + ->get(); + + return view('browse_movies', [ + 'movies' => $movies + ]); + } + } + + .. output:: + :language: none + :visible: false + + Title: Murder in New Hampshire: The Pamela Wojas Smart Story + Year: 1991 + Runtime: 100 + IMDB Rating: 5.9 + IMDB Votes: 350 + Plot: Pamela Smart knows exactly what she wants and is willing to do + anything to get it. She is fed up with teaching, and her marriage offers + little excitement. Looking for a way out she applies ... + + Title: Ah Fu + Year: 2000 + Runtime: 105 + IMDB Rating: 6.6 + IMDB Votes: 350 + Plot: After a 13-year imprisonment in Hong Kong, a kickboxer challenges the + current champion in order to restore his honor. + + Title: Bandage + Year: 2010 + Runtime: 119 + IMDB Rating: 7 + IMDB Votes: 350 + Plot: Four boys have their friendship and musical talents tested in the ever + changing worlds of the music industry and real life in 1990s Japan. + + Title: Great Migrations + Year: 2010 + Runtime: 45 + IMDB Rating: 8.2 + IMDB Votes: 350 + Plot: Great Migrations takes viewers on the epic journeys animals undertake to + ensure the survival of their species. + + Then, make the following changes to your Laravel Quick Start application: + + - Import the ``DB`` facade into your ``MovieController.php`` file by adding the + ``use Illuminate\Support\Facades\DB`` use statement + - Replace the contents of your ``browse_movies.blade.php`` file with the following code: + + .. code-block:: php + + + + + Browse Movies + + +

Movies

+ + @forelse ($movies as $movie) +

+ Title: {{ $movie['title'] }}
+ Year: {{ $movie['year'] }}
+ Runtime: {{ $movie['runtime'] }}
+ IMDB Rating: {{ $movie['imdb']['rating'] }}
+ IMDB Votes: {{ $movie['imdb']['votes'] }}
+ Plot: {{ $movie['plot'] }}
+

+ @empty +

No results

+ @endforelse + + + + + .. note:: + + Since the Laravel query builder returns data as an array rather than as instances of the Eloquent model class, + the view accesses the fields by using the array syntax instead of the ``->`` object operator. + +.. _laravel-retrieve-all: + +Retrieve All Documents in a Collection +-------------------------------------- + +You can retrieve all documents in a collection by omitting the query filter. +To return the documents, call the ``get()`` method on an Eloquent model that +represents your collection. Alternatively, you can use the ``get()`` method's +alias ``all()`` to perform the same operation. + +Use the following syntax to run a find operation that matches all documents: + +.. code-block:: php + + $movies = Movie::get(); + +.. warning:: + + The ``movies`` collection in the Atlas sample dataset contains a large amount of data. + Retrieving and displaying all documents in this collection might cause your web + application to time out. + + To avoid this issue, specify a document limit by using the ``take()`` method. For + more information about ``take()``, see the :ref:`laravel-modify-find` section of this + guide. + +.. _laravel-modify-find: + +Modify Behavior +--------------- + +You can modify the results of a find operation by chaining additional methods +to ``where()``. + +The following sections demonstrate how to modify the behavior of the ``where()`` +method: + +- :ref:`laravel-skip-limit` uses the ``skip()`` method to set the number of documents + to skip and the ``take()`` method to set the total number of documents to return +- :ref:`laravel-retrieve-one` uses the ``first()`` method to return the first document + that matches the query filter + +.. _laravel-skip-limit: + +Skip and Limit Results +~~~~~~~~~~~~~~~~~~~~~~ + +This example queries for documents in which the ``year`` value is ``1999``. +The operation skips the first ``2`` matching documents and outputs a total of ``3`` +documents. + +.. tabs:: + + .. tab:: Query Syntax + :tabid: query-syntax + + Use the following syntax to specify the query: + + .. code-block:: php + + $movies = Movie::where('year', 1999) + ->skip(2) + ->take(3) + ->get(); + + .. tab:: Controller Method + :tabid: controller + + To see the query results in the ``browse_movies`` view, edit the ``show()`` function + in the ``MovieController.php`` file to resemble the following code: + + .. io-code-block:: + :copyable: true + + .. input:: + :language: php + + class MovieController + { + public function show() + { + $movies = Movie::where('year', 1999) + ->skip(2) + ->take(3) + ->get(); + + return view('browse_movies', [ + 'movies' => $movies + ]); + } + } + + .. output:: + :language: none + :visible: false + + Title: Three Kings + Year: 1999 + Runtime: 114 + IMDB Rating: 7.2 + IMDB Votes: 130677 + Plot: In the aftermath of the Persian Gulf War, 4 soldiers set out to steal gold + that was stolen from Kuwait, but they discover people who desperately need their help. + + Title: Toy Story 2 + Year: 1999 + Runtime: 92 + IMDB Rating: 7.9 + IMDB Votes: 346655 + Plot: When Woody is stolen by a toy collector, Buzz and his friends vow to rescue him, + but Woody finds the idea of immortality in a museum tempting. + + Title: Beowulf + Year: 1999 + Runtime: 95 + IMDB Rating: 4 + IMDB Votes: 9296 + Plot: A sci-fi update of the famous 6th Century poem. In a beseiged land, Beowulf must + battle against the hideous creature Grendel and his vengeance seeking mother. + +.. _laravel-retrieve-one: + +Return the First Result +~~~~~~~~~~~~~~~~~~~~~~~ + +To retrieve the first document that matches a set of criteria, use the ``where()`` method +followed by the ``first()`` method. + +Chain the ``orderBy()`` method to ``first()`` to get consistent results when you query on a unique +value. If you omit the ``orderBy()`` method, MongoDB returns the matching documents according to +the documents' natural order, or as they appear in the collection. + +This example queries for documents in which the value of the ``runtime`` field is +``30`` and returns the first matching document according to the value of the ``_id`` +field. + +.. tabs:: + + .. tab:: Query Syntax + :tabid: query-syntax + + Use the following syntax to specify the query: + + .. code-block:: php + + $movies = Movie::where('runtime', 30) + ->orderBy('_id') + ->first(); + + .. tab:: Controller Method + :tabid: controller + + To see the query results in the ``browse_movies`` view, edit the ``show()`` function + in the ``MovieController.php`` file to resemble the following code: + + .. io-code-block:: + :copyable: true + + .. input:: + :language: php + + class MovieController + { + public function show() + { + $movies = Movie::where('runtime', 30) + ->orderBy('_id') + ->first(); + + return view('browse_movies', [ + 'movies' => $movies + ]); + } + } + + .. output:: + :language: none + :visible: false + + Title: Statues also Die + Year: 1953 + Runtime: 30 + IMDB Rating: 7.6 + IMDB Votes: 620 + Plot: A documentary of black art. + +.. tip:: + + To learn more about sorting, see the following resources: + + - :manual:`Natural order ` + in the Server manual glossary + - `Ordering, Grouping, Limit and Offset `__ + in the Laravel documentation + From 7af9a1a3e77aba6112f8b39f1e1a1971f25e6838 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Fri, 1 Mar 2024 14:08:35 +0100 Subject: [PATCH 192/446] PHPORM-143 Ensure date are read using local timezone (#2739) --- CHANGELOG.md | 4 ++++ src/Eloquent/Model.php | 5 ++++- tests/ModelTest.php | 30 ++++++++++++++++++++++++++++++ 3 files changed, 38 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 269992de8..b536def07 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,10 @@ # Changelog All notable changes to this project will be documented in this file. +## [4.1.3] - unreleased + +* Fix the timezone of `datetime` fields when they are read from the database by @GromNaN in [#2739](https://github.com/mongodb/laravel-mongodb/pull/2739) + ## [4.1.2] - 2024-02-22 * Fix support for subqueries using the query builder by @GromNaN in [#2717](https://github.com/mongodb/laravel-mongodb/pull/2717) diff --git a/src/Eloquent/Model.php b/src/Eloquent/Model.php index 80a29e4fa..dbf7579cd 100644 --- a/src/Eloquent/Model.php +++ b/src/Eloquent/Model.php @@ -6,6 +6,7 @@ use Carbon\CarbonInterface; use DateTimeInterface; +use DateTimeZone; use Illuminate\Contracts\Queue\QueueableCollection; use Illuminate\Contracts\Queue\QueueableEntity; use Illuminate\Contracts\Support\Arrayable; @@ -30,6 +31,7 @@ use function array_values; use function class_basename; use function count; +use function date_default_timezone_get; use function explode; use function func_get_args; use function in_array; @@ -137,7 +139,8 @@ protected function asDateTime($value) { // Convert UTCDateTime instances to Carbon. if ($value instanceof UTCDateTime) { - return Date::instance($value->toDateTime()); + return Date::instance($value->toDateTime()) + ->setTimezone(new DateTimeZone(date_default_timezone_get())); } return parent::asDateTime($value); diff --git a/tests/ModelTest.php b/tests/ModelTest.php index e34e3d6f2..ec1579869 100644 --- a/tests/ModelTest.php +++ b/tests/ModelTest.php @@ -31,6 +31,7 @@ use function abs; use function array_keys; use function array_merge; +use function date_default_timezone_set; use function get_debug_type; use function hex2bin; use function sleep; @@ -38,6 +39,8 @@ use function strlen; use function time; +use const DATE_ATOM; + class ModelTest extends TestCase { public function tearDown(): void @@ -670,6 +673,33 @@ public function testUnsetDotAttributesAndSet(): void $this->assertSame(['note2' => 'DEF', 'note1' => 'ABC'], $user->notes); } + public function testDateUseLocalTimeZone(): void + { + // The default timezone is reset to UTC before every test in OrchestraTestCase + $tz = 'Australia/Sydney'; + date_default_timezone_set($tz); + + $date = new DateTime('1965/03/02 15:30:10'); + $user = User::create(['birthday' => $date]); + $this->assertInstanceOf(Carbon::class, $user->birthday); + $this->assertEquals($tz, $user->birthday->getTimezone()->getName()); + $user->save(); + + $user = User::find($user->_id); + $this->assertEquals($date, $user->birthday); + $this->assertEquals($tz, $user->birthday->getTimezone()->getName()); + $this->assertSame('1965-03-02T15:30:10+10:00', $user->birthday->format(DATE_ATOM)); + + $tz = 'America/New_York'; + date_default_timezone_set($tz); + $user = User::find($user->_id); + $this->assertEquals($date, $user->birthday); + $this->assertEquals($tz, $user->birthday->getTimezone()->getName()); + $this->assertSame('1965-03-02T00:30:10-05:00', $user->birthday->format(DATE_ATOM)); + + date_default_timezone_set('UTC'); + } + public function testDates(): void { $user = User::create(['name' => 'John Doe', 'birthday' => new DateTime('1965/1/1')]); From 87741d701dddd8b2b533314a7ebb741589913a09 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 5 Mar 2024 09:49:44 +0100 Subject: [PATCH 193/446] PHPORM-148 Fix `null` in `datetime` fields and reset time in `date` field with custom format (#2741) - Fix #2729 by removing the method `Model::castAttribute()` that was introduced by #2658 in 4.1.0. Tests added to ensure `null` is allowed in `date`, `datetime`, `immutable_date`, `immutable_datetime` and the variants with custom formats. - Change the behavior of `immutable_date:j.n.Y H:i` (with custom format), to reset the time. This behave differently than [Laravel 10.46 that treats it like a `immutable_datetime`](https://github.com/laravel/framework/blob/v10.46.0/src/Illuminate/Database/Eloquent/Concerns/HasAttributes.php#L866-L869). --- CHANGELOG.md | 5 +++-- src/Eloquent/Model.php | 18 +++--------------- tests/Casts/DateTest.php | 24 ++++++++++++++++++++++++ tests/Casts/DatetimeTest.php | 24 ++++++++++++++++++++++++ 4 files changed, 54 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b536def07..56fe478d9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,9 +1,10 @@ # Changelog All notable changes to this project will be documented in this file. -## [4.1.3] - unreleased +## [4.1.3] - 2024-03-05 -* Fix the timezone of `datetime` fields when they are read from the database by @GromNaN in [#2739](https://github.com/mongodb/laravel-mongodb/pull/2739) +* Fix the timezone of `datetime` fields when they are read from the database. By @GromNaN in [#2739](https://github.com/mongodb/laravel-mongodb/pull/2739) +* Fix support for null values in `datetime` and reset `date` fields with custom format to the start of the day. By @GromNaN in [#2741](https://github.com/mongodb/laravel-mongodb/pull/2741) ## [4.1.2] - 2024-02-22 diff --git a/src/Eloquent/Model.php b/src/Eloquent/Model.php index dbf7579cd..83239c8eb 100644 --- a/src/Eloquent/Model.php +++ b/src/Eloquent/Model.php @@ -205,9 +205,10 @@ protected function transformModelValue($key, $value) if ($this->hasCast($key) && $value instanceof CarbonInterface) { $value->settings(array_merge($value->getSettings(), ['toStringFormat' => $this->getDateFormat()])); + // "date" cast resets the time to 00:00:00. $castType = $this->getCasts()[$key]; - if ($this->isCustomDateTimeCast($castType) && str_starts_with($castType, 'date:')) { - $value->startOfDay(); + if (str_starts_with($castType, 'date:') || str_starts_with($castType, 'immutable_date:')) { + $value = $value->startOfDay(); } } @@ -315,19 +316,6 @@ protected function fromDecimal($value, $decimals) return new Decimal128($this->asDecimal($value, $decimals)); } - /** @inheritdoc */ - protected function castAttribute($key, $value) - { - $castType = $this->getCastType($key); - - return match ($castType) { - 'immutable_custom_datetime','immutable_datetime' => str_starts_with($this->getCasts()[$key], 'immutable_date:') ? - $this->asDate($value)->toImmutable() : - $this->asDateTime($value)->toImmutable(), - default => parent::castAttribute($key, $value) - }; - } - /** @inheritdoc */ public function attributesToArray() { diff --git a/tests/Casts/DateTest.php b/tests/Casts/DateTest.php index 20ce5dd9a..64743bce0 100644 --- a/tests/Casts/DateTest.php +++ b/tests/Casts/DateTest.php @@ -52,6 +52,12 @@ public function testDate(): void self::assertInstanceOf(Carbon::class, $refetchedModel->dateField); self::assertInstanceOf(UTCDateTime::class, $model->getRawOriginal('dateField')); self::assertEquals(now()->subDay()->startOfDay()->format('Y-m-d H:i:s'), (string) $refetchedModel->dateField); + + $model = Casting::query()->create(); + $this->assertNull($model->dateField); + + $model->update(['dateField' => null]); + $this->assertNull($model->dateField); } public function testDateAsString(): void @@ -84,6 +90,12 @@ public function testDateWithCustomFormat(): void self::assertInstanceOf(Carbon::class, $model->dateWithFormatField); self::assertEquals(now()->startOfDay()->subDay()->format('j.n.Y H:i'), (string) $model->dateWithFormatField); + + $model = Casting::query()->create(); + $this->assertNull($model->dateWithFormatField); + + $model->update(['dateWithFormatField' => null]); + $this->assertNull($model->dateWithFormatField); } public function testImmutableDate(): void @@ -105,6 +117,12 @@ public function testImmutableDate(): void Carbon::createFromTimestamp(1698577443)->subDay()->startOfDay()->format('Y-m-d H:i:s'), (string) $model->immutableDateField, ); + + $model = Casting::query()->create(); + $this->assertNull($model->immutableDateField); + + $model->update(['immutableDateField' => null]); + $this->assertNull($model->immutableDateField); } public function testImmutableDateWithCustomFormat(): void @@ -126,5 +144,11 @@ public function testImmutableDateWithCustomFormat(): void Carbon::createFromTimestamp(1698577443)->subDay()->startOfDay()->format('j.n.Y H:i'), (string) $model->immutableDateWithFormatField, ); + + $model = Casting::query()->create(); + $this->assertNull($model->immutableDateWithFormatField); + + $model->update(['immutableDateWithFormatField' => null]); + $this->assertNull($model->immutableDateWithFormatField); } } diff --git a/tests/Casts/DatetimeTest.php b/tests/Casts/DatetimeTest.php index 022ed3535..49f1cd9c6 100644 --- a/tests/Casts/DatetimeTest.php +++ b/tests/Casts/DatetimeTest.php @@ -36,6 +36,12 @@ public function testDatetime(): void self::assertInstanceOf(Carbon::class, $model->datetimeField); self::assertInstanceOf(UTCDateTime::class, $model->getRawOriginal('datetimeField')); self::assertEquals(now()->subDay()->format('Y-m-d H:i:s'), (string) $model->datetimeField); + + $model = Casting::query()->create(); + $this->assertNull($model->datetimeField); + + $model->update(['datetimeField' => null]); + $this->assertNull($model->datetimeField); } public function testDatetimeAsString(): void @@ -70,6 +76,12 @@ public function testDatetimeWithCustomFormat(): void self::assertInstanceOf(Carbon::class, $model->datetimeWithFormatField); self::assertEquals(now()->subDay()->format('j.n.Y H:i'), (string) $model->datetimeWithFormatField); + + $model = Casting::query()->create(); + $this->assertNull($model->datetimeWithFormatField); + + $model->update(['datetimeWithFormatField' => null]); + $this->assertNull($model->datetimeWithFormatField); } public function testImmutableDatetime(): void @@ -92,6 +104,12 @@ public function testImmutableDatetime(): void Carbon::createFromTimestamp(1698577443)->subDay()->format('Y-m-d H:i:s'), (string) $model->immutableDatetimeField, ); + + $model = Casting::query()->create(); + $this->assertNull($model->immutableDatetimeField); + + $model->update(['immutableDatetimeField' => null]); + $this->assertNull($model->immutableDatetimeField); } public function testImmutableDatetimeWithCustomFormat(): void @@ -113,5 +131,11 @@ public function testImmutableDatetimeWithCustomFormat(): void Carbon::createFromTimestamp(1698577443)->subDay()->format('j.n.Y H:i'), (string) $model->immutableDatetimeWithFormatField, ); + + $model = Casting::query()->create(); + $this->assertNull($model->immutableDatetimeWithFormatField); + + $model->update(['immutableDatetimeWithFormatField' => null]); + $this->assertNull($model->immutableDatetimeWithFormatField); } } From d2d78455ac5ccf24bed6b37873b61972c6b5b28e Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 5 Mar 2024 09:56:54 +0100 Subject: [PATCH 194/446] Bump ramsey/composer-install from 2.2.0 to 3.0.0 (#2745) --- .github/workflows/coding-standards.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/coding-standards.yml b/.github/workflows/coding-standards.yml index 14202e858..0d5ec53cd 100644 --- a/.github/workflows/coding-standards.yml +++ b/.github/workflows/coding-standards.yml @@ -49,7 +49,7 @@ jobs: run: "php --ri mongodb" - name: "Install dependencies with Composer" - uses: "ramsey/composer-install@2.2.0" + uses: "ramsey/composer-install@3.0.0" with: composer-options: "--no-suggest" From eb9eb100ee845d7a58f47b7a4b5b648e4c63f6f1 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Wed, 6 Mar 2024 11:08:22 -0500 Subject: [PATCH 195/446] DOCSP-35931: Issues and Help page (#2744) --- docs/compatibility.txt | 2 +- docs/index.txt | 61 +++++----------------------------------- docs/issues-and-help.txt | 56 ++++++++++++++++++++++++++++++++++++ 3 files changed, 64 insertions(+), 55 deletions(-) create mode 100644 docs/issues-and-help.txt diff --git a/docs/compatibility.txt b/docs/compatibility.txt index 40ffef740..1ab0f6c91 100644 --- a/docs/compatibility.txt +++ b/docs/compatibility.txt @@ -23,5 +23,5 @@ The following compatibility table specifies the versions of Laravel and .. include:: /includes/framework-compatibility-laravel.rst To find compatibility information for unmaintained versions of {+odm-short+}, -see `Laravel Version Compatibility `__ +see `Laravel Version Compatibility <{+mongodb-laravel-gh+}/blob/3.9/README.md#installation>`__ on GitHub. diff --git a/docs/index.txt b/docs/index.txt index f22848b57..cd210fed2 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -13,7 +13,6 @@ Laravel MongoDB :titlesonly: :maxdepth: 1 - /install /quick-start /retrieve /eloquent-models @@ -21,6 +20,7 @@ Laravel MongoDB /user-authentication /queues /transactions + /issues-and-help /compatibility /upgrade @@ -59,6 +59,12 @@ see the following content: - :ref:`laravel-queues` - :ref:`laravel-transactions` +Issues & Help +------------- + +Learn how to report bugs, contribute to the library, and find +more resources in the :ref:`laravel-issues-and-help` section. + Compatibility ------------- @@ -71,57 +77,4 @@ Upgrade Versions Learn what changes you might need to make to your application to upgrade versions in the :ref:`laravel-upgrading` section. -Reporting Issues ----------------- - -We are lucky to have a vibrant PHP community that includes users of varying -experience with MongoDB PHP Library and {+odm-short+}. To get support for -general questions, search or post in the -:community-forum:`MongoDB Community Forums <>`. - -To learn more about MongoDB support options, see the -`Technical Support `__ page. - - -Bugs / Feature Requests ------------------------ - -If you've found a bug or want to see a new feature in {+odm-short+}, -please report it in the GitHub issues section of the -`mongodb/laravel-mongodb `__ -repository. - -If you want to contribute code, see the following section for instructions on -submitting pull requests. - -To report a bug or request a new feature, perform the following steps: - -1. Visit the `GitHub issues `__ - section and search for any similar issues or bugs. -#. If you find a matching issue, you can reply to the thread to report that - you have a similar issue or request. -#. If you cannot find a matching issue, click :guilabel:`New issue` and select - the appropriate issue type. -#. If you selected "Bug report" or "Feature request", please provide as much - information as possible about the issue. Click :guilabel:`Submit new issue` - to complete your submission. - -If you've identified a security vulnerability in any official MongoDB -product, please report it according to the instructions found in the -:manual:`Create a Vulnerability Report page `. - -For general questions and support requests, please use one of MongoDB's -:manual:`Technical Support ` channels. - -Pull Requests -------------- - -We are happy to accept contributions to help improve the {+odm-short+}. - -We track current development in `PHPORM `__ -MongoDB JIRA project. - -To learn more about contributing to this project, see the -`CONTRIBUTING.md `__ -guide on GitHub. diff --git a/docs/issues-and-help.txt b/docs/issues-and-help.txt new file mode 100644 index 000000000..ff4a1dbb9 --- /dev/null +++ b/docs/issues-and-help.txt @@ -0,0 +1,56 @@ +.. _laravel-issues-and-help: + +============= +Issues & Help +============= + +We are lucky to have a vibrant PHP community that includes users of varying +experience with MongoDB PHP Library and {+odm-short+}. To get support for +general questions, search or post in the +:community-forum:`MongoDB PHP Community Forums `. + +To learn more about MongoDB support options, see the +`Technical Support `__ page. + +Bugs / Feature Requests +----------------------- + +If you find a bug or want to see a new feature in {+odm-short+}, +please report it as a GitHub issue in the `mongodb/laravel-mongodb +<{+mongodb-laravel-gh+}>`__ repository. + +If you want to contribute code, see the :ref:`laravel-pull-requests` section +for instructions on submitting pull requests. + +To report a bug or request a new feature, perform the following steps: + +1. Review the `GitHub issues list <{+mongodb-laravel-gh+}/issues>`__ + in the source repository and search for any existing issues that address your concern. +#. If you find a matching issue, you can reply to the thread to report that + you have a similar issue or request. +#. If you cannot find a matching issue, click :guilabel:`New issue` and select + the appropriate issue type. +#. If you select "Bug report" or "Feature request" as the issue type, please provide as + much information as possible about the issue. Click :guilabel:`Submit new issue` + to complete your submission. + +If you've identified a security vulnerability in any official MongoDB +product, please report it according to the instructions found in the +:manual:`Create a Vulnerability Report page `. + +For general questions and support requests, please use one of MongoDB's +:manual:`Technical Support ` channels. + +.. _laravel-pull-requests: + +Pull Requests +------------- + +We are happy to accept contributions to help improve {+odm-short+}. + +We track current development in `PHPORM `__ +MongoDB JIRA project. + +To learn more about contributing to this project, see the +`CONTRIBUTING.md <{+mongodb-laravel-gh+}/blob/{+package-version+}/CONTRIBUTING.md>`__ +guide on GitHub. From 8a7c780eb06bed3fbea4e90522ee69df2530dbc0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 6 Mar 2024 17:09:51 +0100 Subject: [PATCH 196/446] Add Laravel version to CI job name (#2749) --- .github/workflows/build-ci.yml | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/.github/workflows/build-ci.yml b/.github/workflows/build-ci.yml index 55cf0f773..780f6cbcd 100644 --- a/.github/workflows/build-ci.yml +++ b/.github/workflows/build-ci.yml @@ -8,7 +8,7 @@ jobs: build: runs-on: "${{ matrix.os }}" - name: "PHP v${{ matrix.php }} with MongoDB ${{ matrix.mongodb }} ${{ matrix.mode }}" + name: "PHP ${{ matrix.php }} Laravel ${{ matrix.laravel }} MongoDB ${{ matrix.mongodb }} ${{ matrix.mode }}" strategy: matrix: @@ -23,8 +23,11 @@ jobs: - "8.1" - "8.2" - "8.3" + laravel: + - "10.*" include: - php: "8.1" + laravel: "10.*" mongodb: "5.0" mode: "low-deps" @@ -58,6 +61,9 @@ jobs: if: ${{ runner.debug }} run: "docker version && env" + - name: "Restrict Laravel version" + run: "composer require --dev --no-update 'laravel/framework:${{ matrix.laravel }}'" + - name: "Download Composer cache dependencies from cache" id: "composer-cache" run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT From faaeb3a27231ae3c9310a4d3607a17d25e6fe925 Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Thu, 7 Mar 2024 10:19:10 +0100 Subject: [PATCH 197/446] Add workflow to create merge-up pull request (#2748) --- .github/workflows/merge-up.yml | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 .github/workflows/merge-up.yml diff --git a/.github/workflows/merge-up.yml b/.github/workflows/merge-up.yml new file mode 100644 index 000000000..a44a8501c --- /dev/null +++ b/.github/workflows/merge-up.yml @@ -0,0 +1,33 @@ +name: Merge up + +on: + push: + branches: + - "[0-9]+.[0-9]+" + +permissions: + contents: write + pull-requests: write + +env: + GH_TOKEN: ${{ github.token }} + +jobs: + merge-up: + name: Create merge up pull request + runs-on: ubuntu-latest + + steps: + - name: Checkout + id: checkout + uses: actions/checkout@v4 + with: + # fetch-depth 0 is required to fetch all branches, not just the branch being built + fetch-depth: 0 + + - name: Create pull request + id: create-pull-request + uses: alcaeus/automatic-merge-up-action@main + with: + ref: ${{ github.ref_name }} + branchNamePattern: '.' From 963d01f1af6b1d54082399972523bde4abdf0788 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Thu, 7 Mar 2024 10:30:11 +0100 Subject: [PATCH 198/446] Test Laravel 10 and 11 (#2746) --- .github/workflows/build-ci.yml | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/.github/workflows/build-ci.yml b/.github/workflows/build-ci.yml index 8261f4514..c6a84e120 100644 --- a/.github/workflows/build-ci.yml +++ b/.github/workflows/build-ci.yml @@ -24,16 +24,17 @@ jobs: - "8.2" - "8.3" laravel: - - "10.*" + - "10.*" + - "11.*" include: - php: "8.1" laravel: "10.*" mongodb: "5.0" mode: "low-deps" - # Laravel 11 - - php: "8.3" - mongodb: "7.0" - mode: "dev" + exclude: + - php: "8.1" + laravel: "11.*" + steps: - uses: "actions/checkout@v4" @@ -79,10 +80,7 @@ jobs: restore-keys: "${{ matrix.os }}-composer-" - name: "Install dependencies" - run: | - composer update --no-interaction \ - $([[ "${{ matrix.mode }}" == low-deps ]] && echo ' --prefer-lowest') \ - $([[ "${{ matrix.mode }}" != dev ]] && echo ' --prefer-stable') + run: composer update --no-interaction $([[ "${{ matrix.mode }}" == low-deps ]] && echo ' --prefer-lowest') - name: "Run tests" run: "./vendor/bin/phpunit --coverage-clover coverage.xml" env: From 19fc80159fac77f964e34e271e522c256896a5c0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 11 Mar 2024 10:08:18 +0100 Subject: [PATCH 199/446] PHPORM-139 Implement `Model::createOrFirst()` using `findOneAndUpdate` operation (#2742) Use monitoring to track if model was created or found --- CHANGELOG.md | 1 + src/Eloquent/Builder.php | 38 ++++++++++++++++++ .../FindAndModifyCommandSubscriber.php | 34 ++++++++++++++++ tests/ModelTest.php | 39 +++++++++++++++++++ 4 files changed, 112 insertions(+) create mode 100644 src/Internal/FindAndModifyCommandSubscriber.php diff --git a/CHANGELOG.md b/CHANGELOG.md index 2263ac29d..a8c2cefc4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,7 @@ All notable changes to this project will be documented in this file. ## [unreleased] * Add support for Laravel 11 by @GromNaN in [#2735](https://github.com/mongodb/laravel-mongodb/pull/2735) +* Implement Model::createOrFirst() using findOneAndUpdate operation by @GromNaN in [#2742](https://github.com/mongodb/laravel-mongodb/pull/2742) ## [4.1.3] - 2024-03-05 diff --git a/src/Eloquent/Builder.php b/src/Eloquent/Builder.php index b9005c442..6ef960456 100644 --- a/src/Eloquent/Builder.php +++ b/src/Eloquent/Builder.php @@ -7,9 +7,12 @@ use Illuminate\Database\ConnectionInterface; use Illuminate\Database\Eloquent\Builder as EloquentBuilder; use MongoDB\Driver\Cursor; +use MongoDB\Laravel\Collection; use MongoDB\Laravel\Helpers\QueriesRelationships; +use MongoDB\Laravel\Internal\FindAndModifyCommandSubscriber; use MongoDB\Model\BSONDocument; +use function array_intersect_key; use function array_key_exists; use function array_merge; use function collect; @@ -183,6 +186,41 @@ public function raw($value = null) return $results; } + /** + * Attempt to create the record if it does not exist with the matching attributes. + * If the record exists, it will be returned. + * + * @param array $attributes The attributes to check for duplicate records + * @param array $values The attributes to insert if no matching record is found + */ + public function createOrFirst(array $attributes = [], array $values = []): Model + { + // Apply casting and default values to the attributes + $instance = $this->newModelInstance($values + $attributes); + $values = $instance->getAttributes(); + $attributes = array_intersect_key($attributes, $values); + + return $this->raw(function (Collection $collection) use ($attributes, $values) { + $listener = new FindAndModifyCommandSubscriber(); + $collection->getManager()->addSubscriber($listener); + + try { + $document = $collection->findOneAndUpdate( + $attributes, + ['$setOnInsert' => $values], + ['upsert' => true, 'new' => true, 'typeMap' => ['root' => 'array', 'document' => 'array']], + ); + } finally { + $collection->getManager()->removeSubscriber($listener); + } + + $model = $this->model->newFromBuilder($document); + $model->wasRecentlyCreated = $listener->created; + + return $model; + }); + } + /** * Add the "updated at" column to an array of values. * TODO Remove if https://github.com/laravel/framework/commit/6484744326531829341e1ff886cc9b628b20d73e diff --git a/src/Internal/FindAndModifyCommandSubscriber.php b/src/Internal/FindAndModifyCommandSubscriber.php new file mode 100644 index 000000000..55b13436b --- /dev/null +++ b/src/Internal/FindAndModifyCommandSubscriber.php @@ -0,0 +1,34 @@ +created = ! $event->getReply()->lastErrorObject->updatedExisting; + } +} diff --git a/tests/ModelTest.php b/tests/ModelTest.php index ec1579869..f4d459422 100644 --- a/tests/ModelTest.php +++ b/tests/ModelTest.php @@ -1044,4 +1044,43 @@ public function testNumericFieldName(): void $this->assertInstanceOf(User::class, $found); $this->assertEquals([3 => 'two.three'], $found[2]); } + + public function testCreateOrFirst() + { + $user1 = User::createOrFirst(['email' => 'taylorotwell@gmail.com']); + + $this->assertSame('taylorotwell@gmail.com', $user1->email); + $this->assertNull($user1->name); + $this->assertTrue($user1->wasRecentlyCreated); + + $user2 = User::createOrFirst( + ['email' => 'taylorotwell@gmail.com'], + ['name' => 'Taylor Otwell', 'birthday' => new DateTime('1987-05-28')], + ); + + $this->assertEquals($user1->id, $user2->id); + $this->assertSame('taylorotwell@gmail.com', $user2->email); + $this->assertNull($user2->name); + $this->assertNull($user2->birthday); + $this->assertFalse($user2->wasRecentlyCreated); + + $user3 = User::createOrFirst( + ['email' => 'abigailotwell@gmail.com'], + ['name' => 'Abigail Otwell', 'birthday' => new DateTime('1987-05-28')], + ); + + $this->assertNotEquals($user3->id, $user1->id); + $this->assertSame('abigailotwell@gmail.com', $user3->email); + $this->assertSame('Abigail Otwell', $user3->name); + $this->assertEquals(new DateTime('1987-05-28'), $user3->birthday); + $this->assertTrue($user3->wasRecentlyCreated); + + $user4 = User::createOrFirst( + ['name' => 'Dries Vints'], + ['name' => 'Nuno Maduro', 'email' => 'nuno@laravel.com'], + ); + + $this->assertSame('Nuno Maduro', $user4->name); + $this->assertTrue($user4->wasRecentlyCreated); + } } From 74899f9f94404279a9249cafd9eab79b6e3df8c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 12 Mar 2024 15:40:55 +0100 Subject: [PATCH 200/446] Fix CS (#2765) --- src/Query/Builder.php | 5 ----- tests/Models/User.php | 2 +- 2 files changed, 1 insertion(+), 6 deletions(-) diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 98e6640df..27e788db8 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -1158,11 +1158,6 @@ protected function compileWheres(): array return $compiled; } - /** - * @param array $where - * - * @return array - */ protected function compileWhereBasic(array $where): array { $column = $where['column']; diff --git a/tests/Models/User.php b/tests/Models/User.php index f2d2cf7cc..98f76d931 100644 --- a/tests/Models/User.php +++ b/tests/Models/User.php @@ -130,7 +130,7 @@ protected function username(): Attribute { return Attribute::make( get: fn ($value) => $value, - set: fn ($value) => Str::slug($value) + set: fn ($value) => Str::slug($value), ); } From c8fb0a00a32685271eea01d970db67c32d794ac7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 13 Mar 2024 15:53:09 +0100 Subject: [PATCH 201/446] PHPORM-159 Add tests on `whereAny` and `whereAll` (#2763) New tests require Laravel v10.47 --- tests/Query/BuilderTest.php | 139 ++++++++++++++++++++++++++++++++++++ 1 file changed, 139 insertions(+) diff --git a/tests/Query/BuilderTest.php b/tests/Query/BuilderTest.php index 6df0b1a42..4076b3028 100644 --- a/tests/Query/BuilderTest.php +++ b/tests/Query/BuilderTest.php @@ -23,6 +23,7 @@ use stdClass; use function collect; +use function method_exists; use function now; use function var_export; @@ -1157,6 +1158,144 @@ function (Builder $elemMatchQuery): void { }, ), ]; + + // Method added in Laravel v10.47.0 + if (method_exists(Builder::class, 'whereAll')) { + /** @see DatabaseQueryBuilderTest::testWhereAll */ + yield 'whereAll' => [ + [ + 'find' => [ + ['$and' => [['last_name' => 'Doe'], ['email' => 'Doe']]], + [], // options + ], + ], + fn(Builder $builder) => $builder->whereAll(['last_name', 'email'], 'Doe'), + ]; + + yield 'whereAll operator' => [ + [ + 'find' => [ + [ + '$and' => [ + ['last_name' => ['$not' => new Regex('^.*Doe.*$', 'i')]], + ['email' => ['$not' => new Regex('^.*Doe.*$', 'i')]], + ], + ], + [], // options + ], + ], + fn(Builder $builder) => $builder->whereAll(['last_name', 'email'], 'not like', '%Doe%'), + ]; + + /** @see DatabaseQueryBuilderTest::testOrWhereAll */ + yield 'orWhereAll' => [ + [ + 'find' => [ + [ + '$or' => [ + ['first_name' => 'John'], + ['$and' => [['last_name' => 'Doe'], ['email' => 'Doe']]], + ], + ], + [], // options + ], + ], + fn(Builder $builder) => $builder + ->where('first_name', 'John') + ->orWhereAll(['last_name', 'email'], 'Doe'), + ]; + + yield 'orWhereAll operator' => [ + [ + 'find' => [ + [ + '$or' => [ + ['first_name' => new Regex('^.*John.*$', 'i')], + [ + '$and' => [ + ['last_name' => ['$not' => new Regex('^.*Doe.*$', 'i')]], + ['email' => ['$not' => new Regex('^.*Doe.*$', 'i')]], + ], + ], + ], + ], + [], // options + ], + ], + fn(Builder $builder) => $builder + ->where('first_name', 'like', '%John%') + ->orWhereAll(['last_name', 'email'], 'not like', '%Doe%'), + ]; + } + + // Method added in Laravel v10.47.0 + if (method_exists(Builder::class, 'whereAny')) { + /** @see DatabaseQueryBuilderTest::testWhereAny */ + yield 'whereAny' => [ + [ + 'find' => [ + ['$or' => [['last_name' => 'Doe'], ['email' => 'Doe']]], + [], // options + ], + ], + fn(Builder $builder) => $builder->whereAny(['last_name', 'email'], 'Doe'), + ]; + + yield 'whereAny operator' => [ + [ + 'find' => [ + [ + '$or' => [ + ['last_name' => ['$not' => new Regex('^.*Doe.*$', 'i')]], + ['email' => ['$not' => new Regex('^.*Doe.*$', 'i')]], + ], + ], + [], // options + ], + ], + fn(Builder $builder) => $builder->whereAny(['last_name', 'email'], 'not like', '%Doe%'), + ]; + + /** @see DatabaseQueryBuilderTest::testOrWhereAny */ + yield 'orWhereAny' => [ + [ + 'find' => [ + [ + '$or' => [ + ['first_name' => 'John'], + ['$or' => [['last_name' => 'Doe'], ['email' => 'Doe']]], + ], + ], + [], // options + ], + ], + fn(Builder $builder) => $builder + ->where('first_name', 'John') + ->orWhereAny(['last_name', 'email'], 'Doe'), + ]; + + yield 'orWhereAny operator' => [ + [ + 'find' => [ + [ + '$or' => [ + ['first_name' => new Regex('^.*John.*$', 'i')], + [ + '$or' => [ + ['last_name' => ['$not' => new Regex('^.*Doe.*$', 'i')]], + ['email' => ['$not' => new Regex('^.*Doe.*$', 'i')]], + ], + ], + ], + ], + [], // options + ], + ], + fn(Builder $builder) => $builder + ->where('first_name', 'like', '%John%') + ->orWhereAny(['last_name', 'email'], 'not like', '%Doe%'), + ]; + } } /** @dataProvider provideExceptions */ From f5f86c83c301051c79b3b64742bde2fada4f8c75 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 13 Mar 2024 19:52:10 +0100 Subject: [PATCH 202/446] PHPORM-139 Improve `Model::createOrFirst()` tests and error checking (#2759) --- src/Eloquent/Builder.php | 17 +++++++++++++++-- tests/ModelTest.php | 32 ++++++++++++++++++++------------ 2 files changed, 35 insertions(+), 14 deletions(-) diff --git a/src/Eloquent/Builder.php b/src/Eloquent/Builder.php index 6ef960456..7ea18dfa9 100644 --- a/src/Eloquent/Builder.php +++ b/src/Eloquent/Builder.php @@ -6,11 +6,13 @@ use Illuminate\Database\ConnectionInterface; use Illuminate\Database\Eloquent\Builder as EloquentBuilder; +use InvalidArgumentException; use MongoDB\Driver\Cursor; use MongoDB\Laravel\Collection; use MongoDB\Laravel\Helpers\QueriesRelationships; use MongoDB\Laravel\Internal\FindAndModifyCommandSubscriber; use MongoDB\Model\BSONDocument; +use MongoDB\Operation\FindOneAndUpdate; use function array_intersect_key; use function array_key_exists; @@ -195,7 +197,12 @@ public function raw($value = null) */ public function createOrFirst(array $attributes = [], array $values = []): Model { + if ($attributes === []) { + throw new InvalidArgumentException('You must provide attributes to check for duplicates'); + } + // Apply casting and default values to the attributes + // In case of duplicate key between the attributes and the values, the values have priority $instance = $this->newModelInstance($values + $attributes); $values = $instance->getAttributes(); $attributes = array_intersect_key($attributes, $values); @@ -207,8 +214,14 @@ public function createOrFirst(array $attributes = [], array $values = []): Model try { $document = $collection->findOneAndUpdate( $attributes, - ['$setOnInsert' => $values], - ['upsert' => true, 'new' => true, 'typeMap' => ['root' => 'array', 'document' => 'array']], + // Before MongoDB 5.0, $setOnInsert requires a non-empty document. + // This is should not be an issue as $values includes the query filter. + ['$setOnInsert' => (object) $values], + [ + 'upsert' => true, + 'returnDocument' => FindOneAndUpdate::RETURN_DOCUMENT_AFTER, + 'typeMap' => ['root' => 'array', 'document' => 'array'], + ], ); } finally { $collection->getManager()->removeSubscriber($listener); diff --git a/tests/ModelTest.php b/tests/ModelTest.php index f4d459422..5ab6badee 100644 --- a/tests/ModelTest.php +++ b/tests/ModelTest.php @@ -11,6 +11,7 @@ use Illuminate\Database\Eloquent\ModelNotFoundException; use Illuminate\Support\Facades\Date; use Illuminate\Support\Str; +use InvalidArgumentException; use MongoDB\BSON\Binary; use MongoDB\BSON\ObjectID; use MongoDB\BSON\UTCDateTime; @@ -1047,40 +1048,47 @@ public function testNumericFieldName(): void public function testCreateOrFirst() { - $user1 = User::createOrFirst(['email' => 'taylorotwell@gmail.com']); + $user1 = User::createOrFirst(['email' => 'john.doe@example.com']); - $this->assertSame('taylorotwell@gmail.com', $user1->email); + $this->assertSame('john.doe@example.com', $user1->email); $this->assertNull($user1->name); $this->assertTrue($user1->wasRecentlyCreated); $user2 = User::createOrFirst( - ['email' => 'taylorotwell@gmail.com'], - ['name' => 'Taylor Otwell', 'birthday' => new DateTime('1987-05-28')], + ['email' => 'john.doe@example.com'], + ['name' => 'John Doe', 'birthday' => new DateTime('1987-05-28')], ); $this->assertEquals($user1->id, $user2->id); - $this->assertSame('taylorotwell@gmail.com', $user2->email); + $this->assertSame('john.doe@example.com', $user2->email); $this->assertNull($user2->name); $this->assertNull($user2->birthday); $this->assertFalse($user2->wasRecentlyCreated); $user3 = User::createOrFirst( - ['email' => 'abigailotwell@gmail.com'], - ['name' => 'Abigail Otwell', 'birthday' => new DateTime('1987-05-28')], + ['email' => 'jane.doe@example.com'], + ['name' => 'Jane Doe', 'birthday' => new DateTime('1987-05-28')], ); $this->assertNotEquals($user3->id, $user1->id); - $this->assertSame('abigailotwell@gmail.com', $user3->email); - $this->assertSame('Abigail Otwell', $user3->name); + $this->assertSame('jane.doe@example.com', $user3->email); + $this->assertSame('Jane Doe', $user3->name); $this->assertEquals(new DateTime('1987-05-28'), $user3->birthday); $this->assertTrue($user3->wasRecentlyCreated); $user4 = User::createOrFirst( - ['name' => 'Dries Vints'], - ['name' => 'Nuno Maduro', 'email' => 'nuno@laravel.com'], + ['name' => 'Robert Doe'], + ['name' => 'Maria Doe', 'email' => 'maria.doe@example.com'], ); - $this->assertSame('Nuno Maduro', $user4->name); + $this->assertSame('Maria Doe', $user4->name); $this->assertTrue($user4->wasRecentlyCreated); } + + public function testCreateOrFirstRequiresFilter() + { + $this->expectException(InvalidArgumentException::class); + $this->expectExceptionMessage('You must provide attributes to check for duplicates'); + User::createOrFirst([]); + } } From 09580b36c646514ff6d92eb81f66a68dc310ee55 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Wed, 13 Mar 2024 16:21:41 -0400 Subject: [PATCH 203/446] DOCSP-35933: Upgrade version guide (#2755) * DOCSP-35933: Upgrade version guide * DOCSP-35933: Upgrade guide * source constant fix * wording * JS feedback * odm to library * apply phpcbf formatting * empty commit (checks) --------- Co-authored-by: norareidy --- docs/upgrade.txt | 124 ++++++++++++++++++++++++++++++++++++----------- 1 file changed, 97 insertions(+), 27 deletions(-) diff --git a/docs/upgrade.txt b/docs/upgrade.txt index 8148fbdfc..1aeba2be3 100644 --- a/docs/upgrade.txt +++ b/docs/upgrade.txt @@ -1,8 +1,8 @@ .. _laravel-upgrading: -========= -Upgrading -========= +======================= +Upgrade Library Version +======================= .. facet:: :name: genre @@ -11,39 +11,109 @@ Upgrading .. meta:: :keywords: php framework, odm, code example -The PHP library uses `semantic versioning `__. Upgrading -to a new major version may require changes to your application. +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol -Upgrading from version 3 to 4 ------------------------------ +Overview +-------- -- Laravel 10.x is required +On this page, you can learn how to upgrade {+odm-short+} to a new major version. +This page also includes the changes you must make to your application to upgrade +your object-document mapper (ODM) version without losing functionality, if applicable. -- Change dependency name in your composer.json to ``"mongodb/laravel-mongodb": "^4.0"`` - and run ``composer update`` +How to Upgrade +-------------- -- Change namespace from ``Jenssegers\Mongodb\`` to ``MongoDB\Laravel\`` - in your models and config +Before you upgrade, perform the following actions: -- Remove support for non-Laravel projects +- Ensure the new library version is compatible with the MongoDB Server version + your application connects to and the version of Laravel that your + application runs on. See the :ref:`` + page for this information. +- Address any breaking changes between the version of {+odm-short+} that + your application currently uses and your planned upgrade version in the + :ref:`` section of this guide. -- Replace ``$dates`` with ``$casts`` in your models +To upgrade your library version, run the following command in your application's +directory: -- Call ``$model->save()`` after ``$model->unset('field')`` to persist the change +.. code-block:: bash + + composer require mongodb/laravel-mongodb:{+package-version+} -- Replace calls to ``Query\Builder::whereAll($column, $values)`` with - ``Query\Builder::where($column, 'all', $values)`` +To upgrade to a different version of the library, replace the information after +``laravel-mongodb:`` with your preferred version number. -- ``Query\Builder::delete()`` doesn't accept ``limit()`` other than ``1`` or ``null``. +.. _laravel-breaking-changes: -- ``whereDate``, ``whereDay``, ``whereMonth``, ``whereYear``, ``whereTime`` - now use MongoDB operators on date fields +Breaking Changes +---------------- -- Replace ``Illuminate\Database\Eloquent\MassPrunable`` with ``MongoDB\Laravel\Eloquent\MassPrunable`` - in your models +A breaking change is a modification in a convention or behavior in +a specific version of {+odm-short+} that might prevent your application +from working as expected. -- Remove calls to not-supported methods of ``Query\Builder``: ``toSql``, - ``toRawSql``, ``whereColumn``, ``whereFullText``, ``groupByRaw``, - ``orderByRaw``, ``unionAll``, ``union``, ``having``, ``havingRaw``, - ``havingBetween``, ``whereIntegerInRaw``, ``orWhereIntegerInRaw``, - ``whereIntegerNotInRaw``, ``orWhereIntegerNotInRaw``. +The breaking changes in this section are categorized by the major +version releases that introduced them. When upgrading library versions, +address all the breaking changes between your current version and the +planned upgrade version. + +.. _laravel-breaking-changes-v4.x: + +Version 4.x Breaking Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This library version introduces the following breaking changes: + +- Minimum Laravel version is now 10.0. For instructions on upgrading your Laravel version, + see the `Upgrade Guide `__ in the Laravel + documentation. + +- Dependency name is now ``"mongodb/laravel-mongodb"``. Ensure that the dependency + name in your ``composer.json`` file is ``"mongodb/laravel-mongodb": "^4.0"``. Then, run + ``composer update``. + +- Namespace is now ``MongoDB\Laravel\``. Ensure that you change the namespace from ``Jenssegers\Mongodb\`` + to ``MongoDB\Laravel\`` in your models and config files. + +- Removes support for non-Laravel projects. + +- Removes support for the ``$dates`` property. Ensure that you change all instances of ``$dates`` + to ``$casts`` in your model files. + +- ``Model::unset($field)`` does not persist the change. Ensure that you follow all calls to + ``Model::unset($field)`` with ``Model::save()``. + +- Removes the ``Query\Builder::whereAll($column, $values)`` method. Ensure that you replace all calls + to ``Query\Builder::whereAll($column, $values)`` with ``Query\Builder::where($column, 'all', $values)``. + +- ``Query\Builder::delete()`` can delete one or all documents. Ensure that you pass only the values + ``1`` or ``null`` to ``limit()``. + +- ``whereDate()``, ``whereDay()``, ``whereMonth()``, ``whereYear()``, and ``whereTime()`` methods + now use MongoDB operators on date fields. + +- Adds the ``MongoDB\Laravel\Eloquent\MassPrunable`` trait. Ensure that you replace all instances of + ``Illuminate\Database\Eloquent\MassPrunable`` with ``MongoDB\Laravel\Eloquent\MassPrunable`` + in your models. + +- Removes support for the following ``Query\Builder`` methods: + + - ``toSql()`` + - ``toRawSql()`` + - ``whereColumn()`` + - ``whereFullText()`` + - ``groupByRaw()`` + - ``orderByRaw()`` + - ``unionAll()`` + - ``union()`` + - ``having()`` + - ``havingRaw()`` + - ``havingBetween()`` + - ``whereIntegerInRaw()`` + - ``orWhereIntegerInRaw()`` + - ``whereIntegerNotInRaw()`` + - ``orWhereIntegerNotInRaw()`` From 0a425e1ee9d85c2dea3727cb93eca445cda499d7 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 13 Mar 2024 16:57:25 -0400 Subject: [PATCH 204/446] DOCSP-37601 course and release notes (#2764) * DOCSP-37601: release notes link, university course link fix --- docs/index.txt | 1 + docs/quick-start.txt | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/index.txt b/docs/index.txt index cd210fed2..febdb9371 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -14,6 +14,7 @@ Laravel MongoDB :maxdepth: 1 /quick-start + Release Notes /retrieve /eloquent-models /query-builder diff --git a/docs/quick-start.txt b/docs/quick-start.txt index b5f9166ae..d672f3e31 100644 --- a/docs/quick-start.txt +++ b/docs/quick-start.txt @@ -33,7 +33,7 @@ read and write operations on the data. You can learn how to set up a local Laravel development environment and perform CRUD operations by viewing the - :mdbu-course:`Getting Started with Laravel and MongoDB ` + :mdbu-course:`Getting Started with Laravel and MongoDB ` MongoDB University Learning Byte. If you prefer to connect to MongoDB by using the PHP Library driver without From e915378f5c2fc8291ce5746d2357e75f83618439 Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Thu, 14 Mar 2024 10:26:13 +0100 Subject: [PATCH 205/446] Use bot access token for merge-up pull requests (#2772) --- .github/workflows/merge-up.yml | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/.github/workflows/merge-up.yml b/.github/workflows/merge-up.yml index a44a8501c..215c2d9ac 100644 --- a/.github/workflows/merge-up.yml +++ b/.github/workflows/merge-up.yml @@ -5,12 +5,8 @@ on: branches: - "[0-9]+.[0-9]+" -permissions: - contents: write - pull-requests: write - env: - GH_TOKEN: ${{ github.token }} + GH_TOKEN: ${{ secrets.MERGE_UP_TOKEN }} jobs: merge-up: @@ -24,6 +20,7 @@ jobs: with: # fetch-depth 0 is required to fetch all branches, not just the branch being built fetch-depth: 0 + token: ${{ secrets.MERGE_UP_TOKEN }} - name: Create pull request id: create-pull-request From fcdad94309824478873d3703bf2a65114da7bdb8 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Thu, 14 Mar 2024 16:14:49 -0400 Subject: [PATCH 206/446] DOCSP-37710: v4.2 updates (#2774) --- docs/includes/framework-compatibility-laravel.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/includes/framework-compatibility-laravel.rst b/docs/includes/framework-compatibility-laravel.rst index 9b39db4ea..1efdce964 100644 --- a/docs/includes/framework-compatibility-laravel.rst +++ b/docs/includes/framework-compatibility-laravel.rst @@ -3,14 +3,22 @@ :stub-columns: 1 * - {+odm-short+} Version + - Laravel 11.x - Laravel 10.x - Laravel 9.x + * - 4.2 + - ✓ + - ✓ + - + * - 4.1 + - - ✓ - * - 4.0 + - - ✓ - From b55393ca2cbd9eb68d934089e610390eb5147549 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Fri, 15 Mar 2024 13:40:27 +0100 Subject: [PATCH 207/446] Set distinct version for error (#2779) --- src/Connection.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Connection.php b/src/Connection.php index a859bfa63..3f529cdea 100644 --- a/src/Connection.php +++ b/src/Connection.php @@ -328,7 +328,7 @@ private static function lookupVersion(): string try { return self::$version = InstalledVersions::getPrettyVersion('mongodb/laravel-mongodb'); } catch (Throwable) { - // Ignore exceptions and return unknown version + return self::$version = 'error'; } } From e182c902ef4d5380663ef758abe17c3793bbaca3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 19 Mar 2024 09:54:53 +0100 Subject: [PATCH 208/446] Update changelog for 4.2.0 (#2784) --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index a8c2cefc4..6a1fe6c95 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,9 @@ All notable changes to this project will be documented in this file. ## [unreleased] + +## [4.2.0] - 2024-12-14 + * Add support for Laravel 11 by @GromNaN in [#2735](https://github.com/mongodb/laravel-mongodb/pull/2735) * Implement Model::createOrFirst() using findOneAndUpdate operation by @GromNaN in [#2742](https://github.com/mongodb/laravel-mongodb/pull/2742) From d4a981880e0ded6f3d9ceb608372fb379813364c Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Mon, 25 Mar 2024 16:56:02 -0400 Subject: [PATCH 209/446] DOCSP-37057 eloquent schema builder (#2776) * DOCSP-37057: Eloquent schema builder --- docs/eloquent-models.txt | 518 +----------------- docs/eloquent-models/schema-builder.txt | 393 +++++++++++++ .../schema-builder/astronauts_migration.php | 30 + .../schema-builder/flights_migration.php | 32 ++ .../schema-builder/passengers_migration.php | 32 ++ .../schema-builder/planets_migration.php | 33 ++ .../schema-builder/spaceports_migration.php | 33 ++ .../schema-builder/stars_migration.php | 27 + 8 files changed, 592 insertions(+), 506 deletions(-) create mode 100644 docs/eloquent-models/schema-builder.txt create mode 100644 docs/includes/schema-builder/astronauts_migration.php create mode 100644 docs/includes/schema-builder/flights_migration.php create mode 100644 docs/includes/schema-builder/passengers_migration.php create mode 100644 docs/includes/schema-builder/planets_migration.php create mode 100644 docs/includes/schema-builder/spaceports_migration.php create mode 100644 docs/includes/schema-builder/stars_migration.php diff --git a/docs/eloquent-models.txt b/docs/eloquent-models.txt index 3ce32c124..c0f7cea57 100644 --- a/docs/eloquent-models.txt +++ b/docs/eloquent-models.txt @@ -6,517 +6,23 @@ Eloquent Models .. facet:: :name: genre - :values: tutorial + :values: reference .. meta:: - :keywords: php framework, odm, code example + :keywords: php framework, odm -This package includes a MongoDB enabled Eloquent class that you can use to -define models for corresponding collections. +Eloquent models are part of the Laravel Eloquent object-relational +mapping (ORM) framework that enable you to work with a database by using +model classes. {+odm-short+} extends this framework to use similar +syntax to work with MongoDB as a database. -Extending the base model -~~~~~~~~~~~~~~~~~~~~~~~~ +This section contains guidance on how to use Eloquent models in +{+odm-short+} to work with MongoDB in the following ways: -To get started, create a new model class in your ``app\Models\`` directory. +- :ref:`laravel-schema-builder` shows how to manage indexes on your MongoDB + collections by using Laravel migrations -.. code-block:: php +.. toctree:: - namespace App\Models; + Schema Builder - use MongoDB\Laravel\Eloquent\Model; - - class Book extends Model - { - // - } - -Just like a regular model, the MongoDB model class will know which collection -to use based on the model name. For ``Book``, the collection ``books`` will -be used. - -To change the collection, pass the ``$collection`` property: - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class Book extends Model - { - protected $collection = 'my_books_collection'; - } - -.. note:: - - MongoDB documents are automatically stored with a unique ID that is stored - in the ``_id`` property. If you wish to use your own ID, substitute the - ``$primaryKey`` property and set it to your own primary key attribute name. - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class Book extends Model - { - protected $primaryKey = 'id'; - } - - // MongoDB will also create _id, but the 'id' property will be used for primary key actions like find(). - Book::create(['id' => 1, 'title' => 'The Fault in Our Stars']); - -Likewise, you may define a ``connection`` property to override the name of the -database connection to reference the model. - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class Book extends Model - { - protected $connection = 'mongodb'; - } - -Soft Deletes -~~~~~~~~~~~~ - -When soft deleting a model, it is not actually removed from your database. -Instead, a ``deleted_at`` timestamp is set on the record. - -To enable soft delete for a model, apply the ``MongoDB\Laravel\Eloquent\SoftDeletes`` -Trait to the model: - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\SoftDeletes; - - class User extends Model - { - use SoftDeletes; - } - -For more information check `Laravel Docs about Soft Deleting `__. - -Prunable -~~~~~~~~ - -``Prunable`` and ``MassPrunable`` traits are Laravel features to automatically -remove models from your database. You can use ``Illuminate\Database\Eloquent\Prunable`` -trait to remove models one by one. If you want to remove models in bulk, you -must use the ``MongoDB\Laravel\Eloquent\MassPrunable`` trait instead: it -will be more performant but can break links with other documents as it does -not load the models. - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - use MongoDB\Laravel\Eloquent\MassPrunable; - - class Book extends Model - { - use MassPrunable; - } - -For more information check `Laravel Docs about Pruning Models `__. - -Dates -~~~~~ - -Eloquent allows you to work with Carbon or DateTime objects instead of MongoDate objects. Internally, these dates will be converted to MongoDate objects when saved to the database. - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class User extends Model - { - protected $casts = ['birthday' => 'datetime']; - } - -This allows you to execute queries like this: - -.. code-block:: php - - $users = User::where( - 'birthday', '>', - new DateTime('-18 years') - )->get(); - -Extending the Authenticatable base model -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This package includes a MongoDB Authenticatable Eloquent class ``MongoDB\Laravel\Auth\User`` -that you can use to replace the default Authenticatable class ``Illuminate\Foundation\Auth\User`` -for your ``User`` model. - -.. code-block:: php - - use MongoDB\Laravel\Auth\User as Authenticatable; - - class User extends Authenticatable - { - - } - -Guarding attributes -~~~~~~~~~~~~~~~~~~~ - -When choosing between guarding attributes or marking some as fillable, Taylor -Otwell prefers the fillable route. This is in light of -`recent security issues described here `__. - -Keep in mind guarding still works, but you may experience unexpected behavior. - -Schema ------- - -The database driver also has (limited) schema builder support. You can -conveniently manipulate collections and set indexes. - -Basic Usage -~~~~~~~~~~~ - -.. code-block:: php - - Schema::create('users', function ($collection) { - $collection->index('name'); - $collection->unique('email'); - }); - -You can also pass all the parameters specified :manual:`in the MongoDB docs ` -to the ``$options`` parameter: - -.. code-block:: php - - Schema::create('users', function ($collection) { - $collection->index( - 'username', - null, - null, - [ - 'sparse' => true, - 'unique' => true, - 'background' => true, - ] - ); - }); - -Inherited operations: - - -* create and drop -* collection -* hasCollection -* index and dropIndex (compound indexes supported as well) -* unique - -MongoDB specific operations: - - -* background -* sparse -* expire -* geospatial - -All other (unsupported) operations are implemented as dummy pass-through -methods because MongoDB does not use a predefined schema. - -Read more about the schema builder on `Laravel Docs `__ - -Geospatial indexes -~~~~~~~~~~~~~~~~~~ - -Geospatial indexes can improve query performance of location-based documents. - -They come in two forms: ``2d`` and ``2dsphere``. Use the schema builder to add -these to a collection. - -.. code-block:: php - - Schema::create('bars', function ($collection) { - $collection->geospatial('location', '2d'); - }); - -To add a ``2dsphere`` index: - -.. code-block:: php - - Schema::create('bars', function ($collection) { - $collection->geospatial('location', '2dsphere'); - }); - -Relationships -------------- - -Basic Usage -~~~~~~~~~~~ - -The only available relationships are: - - -* hasOne -* hasMany -* belongsTo -* belongsToMany - -The MongoDB-specific relationships are: - - -* embedsOne -* embedsMany - -Here is a small example: - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class User extends Model - { - public function items() - { - return $this->hasMany(Item::class); - } - } - -The inverse relation of ``hasMany`` is ``belongsTo``: - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class Item extends Model - { - public function user() - { - return $this->belongsTo(User::class); - } - } - -belongsToMany and pivots -~~~~~~~~~~~~~~~~~~~~~~~~ - -The belongsToMany relation will not use a pivot "table" but will push id's to -a **related_ids** attribute instead. This makes the second parameter for the -belongsToMany method useless. - -If you want to define custom keys for your relation, set it to ``null``: - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class User extends Model - { - public function groups() - { - return $this->belongsToMany( - Group::class, null, 'user_ids', 'group_ids' - ); - } - } - -EmbedsMany Relationship -~~~~~~~~~~~~~~~~~~~~~~~ - -If you want to embed models, rather than referencing them, you can use the -``embedsMany`` relation. This relation is similar to the ``hasMany`` relation -but embeds the models inside the parent object. - -**REMEMBER**\ : These relations return Eloquent collections, they don't return -query builder objects! - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class User extends Model - { - public function books() - { - return $this->embedsMany(Book::class); - } - } - -You can access the embedded models through the dynamic property: - -.. code-block:: php - - $user = User::first(); - - foreach ($user->books as $book) { - // - } - -The inverse relation is auto *magically* available. You can omit the reverse -relation definition. - -.. code-block:: php - - $book = User::first()->books()->first(); - - $user = $book->user; - -Inserting and updating embedded models works similar to the ``hasMany`` relation: - -.. code-block:: php - - $book = $user->books()->save( - new Book(['title' => 'A Game of Thrones']) - ); - - // or - $book = - $user->books() - ->create(['title' => 'A Game of Thrones']); - -You can update embedded models using their ``save`` method (available since -release 2.0.0): - -.. code-block:: php - - $book = $user->books()->first(); - - $book->title = 'A Game of Thrones'; - $book->save(); - -You can remove an embedded model by using the ``destroy`` method on the -relation, or the ``delete`` method on the model (available since release 2.0.0): - -.. code-block:: php - - $book->delete(); - - // Similar operation - $user->books()->destroy($book); - -If you want to add or remove an embedded model, without touching the database, -you can use the ``associate`` and ``dissociate`` methods. - -To eventually write the changes to the database, save the parent object: - -.. code-block:: php - - $user->books()->associate($book); - $user->save(); - -Like other relations, embedsMany assumes the local key of the relationship -based on the model name. You can override the default local key by passing a -second argument to the embedsMany method: - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class User extends Model - { - public function books() - { - return $this->embedsMany(Book::class, 'local_key'); - } - } - -Embedded relations will return a Collection of embedded items instead of a -query builder. Check out the available operations here: -`https://laravel.com/docs/master/collections `__ - -EmbedsOne Relationship -~~~~~~~~~~~~~~~~~~~~~~ - -The embedsOne relation is similar to the embedsMany relation, but only embeds a single model. - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class Book extends Model - { - public function author() - { - return $this->embedsOne(Author::class); - } - } - -You can access the embedded models through the dynamic property: - -.. code-block:: php - - $book = Book::first(); - $author = $book->author; - -Inserting and updating embedded models works similar to the ``hasOne`` relation: - -.. code-block:: php - - $author = $book->author()->save( - new Author(['name' => 'John Doe']) - ); - - // Similar - $author = - $book->author() - ->create(['name' => 'John Doe']); - -You can update the embedded model using the ``save`` method (available since -release 2.0.0): - -.. code-block:: php - - $author = $book->author; - - $author->name = 'Jane Doe'; - $author->save(); - -You can replace the embedded model with a new model like this: - -.. code-block:: php - - $newAuthor = new Author(['name' => 'Jane Doe']); - - $book->author()->save($newAuthor); - -Cross-Database Relationships ----------------------------- - -If you're using a hybrid MongoDB and SQL setup, you can define relationships -across them. - -The model will automatically return a MongoDB-related or SQL-related relation -based on the type of the related model. - -If you want this functionality to work both ways, your SQL-models will need -to use the ``MongoDB\Laravel\Eloquent\HybridRelations`` trait. - -**This functionality only works for ``hasOne``, ``hasMany`` and ``belongsTo``.** - -The SQL model must use the ``HybridRelations`` trait: - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\HybridRelations; - - class User extends Model - { - use HybridRelations; - - protected $connection = 'mysql'; - - public function messages() - { - return $this->hasMany(Message::class); - } - } - -Within your MongoDB model, you must define the following relationship: - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class Message extends Model - { - protected $connection = 'mongodb'; - - public function user() - { - return $this->belongsTo(User::class); - } - } diff --git a/docs/eloquent-models/schema-builder.txt b/docs/eloquent-models/schema-builder.txt new file mode 100644 index 000000000..9fd845b55 --- /dev/null +++ b/docs/eloquent-models/schema-builder.txt @@ -0,0 +1,393 @@ +.. _laravel-schema-builder: + +============== +Schema Builder +============== + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :keywords: php framework, odm, code example, schema facade, eloquent, blueprint, artisan, migrate + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +Laravel provides a **facade** to access the schema builder class ``Schema``, +which lets you create and modify tables. Facades are static interfaces to +classes that make the syntax more concise and improve testability. + +{+odm-short+} supports a subset of the index and collection management methods +in the Laravel ``Schema`` facade. + +To learn more about facades, see `Facades `__ +in the Laravel documentation. + +The following sections describe the Laravel schema builder features available +in {+odm-short+} and show examples of how to use them: + +- :ref:`` +- :ref:`` +- :ref:`` + +.. note:: + + {+odm-short+} supports managing indexes and collections, but + excludes support for MongoDB JSON schemas for data validation. To learn + more about JSON schema validation, see :manual:`Schema Validation ` + in the {+server-docs-name+}. + +.. _laravel-eloquent-migrations: + +Perform Laravel Migrations +-------------------------- + +Laravel migrations let you programmatically create, modify, and delete +your database schema by running methods included in the ``Schema`` facade. +The following sections explain how to author a migration class when you use +a MongoDB database and how to run them. + +Create a Migration Class +~~~~~~~~~~~~~~~~~~~~~~~~ + +You can create migration classes manually or generate them by using the +``php artisan make:migration`` command. If you generate them, you must make the +following changes to perform the schema changes on your MongoDB database: + +- Replace the ``Illuminate\Database\Schema\Blueprint`` import with + ``MongoDB\Laravel\Schema\Blueprint`` if it is referenced in your migration +- Use only commands and syntax supported by {+odm-short+} + +.. tip:: + + If your default database connection is set to anything other than your + MongoDB database, update the following setting to make sure the migration + specifies the correct database: + + - Specify ``mongodb`` in the ``$connection`` field of your migration class + - Set ``DB_CONNECTION=mongodb`` in your ``.env`` configuration file + +The following example migration class contains the following methods: + +- ``up()``, which creates a collection and an index when you run the migration +- ``down()``, which drops the collection and all the indexes on it when you roll back the migration + +.. literalinclude:: /includes/schema-builder/astronauts_migration.php + :dedent: + :language: php + :emphasize-lines: 6, 11 + +Run or Roll Back a Migration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To run the database migration from a class file, run the following command +after replacing the placeholder: + +.. code-block:: bash + + php artisan migrate --path= + +This command runs the ``up()`` function in the class file to create the +collection and index in the database specified in the ``config/database.php`` +file. + +To roll back the migration, run the following command after replacing the +placeholder: + +.. code-block:: bash + + php artisan migrate:rollback --path= + +This command runs the ``down()`` function in the class file to drop the +collection and related indexes. + +To learn more about Laravel migrations, see +`Database: Migrations `__ +in the Laravel documentation. + +.. _laravel-eloquent-collection-exists: + +Check Whether a Collection Exists +--------------------------------- + +To check whether a collection exists, call the ``hasCollection()`` method on +the ``Schema`` facade in your migration file. You can use this to +perform migration logic conditionally. + +The following example migration creates a ``stars`` collection if a collection +named ``telescopes`` exists: + +.. literalinclude:: /includes/schema-builder/stars_migration.php + :language: php + :dedent: + :start-after: begin conditional create + :end-before: end conditional create + +.. _laravel-eloquent-indexes: + +Manage Indexes +-------------- + +MongoDB indexes are data structures that improve query efficiency by reducing +the number of documents needed to retrieve query results. Certain indexes, such +as geospatial indexes, extend how you can query the data. + +To improve query performance by using an index, make sure the index covers +the query. To learn more about indexes and query optimization, see the +following {+server-docs-name+} entries: + +- :manual:`Indexes ` +- :manual:`Query Optimization ` + +The following sections show how you can use the schema builder to create and +drop various types of indexes on a collection. + +Create an Index +~~~~~~~~~~~~~~~ + +To create indexes, call the ``create()`` method on the ``Schema`` facade +in your migration file. Pass it the collection name and a callback +method with a ``MongoDB\Laravel\Schema\Blueprint`` parameter. Specify the +index creation details on the ``Blueprint`` instance. + +The following example migration creates indexes on the following collection +fields: + +- Single field index on ``mission_type`` +- Compound index on ``launch_location`` and ``launch_date``, specifying a descending sort order on ``launch_date`` +- Unique index on the ``mission_id`` field, specifying the index name "unique_mission_id_idx" + +Click the :guilabel:`VIEW OUTPUT` button to see the indexes created by running +the migration, including the default index on the ``_id`` field: + +.. io-code-block:: + + .. input:: /includes/schema-builder/flights_migration.php + :language: php + :dedent: + :start-after: begin create index + :end-before: end create index + + .. output:: + :language: json + :visible: false + + [ + { v: 2, key: { _id: 1 }, name: '_id_' }, + { v: 2, key: { mission_type: 1 }, name: 'mission_type_1' }, + { + v: 2, + key: { launch_location: 1, launch_date: -1 }, + name: 'launch_location_1_launch_date_-1' + }, + { + v: 2, + key: { mission_id: 1 }, + name: 'unique_mission_id_idx', + unique: true + } + ] + +Specify Index Options +~~~~~~~~~~~~~~~~~~~~~ + +MongoDB index options determine how the indexes are used and stored. +You can specify index options when calling an index creation method, such +as ``index()``, on a ``Blueprint`` instance. + +The following migration code shows how to add a collation to an index as an +index option. Click the :guilabel:`VIEW OUTPUT` button to see the indexes +created by running the migration, including the default index on the ``_id`` +field: + +.. io-code-block:: + + .. input:: /includes/schema-builder/passengers_migration.php + :language: php + :dedent: + :start-after: begin index options + :end-before: end index options + + .. output:: + :language: json + :visible: false + + [ + { v: 2, key: { _id: 1 }, name: '_id_' }, + { + v: 2, + key: { last_name: 1 }, + name: 'passengers_collation_idx', + collation: { + locale: 'de@collation=phonebook', + caseLevel: false, + caseFirst: 'off', + strength: 3, + numericOrdering: true, + alternate: 'non-ignorable', + maxVariable: 'punct', + normalization: false, + backwards: false, + version: '57.1' + } + } + ] + +To learn more about index options, see :manual:`Options for All Index Types ` +in the {+server-docs-name+}. + +Create Sparse, TTL, and Unique Indexes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can use {+odm-short+} helper methods to create the following types of +indexes: + +- Sparse indexes, which allow index entries only for documents that contain the + specified field +- Time-to-live (TTL) indexes, which expire after a set amount of time +- Unique indexes, which prevent inserting documents that contain duplicate + values for the indexed field + +To create these index types, call the ``create()`` method on the ``Schema`` facade +in your migration file. Pass ``create()`` the collection name and a callback +method with a ``MongoDB\Laravel\Schema\Blueprint`` parameter. Call the +appropriate helper method on the ``Blueprint`` instance and pass the +index creation details. + +The following migration code shows how to create a sparse and a TTL index +by using the index helpers. Click the :guilabel:`VIEW OUTPUT` button to see +the indexes created by running the migration, including the default index on +the ``_id`` field: + +.. io-code-block:: + + .. input:: /includes/schema-builder/planets_migration.php + :language: php + :dedent: + :start-after: begin index helpers + :end-before: end index helpers + + .. output:: + :language: json + :visible: false + + [ + { v: 2, key: { _id: 1 }, name: '_id_' }, + { v: 2, key: { rings: 1 }, name: 'rings_1', sparse: true }, + { + v: 2, + key: { last_visible_dt: 1 }, + name: 'last_visible_dt_1', + expireAfterSeconds: 86400 + } + ] + +You can specify sparse, TTL, and unique indexes on either a single field or +compound index by specifying them in the index options. + +The following migration code shows how to create all three types of indexes +on a single field. Click the :guilabel:`VIEW OUTPUT` button to see the indexes +created by running the migration, including the default index on the ``_id`` +field: + +.. io-code-block:: + + .. input:: /includes/schema-builder/planets_migration.php + :language: php + :dedent: + :start-after: begin multi index helpers + :end-before: end multi index helpers + + .. output:: + :language: json + :visible: false + + [ + { v: 2, key: { _id: 1 }, name: '_id_' }, + { + v: 2, + key: { last_visible_dt: 1 }, + name: 'last_visible_dt_1', + unique: true, + sparse: true, + expireAfterSeconds: 3600 + } + ] + +To learn more about these indexes, see :manual:`Index Properties ` +in the {+server-docs-name+}. + +Create a Geospatial Index +~~~~~~~~~~~~~~~~~~~~~~~~~ + +In MongoDB, geospatial indexes let you query geospatial coordinate data for +inclusion, intersection, and proximity. + +To create geospatial indexes, call the ``create()`` method on the ``Schema`` facade +in your migration file. Pass ``create()`` the collection name and a callback +method with a ``MongoDB\Laravel\Schema\Blueprint`` parameter. Specify the +geospatial index creation details on the ``Blueprint`` instance. + +The following example migration creates a ``2d`` and ``2dsphere`` geospatial +index on the ``spaceports`` collection. Click the :guilabel:`VIEW OUTPUT` +button to see the indexes created by running the migration, including the +default index on the ``_id`` field: + +.. io-code-block:: + .. input:: /includes/schema-builder/spaceports_migration.php + :language: php + :dedent: + :start-after: begin create geospatial index + :end-before: end create geospatial index + + .. output:: + :language: json + :visible: false + + [ + { v: 2, key: { _id: 1 }, name: '_id_' }, + { + v: 2, + key: { launchpad_location: '2dsphere' }, + name: 'launchpad_location_2dsphere', + '2dsphereIndexVersion': 3 + }, + { v: 2, key: { runway_location: '2d' }, name: 'runway_location_2d' } + ] + + +To learn more about geospatial indexes, see +:manual:`Geospatial Indexes ` in +the {+server-docs-name+}. + +Drop an Index +~~~~~~~~~~~~~ + +To drop indexes from a collection, call the ``table()`` method on the +``Schema`` facade in your migration file. Pass it the table name and a +callback method with a ``MongoDB\Laravel\Schema\Blueprint`` parameter. +Call the ``dropIndex()`` method with the index name on the ``Blueprint`` +instance. + +.. note:: + + If you drop a collection, MongoDB automatically drops all the indexes + associated with it. + +The following example migration drops an index called ``unique_mission_id_idx`` +from the ``flights`` collection: + +.. literalinclude:: /includes/schema-builder/flights_migration.php + :language: php + :dedent: + :start-after: begin drop index + :end-before: end drop index + + diff --git a/docs/includes/schema-builder/astronauts_migration.php b/docs/includes/schema-builder/astronauts_migration.php new file mode 100644 index 000000000..1fb7b76e4 --- /dev/null +++ b/docs/includes/schema-builder/astronauts_migration.php @@ -0,0 +1,30 @@ +index('name'); + }); + } + + /** + * Reverse the migrations. + */ + public function down(): void + { + Schema::drop('astronauts'); + } +}; diff --git a/docs/includes/schema-builder/flights_migration.php b/docs/includes/schema-builder/flights_migration.php new file mode 100644 index 000000000..861c339ef --- /dev/null +++ b/docs/includes/schema-builder/flights_migration.php @@ -0,0 +1,32 @@ +index('mission_type'); + $collection->index(['launch_location' => 1, 'launch_date' => -1]); + $collection->unique('mission_id', options: ['name' => 'unique_mission_id_idx']); + }); + // end create index + } + + public function down(): void + { + // begin drop index + Schema::table('flights', function (Blueprint $collection) { + $collection->dropIndex('unique_mission_id_idx'); + }); + // end drop index + } +}; diff --git a/docs/includes/schema-builder/passengers_migration.php b/docs/includes/schema-builder/passengers_migration.php new file mode 100644 index 000000000..f0b498940 --- /dev/null +++ b/docs/includes/schema-builder/passengers_migration.php @@ -0,0 +1,32 @@ +index( + 'last_name', + name: 'passengers_collation_idx', + options: [ + 'collation' => [ 'locale' => 'de@collation=phonebook', 'numericOrdering' => true ], + ], + ); + }); + // end index options + } + + public function down(): void + { + Schema::drop('passengers'); + } +}; diff --git a/docs/includes/schema-builder/planets_migration.php b/docs/includes/schema-builder/planets_migration.php new file mode 100644 index 000000000..90de5bd6e --- /dev/null +++ b/docs/includes/schema-builder/planets_migration.php @@ -0,0 +1,33 @@ +sparse('rings'); + $collection->expire('last_visible_dt', 86400); + }); + // end index helpers + + // begin multi index helpers + Schema::create('planet_systems', function (Blueprint $collection) { + $collection->index('last_visible_dt', options: ['sparse' => true, 'expireAfterSeconds' => 3600, 'unique' => true]); + }); + // end multi index helpers + } + + public function down(): void + { + Schema::drop('planets'); + } +}; diff --git a/docs/includes/schema-builder/spaceports_migration.php b/docs/includes/schema-builder/spaceports_migration.php new file mode 100644 index 000000000..ae96c6066 --- /dev/null +++ b/docs/includes/schema-builder/spaceports_migration.php @@ -0,0 +1,33 @@ +geospatial('launchpad_location', '2dsphere'); + $collection->geospatial('runway_location', '2d'); + }); + // end create geospatial index + } + + /** + * Reverse the migrations. + */ + public function down(): void + { + Schema::drop('spaceports'); + } +}; diff --git a/docs/includes/schema-builder/stars_migration.php b/docs/includes/schema-builder/stars_migration.php new file mode 100644 index 000000000..6249da3cd --- /dev/null +++ b/docs/includes/schema-builder/stars_migration.php @@ -0,0 +1,27 @@ + Date: Mon, 25 Mar 2024 17:01:20 -0400 Subject: [PATCH 210/446] DOCSP-35964 eloquent models standardization (#2726) * DOCSP-35964: Eloquent Models section --- docs/eloquent-models.txt | 6 +- docs/eloquent-models/model-class.txt | 317 ++++++++++++++++++ .../eloquent-models/AuthenticatableUser.php | 9 + docs/includes/eloquent-models/Planet.php | 9 + .../eloquent-models/PlanetCollection.php | 10 + docs/includes/eloquent-models/PlanetDate.php | 12 + .../eloquent-models/PlanetMassAssignment.php | 15 + .../eloquent-models/PlanetMassPrune.php | 18 + .../eloquent-models/PlanetPrimaryKey.php | 10 + docs/includes/eloquent-models/PlanetPrune.php | 22 ++ .../eloquent-models/PlanetSoftDelete.php | 11 + phpcs.xml.dist | 12 + 12 files changed, 449 insertions(+), 2 deletions(-) create mode 100644 docs/eloquent-models/model-class.txt create mode 100644 docs/includes/eloquent-models/AuthenticatableUser.php create mode 100644 docs/includes/eloquent-models/Planet.php create mode 100644 docs/includes/eloquent-models/PlanetCollection.php create mode 100644 docs/includes/eloquent-models/PlanetDate.php create mode 100644 docs/includes/eloquent-models/PlanetMassAssignment.php create mode 100644 docs/includes/eloquent-models/PlanetMassPrune.php create mode 100644 docs/includes/eloquent-models/PlanetPrimaryKey.php create mode 100644 docs/includes/eloquent-models/PlanetPrune.php create mode 100644 docs/includes/eloquent-models/PlanetSoftDelete.php diff --git a/docs/eloquent-models.txt b/docs/eloquent-models.txt index c0f7cea57..2bca40f2d 100644 --- a/docs/eloquent-models.txt +++ b/docs/eloquent-models.txt @@ -19,10 +19,12 @@ syntax to work with MongoDB as a database. This section contains guidance on how to use Eloquent models in {+odm-short+} to work with MongoDB in the following ways: +- :ref:`laravel-eloquent-model-class` shows how to define models and customize + their behavior - :ref:`laravel-schema-builder` shows how to manage indexes on your MongoDB collections by using Laravel migrations - + .. toctree:: + /eloquent-models/model-class/ Schema Builder - diff --git a/docs/eloquent-models/model-class.txt b/docs/eloquent-models/model-class.txt new file mode 100644 index 000000000..85b7b994b --- /dev/null +++ b/docs/eloquent-models/model-class.txt @@ -0,0 +1,317 @@ +.. _laravel-eloquent-model-class: + +==================== +Eloquent Model Class +==================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: php framework, odm, code example, authentication, laravel + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +This guide shows you how to use the {+odm-long+} to define and +customize Laravel Eloquent models. You can use these models to work with +MongoDB data by using the Laravel Eloquent object-relational mapper (ORM). + +The following sections explain how to add Laravel Eloquent ORM behaviors +to {+odm-short+} models: + +- :ref:`laravel-model-define` demonstrates how to create a model class. +- :ref:`laravel-authenticatable-model` shows how to set MongoDB as the + authentication user provider. +- :ref:`laravel-model-customize` explains several model class customizations. +- :ref:`laravel-model-pruning` shows how to periodically remove models that + you no longer need. + +.. _laravel-model-define: + +Define an Eloquent Model Class +------------------------------ + +Eloquent models are classes that represent your data. They include methods +that perform database operations such as inserts, updates, and deletes. + +To declare a {+odm-short+} model, create a class in the ``app/Models`` +directory of your Laravel application that extends +``MongoDB\Laravel\Eloquent\Model`` as shown in the following code example: + +.. literalinclude:: /includes/eloquent-models/Planet.php + :language: php + :emphasize-lines: 3,5,7 + :dedent: + +By default, the model uses the MongoDB database name set in your Laravel +application's ``config/database.php`` setting and the snake case plural +form of your model class name for the collection. + +This model is stored in the ``planets`` MongoDB collection. + +.. tip:: + + Alternatively, use the ``artisan`` console to generate the model class and + change the ``Illuminate\Database\Eloquent\Model`` import to ``MongoDB\Laravel\Eloquent\Model``. + To learn more about the ``artisan`` console, see `Artisan Console `__ + in the Laravel docs. + +To learn how to specify the database name that your Laravel application uses, +:ref:`laravel-quick-start-connect-to-mongodb`. + + +.. _laravel-authenticatable-model: + +Extend the Authenticatable Model +-------------------------------- + +To configure MongoDB as the Laravel user provider, you can extend the +{+odm-short+} ``MongoDB\Laravel\Auth\User`` class. The following code example +shows how to extend this class: + +.. literalinclude:: /includes/eloquent-models/AuthenticatableUser.php + :language: php + :emphasize-lines: 3,5,7 + :dedent: + +To learn more about customizing a Laravel authentication user provider, +see `Adding Custom User Providers `__ +in the Laravel docs. + +.. _laravel-model-customize: + +Customize an Eloquent Model Class +--------------------------------- + +This section shows how to perform the following Eloquent model behavior +customizations: + +- :ref:`laravel-model-customize-collection-name` +- :ref:`laravel-model-customize-primary-key` +- :ref:`laravel-model-soft-delete` +- :ref:`laravel-model-cast-data-types` +- :ref:`laravel-model-mass-assignment` + +.. _laravel-model-customize-collection-name: + +Change the Model Collection Name +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, the model uses the snake case plural form of your model +class name. To change the name of the collection the model uses to retrieve +and save data in MongoDB, override the ``$collection`` property of the model +class. + +.. note:: + + We recommend using the default collection naming behavior to keep + the associations between models and collections straightforward. + +The following example specifies the custom MongoDB collection name, +``celestial_body``, for the ``Planet`` class: + +.. literalinclude:: /includes/eloquent-models/PlanetCollection.php + :language: php + :emphasize-lines: 9 + :dedent: + +Without overriding the ``$collection`` property, this model maps to the +``planets`` collection. With the overridden property, the example class stores +the model in the ``celestial_body`` collection. + +.. _laravel-model-customize-primary-key: + +Change the Primary Key Field +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To customize the model's primary key field that uniquely identifies a MongoDB +document, override the ``$primaryKey`` property of the model class. + +By default, the model uses the PHP MongoDB driver to generate unique ObjectIDs +for each document your Laravel application inserts. + +The following example specifies the ``name`` field as the primary key for +the ``Planet`` class: + +.. literalinclude:: /includes/eloquent-models/PlanetPrimaryKey.php + :language: php + :emphasize-lines: 9 + :dedent: + +To learn more about primary key behavior and customization options, see +`Eloquent Primary Keys `__ +in the Laravel docs. + +To learn more about the ``_id`` field, ObjectIDs, and the MongoDB document +structure, see :manual:`Documents ` in the MongoDB server docs. + +.. _laravel-model-soft-delete: + +Enable Soft Deletes +~~~~~~~~~~~~~~~~~~~ + +Eloquent includes a soft delete feature that changes the behavior of the +``delete()`` method on a model. When soft delete is enabled on a model, the +``delete()`` method marks a document as deleted instead of removing it from the +database. It sets a timestamp on the ``deleted_at`` field to exclude it from +retrieve operations automatically. + +To enable soft deletes on a class, add the ``MongoDB\Laravel\Eloquent\SoftDeletes`` +trait as shown in the following code example: + +.. literalinclude:: /includes/eloquent-models/PlanetSoftDelete.php + :language: php + :emphasize-lines: 6,10 + :dedent: + +To learn about methods you can perform on models with soft deletes enabled, see +`Eloquent Soft Deleting `__ +in the Laravel docs. + +.. _laravel-model-cast-data-types: + +Cast Data Types +--------------- + +Eloquent lets you convert model attribute data types before storing or +retrieving data by using a casting helper. This helper is a convenient +alternative to defining equivalent accessor and mutator methods on your model. + +In the following example, the casting helper converts the ``discovery_dt`` +model attribute, stored in MongoDB as a `MongoDB\\BSON\\UTCDateTime `__ +type, to the Laravel ``datetime`` type. + +.. literalinclude:: /includes/eloquent-models/PlanetDate.php + :language: php + :emphasize-lines: 9-11 + :dedent: + +This conversion lets you use the PHP `DateTime `__ +or the `Carbon class `__ to work with dates +in this field. The following example shows a Laravel query that uses the +casting helper on the model to query for planets with a ``discovery_dt`` of +less than three years ago: + +.. code-block:: php + + Planet::where( 'discovery_dt', '>', new DateTime('-3 years'))->get(); + +To learn more about MongoDB's data types, see :manual:`BSON Types ` +in the MongoDB server docs. + +To learn more about the Laravel casting helper and supported types, see `Attribute Casting `__ +in the Laravel docs. + +.. _laravel-model-mass-assignment: + +Customize Mass Assignment +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Eloquent lets you create several models and their attribute data by passing +an array of data to the ``create()`` model method. This process of inserting +multiple models is called mass assignment. + +Mass assignment can be an efficient way to create multiple models. However, it +can expose an exploitable security vulnerability. The data in the fields +might contain updates that lead to unauthorized permissions or access. + +Eloquent provides the following traits to protect your data from mass +assignment vulnerabilities: + +- ``$fillable`` contains the fields that are writeable in a mass assignment +- ``$guarded`` contains the fields that are ignored in a mass assignment + +.. important:: + + We recommend using ``$fillable`` instead of ``$guarded`` to protect against + vulnerabilities. To learn more about this recommendation, see the + `Security Release: Laravel 6.18.35, 7.24.0 `__ + article on the Laravel site. + +In the following example, the model allows mass assignment of the fields +by using the ``$fillable`` attribute: + +.. literalinclude:: /includes/eloquent-models/PlanetMassAssignment.php + :language: php + :emphasize-lines: 9-14 + :dedent: + +The following code example shows mass assignment of the ``Planet`` model: + +.. code-block:: php + + $planets = [ + [ 'name' => 'Earth', gravity => 9.8, day_length => '24 hours' ], + [ 'name' => 'Mars', gravity => 3.7, day_length => '25 hours' ], + ]; + + Planet::create($planets); + +The models saved to the database contain only the ``name`` and ``gravity`` +fields since ``day_length`` is omitted from the ``$fillable`` attribute. + +To learn how to change the behavior when attempting to fill a field omitted +from the ``$fillable`` array, see `Mass Assignment Exceptions `__ +in the Laravel docs. + +.. _laravel-model-pruning: + +Specify Pruning Behavior +------------------------ + +Eloquent lets you specify criteria to periodically delete model data that you +no longer need. When you schedule or run the ``model:prune`` command, +Laravel calls the ``prunable()`` method on all models that import the +``Prunable`` and ``MassPrunable`` traits to match the models for deletion. + +To use this feature with models that use MongoDB as a database, add the +appropriate import to your model: + +- ``MongoDB\Laravel\Eloquent\Prunable`` optionally performs a cleanup + step before deleting a model that matches the criteria +- ``MongoDB\Laravel\Eloquent\MassPrunable`` deletes models that match the + criteria without fetching the model data + +.. note:: + + When enabling soft deletes on a mass prunable model, you must import the + following {+odm-short+} packages: + + - ``MongoDB\Laravel\Eloquent\SoftDeletes`` + - ``MongoDB\Laravel\Eloquent\MassPrunable`` + + +To learn more about the pruning feature, see `Pruning Models `__ +in the Laravel docs. + +Prunable Example +~~~~~~~~~~~~~~~~ + +The following prunable class includes a ``prunable()`` method that matches +models that the prune action deletes and a ``pruning()`` method that runs +before deleting a matching model: + +.. literalinclude:: /includes/eloquent-models/PlanetPrune.php + :language: php + :emphasize-lines: 6,10,12,18 + :dedent: + +Mass Prunable Example +~~~~~~~~~~~~~~~~~~~~~ + +The following mass prunable class includes a ``prunable()`` method that matches +models that the prune action deletes: + +.. literalinclude:: /includes/eloquent-models/PlanetMassPrune.php + :language: php + :emphasize-lines: 5,10,12 + :dedent: + diff --git a/docs/includes/eloquent-models/AuthenticatableUser.php b/docs/includes/eloquent-models/AuthenticatableUser.php new file mode 100644 index 000000000..694a595df --- /dev/null +++ b/docs/includes/eloquent-models/AuthenticatableUser.php @@ -0,0 +1,9 @@ + 'datetime', + ]; +} diff --git a/docs/includes/eloquent-models/PlanetMassAssignment.php b/docs/includes/eloquent-models/PlanetMassAssignment.php new file mode 100644 index 000000000..b2a91cab1 --- /dev/null +++ b/docs/includes/eloquent-models/PlanetMassAssignment.php @@ -0,0 +1,15 @@ +', 0.5); + } +} diff --git a/docs/includes/eloquent-models/PlanetPrimaryKey.php b/docs/includes/eloquent-models/PlanetPrimaryKey.php new file mode 100644 index 000000000..761593941 --- /dev/null +++ b/docs/includes/eloquent-models/PlanetPrimaryKey.php @@ -0,0 +1,10 @@ + + docs src tests @@ -36,5 +37,16 @@ + + + + docs/**/*.php + + + docs/**/*.php + + + docs/**/*.php + From 2117c2c73d19b0e8c14ee4854b740192d7d45e51 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Mon, 25 Mar 2024 17:07:57 -0400 Subject: [PATCH 211/446] DOCSP-37056 eloquent relationships (#2747) * DOCSP-37056: Eloquent relationships --- docs/eloquent-models.txt | 10 +- docs/eloquent-models/relationships.txt | 536 ++++++++++++++++++ .../relationships/RelationshipController.php | 194 +++++++ .../relationships/cross-db/Passenger.php | 18 + .../relationships/cross-db/SpaceShip.php | 21 + .../relationships/embeds/Cargo.php | 12 + .../relationships/embeds/SpaceShip.php | 18 + .../relationships/many-to-many/Planet.php | 18 + .../many-to-many/SpaceExplorer.php | 18 + .../relationships/one-to-many/Moon.php | 18 + .../relationships/one-to-many/Planet.php | 18 + .../relationships/one-to-one/Orbit.php | 18 + .../relationships/one-to-one/Planet.php | 18 + 13 files changed, 914 insertions(+), 3 deletions(-) create mode 100644 docs/eloquent-models/relationships.txt create mode 100644 docs/includes/eloquent-models/relationships/RelationshipController.php create mode 100644 docs/includes/eloquent-models/relationships/cross-db/Passenger.php create mode 100644 docs/includes/eloquent-models/relationships/cross-db/SpaceShip.php create mode 100644 docs/includes/eloquent-models/relationships/embeds/Cargo.php create mode 100644 docs/includes/eloquent-models/relationships/embeds/SpaceShip.php create mode 100644 docs/includes/eloquent-models/relationships/many-to-many/Planet.php create mode 100644 docs/includes/eloquent-models/relationships/many-to-many/SpaceExplorer.php create mode 100644 docs/includes/eloquent-models/relationships/one-to-many/Moon.php create mode 100644 docs/includes/eloquent-models/relationships/one-to-many/Planet.php create mode 100644 docs/includes/eloquent-models/relationships/one-to-one/Orbit.php create mode 100644 docs/includes/eloquent-models/relationships/one-to-one/Planet.php diff --git a/docs/eloquent-models.txt b/docs/eloquent-models.txt index 2bca40f2d..e7edadcfe 100644 --- a/docs/eloquent-models.txt +++ b/docs/eloquent-models.txt @@ -12,19 +12,23 @@ Eloquent Models :keywords: php framework, odm Eloquent models are part of the Laravel Eloquent object-relational -mapping (ORM) framework that enable you to work with a database by using -model classes. {+odm-short+} extends this framework to use similar -syntax to work with MongoDB as a database. +mapping (ORM) framework, which lets you to work with data in a relational +database by using model classes and Eloquent syntax. {+odm-short+} extends +this framework so that you can use Eloquent syntax to work with data in a +MongoDB database. This section contains guidance on how to use Eloquent models in {+odm-short+} to work with MongoDB in the following ways: - :ref:`laravel-eloquent-model-class` shows how to define models and customize their behavior +- :ref:`laravel-eloquent-model-relationships` shows how to define relationships + between models - :ref:`laravel-schema-builder` shows how to manage indexes on your MongoDB collections by using Laravel migrations .. toctree:: /eloquent-models/model-class/ + Relationships Schema Builder diff --git a/docs/eloquent-models/relationships.txt b/docs/eloquent-models/relationships.txt new file mode 100644 index 000000000..92625f076 --- /dev/null +++ b/docs/eloquent-models/relationships.txt @@ -0,0 +1,536 @@ +.. _laravel-eloquent-model-relationships: + +============================ +Eloquent Model Relationships +============================ + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :keywords: php framework, odm, code example, entity relationship, eloquent + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +When you use a relational database, the Eloquent ORM stores models as rows +in tables that correspond to the model classes. When you use MongoDB, the +{+odm-short+} stores models as documents in collections that correspond to the +model classes. + +To define a relationship, add a function to the model class that calls the +appropriate relationship method. This function allows you to access the related +model as a **dynamic property**. A dynamic property lets you access the +related model by using the same syntax as you use to access a property on the +model. + +The following sections describe the Laravel Eloquent and MongoDB-specific +relationships available in {+odm-short+} and show examples of how to define +and use them: + +- :ref:`One to one relationship `, + created by using the ``hasOne()`` method and its inverse, ``belongsTo()`` +- :ref:`One to many relationship `, + created by using the ``hasMany()`` and its inverse, ``belongsTo()`` +- :ref:`Many to many relationship `, + created by using the ``belongsToMany()`` method +- :ref:`Embedded document pattern `, a + MongoDB-specific relationship that can represent a one to one or one to many + relationship, created by using the ``embedsOne()`` or ``embedsMany()`` method +- :ref:`Cross-database relationships `, + required when you want to create relationships between MongoDB and SQL models + +.. _laravel-eloquent-relationship-one-to-one: + +One to One Relationship +----------------------- + +A one to one relationship between models consists of a model record related to +exactly one other type of model record. + +When you add a one to one relationship, Eloquent lets you access the model by +using a dynamic property and stores the model's document ID on the related +model. + +In {+odm-short+}, you can define a one to one relationship by using the +``hasOne()`` method or ``belongsTo()`` method. + +When you add the inverse of the relationship by using the ``belongsTo()`` +method, Eloquent lets you access the model by using a dynamic property, but +does not add any fields. + +To learn more about one to one relationships, see +`One to One `__ +in the Laravel documentation. + +One to One Example +~~~~~~~~~~~~~~~~~~ + +The following example class shows how to define a ``HasOne`` one to one +relationship between a ``Planet`` and ``Orbit`` model by using the +``hasOne()`` method: + +.. literalinclude:: /includes/eloquent-models/relationships/one-to-one/Planet.php + :language: php + :dedent: + +The following example class shows how to define the inverse ``BelongsTo`` +relationship between ``Orbit`` and ``Planet`` by using the ``belongsTo()`` +method: + +.. literalinclude:: /includes/eloquent-models/relationships/one-to-one/Orbit.php + :language: php + :dedent: + +The following sample code shows how to instantiate a model for each class +and add the relationship between them. Click the :guilabel:`VIEW OUTPUT` +button to see the data created by running the code: + +.. io-code-block:: + + .. input:: /includes/eloquent-models/relationships/RelationshipController.php + :language: php + :dedent: + :start-after: begin one-to-one save + :end-before: end one-to-one save + + .. output:: + :language: json + :visible: false + + // Document in the "planets" collection + { + _id: ObjectId('65de67fb2e59d63e6d07f8b8'), + name: 'Earth', + diameter_km: 12742, + // ... + } + + // Document in the "orbits" collection + { + _id: ObjectId('65de67fb2e59d63e6d07f8b9'), + period: 365.26, + direction: 'counterclockwise', + planet_id: '65de67fb2e59d63e6d07f8b8', + // ... + } + +The following sample code shows how to access the related models by using +the dynamic properties as defined in the example classes: + +.. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php + :language: php + :dedent: + :start-after: begin planet orbit dynamic property example + :end-before: end planet orbit dynamic property example + +.. _laravel-eloquent-relationship-one-to-many: + +One to Many Relationship +------------------------ + +A one to many relationship between models consists of a model that is +the parent and one or more related child model records. + +When you add a one to many relationship method, Eloquent lets you access the +model by using a dynamic property and stores the parent model's document ID +on each child model document. + +In {+odm-short+}, you can define a one to many relationship by adding the +``hasMany()`` method on the parent class and, optionally, the ``belongsTo()`` +method on the child class. + +When you add the inverse of the relationship by using the ``belongsTo()`` +method, Eloquent lets you access the parent model by using a dynamic property +without adding any fields. + +To learn more about one to many relationships, see +`One to Many `__ +in the Laravel documentation. + +One to Many Example +~~~~~~~~~~~~~~~~~~~ + +The following example class shows how to define a ``HasMany`` one to many +relationship between a ``Planet`` parent model and ``Moon`` child model by +using the ``hasMany()`` method: + +.. literalinclude:: /includes/eloquent-models/relationships/one-to-many/Planet.php + :language: php + :dedent: + +The following example class shows how to define the inverse ``BelongsTo`` +relationship between a ``Moon`` child model and the and the ``Planet`` parent +model by using the ``belongsTo()`` method: + +.. literalinclude:: /includes/eloquent-models/relationships/one-to-many/Moon.php + :language: php + :dedent: + +The following sample code shows how to instantiate a model for each class +and add the relationship between them. Click the :guilabel:`VIEW OUTPUT` +button to see the data created by running the code: + +.. io-code-block:: + + .. input:: /includes/eloquent-models/relationships/RelationshipController.php + :language: php + :dedent: + :start-after: begin one-to-many save + :end-before: end one-to-many save + + .. output:: + :language: json + :visible: false + + // Parent document in the "planets" collection + { + _id: ObjectId('65dfb0050e323bbef800f7b2'), + name: 'Jupiter', + diameter_km: 142984, + // ... + } + + // Child documents in the "moons" collection + [ + { + _id: ObjectId('65dfb0050e323bbef800f7b3'), + name: 'Ganymede', + orbital_period: 7.15, + planet_id: '65dfb0050e323bbef800f7b2', + // ... + }, + { + _id: ObjectId('65dfb0050e323bbef800f7b4'), + name: 'Europa', + orbital_period: 3.55, + planet_id: '65dfb0050e323bbef800f7b2', + // ... + } + ] + +The following sample code shows how to access the related models by using +the dynamic properties as defined in the example classes. + +.. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php + :language: php + :dedent: + :start-after: begin planet moons dynamic property example + :end-before: end planet moons dynamic property example + +.. _laravel-eloquent-relationship-many-to-many: + +Many to Many Relationship +------------------------- + +A many to many relationship consists of a relationship between two different +model types in which, for each type of model, an instance of the model can +be related to multiple instances of the other type. + +In {+odm-short+}, you can define a many to many relationship by adding the +``belongsToMany()`` method to both related classes. + +When you define a many to many relationship in a relational database, Laravel +creates a pivot table to track the relationships. When you use {+odm-short+}, +it omits the pivot table creation and adds the related document IDs to a +document field derived from the related model class name. + +.. tip:: + + Since {+odm-short+} uses a document field instead of a pivot table, omit + the pivot table parameter from the ``belongsToMany()`` constructor or set + it to ``null``. + +To learn more about many to many relationships in Laravel, see +`Many to Many `__ +in the Laravel documentation. + +The following section shows an example of how to create a many to many +relationship between model classes. + +Many to Many Example +~~~~~~~~~~~~~~~~~~~~ + +The following example class shows how to define a ``BelongsToMany`` many to +many relationship between a ``Planet`` and ``SpaceExplorer`` model by using +the ``belongsToMany()`` method: + +.. literalinclude:: /includes/eloquent-models/relationships/many-to-many/Planet.php + :language: php + :dedent: + +The following example class shows how to define the inverse ``BelongsToMany`` +many to many relationship between a ``SpaceExplorer`` and ``Planet`` model by +using the ``belongsToMany()`` method: + +.. literalinclude:: /includes/eloquent-models/relationships/many-to-many/SpaceExplorer.php + :language: php + :dedent: + +The following sample code shows how to instantiate a model for each class +and add the relationship between them. Click the :guilabel:`VIEW OUTPUT` +button to see the data created by running the code: + +.. io-code-block:: + + .. input:: /includes/eloquent-models/relationships/RelationshipController.php + :language: php + :dedent: + :start-after: begin many-to-many save + :end-before: end many-to-many save + + .. output:: + :language: json + :visible: false + + // Documents in the "planets" collection + [ + { + _id: ObjectId('65e1043a5265269a03078ad0'), + name: 'Earth', + // ... + space_explorer_ids: [ + '65e1043b5265269a03078ad3', + '65e1043b5265269a03078ad4', + '65e1043b5265269a03078ad5' + ], + }, + { + _id: ObjectId('65e1043a5265269a03078ad1'), + name: 'Mars', + // ... + space_explorer_ids: [ '65e1043b5265269a03078ad4', '65e1043b5265269a03078ad5' ] + }, + { + _id: ObjectId('65e1043b5265269a03078ad2'), + name: 'Jupiter', + // ... + space_explorer_ids: [ '65e1043b5265269a03078ad3', '65e1043b5265269a03078ad5' ] + } + ] + + // Documents in the "space_explorers" collection + [ + { + _id: ObjectId('65e1043b5265269a03078ad3'), + name: 'Tanya Kirbuk', + // ... + planet_ids: [ '65e1043a5265269a03078ad0', '65e1043b5265269a03078ad2' ] + }, + { + _id: ObjectId('65e1043b5265269a03078ad4'), + name: 'Mark Watney', + // ... + planet_ids: [ '65e1043a5265269a03078ad0', '65e1043a5265269a03078ad1' ] + }, + { + _id: ObjectId('65e1043b5265269a03078ad5'), + name: 'Jean-Luc Picard', + // ... + planet_ids: [ + '65e1043a5265269a03078ad0', + '65e1043a5265269a03078ad1', + '65e1043b5265269a03078ad2' + ] + } + ] + +The following sample code shows how to access the related models by using +the dynamic properties as defined in the example classes. + +.. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php + :language: php + :dedent: + :start-after: begin many-to-many dynamic property example + :end-before: end many-to-many dynamic property example + +.. _laravel-embedded-document-pattern: + +Embedded Document Pattern +------------------------- + +In MongoDB, the embedded document pattern adds the related model's data into +the parent model instead of keeping foreign key references. Use this pattern +to meet one or more of the following requirements: + +- Keeping associated data together in a single collection +- Performing atomic updates on multiple fields of the document and the associated + data +- Reducing the number of reads required to fetch the data + +In {+odm-short+}, you can define embedded documents by adding one of the +following methods: + +- ``embedsOne()`` to embed a single document +- ``embedsMany()`` to embed multiple documents + +.. note:: + + These methods return Eloquent collections, which differ from query builder + objects. + +To learn more about the MongoDB embedded document pattern, see the following +MongoDB server tutorials: + +- :manual:`Model One-to-One Relationships with Embedded Documents ` +- :manual:`Model One-to-Many Relationships with Embedded Documents ` + +The following section shows an example of how to use the embedded document +pattern. + +Embedded Document Example +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following example class shows how to define an ``EmbedsMany`` one to many +relationship between a ``SpaceShip`` and ``Cargo`` model by using the +``embedsMany()`` method: + +.. literalinclude:: /includes/eloquent-models/relationships/embeds/SpaceShip.php + :language: php + :dedent: + +The embedded model class omits the relationship definition as shown in the +following ``Cargo`` model class: + +.. literalinclude:: /includes/eloquent-models/relationships/embeds/Cargo.php + :language: php + :dedent: + +The following sample code shows how to create a ``SpaceShip`` model and +embed multiple ``Cargo`` models and the MongoDB document created by running the +code. Click the :guilabel:`VIEW OUTPUT` button to see the data created by +running the code: + +.. io-code-block:: + + .. input:: /includes/eloquent-models/relationships/RelationshipController.php + :language: php + :dedent: + :start-after: begin embedsMany save + :end-before: end embedsMany save + + .. output:: + :language: json + :visible: false + + // Document in the "space_ships" collection + { + _id: ObjectId('65e207b9aa167d29a3048853'), + name: 'The Millenium Falcon', + // ... + cargo: [ + { + name: 'spice', + weight: 50, + // ... + _id: ObjectId('65e207b9aa167d29a3048854') + }, + { + name: 'hyperdrive', + weight: 25, + // ... + _id: ObjectId('65e207b9aa167d29a3048855') + } + ] + } + +.. _laravel-relationship-cross-database: + +Cross-Database Relationships +---------------------------- + +A cross-database relationship in {+odm-short+} is a relationship between models +stored in a relational database and models stored in a MongoDB database. + +When you add a cross-database relationship, Eloquent lets you access the +related models by using a dynamic property. + +{+odm-short+} supports the following cross-database relationship methods: + +- ``hasOne()`` +- ``hasMany()`` +- ``belongsTo()`` + +To define a cross-database relationship, you must import the +``MongoDB\Laravel\Eloquent\HybridRelations`` package in the class stored in +the relational database. + +The following section shows an example of how to define a cross-database +relationship. + +Cross-Database Relationship Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following example class shows how to define a ``HasMany`` relationship +between a ``SpaceShip`` model stored in a relational database and a +``Passenger`` model stored in a MongoDB database: + +.. literalinclude:: /includes/eloquent-models/relationships/cross-db/SpaceShip.php + :language: php + :dedent: + +The following example class shows how to define the inverse ``BelongsTo`` +relationship between a ``Passenger`` model and the and the ``Spaceship`` +model by using the ``belongsTo()`` method: + +.. literalinclude:: /includes/eloquent-models/relationships/cross-db/Passenger.php + :language: php + :dedent: + +.. tip:: + + Make sure that the primary key defined in your relational database table + schema matches the one that your model uses. To learn more about Laravel + primary keys and schema definitions, see the following pages in the Laravel + documentation: + + - `Primary Keys `__ + - `Database: Migrations `__ + +The following sample code shows how to create a ``SpaceShip`` model in +a MySQL database and related ``Passenger`` models in a MongoDB database as well +as the data created by running the code. Click the :guilabel:`VIEW OUTPUT` button +to see the data created by running the code: + +.. io-code-block:: + + .. input:: /includes/eloquent-models/relationships/RelationshipController.php + :language: php + :dedent: + :start-after: begin cross-database save + :end-before: end cross-database save + + .. output:: + :language: none + :visible: false + + -- Row in the "space_ships" table + +------+----------+ + | id | name | + +------+----------+ + | 1234 | Nostromo | + +------+----------+ + + // Document in the "passengers" collection + [ + { + _id: ObjectId('65e625e74903fd63af0a5524'), + name: 'Ellen Ripley', + space_ship_id: 1234, + // ... + }, + { + _id: ObjectId('65e625e74903fd63af0a5525'), + name: 'Dwayne Hicks', + space_ship_id: 1234, + // ... + } + ] + diff --git a/docs/includes/eloquent-models/relationships/RelationshipController.php b/docs/includes/eloquent-models/relationships/RelationshipController.php new file mode 100644 index 000000000..fc10184d3 --- /dev/null +++ b/docs/includes/eloquent-models/relationships/RelationshipController.php @@ -0,0 +1,194 @@ +name = 'Earth'; + $planet->diameter_km = 12742; + $planet->save(); + + $orbit = new Orbit(); + $orbit->period = 365.26; + $orbit->direction = 'counterclockwise'; + + $planet->orbit()->save($orbit); + // end one-to-one save + } + + private function oneToMany() + { + // begin one-to-many save + $planet = new Planet(); + $planet->name = 'Jupiter'; + $planet->diameter_km = 142984; + $planet->save(); + + $moon1 = new Moon(); + $moon1->name = 'Ganymede'; + $moon1->orbital_period = 7.15; + + $moon2 = new Moon(); + $moon2->name = 'Europa'; + $moon2->orbital_period = 3.55; + + $planet->moons()->save($moon1); + $planet->moons()->save($moon2); + // end one-to-many save + } + + private function planetOrbitDynamic() + { + // begin planet orbit dynamic property example + $planet = Planet::first(); + $relatedOrbit = $planet->orbit; + + $orbit = Orbit::first(); + $relatedPlanet = $orbit->planet; + // end planet orbit dynamic property example + } + + private function planetMoonsDynamic() + { + // begin planet moons dynamic property example + $planet = Planet::first(); + $relatedMoons = $planet->moons; + + $moon = Moon::first(); + $relatedPlanet = $moon->planet; + // end planet moons dynamic property example + } + + private function manyToMany() + { + // begin many-to-many save + $planetEarth = new Planet(); + $planetEarth->name = 'Earth'; + $planetEarth->save(); + + $planetMars = new Planet(); + $planetMars->name = 'Mars'; + $planetMars->save(); + + $planetJupiter = new Planet(); + $planetJupiter->name = 'Jupiter'; + $planetJupiter->save(); + + $explorerTanya = new SpaceExplorer(); + $explorerTanya->name = 'Tanya Kirbuk'; + $explorerTanya->save(); + + $explorerMark = new SpaceExplorer(); + $explorerMark->name = 'Mark Watney'; + $explorerMark->save(); + + $explorerJeanluc = new SpaceExplorer(); + $explorerJeanluc->name = 'Jean-Luc Picard'; + $explorerJeanluc->save(); + + $explorerTanya->planetsVisited()->attach($planetEarth); + $explorerTanya->planetsVisited()->attach($planetJupiter); + $explorerMark->planetsVisited()->attach($planetEarth); + $explorerMark->planetsVisited()->attach($planetMars); + $explorerJeanluc->planetsVisited()->attach($planetEarth); + $explorerJeanluc->planetsVisited()->attach($planetMars); + $explorerJeanluc->planetsVisited()->attach($planetJupiter); + // end many-to-many save + } + + private function manyToManyDynamic() + { + // begin many-to-many dynamic property example + $planet = Planet::first(); + $explorers = $planet->visitors; + + $spaceExplorer = SpaceExplorer::first(); + $explored = $spaceExplorer->planetsVisited; + // end many-to-many dynamic property example + } + + private function embedsMany() + { + // begin embedsMany save + $spaceship = new SpaceShip(); + $spaceship->name = 'The Millenium Falcon'; + $spaceship->save(); + + $cargoSpice = new Cargo(); + $cargoSpice->name = 'spice'; + $cargoSpice->weight = 50; + + $cargoHyperdrive = new Cargo(); + $cargoHyperdrive->name = 'hyperdrive'; + $cargoHyperdrive->weight = 25; + + $spaceship->cargo()->attach($cargoSpice); + $spaceship->cargo()->attach($cargoHyperdrive); + // end embedsMany save + } + + private function crossDatabase() + { + // begin cross-database save + $spaceship = new SpaceShip(); + $spaceship->id = 1234; + $spaceship->name = 'Nostromo'; + $spaceship->save(); + + $passengerEllen = new Passenger(); + $passengerEllen->name = 'Ellen Ripley'; + + $passengerDwayne = new Passenger(); + $passengerDwayne->name = 'Dwayne Hicks'; + + $spaceship->passengers()->save($passengerEllen); + $spaceship->passengers()->save($passengerDwayne); + // end cross-database save + } + + /** + * Store a newly created resource in storage. + */ + public function store(Request $request) + { + } + + /** + * Display the specified resource. + */ + public function show() + { + return 'ok'; + } + + /** + * Show the form for editing the specified resource. + */ + public function edit(Planet $planet) + { + } + + /** + * Update the specified resource in storage. + */ + public function update(Request $request, Planet $planet) + { + } + + /** + * Remove the specified resource from storage. + */ + public function destroy(Planet $planet) + { + } +} diff --git a/docs/includes/eloquent-models/relationships/cross-db/Passenger.php b/docs/includes/eloquent-models/relationships/cross-db/Passenger.php new file mode 100644 index 000000000..4ceb7c45b --- /dev/null +++ b/docs/includes/eloquent-models/relationships/cross-db/Passenger.php @@ -0,0 +1,18 @@ +belongsTo(SpaceShip::class); + } +} diff --git a/docs/includes/eloquent-models/relationships/cross-db/SpaceShip.php b/docs/includes/eloquent-models/relationships/cross-db/SpaceShip.php new file mode 100644 index 000000000..1f3c5d120 --- /dev/null +++ b/docs/includes/eloquent-models/relationships/cross-db/SpaceShip.php @@ -0,0 +1,21 @@ +hasMany(Passenger::class); + } +} diff --git a/docs/includes/eloquent-models/relationships/embeds/Cargo.php b/docs/includes/eloquent-models/relationships/embeds/Cargo.php new file mode 100644 index 000000000..3ce144815 --- /dev/null +++ b/docs/includes/eloquent-models/relationships/embeds/Cargo.php @@ -0,0 +1,12 @@ +embedsMany(Cargo::class); + } +} diff --git a/docs/includes/eloquent-models/relationships/many-to-many/Planet.php b/docs/includes/eloquent-models/relationships/many-to-many/Planet.php new file mode 100644 index 000000000..4059d634d --- /dev/null +++ b/docs/includes/eloquent-models/relationships/many-to-many/Planet.php @@ -0,0 +1,18 @@ +belongsToMany(SpaceExplorer::class); + } +} diff --git a/docs/includes/eloquent-models/relationships/many-to-many/SpaceExplorer.php b/docs/includes/eloquent-models/relationships/many-to-many/SpaceExplorer.php new file mode 100644 index 000000000..aa9b2829d --- /dev/null +++ b/docs/includes/eloquent-models/relationships/many-to-many/SpaceExplorer.php @@ -0,0 +1,18 @@ +belongsToMany(Planet::class); + } +} diff --git a/docs/includes/eloquent-models/relationships/one-to-many/Moon.php b/docs/includes/eloquent-models/relationships/one-to-many/Moon.php new file mode 100644 index 000000000..ca5b7ae7c --- /dev/null +++ b/docs/includes/eloquent-models/relationships/one-to-many/Moon.php @@ -0,0 +1,18 @@ +belongsTo(Planet::class); + } +} diff --git a/docs/includes/eloquent-models/relationships/one-to-many/Planet.php b/docs/includes/eloquent-models/relationships/one-to-many/Planet.php new file mode 100644 index 000000000..679877ae5 --- /dev/null +++ b/docs/includes/eloquent-models/relationships/one-to-many/Planet.php @@ -0,0 +1,18 @@ +hasMany(Moon::class); + } +} diff --git a/docs/includes/eloquent-models/relationships/one-to-one/Orbit.php b/docs/includes/eloquent-models/relationships/one-to-one/Orbit.php new file mode 100644 index 000000000..4cb526309 --- /dev/null +++ b/docs/includes/eloquent-models/relationships/one-to-one/Orbit.php @@ -0,0 +1,18 @@ +belongsTo(Planet::class); + } +} diff --git a/docs/includes/eloquent-models/relationships/one-to-one/Planet.php b/docs/includes/eloquent-models/relationships/one-to-one/Planet.php new file mode 100644 index 000000000..e3137ab3a --- /dev/null +++ b/docs/includes/eloquent-models/relationships/one-to-one/Planet.php @@ -0,0 +1,18 @@ +hasOne(Orbit::class); + } +} From 260620e61a9226c9f98cc1e751b569d00413be85 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 26 Mar 2024 16:06:43 +0100 Subject: [PATCH 212/446] Add tests to doc examples (#2775) --- docs/eloquent-models/relationships.txt | 16 +- .../relationships/RelationshipController.php | 194 ------------- .../RelationshipsExamplesTest.php | 265 ++++++++++++++++++ .../relationships/cross-db/Passenger.php | 2 +- 4 files changed, 274 insertions(+), 203 deletions(-) delete mode 100644 docs/includes/eloquent-models/relationships/RelationshipController.php create mode 100644 docs/includes/eloquent-models/relationships/RelationshipsExamplesTest.php diff --git a/docs/eloquent-models/relationships.txt b/docs/eloquent-models/relationships.txt index 92625f076..2ae716132 100644 --- a/docs/eloquent-models/relationships.txt +++ b/docs/eloquent-models/relationships.txt @@ -95,7 +95,7 @@ button to see the data created by running the code: .. io-code-block:: - .. input:: /includes/eloquent-models/relationships/RelationshipController.php + .. input:: /includes/eloquent-models/relationships/RelationshipsExamplesTest.php :language: php :dedent: :start-after: begin one-to-one save @@ -125,7 +125,7 @@ button to see the data created by running the code: The following sample code shows how to access the related models by using the dynamic properties as defined in the example classes: -.. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php +.. literalinclude:: /includes/eloquent-models/relationships/RelationshipsExamplesTest.php :language: php :dedent: :start-after: begin planet orbit dynamic property example @@ -180,7 +180,7 @@ button to see the data created by running the code: .. io-code-block:: - .. input:: /includes/eloquent-models/relationships/RelationshipController.php + .. input:: /includes/eloquent-models/relationships/RelationshipsExamplesTest.php :language: php :dedent: :start-after: begin one-to-many save @@ -219,7 +219,7 @@ button to see the data created by running the code: The following sample code shows how to access the related models by using the dynamic properties as defined in the example classes. -.. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php +.. literalinclude:: /includes/eloquent-models/relationships/RelationshipsExamplesTest.php :language: php :dedent: :start-after: begin planet moons dynamic property example @@ -280,7 +280,7 @@ button to see the data created by running the code: .. io-code-block:: - .. input:: /includes/eloquent-models/relationships/RelationshipController.php + .. input:: /includes/eloquent-models/relationships/RelationshipsExamplesTest.php :language: php :dedent: :start-after: begin many-to-many save @@ -345,7 +345,7 @@ button to see the data created by running the code: The following sample code shows how to access the related models by using the dynamic properties as defined in the example classes. -.. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php +.. literalinclude:: /includes/eloquent-models/relationships/RelationshipsExamplesTest.php :language: php :dedent: :start-after: begin many-to-many dynamic property example @@ -410,7 +410,7 @@ running the code: .. io-code-block:: - .. input:: /includes/eloquent-models/relationships/RelationshipController.php + .. input:: /includes/eloquent-models/relationships/RelationshipsExamplesTest.php :language: php :dedent: :start-after: begin embedsMany save @@ -501,7 +501,7 @@ to see the data created by running the code: .. io-code-block:: - .. input:: /includes/eloquent-models/relationships/RelationshipController.php + .. input:: /includes/eloquent-models/relationships/RelationshipsExamplesTest.php :language: php :dedent: :start-after: begin cross-database save diff --git a/docs/includes/eloquent-models/relationships/RelationshipController.php b/docs/includes/eloquent-models/relationships/RelationshipController.php deleted file mode 100644 index fc10184d3..000000000 --- a/docs/includes/eloquent-models/relationships/RelationshipController.php +++ /dev/null @@ -1,194 +0,0 @@ -name = 'Earth'; - $planet->diameter_km = 12742; - $planet->save(); - - $orbit = new Orbit(); - $orbit->period = 365.26; - $orbit->direction = 'counterclockwise'; - - $planet->orbit()->save($orbit); - // end one-to-one save - } - - private function oneToMany() - { - // begin one-to-many save - $planet = new Planet(); - $planet->name = 'Jupiter'; - $planet->diameter_km = 142984; - $planet->save(); - - $moon1 = new Moon(); - $moon1->name = 'Ganymede'; - $moon1->orbital_period = 7.15; - - $moon2 = new Moon(); - $moon2->name = 'Europa'; - $moon2->orbital_period = 3.55; - - $planet->moons()->save($moon1); - $planet->moons()->save($moon2); - // end one-to-many save - } - - private function planetOrbitDynamic() - { - // begin planet orbit dynamic property example - $planet = Planet::first(); - $relatedOrbit = $planet->orbit; - - $orbit = Orbit::first(); - $relatedPlanet = $orbit->planet; - // end planet orbit dynamic property example - } - - private function planetMoonsDynamic() - { - // begin planet moons dynamic property example - $planet = Planet::first(); - $relatedMoons = $planet->moons; - - $moon = Moon::first(); - $relatedPlanet = $moon->planet; - // end planet moons dynamic property example - } - - private function manyToMany() - { - // begin many-to-many save - $planetEarth = new Planet(); - $planetEarth->name = 'Earth'; - $planetEarth->save(); - - $planetMars = new Planet(); - $planetMars->name = 'Mars'; - $planetMars->save(); - - $planetJupiter = new Planet(); - $planetJupiter->name = 'Jupiter'; - $planetJupiter->save(); - - $explorerTanya = new SpaceExplorer(); - $explorerTanya->name = 'Tanya Kirbuk'; - $explorerTanya->save(); - - $explorerMark = new SpaceExplorer(); - $explorerMark->name = 'Mark Watney'; - $explorerMark->save(); - - $explorerJeanluc = new SpaceExplorer(); - $explorerJeanluc->name = 'Jean-Luc Picard'; - $explorerJeanluc->save(); - - $explorerTanya->planetsVisited()->attach($planetEarth); - $explorerTanya->planetsVisited()->attach($planetJupiter); - $explorerMark->planetsVisited()->attach($planetEarth); - $explorerMark->planetsVisited()->attach($planetMars); - $explorerJeanluc->planetsVisited()->attach($planetEarth); - $explorerJeanluc->planetsVisited()->attach($planetMars); - $explorerJeanluc->planetsVisited()->attach($planetJupiter); - // end many-to-many save - } - - private function manyToManyDynamic() - { - // begin many-to-many dynamic property example - $planet = Planet::first(); - $explorers = $planet->visitors; - - $spaceExplorer = SpaceExplorer::first(); - $explored = $spaceExplorer->planetsVisited; - // end many-to-many dynamic property example - } - - private function embedsMany() - { - // begin embedsMany save - $spaceship = new SpaceShip(); - $spaceship->name = 'The Millenium Falcon'; - $spaceship->save(); - - $cargoSpice = new Cargo(); - $cargoSpice->name = 'spice'; - $cargoSpice->weight = 50; - - $cargoHyperdrive = new Cargo(); - $cargoHyperdrive->name = 'hyperdrive'; - $cargoHyperdrive->weight = 25; - - $spaceship->cargo()->attach($cargoSpice); - $spaceship->cargo()->attach($cargoHyperdrive); - // end embedsMany save - } - - private function crossDatabase() - { - // begin cross-database save - $spaceship = new SpaceShip(); - $spaceship->id = 1234; - $spaceship->name = 'Nostromo'; - $spaceship->save(); - - $passengerEllen = new Passenger(); - $passengerEllen->name = 'Ellen Ripley'; - - $passengerDwayne = new Passenger(); - $passengerDwayne->name = 'Dwayne Hicks'; - - $spaceship->passengers()->save($passengerEllen); - $spaceship->passengers()->save($passengerDwayne); - // end cross-database save - } - - /** - * Store a newly created resource in storage. - */ - public function store(Request $request) - { - } - - /** - * Display the specified resource. - */ - public function show() - { - return 'ok'; - } - - /** - * Show the form for editing the specified resource. - */ - public function edit(Planet $planet) - { - } - - /** - * Update the specified resource in storage. - */ - public function update(Request $request, Planet $planet) - { - } - - /** - * Remove the specified resource from storage. - */ - public function destroy(Planet $planet) - { - } -} diff --git a/docs/includes/eloquent-models/relationships/RelationshipsExamplesTest.php b/docs/includes/eloquent-models/relationships/RelationshipsExamplesTest.php new file mode 100644 index 000000000..51876416a --- /dev/null +++ b/docs/includes/eloquent-models/relationships/RelationshipsExamplesTest.php @@ -0,0 +1,265 @@ +name = 'Earth'; + $planet->diameter_km = 12742; + $planet->save(); + + $orbit = new Orbit(); + $orbit->period = 365.26; + $orbit->direction = 'counterclockwise'; + + $planet->orbit()->save($orbit); + // end one-to-one save + + $planet = Planet::first(); + $this->assertInstanceOf(Planet::class, $planet); + $this->assertInstanceOf(Orbit::class, $planet->orbit); + + // begin planet orbit dynamic property example + $planet = Planet::first(); + $relatedOrbit = $planet->orbit; + + $orbit = Orbit::first(); + $relatedPlanet = $orbit->planet; + // end planet orbit dynamic property example + + $this->assertInstanceOf(Orbit::class, $relatedOrbit); + $this->assertInstanceOf(Planet::class, $relatedPlanet); + } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function testOneToMany(): void + { + require_once __DIR__ . '/one-to-many/Planet.php'; + require_once __DIR__ . '/one-to-many/Moon.php'; + + // Clear the database + Planet::truncate(); + Moon::truncate(); + + // begin one-to-many save + $planet = new Planet(); + $planet->name = 'Jupiter'; + $planet->diameter_km = 142984; + $planet->save(); + + $moon1 = new Moon(); + $moon1->name = 'Ganymede'; + $moon1->orbital_period = 7.15; + + $moon2 = new Moon(); + $moon2->name = 'Europa'; + $moon2->orbital_period = 3.55; + + $planet->moons()->save($moon1); + $planet->moons()->save($moon2); + // end one-to-many save + + $planet = Planet::first(); + $this->assertInstanceOf(Planet::class, $planet); + $this->assertCount(2, $planet->moons); + $this->assertInstanceOf(Moon::class, $planet->moons->first()); + + // begin planet moons dynamic property example + $planet = Planet::first(); + $relatedMoons = $planet->moons; + + $moon = Moon::first(); + $relatedPlanet = $moon->planet; + // end planet moons dynamic property example + + $this->assertInstanceOf(Moon::class, $relatedMoons->first()); + $this->assertInstanceOf(Planet::class, $relatedPlanet); + } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function testManyToMany(): void + { + require_once __DIR__ . '/many-to-many/Planet.php'; + require_once __DIR__ . '/many-to-many/SpaceExplorer.php'; + + // Clear the database + Planet::truncate(); + SpaceExplorer::truncate(); + + // begin many-to-many save + $planetEarth = new Planet(); + $planetEarth->name = 'Earth'; + $planetEarth->save(); + + $planetMars = new Planet(); + $planetMars->name = 'Mars'; + $planetMars->save(); + + $planetJupiter = new Planet(); + $planetJupiter->name = 'Jupiter'; + $planetJupiter->save(); + + $explorerTanya = new SpaceExplorer(); + $explorerTanya->name = 'Tanya Kirbuk'; + $explorerTanya->save(); + + $explorerMark = new SpaceExplorer(); + $explorerMark->name = 'Mark Watney'; + $explorerMark->save(); + + $explorerJeanluc = new SpaceExplorer(); + $explorerJeanluc->name = 'Jean-Luc Picard'; + $explorerJeanluc->save(); + + $explorerTanya->planetsVisited()->attach($planetEarth); + $explorerTanya->planetsVisited()->attach($planetJupiter); + $explorerMark->planetsVisited()->attach($planetEarth); + $explorerMark->planetsVisited()->attach($planetMars); + $explorerJeanluc->planetsVisited()->attach($planetEarth); + $explorerJeanluc->planetsVisited()->attach($planetMars); + $explorerJeanluc->planetsVisited()->attach($planetJupiter); + // end many-to-many save + + $planet = Planet::where('name', 'Earth')->first(); + $this->assertInstanceOf(Planet::class, $planet); + $this->assertCount(3, $planet->visitors); + $this->assertInstanceOf(SpaceExplorer::class, $planet->visitors->first()); + + $explorer = SpaceExplorer::where('name', 'Jean-Luc Picard')->first(); + $this->assertInstanceOf(SpaceExplorer::class, $explorer); + $this->assertCount(3, $explorer->planetsVisited); + $this->assertInstanceOf(Planet::class, $explorer->planetsVisited->first()); + + // begin many-to-many dynamic property example + $planet = Planet::first(); + $explorers = $planet->visitors; + + $spaceExplorer = SpaceExplorer::first(); + $explored = $spaceExplorer->planetsVisited; + // end many-to-many dynamic property example + + $this->assertCount(3, $explorers); + $this->assertInstanceOf(SpaceExplorer::class, $explorers->first()); + $this->assertCount(2, $explored); + $this->assertInstanceOf(Planet::class, $explored->first()); + } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function testEmbedsMany(): void + { + require_once __DIR__ . '/embeds/Cargo.php'; + require_once __DIR__ . '/embeds/SpaceShip.php'; + + // Clear the database + SpaceShip::truncate(); + + // begin embedsMany save + $spaceship = new SpaceShip(); + $spaceship->name = 'The Millenium Falcon'; + $spaceship->save(); + + $cargoSpice = new Cargo(); + $cargoSpice->name = 'spice'; + $cargoSpice->weight = 50; + + $cargoHyperdrive = new Cargo(); + $cargoHyperdrive->name = 'hyperdrive'; + $cargoHyperdrive->weight = 25; + + $spaceship->cargo()->attach($cargoSpice); + $spaceship->cargo()->attach($cargoHyperdrive); + // end embedsMany save + + $spaceship = SpaceShip::first(); + $this->assertInstanceOf(SpaceShip::class, $spaceship); + $this->assertCount(2, $spaceship->cargo); + $this->assertInstanceOf(Cargo::class, $spaceship->cargo->first()); + } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function testCrossDatabase(): void + { + require_once __DIR__ . '/cross-db/Passenger.php'; + require_once __DIR__ . '/cross-db/SpaceShip.php'; + + $schema = Schema::connection('sqlite'); + assert($schema instanceof SQLiteBuilder); + + $schema->dropIfExists('space_ships'); + $schema->create('space_ships', function (Blueprint $table) { + $table->id(); + $table->string('name'); + $table->timestamps(); + }); + + // Clear the database + Passenger::truncate(); + + // begin cross-database save + $spaceship = new SpaceShip(); + $spaceship->id = 1234; + $spaceship->name = 'Nostromo'; + $spaceship->save(); + + $passengerEllen = new Passenger(); + $passengerEllen->name = 'Ellen Ripley'; + + $passengerDwayne = new Passenger(); + $passengerDwayne->name = 'Dwayne Hicks'; + + $spaceship->passengers()->save($passengerEllen); + $spaceship->passengers()->save($passengerDwayne); + // end cross-database save + + $spaceship = SpaceShip::first(); + $this->assertInstanceOf(SpaceShip::class, $spaceship); + $this->assertCount(2, $spaceship->passengers); + $this->assertInstanceOf(Passenger::class, $spaceship->passengers->first()); + + $passenger = Passenger::first(); + $this->assertInstanceOf(Passenger::class, $passenger); + } +} diff --git a/docs/includes/eloquent-models/relationships/cross-db/Passenger.php b/docs/includes/eloquent-models/relationships/cross-db/Passenger.php index 4ceb7c45b..3379c866b 100644 --- a/docs/includes/eloquent-models/relationships/cross-db/Passenger.php +++ b/docs/includes/eloquent-models/relationships/cross-db/Passenger.php @@ -4,8 +4,8 @@ namespace App\Models; +use Illuminate\Database\Eloquent\Relations\BelongsTo; use MongoDB\Laravel\Eloquent\Model; -use MongoDB\Laravel\Relations\BelongsTo; class Passenger extends Model { From fdfb5e5027bf46744c28862d042b3063c7d7a782 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 26 Mar 2024 17:57:57 +0100 Subject: [PATCH 213/446] PHPORM-155 Fluent aggregation builder (#2738) --- CHANGELOG.md | 1 + composer.json | 4 + src/Eloquent/Builder.php | 15 ++- src/Eloquent/Model.php | 1 + src/Query/AggregationBuilder.php | 98 +++++++++++++++++ src/Query/Builder.php | 27 ++++- tests/Query/AggregationBuilderTest.php | 147 +++++++++++++++++++++++++ 7 files changed, 288 insertions(+), 5 deletions(-) create mode 100644 src/Query/AggregationBuilder.php create mode 100644 tests/Query/AggregationBuilderTest.php diff --git a/CHANGELOG.md b/CHANGELOG.md index 6a1fe6c95..edd119625 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,7 @@ All notable changes to this project will be documented in this file. ## [unreleased] +* New aggregation pipeline builder by @GromNaN in [#2738](https://github.com/mongodb/laravel-mongodb/pull/2738) ## [4.2.0] - 2024-12-14 diff --git a/composer.json b/composer.json index d19c1149a..3769bdfe6 100644 --- a/composer.json +++ b/composer.json @@ -31,6 +31,7 @@ "mongodb/mongodb": "^1.15" }, "require-dev": { + "mongodb/builder": "^0.2", "phpunit/phpunit": "^10.3", "orchestra/testbench": "^8.0|^9.0", "mockery/mockery": "^1.4.4", @@ -38,6 +39,9 @@ "spatie/laravel-query-builder": "^5.6", "phpstan/phpstan": "^1.10" }, + "suggest": { + "mongodb/builder": "Provides a fluent aggregation builder for MongoDB pipelines" + }, "minimum-stability": "dev", "replace": { "jenssegers/mongodb": "self.version" diff --git a/src/Eloquent/Builder.php b/src/Eloquent/Builder.php index 7ea18dfa9..aa01bee6c 100644 --- a/src/Eloquent/Builder.php +++ b/src/Eloquent/Builder.php @@ -11,6 +11,7 @@ use MongoDB\Laravel\Collection; use MongoDB\Laravel\Helpers\QueriesRelationships; use MongoDB\Laravel\Internal\FindAndModifyCommandSubscriber; +use MongoDB\Laravel\Query\AggregationBuilder; use MongoDB\Model\BSONDocument; use MongoDB\Operation\FindOneAndUpdate; @@ -56,6 +57,18 @@ class Builder extends EloquentBuilder 'tomql', ]; + /** + * @return ($function is null ? AggregationBuilder : self) + * + * @inheritdoc + */ + public function aggregate($function = null, $columns = ['*']) + { + $result = $this->toBase()->aggregate($function, $columns); + + return $result ?: $this; + } + /** @inheritdoc */ public function update(array $values, array $options = []) { @@ -215,7 +228,7 @@ public function createOrFirst(array $attributes = [], array $values = []): Model $document = $collection->findOneAndUpdate( $attributes, // Before MongoDB 5.0, $setOnInsert requires a non-empty document. - // This is should not be an issue as $values includes the query filter. + // This should not be an issue as $values includes the query filter. ['$setOnInsert' => (object) $values], [ 'upsert' => true, diff --git a/src/Eloquent/Model.php b/src/Eloquent/Model.php index 78999bce8..de5ddc3ea 100644 --- a/src/Eloquent/Model.php +++ b/src/Eloquent/Model.php @@ -49,6 +49,7 @@ use function uniqid; use function var_export; +/** @mixin Builder */ abstract class Model extends BaseModel { use HybridRelations; diff --git a/src/Query/AggregationBuilder.php b/src/Query/AggregationBuilder.php new file mode 100644 index 000000000..ad0c195d4 --- /dev/null +++ b/src/Query/AggregationBuilder.php @@ -0,0 +1,98 @@ +pipeline[] = [$operator => $value]; + + return $this; + } + + /** + * Execute the aggregation pipeline and return the results. + */ + public function get(array $options = []): LaravelCollection|LazyCollection + { + $cursor = $this->execute($options); + + return collect($cursor->toArray()); + } + + /** + * Execute the aggregation pipeline and return the results in a lazy collection. + */ + public function cursor($options = []): LazyCollection + { + $cursor = $this->execute($options); + + return LazyCollection::make(function () use ($cursor) { + foreach ($cursor as $item) { + yield $item; + } + }); + } + + /** + * Execute the aggregation pipeline and return the first result. + */ + public function first(array $options = []): mixed + { + return (clone $this) + ->limit(1) + ->get($options) + ->first(); + } + + /** + * Execute the aggregation pipeline and return MongoDB cursor. + */ + private function execute(array $options): CursorInterface&Iterator + { + $encoder = new BuilderEncoder(); + $pipeline = $encoder->encode($this->getPipeline()); + + $options = array_replace( + ['typeMap' => ['root' => 'array', 'document' => 'array']], + $this->options, + $options, + ); + + return $this->collection->aggregate($pipeline, $options); + } +} diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 0f05f4577..89faa4b17 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -21,6 +21,7 @@ use MongoDB\BSON\ObjectID; use MongoDB\BSON\Regex; use MongoDB\BSON\UTCDateTime; +use MongoDB\Builder\Stage\FluentFactoryTrait; use MongoDB\Driver\Cursor; use Override; use RuntimeException; @@ -65,6 +66,7 @@ use function strlen; use function strtolower; use function substr; +use function trait_exists; use function var_export; class Builder extends BaseBuilder @@ -74,7 +76,7 @@ class Builder extends BaseBuilder /** * The database collection. * - * @var \MongoDB\Collection + * @var \MongoDB\Laravel\Collection */ protected $collection; @@ -83,7 +85,7 @@ class Builder extends BaseBuilder * * @var array */ - public $projections; + public $projections = []; /** * The maximum amount of seconds to allow the query to run. @@ -538,9 +540,26 @@ public function generateCacheKey() return md5(serialize(array_values($key))); } - /** @inheritdoc */ - public function aggregate($function, $columns = []) + /** @return ($function is null ? AggregationBuilder : mixed) */ + public function aggregate($function = null, $columns = ['*']) { + if ($function === null) { + if (! trait_exists(FluentFactoryTrait::class)) { + // This error will be unreachable when the mongodb/builder package will be merged into mongodb/mongodb + throw new BadMethodCallException('Aggregation builder requires package mongodb/builder 0.2+'); + } + + if ($columns !== ['*']) { + throw new InvalidArgumentException('Columns cannot be specified to create an aggregation builder. Add a $project stage instead.'); + } + + if ($this->wheres) { + throw new BadMethodCallException('Aggregation builder does not support previous query-builder instructions. Use a $match stage instead.'); + } + + return new AggregationBuilder($this->collection, $this->options); + } + $this->aggregate = [ 'function' => $function, 'columns' => $columns, diff --git a/tests/Query/AggregationBuilderTest.php b/tests/Query/AggregationBuilderTest.php new file mode 100644 index 000000000..b3828597d --- /dev/null +++ b/tests/Query/AggregationBuilderTest.php @@ -0,0 +1,147 @@ + 'John Doe', 'birthday' => new UTCDateTime(new DateTimeImmutable('1989-01-01'))], + ['name' => 'Jane Doe', 'birthday' => new UTCDateTime(new DateTimeImmutable('1990-01-01'))], + ]); + + // Create the aggregation pipeline from the query builder + $pipeline = User::aggregate(); + + $this->assertInstanceOf(AggregationBuilder::class, $pipeline); + + $pipeline + ->match(name: 'John Doe') + ->limit(10) + ->addFields( + // Requires MongoDB 5.0+ + year: Expression::year( + Expression::dateFieldPath('birthday'), + ), + ) + ->sort(year: Sort::Desc, name: Sort::Asc) + ->unset('birthday'); + + // Compare with the expected pipeline + $expected = [ + ['$match' => ['name' => 'John Doe']], + ['$limit' => 10], + [ + '$addFields' => [ + 'year' => ['$year' => ['date' => '$birthday']], + ], + ], + ['$sort' => ['year' => -1, 'name' => 1]], + ['$unset' => ['birthday']], + ]; + + $this->assertSamePipeline($expected, $pipeline->getPipeline()); + + // Execute the pipeline and validate the results + $results = $pipeline->get(); + $this->assertInstanceOf(Collection::class, $results); + $this->assertCount(1, $results); + $this->assertInstanceOf(ObjectId::class, $results->first()['_id']); + $this->assertSame('John Doe', $results->first()['name']); + $this->assertIsInt($results->first()['year']); + $this->assertArrayNotHasKey('birthday', $results->first()); + + // Execute the pipeline and validate the results in a lazy collection + $results = $pipeline->cursor(); + $this->assertInstanceOf(LazyCollection::class, $results); + + // Execute the pipeline and return the first result + $result = $pipeline->first(); + $this->assertIsArray($result); + $this->assertInstanceOf(ObjectId::class, $result['_id']); + $this->assertSame('John Doe', $result['name']); + } + + public function testAddRawStage(): void + { + $collection = $this->createMock(MongoDBCollection::class); + + $pipeline = new AggregationBuilder($collection); + $pipeline + ->addRawStage('$match', ['name' => 'John Doe']) + ->addRawStage('$limit', 10) + ->addRawStage('$replaceRoot', (object) ['newRoot' => '$$ROOT']); + + $expected = [ + ['$match' => ['name' => 'John Doe']], + ['$limit' => 10], + ['$replaceRoot' => ['newRoot' => '$$ROOT']], + ]; + + $this->assertSamePipeline($expected, $pipeline->getPipeline()); + } + + public function testAddRawStageInvalid(): void + { + $collection = $this->createMock(MongoDBCollection::class); + + $pipeline = new AggregationBuilder($collection); + + $this->expectException(InvalidArgumentException::class); + $this->expectExceptionMessage('The stage name "match" is invalid. It must start with a "$" sign.'); + $pipeline->addRawStage('match', ['name' => 'John Doe']); + } + + public function testColumnsCannotBeSpecifiedToCreateAnAggregationBuilder(): void + { + $this->expectException(InvalidArgumentException::class); + $this->expectExceptionMessage('Columns cannot be specified to create an aggregation builder.'); + User::aggregate(null, ['name']); + } + + public function testAggrecationBuilderDoesNotSupportPreviousQueryBuilderInstructions(): void + { + $this->expectException(BadMethodCallException::class); + $this->expectExceptionMessage('Aggregation builder does not support previous query-builder instructions.'); + User::where('name', 'John Doe')->aggregate(); + } + + private static function assertSamePipeline(array $expected, Pipeline $pipeline): void + { + $expected = Document::fromPHP(['pipeline' => $expected])->toCanonicalExtendedJSON(); + + $codec = new BuilderEncoder(); + $actual = $codec->encode($pipeline); + // Normalize with BSON round-trip + $actual = Document::fromPHP(['pipeline' => $actual])->toCanonicalExtendedJSON(); + + self::assertJsonStringEqualsJsonString($expected, $actual); + } +} From f2d2820e145fc8fa5d16fa48f5e8462de508122d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 27 Mar 2024 16:10:11 +0100 Subject: [PATCH 214/446] PHPORM-162 Drop support for Composer 1.x (#2785) Co-authored-by: Jeremy Mikola --- CHANGELOG.md | 3 ++- composer.json | 1 + src/Connection.php | 13 ++++--------- 3 files changed, 7 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index edd119625..382bee76a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,8 +4,9 @@ All notable changes to this project will be documented in this file. ## [unreleased] * New aggregation pipeline builder by @GromNaN in [#2738](https://github.com/mongodb/laravel-mongodb/pull/2738) +* Drop support for Composer 1.x by @GromNaN in [#2784](https://github.com/mongodb/laravel-mongodb/pull/2784) -## [4.2.0] - 2024-12-14 +## [4.2.0] - 2024-03-14 * Add support for Laravel 11 by @GromNaN in [#2735](https://github.com/mongodb/laravel-mongodb/pull/2735) * Implement Model::createOrFirst() using findOneAndUpdate operation by @GromNaN in [#2742](https://github.com/mongodb/laravel-mongodb/pull/2742) diff --git a/composer.json b/composer.json index 3769bdfe6..51c7e1e43 100644 --- a/composer.json +++ b/composer.json @@ -24,6 +24,7 @@ "require": { "php": "^8.1", "ext-mongodb": "^1.15", + "composer-runtime-api": "^2.0.0", "illuminate/support": "^10.0|^11", "illuminate/container": "^10.0|^11", "illuminate/database": "^10.30|^11", diff --git a/src/Connection.php b/src/Connection.php index 3f529cdea..01232c7ae 100644 --- a/src/Connection.php +++ b/src/Connection.php @@ -16,7 +16,6 @@ use MongoDB\Laravel\Concerns\ManagesTransactions; use Throwable; -use function class_exists; use function filter_var; use function implode; use function is_array; @@ -324,14 +323,10 @@ private static function getVersion(): string private static function lookupVersion(): string { - if (class_exists(InstalledVersions::class)) { - try { - return self::$version = InstalledVersions::getPrettyVersion('mongodb/laravel-mongodb'); - } catch (Throwable) { - return self::$version = 'error'; - } + try { + return self::$version = InstalledVersions::getPrettyVersion('mongodb/laravel-mongodb') ?? 'unknown'; + } catch (Throwable) { + return self::$version = 'error'; } - - return self::$version = 'unknown'; } } From 586a4206161aade8ed4119e7da03d9dd96187961 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Mon, 25 Mar 2024 16:56:02 -0400 Subject: [PATCH 215/446] DOCSP-37057 eloquent schema builder (#2776) * DOCSP-37057: Eloquent schema builder --- docs/eloquent-models.txt | 518 +----------------- docs/eloquent-models/schema-builder.txt | 393 +++++++++++++ .../schema-builder/astronauts_migration.php | 30 + .../schema-builder/flights_migration.php | 32 ++ .../schema-builder/passengers_migration.php | 32 ++ .../schema-builder/planets_migration.php | 33 ++ .../schema-builder/spaceports_migration.php | 33 ++ .../schema-builder/stars_migration.php | 27 + 8 files changed, 592 insertions(+), 506 deletions(-) create mode 100644 docs/eloquent-models/schema-builder.txt create mode 100644 docs/includes/schema-builder/astronauts_migration.php create mode 100644 docs/includes/schema-builder/flights_migration.php create mode 100644 docs/includes/schema-builder/passengers_migration.php create mode 100644 docs/includes/schema-builder/planets_migration.php create mode 100644 docs/includes/schema-builder/spaceports_migration.php create mode 100644 docs/includes/schema-builder/stars_migration.php diff --git a/docs/eloquent-models.txt b/docs/eloquent-models.txt index 3ce32c124..c0f7cea57 100644 --- a/docs/eloquent-models.txt +++ b/docs/eloquent-models.txt @@ -6,517 +6,23 @@ Eloquent Models .. facet:: :name: genre - :values: tutorial + :values: reference .. meta:: - :keywords: php framework, odm, code example + :keywords: php framework, odm -This package includes a MongoDB enabled Eloquent class that you can use to -define models for corresponding collections. +Eloquent models are part of the Laravel Eloquent object-relational +mapping (ORM) framework that enable you to work with a database by using +model classes. {+odm-short+} extends this framework to use similar +syntax to work with MongoDB as a database. -Extending the base model -~~~~~~~~~~~~~~~~~~~~~~~~ +This section contains guidance on how to use Eloquent models in +{+odm-short+} to work with MongoDB in the following ways: -To get started, create a new model class in your ``app\Models\`` directory. +- :ref:`laravel-schema-builder` shows how to manage indexes on your MongoDB + collections by using Laravel migrations -.. code-block:: php +.. toctree:: - namespace App\Models; + Schema Builder - use MongoDB\Laravel\Eloquent\Model; - - class Book extends Model - { - // - } - -Just like a regular model, the MongoDB model class will know which collection -to use based on the model name. For ``Book``, the collection ``books`` will -be used. - -To change the collection, pass the ``$collection`` property: - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class Book extends Model - { - protected $collection = 'my_books_collection'; - } - -.. note:: - - MongoDB documents are automatically stored with a unique ID that is stored - in the ``_id`` property. If you wish to use your own ID, substitute the - ``$primaryKey`` property and set it to your own primary key attribute name. - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class Book extends Model - { - protected $primaryKey = 'id'; - } - - // MongoDB will also create _id, but the 'id' property will be used for primary key actions like find(). - Book::create(['id' => 1, 'title' => 'The Fault in Our Stars']); - -Likewise, you may define a ``connection`` property to override the name of the -database connection to reference the model. - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class Book extends Model - { - protected $connection = 'mongodb'; - } - -Soft Deletes -~~~~~~~~~~~~ - -When soft deleting a model, it is not actually removed from your database. -Instead, a ``deleted_at`` timestamp is set on the record. - -To enable soft delete for a model, apply the ``MongoDB\Laravel\Eloquent\SoftDeletes`` -Trait to the model: - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\SoftDeletes; - - class User extends Model - { - use SoftDeletes; - } - -For more information check `Laravel Docs about Soft Deleting `__. - -Prunable -~~~~~~~~ - -``Prunable`` and ``MassPrunable`` traits are Laravel features to automatically -remove models from your database. You can use ``Illuminate\Database\Eloquent\Prunable`` -trait to remove models one by one. If you want to remove models in bulk, you -must use the ``MongoDB\Laravel\Eloquent\MassPrunable`` trait instead: it -will be more performant but can break links with other documents as it does -not load the models. - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - use MongoDB\Laravel\Eloquent\MassPrunable; - - class Book extends Model - { - use MassPrunable; - } - -For more information check `Laravel Docs about Pruning Models `__. - -Dates -~~~~~ - -Eloquent allows you to work with Carbon or DateTime objects instead of MongoDate objects. Internally, these dates will be converted to MongoDate objects when saved to the database. - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class User extends Model - { - protected $casts = ['birthday' => 'datetime']; - } - -This allows you to execute queries like this: - -.. code-block:: php - - $users = User::where( - 'birthday', '>', - new DateTime('-18 years') - )->get(); - -Extending the Authenticatable base model -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This package includes a MongoDB Authenticatable Eloquent class ``MongoDB\Laravel\Auth\User`` -that you can use to replace the default Authenticatable class ``Illuminate\Foundation\Auth\User`` -for your ``User`` model. - -.. code-block:: php - - use MongoDB\Laravel\Auth\User as Authenticatable; - - class User extends Authenticatable - { - - } - -Guarding attributes -~~~~~~~~~~~~~~~~~~~ - -When choosing between guarding attributes or marking some as fillable, Taylor -Otwell prefers the fillable route. This is in light of -`recent security issues described here `__. - -Keep in mind guarding still works, but you may experience unexpected behavior. - -Schema ------- - -The database driver also has (limited) schema builder support. You can -conveniently manipulate collections and set indexes. - -Basic Usage -~~~~~~~~~~~ - -.. code-block:: php - - Schema::create('users', function ($collection) { - $collection->index('name'); - $collection->unique('email'); - }); - -You can also pass all the parameters specified :manual:`in the MongoDB docs ` -to the ``$options`` parameter: - -.. code-block:: php - - Schema::create('users', function ($collection) { - $collection->index( - 'username', - null, - null, - [ - 'sparse' => true, - 'unique' => true, - 'background' => true, - ] - ); - }); - -Inherited operations: - - -* create and drop -* collection -* hasCollection -* index and dropIndex (compound indexes supported as well) -* unique - -MongoDB specific operations: - - -* background -* sparse -* expire -* geospatial - -All other (unsupported) operations are implemented as dummy pass-through -methods because MongoDB does not use a predefined schema. - -Read more about the schema builder on `Laravel Docs `__ - -Geospatial indexes -~~~~~~~~~~~~~~~~~~ - -Geospatial indexes can improve query performance of location-based documents. - -They come in two forms: ``2d`` and ``2dsphere``. Use the schema builder to add -these to a collection. - -.. code-block:: php - - Schema::create('bars', function ($collection) { - $collection->geospatial('location', '2d'); - }); - -To add a ``2dsphere`` index: - -.. code-block:: php - - Schema::create('bars', function ($collection) { - $collection->geospatial('location', '2dsphere'); - }); - -Relationships -------------- - -Basic Usage -~~~~~~~~~~~ - -The only available relationships are: - - -* hasOne -* hasMany -* belongsTo -* belongsToMany - -The MongoDB-specific relationships are: - - -* embedsOne -* embedsMany - -Here is a small example: - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class User extends Model - { - public function items() - { - return $this->hasMany(Item::class); - } - } - -The inverse relation of ``hasMany`` is ``belongsTo``: - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class Item extends Model - { - public function user() - { - return $this->belongsTo(User::class); - } - } - -belongsToMany and pivots -~~~~~~~~~~~~~~~~~~~~~~~~ - -The belongsToMany relation will not use a pivot "table" but will push id's to -a **related_ids** attribute instead. This makes the second parameter for the -belongsToMany method useless. - -If you want to define custom keys for your relation, set it to ``null``: - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class User extends Model - { - public function groups() - { - return $this->belongsToMany( - Group::class, null, 'user_ids', 'group_ids' - ); - } - } - -EmbedsMany Relationship -~~~~~~~~~~~~~~~~~~~~~~~ - -If you want to embed models, rather than referencing them, you can use the -``embedsMany`` relation. This relation is similar to the ``hasMany`` relation -but embeds the models inside the parent object. - -**REMEMBER**\ : These relations return Eloquent collections, they don't return -query builder objects! - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class User extends Model - { - public function books() - { - return $this->embedsMany(Book::class); - } - } - -You can access the embedded models through the dynamic property: - -.. code-block:: php - - $user = User::first(); - - foreach ($user->books as $book) { - // - } - -The inverse relation is auto *magically* available. You can omit the reverse -relation definition. - -.. code-block:: php - - $book = User::first()->books()->first(); - - $user = $book->user; - -Inserting and updating embedded models works similar to the ``hasMany`` relation: - -.. code-block:: php - - $book = $user->books()->save( - new Book(['title' => 'A Game of Thrones']) - ); - - // or - $book = - $user->books() - ->create(['title' => 'A Game of Thrones']); - -You can update embedded models using their ``save`` method (available since -release 2.0.0): - -.. code-block:: php - - $book = $user->books()->first(); - - $book->title = 'A Game of Thrones'; - $book->save(); - -You can remove an embedded model by using the ``destroy`` method on the -relation, or the ``delete`` method on the model (available since release 2.0.0): - -.. code-block:: php - - $book->delete(); - - // Similar operation - $user->books()->destroy($book); - -If you want to add or remove an embedded model, without touching the database, -you can use the ``associate`` and ``dissociate`` methods. - -To eventually write the changes to the database, save the parent object: - -.. code-block:: php - - $user->books()->associate($book); - $user->save(); - -Like other relations, embedsMany assumes the local key of the relationship -based on the model name. You can override the default local key by passing a -second argument to the embedsMany method: - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class User extends Model - { - public function books() - { - return $this->embedsMany(Book::class, 'local_key'); - } - } - -Embedded relations will return a Collection of embedded items instead of a -query builder. Check out the available operations here: -`https://laravel.com/docs/master/collections `__ - -EmbedsOne Relationship -~~~~~~~~~~~~~~~~~~~~~~ - -The embedsOne relation is similar to the embedsMany relation, but only embeds a single model. - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class Book extends Model - { - public function author() - { - return $this->embedsOne(Author::class); - } - } - -You can access the embedded models through the dynamic property: - -.. code-block:: php - - $book = Book::first(); - $author = $book->author; - -Inserting and updating embedded models works similar to the ``hasOne`` relation: - -.. code-block:: php - - $author = $book->author()->save( - new Author(['name' => 'John Doe']) - ); - - // Similar - $author = - $book->author() - ->create(['name' => 'John Doe']); - -You can update the embedded model using the ``save`` method (available since -release 2.0.0): - -.. code-block:: php - - $author = $book->author; - - $author->name = 'Jane Doe'; - $author->save(); - -You can replace the embedded model with a new model like this: - -.. code-block:: php - - $newAuthor = new Author(['name' => 'Jane Doe']); - - $book->author()->save($newAuthor); - -Cross-Database Relationships ----------------------------- - -If you're using a hybrid MongoDB and SQL setup, you can define relationships -across them. - -The model will automatically return a MongoDB-related or SQL-related relation -based on the type of the related model. - -If you want this functionality to work both ways, your SQL-models will need -to use the ``MongoDB\Laravel\Eloquent\HybridRelations`` trait. - -**This functionality only works for ``hasOne``, ``hasMany`` and ``belongsTo``.** - -The SQL model must use the ``HybridRelations`` trait: - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\HybridRelations; - - class User extends Model - { - use HybridRelations; - - protected $connection = 'mysql'; - - public function messages() - { - return $this->hasMany(Message::class); - } - } - -Within your MongoDB model, you must define the following relationship: - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class Message extends Model - { - protected $connection = 'mongodb'; - - public function user() - { - return $this->belongsTo(User::class); - } - } diff --git a/docs/eloquent-models/schema-builder.txt b/docs/eloquent-models/schema-builder.txt new file mode 100644 index 000000000..9fd845b55 --- /dev/null +++ b/docs/eloquent-models/schema-builder.txt @@ -0,0 +1,393 @@ +.. _laravel-schema-builder: + +============== +Schema Builder +============== + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :keywords: php framework, odm, code example, schema facade, eloquent, blueprint, artisan, migrate + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +Laravel provides a **facade** to access the schema builder class ``Schema``, +which lets you create and modify tables. Facades are static interfaces to +classes that make the syntax more concise and improve testability. + +{+odm-short+} supports a subset of the index and collection management methods +in the Laravel ``Schema`` facade. + +To learn more about facades, see `Facades `__ +in the Laravel documentation. + +The following sections describe the Laravel schema builder features available +in {+odm-short+} and show examples of how to use them: + +- :ref:`` +- :ref:`` +- :ref:`` + +.. note:: + + {+odm-short+} supports managing indexes and collections, but + excludes support for MongoDB JSON schemas for data validation. To learn + more about JSON schema validation, see :manual:`Schema Validation ` + in the {+server-docs-name+}. + +.. _laravel-eloquent-migrations: + +Perform Laravel Migrations +-------------------------- + +Laravel migrations let you programmatically create, modify, and delete +your database schema by running methods included in the ``Schema`` facade. +The following sections explain how to author a migration class when you use +a MongoDB database and how to run them. + +Create a Migration Class +~~~~~~~~~~~~~~~~~~~~~~~~ + +You can create migration classes manually or generate them by using the +``php artisan make:migration`` command. If you generate them, you must make the +following changes to perform the schema changes on your MongoDB database: + +- Replace the ``Illuminate\Database\Schema\Blueprint`` import with + ``MongoDB\Laravel\Schema\Blueprint`` if it is referenced in your migration +- Use only commands and syntax supported by {+odm-short+} + +.. tip:: + + If your default database connection is set to anything other than your + MongoDB database, update the following setting to make sure the migration + specifies the correct database: + + - Specify ``mongodb`` in the ``$connection`` field of your migration class + - Set ``DB_CONNECTION=mongodb`` in your ``.env`` configuration file + +The following example migration class contains the following methods: + +- ``up()``, which creates a collection and an index when you run the migration +- ``down()``, which drops the collection and all the indexes on it when you roll back the migration + +.. literalinclude:: /includes/schema-builder/astronauts_migration.php + :dedent: + :language: php + :emphasize-lines: 6, 11 + +Run or Roll Back a Migration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To run the database migration from a class file, run the following command +after replacing the placeholder: + +.. code-block:: bash + + php artisan migrate --path= + +This command runs the ``up()`` function in the class file to create the +collection and index in the database specified in the ``config/database.php`` +file. + +To roll back the migration, run the following command after replacing the +placeholder: + +.. code-block:: bash + + php artisan migrate:rollback --path= + +This command runs the ``down()`` function in the class file to drop the +collection and related indexes. + +To learn more about Laravel migrations, see +`Database: Migrations `__ +in the Laravel documentation. + +.. _laravel-eloquent-collection-exists: + +Check Whether a Collection Exists +--------------------------------- + +To check whether a collection exists, call the ``hasCollection()`` method on +the ``Schema`` facade in your migration file. You can use this to +perform migration logic conditionally. + +The following example migration creates a ``stars`` collection if a collection +named ``telescopes`` exists: + +.. literalinclude:: /includes/schema-builder/stars_migration.php + :language: php + :dedent: + :start-after: begin conditional create + :end-before: end conditional create + +.. _laravel-eloquent-indexes: + +Manage Indexes +-------------- + +MongoDB indexes are data structures that improve query efficiency by reducing +the number of documents needed to retrieve query results. Certain indexes, such +as geospatial indexes, extend how you can query the data. + +To improve query performance by using an index, make sure the index covers +the query. To learn more about indexes and query optimization, see the +following {+server-docs-name+} entries: + +- :manual:`Indexes ` +- :manual:`Query Optimization ` + +The following sections show how you can use the schema builder to create and +drop various types of indexes on a collection. + +Create an Index +~~~~~~~~~~~~~~~ + +To create indexes, call the ``create()`` method on the ``Schema`` facade +in your migration file. Pass it the collection name and a callback +method with a ``MongoDB\Laravel\Schema\Blueprint`` parameter. Specify the +index creation details on the ``Blueprint`` instance. + +The following example migration creates indexes on the following collection +fields: + +- Single field index on ``mission_type`` +- Compound index on ``launch_location`` and ``launch_date``, specifying a descending sort order on ``launch_date`` +- Unique index on the ``mission_id`` field, specifying the index name "unique_mission_id_idx" + +Click the :guilabel:`VIEW OUTPUT` button to see the indexes created by running +the migration, including the default index on the ``_id`` field: + +.. io-code-block:: + + .. input:: /includes/schema-builder/flights_migration.php + :language: php + :dedent: + :start-after: begin create index + :end-before: end create index + + .. output:: + :language: json + :visible: false + + [ + { v: 2, key: { _id: 1 }, name: '_id_' }, + { v: 2, key: { mission_type: 1 }, name: 'mission_type_1' }, + { + v: 2, + key: { launch_location: 1, launch_date: -1 }, + name: 'launch_location_1_launch_date_-1' + }, + { + v: 2, + key: { mission_id: 1 }, + name: 'unique_mission_id_idx', + unique: true + } + ] + +Specify Index Options +~~~~~~~~~~~~~~~~~~~~~ + +MongoDB index options determine how the indexes are used and stored. +You can specify index options when calling an index creation method, such +as ``index()``, on a ``Blueprint`` instance. + +The following migration code shows how to add a collation to an index as an +index option. Click the :guilabel:`VIEW OUTPUT` button to see the indexes +created by running the migration, including the default index on the ``_id`` +field: + +.. io-code-block:: + + .. input:: /includes/schema-builder/passengers_migration.php + :language: php + :dedent: + :start-after: begin index options + :end-before: end index options + + .. output:: + :language: json + :visible: false + + [ + { v: 2, key: { _id: 1 }, name: '_id_' }, + { + v: 2, + key: { last_name: 1 }, + name: 'passengers_collation_idx', + collation: { + locale: 'de@collation=phonebook', + caseLevel: false, + caseFirst: 'off', + strength: 3, + numericOrdering: true, + alternate: 'non-ignorable', + maxVariable: 'punct', + normalization: false, + backwards: false, + version: '57.1' + } + } + ] + +To learn more about index options, see :manual:`Options for All Index Types ` +in the {+server-docs-name+}. + +Create Sparse, TTL, and Unique Indexes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can use {+odm-short+} helper methods to create the following types of +indexes: + +- Sparse indexes, which allow index entries only for documents that contain the + specified field +- Time-to-live (TTL) indexes, which expire after a set amount of time +- Unique indexes, which prevent inserting documents that contain duplicate + values for the indexed field + +To create these index types, call the ``create()`` method on the ``Schema`` facade +in your migration file. Pass ``create()`` the collection name and a callback +method with a ``MongoDB\Laravel\Schema\Blueprint`` parameter. Call the +appropriate helper method on the ``Blueprint`` instance and pass the +index creation details. + +The following migration code shows how to create a sparse and a TTL index +by using the index helpers. Click the :guilabel:`VIEW OUTPUT` button to see +the indexes created by running the migration, including the default index on +the ``_id`` field: + +.. io-code-block:: + + .. input:: /includes/schema-builder/planets_migration.php + :language: php + :dedent: + :start-after: begin index helpers + :end-before: end index helpers + + .. output:: + :language: json + :visible: false + + [ + { v: 2, key: { _id: 1 }, name: '_id_' }, + { v: 2, key: { rings: 1 }, name: 'rings_1', sparse: true }, + { + v: 2, + key: { last_visible_dt: 1 }, + name: 'last_visible_dt_1', + expireAfterSeconds: 86400 + } + ] + +You can specify sparse, TTL, and unique indexes on either a single field or +compound index by specifying them in the index options. + +The following migration code shows how to create all three types of indexes +on a single field. Click the :guilabel:`VIEW OUTPUT` button to see the indexes +created by running the migration, including the default index on the ``_id`` +field: + +.. io-code-block:: + + .. input:: /includes/schema-builder/planets_migration.php + :language: php + :dedent: + :start-after: begin multi index helpers + :end-before: end multi index helpers + + .. output:: + :language: json + :visible: false + + [ + { v: 2, key: { _id: 1 }, name: '_id_' }, + { + v: 2, + key: { last_visible_dt: 1 }, + name: 'last_visible_dt_1', + unique: true, + sparse: true, + expireAfterSeconds: 3600 + } + ] + +To learn more about these indexes, see :manual:`Index Properties ` +in the {+server-docs-name+}. + +Create a Geospatial Index +~~~~~~~~~~~~~~~~~~~~~~~~~ + +In MongoDB, geospatial indexes let you query geospatial coordinate data for +inclusion, intersection, and proximity. + +To create geospatial indexes, call the ``create()`` method on the ``Schema`` facade +in your migration file. Pass ``create()`` the collection name and a callback +method with a ``MongoDB\Laravel\Schema\Blueprint`` parameter. Specify the +geospatial index creation details on the ``Blueprint`` instance. + +The following example migration creates a ``2d`` and ``2dsphere`` geospatial +index on the ``spaceports`` collection. Click the :guilabel:`VIEW OUTPUT` +button to see the indexes created by running the migration, including the +default index on the ``_id`` field: + +.. io-code-block:: + .. input:: /includes/schema-builder/spaceports_migration.php + :language: php + :dedent: + :start-after: begin create geospatial index + :end-before: end create geospatial index + + .. output:: + :language: json + :visible: false + + [ + { v: 2, key: { _id: 1 }, name: '_id_' }, + { + v: 2, + key: { launchpad_location: '2dsphere' }, + name: 'launchpad_location_2dsphere', + '2dsphereIndexVersion': 3 + }, + { v: 2, key: { runway_location: '2d' }, name: 'runway_location_2d' } + ] + + +To learn more about geospatial indexes, see +:manual:`Geospatial Indexes ` in +the {+server-docs-name+}. + +Drop an Index +~~~~~~~~~~~~~ + +To drop indexes from a collection, call the ``table()`` method on the +``Schema`` facade in your migration file. Pass it the table name and a +callback method with a ``MongoDB\Laravel\Schema\Blueprint`` parameter. +Call the ``dropIndex()`` method with the index name on the ``Blueprint`` +instance. + +.. note:: + + If you drop a collection, MongoDB automatically drops all the indexes + associated with it. + +The following example migration drops an index called ``unique_mission_id_idx`` +from the ``flights`` collection: + +.. literalinclude:: /includes/schema-builder/flights_migration.php + :language: php + :dedent: + :start-after: begin drop index + :end-before: end drop index + + diff --git a/docs/includes/schema-builder/astronauts_migration.php b/docs/includes/schema-builder/astronauts_migration.php new file mode 100644 index 000000000..1fb7b76e4 --- /dev/null +++ b/docs/includes/schema-builder/astronauts_migration.php @@ -0,0 +1,30 @@ +index('name'); + }); + } + + /** + * Reverse the migrations. + */ + public function down(): void + { + Schema::drop('astronauts'); + } +}; diff --git a/docs/includes/schema-builder/flights_migration.php b/docs/includes/schema-builder/flights_migration.php new file mode 100644 index 000000000..861c339ef --- /dev/null +++ b/docs/includes/schema-builder/flights_migration.php @@ -0,0 +1,32 @@ +index('mission_type'); + $collection->index(['launch_location' => 1, 'launch_date' => -1]); + $collection->unique('mission_id', options: ['name' => 'unique_mission_id_idx']); + }); + // end create index + } + + public function down(): void + { + // begin drop index + Schema::table('flights', function (Blueprint $collection) { + $collection->dropIndex('unique_mission_id_idx'); + }); + // end drop index + } +}; diff --git a/docs/includes/schema-builder/passengers_migration.php b/docs/includes/schema-builder/passengers_migration.php new file mode 100644 index 000000000..f0b498940 --- /dev/null +++ b/docs/includes/schema-builder/passengers_migration.php @@ -0,0 +1,32 @@ +index( + 'last_name', + name: 'passengers_collation_idx', + options: [ + 'collation' => [ 'locale' => 'de@collation=phonebook', 'numericOrdering' => true ], + ], + ); + }); + // end index options + } + + public function down(): void + { + Schema::drop('passengers'); + } +}; diff --git a/docs/includes/schema-builder/planets_migration.php b/docs/includes/schema-builder/planets_migration.php new file mode 100644 index 000000000..90de5bd6e --- /dev/null +++ b/docs/includes/schema-builder/planets_migration.php @@ -0,0 +1,33 @@ +sparse('rings'); + $collection->expire('last_visible_dt', 86400); + }); + // end index helpers + + // begin multi index helpers + Schema::create('planet_systems', function (Blueprint $collection) { + $collection->index('last_visible_dt', options: ['sparse' => true, 'expireAfterSeconds' => 3600, 'unique' => true]); + }); + // end multi index helpers + } + + public function down(): void + { + Schema::drop('planets'); + } +}; diff --git a/docs/includes/schema-builder/spaceports_migration.php b/docs/includes/schema-builder/spaceports_migration.php new file mode 100644 index 000000000..ae96c6066 --- /dev/null +++ b/docs/includes/schema-builder/spaceports_migration.php @@ -0,0 +1,33 @@ +geospatial('launchpad_location', '2dsphere'); + $collection->geospatial('runway_location', '2d'); + }); + // end create geospatial index + } + + /** + * Reverse the migrations. + */ + public function down(): void + { + Schema::drop('spaceports'); + } +}; diff --git a/docs/includes/schema-builder/stars_migration.php b/docs/includes/schema-builder/stars_migration.php new file mode 100644 index 000000000..6249da3cd --- /dev/null +++ b/docs/includes/schema-builder/stars_migration.php @@ -0,0 +1,27 @@ + Date: Mon, 25 Mar 2024 17:01:20 -0400 Subject: [PATCH 216/446] DOCSP-35964 eloquent models standardization (#2726) * DOCSP-35964: Eloquent Models section --- docs/eloquent-models.txt | 6 +- docs/eloquent-models/model-class.txt | 317 ++++++++++++++++++ .../eloquent-models/AuthenticatableUser.php | 9 + docs/includes/eloquent-models/Planet.php | 9 + .../eloquent-models/PlanetCollection.php | 10 + docs/includes/eloquent-models/PlanetDate.php | 12 + .../eloquent-models/PlanetMassAssignment.php | 15 + .../eloquent-models/PlanetMassPrune.php | 18 + .../eloquent-models/PlanetPrimaryKey.php | 10 + docs/includes/eloquent-models/PlanetPrune.php | 22 ++ .../eloquent-models/PlanetSoftDelete.php | 11 + phpcs.xml.dist | 12 + 12 files changed, 449 insertions(+), 2 deletions(-) create mode 100644 docs/eloquent-models/model-class.txt create mode 100644 docs/includes/eloquent-models/AuthenticatableUser.php create mode 100644 docs/includes/eloquent-models/Planet.php create mode 100644 docs/includes/eloquent-models/PlanetCollection.php create mode 100644 docs/includes/eloquent-models/PlanetDate.php create mode 100644 docs/includes/eloquent-models/PlanetMassAssignment.php create mode 100644 docs/includes/eloquent-models/PlanetMassPrune.php create mode 100644 docs/includes/eloquent-models/PlanetPrimaryKey.php create mode 100644 docs/includes/eloquent-models/PlanetPrune.php create mode 100644 docs/includes/eloquent-models/PlanetSoftDelete.php diff --git a/docs/eloquent-models.txt b/docs/eloquent-models.txt index c0f7cea57..2bca40f2d 100644 --- a/docs/eloquent-models.txt +++ b/docs/eloquent-models.txt @@ -19,10 +19,12 @@ syntax to work with MongoDB as a database. This section contains guidance on how to use Eloquent models in {+odm-short+} to work with MongoDB in the following ways: +- :ref:`laravel-eloquent-model-class` shows how to define models and customize + their behavior - :ref:`laravel-schema-builder` shows how to manage indexes on your MongoDB collections by using Laravel migrations - + .. toctree:: + /eloquent-models/model-class/ Schema Builder - diff --git a/docs/eloquent-models/model-class.txt b/docs/eloquent-models/model-class.txt new file mode 100644 index 000000000..85b7b994b --- /dev/null +++ b/docs/eloquent-models/model-class.txt @@ -0,0 +1,317 @@ +.. _laravel-eloquent-model-class: + +==================== +Eloquent Model Class +==================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: php framework, odm, code example, authentication, laravel + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +This guide shows you how to use the {+odm-long+} to define and +customize Laravel Eloquent models. You can use these models to work with +MongoDB data by using the Laravel Eloquent object-relational mapper (ORM). + +The following sections explain how to add Laravel Eloquent ORM behaviors +to {+odm-short+} models: + +- :ref:`laravel-model-define` demonstrates how to create a model class. +- :ref:`laravel-authenticatable-model` shows how to set MongoDB as the + authentication user provider. +- :ref:`laravel-model-customize` explains several model class customizations. +- :ref:`laravel-model-pruning` shows how to periodically remove models that + you no longer need. + +.. _laravel-model-define: + +Define an Eloquent Model Class +------------------------------ + +Eloquent models are classes that represent your data. They include methods +that perform database operations such as inserts, updates, and deletes. + +To declare a {+odm-short+} model, create a class in the ``app/Models`` +directory of your Laravel application that extends +``MongoDB\Laravel\Eloquent\Model`` as shown in the following code example: + +.. literalinclude:: /includes/eloquent-models/Planet.php + :language: php + :emphasize-lines: 3,5,7 + :dedent: + +By default, the model uses the MongoDB database name set in your Laravel +application's ``config/database.php`` setting and the snake case plural +form of your model class name for the collection. + +This model is stored in the ``planets`` MongoDB collection. + +.. tip:: + + Alternatively, use the ``artisan`` console to generate the model class and + change the ``Illuminate\Database\Eloquent\Model`` import to ``MongoDB\Laravel\Eloquent\Model``. + To learn more about the ``artisan`` console, see `Artisan Console `__ + in the Laravel docs. + +To learn how to specify the database name that your Laravel application uses, +:ref:`laravel-quick-start-connect-to-mongodb`. + + +.. _laravel-authenticatable-model: + +Extend the Authenticatable Model +-------------------------------- + +To configure MongoDB as the Laravel user provider, you can extend the +{+odm-short+} ``MongoDB\Laravel\Auth\User`` class. The following code example +shows how to extend this class: + +.. literalinclude:: /includes/eloquent-models/AuthenticatableUser.php + :language: php + :emphasize-lines: 3,5,7 + :dedent: + +To learn more about customizing a Laravel authentication user provider, +see `Adding Custom User Providers `__ +in the Laravel docs. + +.. _laravel-model-customize: + +Customize an Eloquent Model Class +--------------------------------- + +This section shows how to perform the following Eloquent model behavior +customizations: + +- :ref:`laravel-model-customize-collection-name` +- :ref:`laravel-model-customize-primary-key` +- :ref:`laravel-model-soft-delete` +- :ref:`laravel-model-cast-data-types` +- :ref:`laravel-model-mass-assignment` + +.. _laravel-model-customize-collection-name: + +Change the Model Collection Name +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, the model uses the snake case plural form of your model +class name. To change the name of the collection the model uses to retrieve +and save data in MongoDB, override the ``$collection`` property of the model +class. + +.. note:: + + We recommend using the default collection naming behavior to keep + the associations between models and collections straightforward. + +The following example specifies the custom MongoDB collection name, +``celestial_body``, for the ``Planet`` class: + +.. literalinclude:: /includes/eloquent-models/PlanetCollection.php + :language: php + :emphasize-lines: 9 + :dedent: + +Without overriding the ``$collection`` property, this model maps to the +``planets`` collection. With the overridden property, the example class stores +the model in the ``celestial_body`` collection. + +.. _laravel-model-customize-primary-key: + +Change the Primary Key Field +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To customize the model's primary key field that uniquely identifies a MongoDB +document, override the ``$primaryKey`` property of the model class. + +By default, the model uses the PHP MongoDB driver to generate unique ObjectIDs +for each document your Laravel application inserts. + +The following example specifies the ``name`` field as the primary key for +the ``Planet`` class: + +.. literalinclude:: /includes/eloquent-models/PlanetPrimaryKey.php + :language: php + :emphasize-lines: 9 + :dedent: + +To learn more about primary key behavior and customization options, see +`Eloquent Primary Keys `__ +in the Laravel docs. + +To learn more about the ``_id`` field, ObjectIDs, and the MongoDB document +structure, see :manual:`Documents ` in the MongoDB server docs. + +.. _laravel-model-soft-delete: + +Enable Soft Deletes +~~~~~~~~~~~~~~~~~~~ + +Eloquent includes a soft delete feature that changes the behavior of the +``delete()`` method on a model. When soft delete is enabled on a model, the +``delete()`` method marks a document as deleted instead of removing it from the +database. It sets a timestamp on the ``deleted_at`` field to exclude it from +retrieve operations automatically. + +To enable soft deletes on a class, add the ``MongoDB\Laravel\Eloquent\SoftDeletes`` +trait as shown in the following code example: + +.. literalinclude:: /includes/eloquent-models/PlanetSoftDelete.php + :language: php + :emphasize-lines: 6,10 + :dedent: + +To learn about methods you can perform on models with soft deletes enabled, see +`Eloquent Soft Deleting `__ +in the Laravel docs. + +.. _laravel-model-cast-data-types: + +Cast Data Types +--------------- + +Eloquent lets you convert model attribute data types before storing or +retrieving data by using a casting helper. This helper is a convenient +alternative to defining equivalent accessor and mutator methods on your model. + +In the following example, the casting helper converts the ``discovery_dt`` +model attribute, stored in MongoDB as a `MongoDB\\BSON\\UTCDateTime `__ +type, to the Laravel ``datetime`` type. + +.. literalinclude:: /includes/eloquent-models/PlanetDate.php + :language: php + :emphasize-lines: 9-11 + :dedent: + +This conversion lets you use the PHP `DateTime `__ +or the `Carbon class `__ to work with dates +in this field. The following example shows a Laravel query that uses the +casting helper on the model to query for planets with a ``discovery_dt`` of +less than three years ago: + +.. code-block:: php + + Planet::where( 'discovery_dt', '>', new DateTime('-3 years'))->get(); + +To learn more about MongoDB's data types, see :manual:`BSON Types ` +in the MongoDB server docs. + +To learn more about the Laravel casting helper and supported types, see `Attribute Casting `__ +in the Laravel docs. + +.. _laravel-model-mass-assignment: + +Customize Mass Assignment +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Eloquent lets you create several models and their attribute data by passing +an array of data to the ``create()`` model method. This process of inserting +multiple models is called mass assignment. + +Mass assignment can be an efficient way to create multiple models. However, it +can expose an exploitable security vulnerability. The data in the fields +might contain updates that lead to unauthorized permissions or access. + +Eloquent provides the following traits to protect your data from mass +assignment vulnerabilities: + +- ``$fillable`` contains the fields that are writeable in a mass assignment +- ``$guarded`` contains the fields that are ignored in a mass assignment + +.. important:: + + We recommend using ``$fillable`` instead of ``$guarded`` to protect against + vulnerabilities. To learn more about this recommendation, see the + `Security Release: Laravel 6.18.35, 7.24.0 `__ + article on the Laravel site. + +In the following example, the model allows mass assignment of the fields +by using the ``$fillable`` attribute: + +.. literalinclude:: /includes/eloquent-models/PlanetMassAssignment.php + :language: php + :emphasize-lines: 9-14 + :dedent: + +The following code example shows mass assignment of the ``Planet`` model: + +.. code-block:: php + + $planets = [ + [ 'name' => 'Earth', gravity => 9.8, day_length => '24 hours' ], + [ 'name' => 'Mars', gravity => 3.7, day_length => '25 hours' ], + ]; + + Planet::create($planets); + +The models saved to the database contain only the ``name`` and ``gravity`` +fields since ``day_length`` is omitted from the ``$fillable`` attribute. + +To learn how to change the behavior when attempting to fill a field omitted +from the ``$fillable`` array, see `Mass Assignment Exceptions `__ +in the Laravel docs. + +.. _laravel-model-pruning: + +Specify Pruning Behavior +------------------------ + +Eloquent lets you specify criteria to periodically delete model data that you +no longer need. When you schedule or run the ``model:prune`` command, +Laravel calls the ``prunable()`` method on all models that import the +``Prunable`` and ``MassPrunable`` traits to match the models for deletion. + +To use this feature with models that use MongoDB as a database, add the +appropriate import to your model: + +- ``MongoDB\Laravel\Eloquent\Prunable`` optionally performs a cleanup + step before deleting a model that matches the criteria +- ``MongoDB\Laravel\Eloquent\MassPrunable`` deletes models that match the + criteria without fetching the model data + +.. note:: + + When enabling soft deletes on a mass prunable model, you must import the + following {+odm-short+} packages: + + - ``MongoDB\Laravel\Eloquent\SoftDeletes`` + - ``MongoDB\Laravel\Eloquent\MassPrunable`` + + +To learn more about the pruning feature, see `Pruning Models `__ +in the Laravel docs. + +Prunable Example +~~~~~~~~~~~~~~~~ + +The following prunable class includes a ``prunable()`` method that matches +models that the prune action deletes and a ``pruning()`` method that runs +before deleting a matching model: + +.. literalinclude:: /includes/eloquent-models/PlanetPrune.php + :language: php + :emphasize-lines: 6,10,12,18 + :dedent: + +Mass Prunable Example +~~~~~~~~~~~~~~~~~~~~~ + +The following mass prunable class includes a ``prunable()`` method that matches +models that the prune action deletes: + +.. literalinclude:: /includes/eloquent-models/PlanetMassPrune.php + :language: php + :emphasize-lines: 5,10,12 + :dedent: + diff --git a/docs/includes/eloquent-models/AuthenticatableUser.php b/docs/includes/eloquent-models/AuthenticatableUser.php new file mode 100644 index 000000000..694a595df --- /dev/null +++ b/docs/includes/eloquent-models/AuthenticatableUser.php @@ -0,0 +1,9 @@ + 'datetime', + ]; +} diff --git a/docs/includes/eloquent-models/PlanetMassAssignment.php b/docs/includes/eloquent-models/PlanetMassAssignment.php new file mode 100644 index 000000000..b2a91cab1 --- /dev/null +++ b/docs/includes/eloquent-models/PlanetMassAssignment.php @@ -0,0 +1,15 @@ +', 0.5); + } +} diff --git a/docs/includes/eloquent-models/PlanetPrimaryKey.php b/docs/includes/eloquent-models/PlanetPrimaryKey.php new file mode 100644 index 000000000..761593941 --- /dev/null +++ b/docs/includes/eloquent-models/PlanetPrimaryKey.php @@ -0,0 +1,10 @@ + + docs src tests @@ -36,5 +37,16 @@ + + + + docs/**/*.php + + + docs/**/*.php + + + docs/**/*.php + From 642bd222333af2214136c9f326b55857c471aae6 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Mon, 25 Mar 2024 17:07:57 -0400 Subject: [PATCH 217/446] DOCSP-37056 eloquent relationships (#2747) * DOCSP-37056: Eloquent relationships --- docs/eloquent-models.txt | 10 +- docs/eloquent-models/relationships.txt | 536 ++++++++++++++++++ .../relationships/RelationshipController.php | 194 +++++++ .../relationships/cross-db/Passenger.php | 18 + .../relationships/cross-db/SpaceShip.php | 21 + .../relationships/embeds/Cargo.php | 12 + .../relationships/embeds/SpaceShip.php | 18 + .../relationships/many-to-many/Planet.php | 18 + .../many-to-many/SpaceExplorer.php | 18 + .../relationships/one-to-many/Moon.php | 18 + .../relationships/one-to-many/Planet.php | 18 + .../relationships/one-to-one/Orbit.php | 18 + .../relationships/one-to-one/Planet.php | 18 + 13 files changed, 914 insertions(+), 3 deletions(-) create mode 100644 docs/eloquent-models/relationships.txt create mode 100644 docs/includes/eloquent-models/relationships/RelationshipController.php create mode 100644 docs/includes/eloquent-models/relationships/cross-db/Passenger.php create mode 100644 docs/includes/eloquent-models/relationships/cross-db/SpaceShip.php create mode 100644 docs/includes/eloquent-models/relationships/embeds/Cargo.php create mode 100644 docs/includes/eloquent-models/relationships/embeds/SpaceShip.php create mode 100644 docs/includes/eloquent-models/relationships/many-to-many/Planet.php create mode 100644 docs/includes/eloquent-models/relationships/many-to-many/SpaceExplorer.php create mode 100644 docs/includes/eloquent-models/relationships/one-to-many/Moon.php create mode 100644 docs/includes/eloquent-models/relationships/one-to-many/Planet.php create mode 100644 docs/includes/eloquent-models/relationships/one-to-one/Orbit.php create mode 100644 docs/includes/eloquent-models/relationships/one-to-one/Planet.php diff --git a/docs/eloquent-models.txt b/docs/eloquent-models.txt index 2bca40f2d..e7edadcfe 100644 --- a/docs/eloquent-models.txt +++ b/docs/eloquent-models.txt @@ -12,19 +12,23 @@ Eloquent Models :keywords: php framework, odm Eloquent models are part of the Laravel Eloquent object-relational -mapping (ORM) framework that enable you to work with a database by using -model classes. {+odm-short+} extends this framework to use similar -syntax to work with MongoDB as a database. +mapping (ORM) framework, which lets you to work with data in a relational +database by using model classes and Eloquent syntax. {+odm-short+} extends +this framework so that you can use Eloquent syntax to work with data in a +MongoDB database. This section contains guidance on how to use Eloquent models in {+odm-short+} to work with MongoDB in the following ways: - :ref:`laravel-eloquent-model-class` shows how to define models and customize their behavior +- :ref:`laravel-eloquent-model-relationships` shows how to define relationships + between models - :ref:`laravel-schema-builder` shows how to manage indexes on your MongoDB collections by using Laravel migrations .. toctree:: /eloquent-models/model-class/ + Relationships Schema Builder diff --git a/docs/eloquent-models/relationships.txt b/docs/eloquent-models/relationships.txt new file mode 100644 index 000000000..92625f076 --- /dev/null +++ b/docs/eloquent-models/relationships.txt @@ -0,0 +1,536 @@ +.. _laravel-eloquent-model-relationships: + +============================ +Eloquent Model Relationships +============================ + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :keywords: php framework, odm, code example, entity relationship, eloquent + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +When you use a relational database, the Eloquent ORM stores models as rows +in tables that correspond to the model classes. When you use MongoDB, the +{+odm-short+} stores models as documents in collections that correspond to the +model classes. + +To define a relationship, add a function to the model class that calls the +appropriate relationship method. This function allows you to access the related +model as a **dynamic property**. A dynamic property lets you access the +related model by using the same syntax as you use to access a property on the +model. + +The following sections describe the Laravel Eloquent and MongoDB-specific +relationships available in {+odm-short+} and show examples of how to define +and use them: + +- :ref:`One to one relationship `, + created by using the ``hasOne()`` method and its inverse, ``belongsTo()`` +- :ref:`One to many relationship `, + created by using the ``hasMany()`` and its inverse, ``belongsTo()`` +- :ref:`Many to many relationship `, + created by using the ``belongsToMany()`` method +- :ref:`Embedded document pattern `, a + MongoDB-specific relationship that can represent a one to one or one to many + relationship, created by using the ``embedsOne()`` or ``embedsMany()`` method +- :ref:`Cross-database relationships `, + required when you want to create relationships between MongoDB and SQL models + +.. _laravel-eloquent-relationship-one-to-one: + +One to One Relationship +----------------------- + +A one to one relationship between models consists of a model record related to +exactly one other type of model record. + +When you add a one to one relationship, Eloquent lets you access the model by +using a dynamic property and stores the model's document ID on the related +model. + +In {+odm-short+}, you can define a one to one relationship by using the +``hasOne()`` method or ``belongsTo()`` method. + +When you add the inverse of the relationship by using the ``belongsTo()`` +method, Eloquent lets you access the model by using a dynamic property, but +does not add any fields. + +To learn more about one to one relationships, see +`One to One `__ +in the Laravel documentation. + +One to One Example +~~~~~~~~~~~~~~~~~~ + +The following example class shows how to define a ``HasOne`` one to one +relationship between a ``Planet`` and ``Orbit`` model by using the +``hasOne()`` method: + +.. literalinclude:: /includes/eloquent-models/relationships/one-to-one/Planet.php + :language: php + :dedent: + +The following example class shows how to define the inverse ``BelongsTo`` +relationship between ``Orbit`` and ``Planet`` by using the ``belongsTo()`` +method: + +.. literalinclude:: /includes/eloquent-models/relationships/one-to-one/Orbit.php + :language: php + :dedent: + +The following sample code shows how to instantiate a model for each class +and add the relationship between them. Click the :guilabel:`VIEW OUTPUT` +button to see the data created by running the code: + +.. io-code-block:: + + .. input:: /includes/eloquent-models/relationships/RelationshipController.php + :language: php + :dedent: + :start-after: begin one-to-one save + :end-before: end one-to-one save + + .. output:: + :language: json + :visible: false + + // Document in the "planets" collection + { + _id: ObjectId('65de67fb2e59d63e6d07f8b8'), + name: 'Earth', + diameter_km: 12742, + // ... + } + + // Document in the "orbits" collection + { + _id: ObjectId('65de67fb2e59d63e6d07f8b9'), + period: 365.26, + direction: 'counterclockwise', + planet_id: '65de67fb2e59d63e6d07f8b8', + // ... + } + +The following sample code shows how to access the related models by using +the dynamic properties as defined in the example classes: + +.. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php + :language: php + :dedent: + :start-after: begin planet orbit dynamic property example + :end-before: end planet orbit dynamic property example + +.. _laravel-eloquent-relationship-one-to-many: + +One to Many Relationship +------------------------ + +A one to many relationship between models consists of a model that is +the parent and one or more related child model records. + +When you add a one to many relationship method, Eloquent lets you access the +model by using a dynamic property and stores the parent model's document ID +on each child model document. + +In {+odm-short+}, you can define a one to many relationship by adding the +``hasMany()`` method on the parent class and, optionally, the ``belongsTo()`` +method on the child class. + +When you add the inverse of the relationship by using the ``belongsTo()`` +method, Eloquent lets you access the parent model by using a dynamic property +without adding any fields. + +To learn more about one to many relationships, see +`One to Many `__ +in the Laravel documentation. + +One to Many Example +~~~~~~~~~~~~~~~~~~~ + +The following example class shows how to define a ``HasMany`` one to many +relationship between a ``Planet`` parent model and ``Moon`` child model by +using the ``hasMany()`` method: + +.. literalinclude:: /includes/eloquent-models/relationships/one-to-many/Planet.php + :language: php + :dedent: + +The following example class shows how to define the inverse ``BelongsTo`` +relationship between a ``Moon`` child model and the and the ``Planet`` parent +model by using the ``belongsTo()`` method: + +.. literalinclude:: /includes/eloquent-models/relationships/one-to-many/Moon.php + :language: php + :dedent: + +The following sample code shows how to instantiate a model for each class +and add the relationship between them. Click the :guilabel:`VIEW OUTPUT` +button to see the data created by running the code: + +.. io-code-block:: + + .. input:: /includes/eloquent-models/relationships/RelationshipController.php + :language: php + :dedent: + :start-after: begin one-to-many save + :end-before: end one-to-many save + + .. output:: + :language: json + :visible: false + + // Parent document in the "planets" collection + { + _id: ObjectId('65dfb0050e323bbef800f7b2'), + name: 'Jupiter', + diameter_km: 142984, + // ... + } + + // Child documents in the "moons" collection + [ + { + _id: ObjectId('65dfb0050e323bbef800f7b3'), + name: 'Ganymede', + orbital_period: 7.15, + planet_id: '65dfb0050e323bbef800f7b2', + // ... + }, + { + _id: ObjectId('65dfb0050e323bbef800f7b4'), + name: 'Europa', + orbital_period: 3.55, + planet_id: '65dfb0050e323bbef800f7b2', + // ... + } + ] + +The following sample code shows how to access the related models by using +the dynamic properties as defined in the example classes. + +.. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php + :language: php + :dedent: + :start-after: begin planet moons dynamic property example + :end-before: end planet moons dynamic property example + +.. _laravel-eloquent-relationship-many-to-many: + +Many to Many Relationship +------------------------- + +A many to many relationship consists of a relationship between two different +model types in which, for each type of model, an instance of the model can +be related to multiple instances of the other type. + +In {+odm-short+}, you can define a many to many relationship by adding the +``belongsToMany()`` method to both related classes. + +When you define a many to many relationship in a relational database, Laravel +creates a pivot table to track the relationships. When you use {+odm-short+}, +it omits the pivot table creation and adds the related document IDs to a +document field derived from the related model class name. + +.. tip:: + + Since {+odm-short+} uses a document field instead of a pivot table, omit + the pivot table parameter from the ``belongsToMany()`` constructor or set + it to ``null``. + +To learn more about many to many relationships in Laravel, see +`Many to Many `__ +in the Laravel documentation. + +The following section shows an example of how to create a many to many +relationship between model classes. + +Many to Many Example +~~~~~~~~~~~~~~~~~~~~ + +The following example class shows how to define a ``BelongsToMany`` many to +many relationship between a ``Planet`` and ``SpaceExplorer`` model by using +the ``belongsToMany()`` method: + +.. literalinclude:: /includes/eloquent-models/relationships/many-to-many/Planet.php + :language: php + :dedent: + +The following example class shows how to define the inverse ``BelongsToMany`` +many to many relationship between a ``SpaceExplorer`` and ``Planet`` model by +using the ``belongsToMany()`` method: + +.. literalinclude:: /includes/eloquent-models/relationships/many-to-many/SpaceExplorer.php + :language: php + :dedent: + +The following sample code shows how to instantiate a model for each class +and add the relationship between them. Click the :guilabel:`VIEW OUTPUT` +button to see the data created by running the code: + +.. io-code-block:: + + .. input:: /includes/eloquent-models/relationships/RelationshipController.php + :language: php + :dedent: + :start-after: begin many-to-many save + :end-before: end many-to-many save + + .. output:: + :language: json + :visible: false + + // Documents in the "planets" collection + [ + { + _id: ObjectId('65e1043a5265269a03078ad0'), + name: 'Earth', + // ... + space_explorer_ids: [ + '65e1043b5265269a03078ad3', + '65e1043b5265269a03078ad4', + '65e1043b5265269a03078ad5' + ], + }, + { + _id: ObjectId('65e1043a5265269a03078ad1'), + name: 'Mars', + // ... + space_explorer_ids: [ '65e1043b5265269a03078ad4', '65e1043b5265269a03078ad5' ] + }, + { + _id: ObjectId('65e1043b5265269a03078ad2'), + name: 'Jupiter', + // ... + space_explorer_ids: [ '65e1043b5265269a03078ad3', '65e1043b5265269a03078ad5' ] + } + ] + + // Documents in the "space_explorers" collection + [ + { + _id: ObjectId('65e1043b5265269a03078ad3'), + name: 'Tanya Kirbuk', + // ... + planet_ids: [ '65e1043a5265269a03078ad0', '65e1043b5265269a03078ad2' ] + }, + { + _id: ObjectId('65e1043b5265269a03078ad4'), + name: 'Mark Watney', + // ... + planet_ids: [ '65e1043a5265269a03078ad0', '65e1043a5265269a03078ad1' ] + }, + { + _id: ObjectId('65e1043b5265269a03078ad5'), + name: 'Jean-Luc Picard', + // ... + planet_ids: [ + '65e1043a5265269a03078ad0', + '65e1043a5265269a03078ad1', + '65e1043b5265269a03078ad2' + ] + } + ] + +The following sample code shows how to access the related models by using +the dynamic properties as defined in the example classes. + +.. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php + :language: php + :dedent: + :start-after: begin many-to-many dynamic property example + :end-before: end many-to-many dynamic property example + +.. _laravel-embedded-document-pattern: + +Embedded Document Pattern +------------------------- + +In MongoDB, the embedded document pattern adds the related model's data into +the parent model instead of keeping foreign key references. Use this pattern +to meet one or more of the following requirements: + +- Keeping associated data together in a single collection +- Performing atomic updates on multiple fields of the document and the associated + data +- Reducing the number of reads required to fetch the data + +In {+odm-short+}, you can define embedded documents by adding one of the +following methods: + +- ``embedsOne()`` to embed a single document +- ``embedsMany()`` to embed multiple documents + +.. note:: + + These methods return Eloquent collections, which differ from query builder + objects. + +To learn more about the MongoDB embedded document pattern, see the following +MongoDB server tutorials: + +- :manual:`Model One-to-One Relationships with Embedded Documents ` +- :manual:`Model One-to-Many Relationships with Embedded Documents ` + +The following section shows an example of how to use the embedded document +pattern. + +Embedded Document Example +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following example class shows how to define an ``EmbedsMany`` one to many +relationship between a ``SpaceShip`` and ``Cargo`` model by using the +``embedsMany()`` method: + +.. literalinclude:: /includes/eloquent-models/relationships/embeds/SpaceShip.php + :language: php + :dedent: + +The embedded model class omits the relationship definition as shown in the +following ``Cargo`` model class: + +.. literalinclude:: /includes/eloquent-models/relationships/embeds/Cargo.php + :language: php + :dedent: + +The following sample code shows how to create a ``SpaceShip`` model and +embed multiple ``Cargo`` models and the MongoDB document created by running the +code. Click the :guilabel:`VIEW OUTPUT` button to see the data created by +running the code: + +.. io-code-block:: + + .. input:: /includes/eloquent-models/relationships/RelationshipController.php + :language: php + :dedent: + :start-after: begin embedsMany save + :end-before: end embedsMany save + + .. output:: + :language: json + :visible: false + + // Document in the "space_ships" collection + { + _id: ObjectId('65e207b9aa167d29a3048853'), + name: 'The Millenium Falcon', + // ... + cargo: [ + { + name: 'spice', + weight: 50, + // ... + _id: ObjectId('65e207b9aa167d29a3048854') + }, + { + name: 'hyperdrive', + weight: 25, + // ... + _id: ObjectId('65e207b9aa167d29a3048855') + } + ] + } + +.. _laravel-relationship-cross-database: + +Cross-Database Relationships +---------------------------- + +A cross-database relationship in {+odm-short+} is a relationship between models +stored in a relational database and models stored in a MongoDB database. + +When you add a cross-database relationship, Eloquent lets you access the +related models by using a dynamic property. + +{+odm-short+} supports the following cross-database relationship methods: + +- ``hasOne()`` +- ``hasMany()`` +- ``belongsTo()`` + +To define a cross-database relationship, you must import the +``MongoDB\Laravel\Eloquent\HybridRelations`` package in the class stored in +the relational database. + +The following section shows an example of how to define a cross-database +relationship. + +Cross-Database Relationship Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following example class shows how to define a ``HasMany`` relationship +between a ``SpaceShip`` model stored in a relational database and a +``Passenger`` model stored in a MongoDB database: + +.. literalinclude:: /includes/eloquent-models/relationships/cross-db/SpaceShip.php + :language: php + :dedent: + +The following example class shows how to define the inverse ``BelongsTo`` +relationship between a ``Passenger`` model and the and the ``Spaceship`` +model by using the ``belongsTo()`` method: + +.. literalinclude:: /includes/eloquent-models/relationships/cross-db/Passenger.php + :language: php + :dedent: + +.. tip:: + + Make sure that the primary key defined in your relational database table + schema matches the one that your model uses. To learn more about Laravel + primary keys and schema definitions, see the following pages in the Laravel + documentation: + + - `Primary Keys `__ + - `Database: Migrations `__ + +The following sample code shows how to create a ``SpaceShip`` model in +a MySQL database and related ``Passenger`` models in a MongoDB database as well +as the data created by running the code. Click the :guilabel:`VIEW OUTPUT` button +to see the data created by running the code: + +.. io-code-block:: + + .. input:: /includes/eloquent-models/relationships/RelationshipController.php + :language: php + :dedent: + :start-after: begin cross-database save + :end-before: end cross-database save + + .. output:: + :language: none + :visible: false + + -- Row in the "space_ships" table + +------+----------+ + | id | name | + +------+----------+ + | 1234 | Nostromo | + +------+----------+ + + // Document in the "passengers" collection + [ + { + _id: ObjectId('65e625e74903fd63af0a5524'), + name: 'Ellen Ripley', + space_ship_id: 1234, + // ... + }, + { + _id: ObjectId('65e625e74903fd63af0a5525'), + name: 'Dwayne Hicks', + space_ship_id: 1234, + // ... + } + ] + diff --git a/docs/includes/eloquent-models/relationships/RelationshipController.php b/docs/includes/eloquent-models/relationships/RelationshipController.php new file mode 100644 index 000000000..fc10184d3 --- /dev/null +++ b/docs/includes/eloquent-models/relationships/RelationshipController.php @@ -0,0 +1,194 @@ +name = 'Earth'; + $planet->diameter_km = 12742; + $planet->save(); + + $orbit = new Orbit(); + $orbit->period = 365.26; + $orbit->direction = 'counterclockwise'; + + $planet->orbit()->save($orbit); + // end one-to-one save + } + + private function oneToMany() + { + // begin one-to-many save + $planet = new Planet(); + $planet->name = 'Jupiter'; + $planet->diameter_km = 142984; + $planet->save(); + + $moon1 = new Moon(); + $moon1->name = 'Ganymede'; + $moon1->orbital_period = 7.15; + + $moon2 = new Moon(); + $moon2->name = 'Europa'; + $moon2->orbital_period = 3.55; + + $planet->moons()->save($moon1); + $planet->moons()->save($moon2); + // end one-to-many save + } + + private function planetOrbitDynamic() + { + // begin planet orbit dynamic property example + $planet = Planet::first(); + $relatedOrbit = $planet->orbit; + + $orbit = Orbit::first(); + $relatedPlanet = $orbit->planet; + // end planet orbit dynamic property example + } + + private function planetMoonsDynamic() + { + // begin planet moons dynamic property example + $planet = Planet::first(); + $relatedMoons = $planet->moons; + + $moon = Moon::first(); + $relatedPlanet = $moon->planet; + // end planet moons dynamic property example + } + + private function manyToMany() + { + // begin many-to-many save + $planetEarth = new Planet(); + $planetEarth->name = 'Earth'; + $planetEarth->save(); + + $planetMars = new Planet(); + $planetMars->name = 'Mars'; + $planetMars->save(); + + $planetJupiter = new Planet(); + $planetJupiter->name = 'Jupiter'; + $planetJupiter->save(); + + $explorerTanya = new SpaceExplorer(); + $explorerTanya->name = 'Tanya Kirbuk'; + $explorerTanya->save(); + + $explorerMark = new SpaceExplorer(); + $explorerMark->name = 'Mark Watney'; + $explorerMark->save(); + + $explorerJeanluc = new SpaceExplorer(); + $explorerJeanluc->name = 'Jean-Luc Picard'; + $explorerJeanluc->save(); + + $explorerTanya->planetsVisited()->attach($planetEarth); + $explorerTanya->planetsVisited()->attach($planetJupiter); + $explorerMark->planetsVisited()->attach($planetEarth); + $explorerMark->planetsVisited()->attach($planetMars); + $explorerJeanluc->planetsVisited()->attach($planetEarth); + $explorerJeanluc->planetsVisited()->attach($planetMars); + $explorerJeanluc->planetsVisited()->attach($planetJupiter); + // end many-to-many save + } + + private function manyToManyDynamic() + { + // begin many-to-many dynamic property example + $planet = Planet::first(); + $explorers = $planet->visitors; + + $spaceExplorer = SpaceExplorer::first(); + $explored = $spaceExplorer->planetsVisited; + // end many-to-many dynamic property example + } + + private function embedsMany() + { + // begin embedsMany save + $spaceship = new SpaceShip(); + $spaceship->name = 'The Millenium Falcon'; + $spaceship->save(); + + $cargoSpice = new Cargo(); + $cargoSpice->name = 'spice'; + $cargoSpice->weight = 50; + + $cargoHyperdrive = new Cargo(); + $cargoHyperdrive->name = 'hyperdrive'; + $cargoHyperdrive->weight = 25; + + $spaceship->cargo()->attach($cargoSpice); + $spaceship->cargo()->attach($cargoHyperdrive); + // end embedsMany save + } + + private function crossDatabase() + { + // begin cross-database save + $spaceship = new SpaceShip(); + $spaceship->id = 1234; + $spaceship->name = 'Nostromo'; + $spaceship->save(); + + $passengerEllen = new Passenger(); + $passengerEllen->name = 'Ellen Ripley'; + + $passengerDwayne = new Passenger(); + $passengerDwayne->name = 'Dwayne Hicks'; + + $spaceship->passengers()->save($passengerEllen); + $spaceship->passengers()->save($passengerDwayne); + // end cross-database save + } + + /** + * Store a newly created resource in storage. + */ + public function store(Request $request) + { + } + + /** + * Display the specified resource. + */ + public function show() + { + return 'ok'; + } + + /** + * Show the form for editing the specified resource. + */ + public function edit(Planet $planet) + { + } + + /** + * Update the specified resource in storage. + */ + public function update(Request $request, Planet $planet) + { + } + + /** + * Remove the specified resource from storage. + */ + public function destroy(Planet $planet) + { + } +} diff --git a/docs/includes/eloquent-models/relationships/cross-db/Passenger.php b/docs/includes/eloquent-models/relationships/cross-db/Passenger.php new file mode 100644 index 000000000..4ceb7c45b --- /dev/null +++ b/docs/includes/eloquent-models/relationships/cross-db/Passenger.php @@ -0,0 +1,18 @@ +belongsTo(SpaceShip::class); + } +} diff --git a/docs/includes/eloquent-models/relationships/cross-db/SpaceShip.php b/docs/includes/eloquent-models/relationships/cross-db/SpaceShip.php new file mode 100644 index 000000000..1f3c5d120 --- /dev/null +++ b/docs/includes/eloquent-models/relationships/cross-db/SpaceShip.php @@ -0,0 +1,21 @@ +hasMany(Passenger::class); + } +} diff --git a/docs/includes/eloquent-models/relationships/embeds/Cargo.php b/docs/includes/eloquent-models/relationships/embeds/Cargo.php new file mode 100644 index 000000000..3ce144815 --- /dev/null +++ b/docs/includes/eloquent-models/relationships/embeds/Cargo.php @@ -0,0 +1,12 @@ +embedsMany(Cargo::class); + } +} diff --git a/docs/includes/eloquent-models/relationships/many-to-many/Planet.php b/docs/includes/eloquent-models/relationships/many-to-many/Planet.php new file mode 100644 index 000000000..4059d634d --- /dev/null +++ b/docs/includes/eloquent-models/relationships/many-to-many/Planet.php @@ -0,0 +1,18 @@ +belongsToMany(SpaceExplorer::class); + } +} diff --git a/docs/includes/eloquent-models/relationships/many-to-many/SpaceExplorer.php b/docs/includes/eloquent-models/relationships/many-to-many/SpaceExplorer.php new file mode 100644 index 000000000..aa9b2829d --- /dev/null +++ b/docs/includes/eloquent-models/relationships/many-to-many/SpaceExplorer.php @@ -0,0 +1,18 @@ +belongsToMany(Planet::class); + } +} diff --git a/docs/includes/eloquent-models/relationships/one-to-many/Moon.php b/docs/includes/eloquent-models/relationships/one-to-many/Moon.php new file mode 100644 index 000000000..ca5b7ae7c --- /dev/null +++ b/docs/includes/eloquent-models/relationships/one-to-many/Moon.php @@ -0,0 +1,18 @@ +belongsTo(Planet::class); + } +} diff --git a/docs/includes/eloquent-models/relationships/one-to-many/Planet.php b/docs/includes/eloquent-models/relationships/one-to-many/Planet.php new file mode 100644 index 000000000..679877ae5 --- /dev/null +++ b/docs/includes/eloquent-models/relationships/one-to-many/Planet.php @@ -0,0 +1,18 @@ +hasMany(Moon::class); + } +} diff --git a/docs/includes/eloquent-models/relationships/one-to-one/Orbit.php b/docs/includes/eloquent-models/relationships/one-to-one/Orbit.php new file mode 100644 index 000000000..4cb526309 --- /dev/null +++ b/docs/includes/eloquent-models/relationships/one-to-one/Orbit.php @@ -0,0 +1,18 @@ +belongsTo(Planet::class); + } +} diff --git a/docs/includes/eloquent-models/relationships/one-to-one/Planet.php b/docs/includes/eloquent-models/relationships/one-to-one/Planet.php new file mode 100644 index 000000000..e3137ab3a --- /dev/null +++ b/docs/includes/eloquent-models/relationships/one-to-one/Planet.php @@ -0,0 +1,18 @@ +hasOne(Orbit::class); + } +} From 90ebf120d32c7608989ef91df96d2145f747b27f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 26 Mar 2024 16:06:43 +0100 Subject: [PATCH 218/446] Add tests to doc examples (#2775) --- docs/eloquent-models/relationships.txt | 16 +- .../relationships/RelationshipController.php | 194 ------------- .../RelationshipsExamplesTest.php | 265 ++++++++++++++++++ .../relationships/cross-db/Passenger.php | 2 +- 4 files changed, 274 insertions(+), 203 deletions(-) delete mode 100644 docs/includes/eloquent-models/relationships/RelationshipController.php create mode 100644 docs/includes/eloquent-models/relationships/RelationshipsExamplesTest.php diff --git a/docs/eloquent-models/relationships.txt b/docs/eloquent-models/relationships.txt index 92625f076..2ae716132 100644 --- a/docs/eloquent-models/relationships.txt +++ b/docs/eloquent-models/relationships.txt @@ -95,7 +95,7 @@ button to see the data created by running the code: .. io-code-block:: - .. input:: /includes/eloquent-models/relationships/RelationshipController.php + .. input:: /includes/eloquent-models/relationships/RelationshipsExamplesTest.php :language: php :dedent: :start-after: begin one-to-one save @@ -125,7 +125,7 @@ button to see the data created by running the code: The following sample code shows how to access the related models by using the dynamic properties as defined in the example classes: -.. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php +.. literalinclude:: /includes/eloquent-models/relationships/RelationshipsExamplesTest.php :language: php :dedent: :start-after: begin planet orbit dynamic property example @@ -180,7 +180,7 @@ button to see the data created by running the code: .. io-code-block:: - .. input:: /includes/eloquent-models/relationships/RelationshipController.php + .. input:: /includes/eloquent-models/relationships/RelationshipsExamplesTest.php :language: php :dedent: :start-after: begin one-to-many save @@ -219,7 +219,7 @@ button to see the data created by running the code: The following sample code shows how to access the related models by using the dynamic properties as defined in the example classes. -.. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php +.. literalinclude:: /includes/eloquent-models/relationships/RelationshipsExamplesTest.php :language: php :dedent: :start-after: begin planet moons dynamic property example @@ -280,7 +280,7 @@ button to see the data created by running the code: .. io-code-block:: - .. input:: /includes/eloquent-models/relationships/RelationshipController.php + .. input:: /includes/eloquent-models/relationships/RelationshipsExamplesTest.php :language: php :dedent: :start-after: begin many-to-many save @@ -345,7 +345,7 @@ button to see the data created by running the code: The following sample code shows how to access the related models by using the dynamic properties as defined in the example classes. -.. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php +.. literalinclude:: /includes/eloquent-models/relationships/RelationshipsExamplesTest.php :language: php :dedent: :start-after: begin many-to-many dynamic property example @@ -410,7 +410,7 @@ running the code: .. io-code-block:: - .. input:: /includes/eloquent-models/relationships/RelationshipController.php + .. input:: /includes/eloquent-models/relationships/RelationshipsExamplesTest.php :language: php :dedent: :start-after: begin embedsMany save @@ -501,7 +501,7 @@ to see the data created by running the code: .. io-code-block:: - .. input:: /includes/eloquent-models/relationships/RelationshipController.php + .. input:: /includes/eloquent-models/relationships/RelationshipsExamplesTest.php :language: php :dedent: :start-after: begin cross-database save diff --git a/docs/includes/eloquent-models/relationships/RelationshipController.php b/docs/includes/eloquent-models/relationships/RelationshipController.php deleted file mode 100644 index fc10184d3..000000000 --- a/docs/includes/eloquent-models/relationships/RelationshipController.php +++ /dev/null @@ -1,194 +0,0 @@ -name = 'Earth'; - $planet->diameter_km = 12742; - $planet->save(); - - $orbit = new Orbit(); - $orbit->period = 365.26; - $orbit->direction = 'counterclockwise'; - - $planet->orbit()->save($orbit); - // end one-to-one save - } - - private function oneToMany() - { - // begin one-to-many save - $planet = new Planet(); - $planet->name = 'Jupiter'; - $planet->diameter_km = 142984; - $planet->save(); - - $moon1 = new Moon(); - $moon1->name = 'Ganymede'; - $moon1->orbital_period = 7.15; - - $moon2 = new Moon(); - $moon2->name = 'Europa'; - $moon2->orbital_period = 3.55; - - $planet->moons()->save($moon1); - $planet->moons()->save($moon2); - // end one-to-many save - } - - private function planetOrbitDynamic() - { - // begin planet orbit dynamic property example - $planet = Planet::first(); - $relatedOrbit = $planet->orbit; - - $orbit = Orbit::first(); - $relatedPlanet = $orbit->planet; - // end planet orbit dynamic property example - } - - private function planetMoonsDynamic() - { - // begin planet moons dynamic property example - $planet = Planet::first(); - $relatedMoons = $planet->moons; - - $moon = Moon::first(); - $relatedPlanet = $moon->planet; - // end planet moons dynamic property example - } - - private function manyToMany() - { - // begin many-to-many save - $planetEarth = new Planet(); - $planetEarth->name = 'Earth'; - $planetEarth->save(); - - $planetMars = new Planet(); - $planetMars->name = 'Mars'; - $planetMars->save(); - - $planetJupiter = new Planet(); - $planetJupiter->name = 'Jupiter'; - $planetJupiter->save(); - - $explorerTanya = new SpaceExplorer(); - $explorerTanya->name = 'Tanya Kirbuk'; - $explorerTanya->save(); - - $explorerMark = new SpaceExplorer(); - $explorerMark->name = 'Mark Watney'; - $explorerMark->save(); - - $explorerJeanluc = new SpaceExplorer(); - $explorerJeanluc->name = 'Jean-Luc Picard'; - $explorerJeanluc->save(); - - $explorerTanya->planetsVisited()->attach($planetEarth); - $explorerTanya->planetsVisited()->attach($planetJupiter); - $explorerMark->planetsVisited()->attach($planetEarth); - $explorerMark->planetsVisited()->attach($planetMars); - $explorerJeanluc->planetsVisited()->attach($planetEarth); - $explorerJeanluc->planetsVisited()->attach($planetMars); - $explorerJeanluc->planetsVisited()->attach($planetJupiter); - // end many-to-many save - } - - private function manyToManyDynamic() - { - // begin many-to-many dynamic property example - $planet = Planet::first(); - $explorers = $planet->visitors; - - $spaceExplorer = SpaceExplorer::first(); - $explored = $spaceExplorer->planetsVisited; - // end many-to-many dynamic property example - } - - private function embedsMany() - { - // begin embedsMany save - $spaceship = new SpaceShip(); - $spaceship->name = 'The Millenium Falcon'; - $spaceship->save(); - - $cargoSpice = new Cargo(); - $cargoSpice->name = 'spice'; - $cargoSpice->weight = 50; - - $cargoHyperdrive = new Cargo(); - $cargoHyperdrive->name = 'hyperdrive'; - $cargoHyperdrive->weight = 25; - - $spaceship->cargo()->attach($cargoSpice); - $spaceship->cargo()->attach($cargoHyperdrive); - // end embedsMany save - } - - private function crossDatabase() - { - // begin cross-database save - $spaceship = new SpaceShip(); - $spaceship->id = 1234; - $spaceship->name = 'Nostromo'; - $spaceship->save(); - - $passengerEllen = new Passenger(); - $passengerEllen->name = 'Ellen Ripley'; - - $passengerDwayne = new Passenger(); - $passengerDwayne->name = 'Dwayne Hicks'; - - $spaceship->passengers()->save($passengerEllen); - $spaceship->passengers()->save($passengerDwayne); - // end cross-database save - } - - /** - * Store a newly created resource in storage. - */ - public function store(Request $request) - { - } - - /** - * Display the specified resource. - */ - public function show() - { - return 'ok'; - } - - /** - * Show the form for editing the specified resource. - */ - public function edit(Planet $planet) - { - } - - /** - * Update the specified resource in storage. - */ - public function update(Request $request, Planet $planet) - { - } - - /** - * Remove the specified resource from storage. - */ - public function destroy(Planet $planet) - { - } -} diff --git a/docs/includes/eloquent-models/relationships/RelationshipsExamplesTest.php b/docs/includes/eloquent-models/relationships/RelationshipsExamplesTest.php new file mode 100644 index 000000000..51876416a --- /dev/null +++ b/docs/includes/eloquent-models/relationships/RelationshipsExamplesTest.php @@ -0,0 +1,265 @@ +name = 'Earth'; + $planet->diameter_km = 12742; + $planet->save(); + + $orbit = new Orbit(); + $orbit->period = 365.26; + $orbit->direction = 'counterclockwise'; + + $planet->orbit()->save($orbit); + // end one-to-one save + + $planet = Planet::first(); + $this->assertInstanceOf(Planet::class, $planet); + $this->assertInstanceOf(Orbit::class, $planet->orbit); + + // begin planet orbit dynamic property example + $planet = Planet::first(); + $relatedOrbit = $planet->orbit; + + $orbit = Orbit::first(); + $relatedPlanet = $orbit->planet; + // end planet orbit dynamic property example + + $this->assertInstanceOf(Orbit::class, $relatedOrbit); + $this->assertInstanceOf(Planet::class, $relatedPlanet); + } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function testOneToMany(): void + { + require_once __DIR__ . '/one-to-many/Planet.php'; + require_once __DIR__ . '/one-to-many/Moon.php'; + + // Clear the database + Planet::truncate(); + Moon::truncate(); + + // begin one-to-many save + $planet = new Planet(); + $planet->name = 'Jupiter'; + $planet->diameter_km = 142984; + $planet->save(); + + $moon1 = new Moon(); + $moon1->name = 'Ganymede'; + $moon1->orbital_period = 7.15; + + $moon2 = new Moon(); + $moon2->name = 'Europa'; + $moon2->orbital_period = 3.55; + + $planet->moons()->save($moon1); + $planet->moons()->save($moon2); + // end one-to-many save + + $planet = Planet::first(); + $this->assertInstanceOf(Planet::class, $planet); + $this->assertCount(2, $planet->moons); + $this->assertInstanceOf(Moon::class, $planet->moons->first()); + + // begin planet moons dynamic property example + $planet = Planet::first(); + $relatedMoons = $planet->moons; + + $moon = Moon::first(); + $relatedPlanet = $moon->planet; + // end planet moons dynamic property example + + $this->assertInstanceOf(Moon::class, $relatedMoons->first()); + $this->assertInstanceOf(Planet::class, $relatedPlanet); + } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function testManyToMany(): void + { + require_once __DIR__ . '/many-to-many/Planet.php'; + require_once __DIR__ . '/many-to-many/SpaceExplorer.php'; + + // Clear the database + Planet::truncate(); + SpaceExplorer::truncate(); + + // begin many-to-many save + $planetEarth = new Planet(); + $planetEarth->name = 'Earth'; + $planetEarth->save(); + + $planetMars = new Planet(); + $planetMars->name = 'Mars'; + $planetMars->save(); + + $planetJupiter = new Planet(); + $planetJupiter->name = 'Jupiter'; + $planetJupiter->save(); + + $explorerTanya = new SpaceExplorer(); + $explorerTanya->name = 'Tanya Kirbuk'; + $explorerTanya->save(); + + $explorerMark = new SpaceExplorer(); + $explorerMark->name = 'Mark Watney'; + $explorerMark->save(); + + $explorerJeanluc = new SpaceExplorer(); + $explorerJeanluc->name = 'Jean-Luc Picard'; + $explorerJeanluc->save(); + + $explorerTanya->planetsVisited()->attach($planetEarth); + $explorerTanya->planetsVisited()->attach($planetJupiter); + $explorerMark->planetsVisited()->attach($planetEarth); + $explorerMark->planetsVisited()->attach($planetMars); + $explorerJeanluc->planetsVisited()->attach($planetEarth); + $explorerJeanluc->planetsVisited()->attach($planetMars); + $explorerJeanluc->planetsVisited()->attach($planetJupiter); + // end many-to-many save + + $planet = Planet::where('name', 'Earth')->first(); + $this->assertInstanceOf(Planet::class, $planet); + $this->assertCount(3, $planet->visitors); + $this->assertInstanceOf(SpaceExplorer::class, $planet->visitors->first()); + + $explorer = SpaceExplorer::where('name', 'Jean-Luc Picard')->first(); + $this->assertInstanceOf(SpaceExplorer::class, $explorer); + $this->assertCount(3, $explorer->planetsVisited); + $this->assertInstanceOf(Planet::class, $explorer->planetsVisited->first()); + + // begin many-to-many dynamic property example + $planet = Planet::first(); + $explorers = $planet->visitors; + + $spaceExplorer = SpaceExplorer::first(); + $explored = $spaceExplorer->planetsVisited; + // end many-to-many dynamic property example + + $this->assertCount(3, $explorers); + $this->assertInstanceOf(SpaceExplorer::class, $explorers->first()); + $this->assertCount(2, $explored); + $this->assertInstanceOf(Planet::class, $explored->first()); + } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function testEmbedsMany(): void + { + require_once __DIR__ . '/embeds/Cargo.php'; + require_once __DIR__ . '/embeds/SpaceShip.php'; + + // Clear the database + SpaceShip::truncate(); + + // begin embedsMany save + $spaceship = new SpaceShip(); + $spaceship->name = 'The Millenium Falcon'; + $spaceship->save(); + + $cargoSpice = new Cargo(); + $cargoSpice->name = 'spice'; + $cargoSpice->weight = 50; + + $cargoHyperdrive = new Cargo(); + $cargoHyperdrive->name = 'hyperdrive'; + $cargoHyperdrive->weight = 25; + + $spaceship->cargo()->attach($cargoSpice); + $spaceship->cargo()->attach($cargoHyperdrive); + // end embedsMany save + + $spaceship = SpaceShip::first(); + $this->assertInstanceOf(SpaceShip::class, $spaceship); + $this->assertCount(2, $spaceship->cargo); + $this->assertInstanceOf(Cargo::class, $spaceship->cargo->first()); + } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function testCrossDatabase(): void + { + require_once __DIR__ . '/cross-db/Passenger.php'; + require_once __DIR__ . '/cross-db/SpaceShip.php'; + + $schema = Schema::connection('sqlite'); + assert($schema instanceof SQLiteBuilder); + + $schema->dropIfExists('space_ships'); + $schema->create('space_ships', function (Blueprint $table) { + $table->id(); + $table->string('name'); + $table->timestamps(); + }); + + // Clear the database + Passenger::truncate(); + + // begin cross-database save + $spaceship = new SpaceShip(); + $spaceship->id = 1234; + $spaceship->name = 'Nostromo'; + $spaceship->save(); + + $passengerEllen = new Passenger(); + $passengerEllen->name = 'Ellen Ripley'; + + $passengerDwayne = new Passenger(); + $passengerDwayne->name = 'Dwayne Hicks'; + + $spaceship->passengers()->save($passengerEllen); + $spaceship->passengers()->save($passengerDwayne); + // end cross-database save + + $spaceship = SpaceShip::first(); + $this->assertInstanceOf(SpaceShip::class, $spaceship); + $this->assertCount(2, $spaceship->passengers); + $this->assertInstanceOf(Passenger::class, $spaceship->passengers->first()); + + $passenger = Passenger::first(); + $this->assertInstanceOf(Passenger::class, $passenger); + } +} diff --git a/docs/includes/eloquent-models/relationships/cross-db/Passenger.php b/docs/includes/eloquent-models/relationships/cross-db/Passenger.php index 4ceb7c45b..3379c866b 100644 --- a/docs/includes/eloquent-models/relationships/cross-db/Passenger.php +++ b/docs/includes/eloquent-models/relationships/cross-db/Passenger.php @@ -4,8 +4,8 @@ namespace App\Models; +use Illuminate\Database\Eloquent\Relations\BelongsTo; use MongoDB\Laravel\Eloquent\Model; -use MongoDB\Laravel\Relations\BelongsTo; class Passenger extends Model { From 860dfaf9fd9d39693367aba5fa97e5f00067762a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 2 Apr 2024 15:30:17 +0200 Subject: [PATCH 219/446] PHPORM-160 Run doc tests (#2795) --- phpunit.xml.dist | 3 +++ 1 file changed, 3 insertions(+) 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/ + From 9a616f9b30efe8645d0bf72f5597ad75979a6a5a Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Wed, 3 Apr 2024 10:24:41 -0400 Subject: [PATCH 220/446] DOCSP-37618: Usage Examples landing page (#2767) * DOCSP-37618: Usage Examples landing page * fix refs * update TOC * format fix * CC feedback * remove info * add back * typo * CC feedback 2 * add section toc * feedback, removing tabs * workflow file * edits * fix * more CC feedback * run -> use * changes to running instructions * turn back into steps * small fixes * more reworking * reword * reworking * feedback * newline * remove file * edits * fix --- docs/index.txt | 9 ++++- docs/quick-start/view-data.txt | 2 +- docs/usage-examples.txt | 68 ++++++++++++++++++++++++++++++++++ 3 files changed, 77 insertions(+), 2 deletions(-) create mode 100644 docs/usage-examples.txt diff --git a/docs/index.txt b/docs/index.txt index febdb9371..ec6825419 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 @@ -47,10 +48,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/quick-start/view-data.txt b/docs/quick-start/view-data.txt index 35d53368c..1be17bb3f 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..bf14bba4a --- /dev/null +++ b/docs/usage-examples.txt @@ -0,0 +1,68 @@ +.. _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. \ No newline at end of file From 8eb9271201795931bc54e4e06e04a31f581485cb Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Wed, 3 Apr 2024 10:51:03 -0400 Subject: [PATCH 221/446] DOCSP-35974: Update one usage example (#2781) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * DOCSP-35974: Update one usage example * fixes * other usage ex changes * reworking the example * add tip, spacing * restructuring * reword tip * fixes * edits * reword * add more running info * small change * edits * source constant * test file * move test file * single quotes * print syntax * print statement again * JT feedback * apply phpcbf formatting * code * apply phpcbf formatting * JT feedback * Fix UpdateOneTest example * add to TOC --------- Co-authored-by: norareidy Co-authored-by: Jérôme Tamarelle --- docs/includes/usage-examples/Movie.php | 12 ++++ .../includes/usage-examples/UpdateOneTest.php | 48 +++++++++++++ docs/usage-examples.txt | 8 ++- docs/usage-examples/updateOne.txt | 67 +++++++++++++++++++ 4 files changed, 134 insertions(+), 1 deletion(-) create mode 100644 docs/includes/usage-examples/Movie.php create mode 100644 docs/includes/usage-examples/UpdateOneTest.php create mode 100644 docs/usage-examples/updateOne.txt 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/usage-examples.txt b/docs/usage-examples.txt index bf14bba4a..08dda77ea 100644 --- a/docs/usage-examples.txt +++ b/docs/usage-examples.txt @@ -65,4 +65,10 @@ a result. To run the operation, you can copy the sample code to a controller end 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. \ No newline at end of file +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. + From e338fc20674453c00dc720d1659a66abf4eb083d Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 3 Apr 2024 11:54:36 -0400 Subject: [PATCH 222/446] DOCSP-38076 quickstart updates for 11 (#2799) * DOCSP-38076: quick start changes for Laravel 11 --- docs/quick-start.txt | 2 +- docs/quick-start/configure-mongodb.txt | 11 ++++++++--- docs/quick-start/view-data.txt | 14 +++++++------- docs/quick-start/write-data.txt | 17 ++++++++++++++--- 4 files changed, 30 insertions(+), 14 deletions(-) diff --git a/docs/quick-start.txt b/docs/quick-start.txt index d672f3e31..fb8ad6fe2 100644 --- a/docs/quick-start.txt +++ b/docs/quick-start.txt @@ -53,7 +53,7 @@ that connects to a MongoDB deployment. .. tip:: You can download the complete web application project by cloning the - `laravel-quickstart `__ + `laravel-quickstart `__ GitHub repository. .. button:: Next: Download and Install diff --git a/docs/quick-start/configure-mongodb.txt b/docs/quick-start/configure-mongodb.txt index 66cd2380c..2f6dd0e36 100644 --- a/docs/quick-start/configure-mongodb.txt +++ b/docs/quick-start/configure-mongodb.txt @@ -41,15 +41,20 @@ Configure Your MongoDB Connection // ... - .. step:: Add the Laravel MongoDB provider + .. step:: Add the MongoDB provider - Open the ``app.php`` file in the ``config`` directory and - add the following entry into the ``providers`` array: + Open the ``providers.php`` file in the ``bootstrap`` directory and add + the following entry into the array: .. code-block:: MongoDB\Laravel\MongoDBServiceProvider::class, + .. tip:: + + To learn how to register the provider in Laravel 10.x, see + `Registering Providers `__. + After completing these steps, your Laravel web application is ready to connect to MongoDB. diff --git a/docs/quick-start/view-data.txt b/docs/quick-start/view-data.txt index 35d53368c..52c0e5dc4 100644 --- a/docs/quick-start/view-data.txt +++ b/docs/quick-start/view-data.txt @@ -67,13 +67,13 @@ View MongoDB Data public function show() { - return view('browse_movies', [ - 'movies' => Movie::where('runtime', '<', 60) - ->where('imdb.rating', '>', 8.5) - ->orderBy('imdb.rating', 'desc') - ->take(10) - ->get() - ]); + return view('browse_movies', [ + 'movies' => Movie::where('runtime', '<', 60) + ->where('imdb.rating', '>', 8.5) + ->orderBy('imdb.rating', 'desc') + ->take(10) + ->get() + ]); } .. step:: Add a web route diff --git a/docs/quick-start/write-data.txt b/docs/quick-start/write-data.txt index 31568286a..ddf2a98d9 100644 --- a/docs/quick-start/write-data.txt +++ b/docs/quick-start/write-data.txt @@ -32,6 +32,17 @@ Write Data to MongoDB .. step:: Add an API route that calls the controller function + Generate an API route file by running the following command: + + .. code-block:: bash + + php artisan install:api + + .. tip:: + + Skip this step if you are using Laravel 10.x because the file that + the command generates already exists. + Import the controller and add an API route that calls the ``store()`` method in the ``routes/api.php`` file: @@ -42,7 +53,7 @@ Write Data to MongoDB // ... Route::resource('movies', MovieController::class)->only([ - 'store' + 'store' ]); @@ -57,8 +68,8 @@ Write Data to MongoDB class Movie extends Model { - protected $connection = 'mongodb'; - protected $fillable = ['title', 'year', 'runtime', 'imdb', 'plot']; + protected $connection = 'mongodb'; + protected $fillable = ['title', 'year', 'runtime', 'imdb', 'plot']; } .. step:: Post a request to the API From d4e5e2b445d7fd991c43492c375340e3c821771b Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Wed, 3 Apr 2024 12:31:45 -0400 Subject: [PATCH 223/446] DOCSP-36631: laravel feature compatibility (#2802) * DOCSP-36631: laravel feature compatibility * NR PR fixes 1 --- docs/feature-compatibility.txt | 307 +++++++++++++++++++++++++++++++++ docs/index.txt | 1 + docs/query-builder.txt | 2 + 3 files changed, 310 insertions(+) create mode 100644 docs/feature-compatibility.txt 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/index.txt b/docs/index.txt index ec6825419..af09ee013 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -23,6 +23,7 @@ Laravel MongoDB /queues /transactions /issues-and-help + /feature-compatibility /compatibility /upgrade 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** From e77a4743b1d212f3f103d920b4a55f8ffdc6d466 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Thu, 4 Apr 2024 10:17:51 -0400 Subject: [PATCH 224/446] DOCSP-35970: Find one usage example (#2768) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a usage example page showing how to retrieve one document --------- Co-authored-by: norareidy Co-authored-by: Jérôme Tamarelle --- docs/includes/usage-examples/FindOneTest.php | 36 ++++++++++ docs/usage-examples.txt | 3 +- docs/usage-examples/findOne.txt | 74 ++++++++++++++++++++ 3 files changed, 112 insertions(+), 1 deletion(-) create mode 100644 docs/includes/usage-examples/FindOneTest.php create mode 100644 docs/usage-examples/findOne.txt diff --git a/docs/includes/usage-examples/FindOneTest.php b/docs/includes/usage-examples/FindOneTest.php new file mode 100644 index 000000000..98452a6a6 --- /dev/null +++ b/docs/includes/usage-examples/FindOneTest.php @@ -0,0 +1,36 @@ + 'The Shawshank Redemption', 'directors' => ['Frank Darabont', 'Rob Reiner']], + ]); + + // begin-find-one + $movie = Movie::where('directors', 'Rob Reiner') + ->orderBy('_id') + ->first(); + + echo $movie->toJson(); + // end-find-one + + $this->assertInstanceOf(Movie::class, $movie); + $this->expectOutputRegex('/^{"_id":"[a-z0-9]{24}","title":"The Shawshank Redemption","directors":\["Frank Darabont","Rob Reiner"\]}$/'); + } +} diff --git a/docs/usage-examples.txt b/docs/usage-examples.txt index 08dda77ea..2bcd9ac58 100644 --- a/docs/usage-examples.txt +++ b/docs/usage-examples.txt @@ -71,4 +71,5 @@ calls the controller function and returns the result to a web interface. :titlesonly: :maxdepth: 1 - /usage-examples/updateOne \ No newline at end of file + /usage-examples/findOne + /usage-examples/updateOne diff --git a/docs/usage-examples/findOne.txt b/docs/usage-examples/findOne.txt new file mode 100644 index 000000000..39fde3d56 --- /dev/null +++ b/docs/usage-examples/findOne.txt @@ -0,0 +1,74 @@ +.. _laravel-find-one-usage: + +=============== +Find a Document +=============== + +You can retrieve a single document from a collection by calling the ``where()`` and +``first()`` methods on an Eloquent model or a query builder. + +Pass a query filter to the ``where()`` method and then call the ``first()`` method to +return one document in the collection that matches the filter. If multiple documents match +the query filter, ``first()`` returns the first matching document according to the documents' +:term:`natural order` in the database or according to the sort order that you can specify +by using the ``orderBy()`` method. + +Example +------- + +This usage example performs the following actions: + +- Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the + ``sample_mflix`` database. +- Retrieves 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 ``directors`` field includes ``'Rob Reiner'``. +- ``orderBy()``: sorts matched documents by their ascending ``_id`` values. +- ``first()``: retrieves only the first matching document. + +.. io-code-block:: + + .. input:: ../includes/usage-examples/FindOneTest.php + :start-after: begin-find-one + :end-before: end-find-one + :language: php + :dedent: + + .. output:: + :language: console + :visible: false + + // Result is truncated + + { + "_id": "573a1398f29313caabce94a3", + "plot": "Spinal Tap, one of England's loudest bands, is chronicled by film director + Marty DeBergi on what proves to be a fateful tour.", + "genres": [ + "Comedy", + "Music" + ], + "runtime": 82, + "metacritic": 85, + "rated": "R", + "cast": [ + "Rob Reiner", + "Kimberly Stringer", + "Chazz Dominguez", + "Shari Hall" + ], + "poster": "https://m.media-amazon.com/images/M/MV5BMTQ2MTIzMzg5Nl5BMl5BanBnXkFtZTgwOTc5NDI1MDE@._V1_SY1000_SX677_AL_.jpg", + "title": "This Is Spinal Tap", + ... + } + + +For instructions on editing your Laravel application to run the usage example, see the +:ref:`Usage Example landing page `. + +.. tip:: + + To learn more about retrieving documents with {+odm-short+}, see the + :ref:`laravel-fundamentals-retrieve` guide \ No newline at end of file From e95992502233988e6ffa44e4e9add415cc421ef2 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Thu, 4 Apr 2024 10:41:19 -0400 Subject: [PATCH 225/446] 040124: Code example syntax fix for Eloquent Model Class page (#2809) * 040124: Code example syntax fix --- docs/eloquent-models/model-class.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/eloquent-models/model-class.txt b/docs/eloquent-models/model-class.txt index 85b7b994b..5542b35ea 100644 --- a/docs/eloquent-models/model-class.txt +++ b/docs/eloquent-models/model-class.txt @@ -249,8 +249,8 @@ The following code example shows mass assignment of the ``Planet`` model: .. code-block:: php $planets = [ - [ 'name' => 'Earth', gravity => 9.8, day_length => '24 hours' ], - [ 'name' => 'Mars', gravity => 3.7, day_length => '25 hours' ], + [ 'name' => 'Earth', 'gravitational_force' => 9.8, 'day_length' => '24 hours' ], + [ 'name' => 'Mars', 'gravitational_force' => 3.7, 'day_length' => '25 hours' ], ]; Planet::create($planets); From 2074da3e2bab6c488da1aef77c61c1081208388b Mon Sep 17 00:00:00 2001 From: stayweek <165480133+stayweek@users.noreply.github.com> Date: Fri, 5 Apr 2024 17:40:13 +0800 Subject: [PATCH 226/446] chore: fix typos in comment (#2806) --- docs/retrieve.txt | 2 +- tests/RelationsTest.php | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/retrieve.txt b/docs/retrieve.txt index b607d3d4f..1665291e8 100644 --- a/docs/retrieve.txt +++ b/docs/retrieve.txt @@ -393,7 +393,7 @@ documents. Runtime: 95 IMDB Rating: 4 IMDB Votes: 9296 - Plot: A sci-fi update of the famous 6th Century poem. In a beseiged land, Beowulf must + Plot: A sci-fi update of the famous 6th Century poem. In a besieged land, Beowulf must battle against the hideous creature Grendel and his vengeance seeking mother. .. _laravel-retrieve-one: diff --git a/tests/RelationsTest.php b/tests/RelationsTest.php index 8c0a7a4a7..368406feb 100644 --- a/tests/RelationsTest.php +++ b/tests/RelationsTest.php @@ -279,7 +279,7 @@ public function testBelongsToManyAttachesExistingModels(): void $user = User::with('clients')->find($user->_id); - // Assert non attached ID's are detached succesfully + // Assert non attached ID's are detached successfully $this->assertNotContains('1234523', $user->client_ids); // Assert there are two client objects in the relationship From 2b0b5e6e693ae712525f24dafefd3c93d7fbbd40 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Mon, 8 Apr 2024 09:45:49 -0400 Subject: [PATCH 227/446] DOCSP-35966 query builder (#2790) * DOCSP-35966: Query builder docs standardization --- docs/eloquent-models/schema-builder.txt | 2 + .../query-builder/QueryBuilderTest.php | 579 +++++++ .../query-builder/sample_mflix.movies.json | 196 +++ .../query-builder/sample_mflix.theaters.json | 39 + docs/query-builder.txt | 1400 ++++++++++++----- docs/retrieve.txt | 190 +-- 6 files changed, 1810 insertions(+), 596 deletions(-) create mode 100644 docs/includes/query-builder/QueryBuilderTest.php create mode 100644 docs/includes/query-builder/sample_mflix.movies.json create mode 100644 docs/includes/query-builder/sample_mflix.theaters.json diff --git a/docs/eloquent-models/schema-builder.txt b/docs/eloquent-models/schema-builder.txt index 9fd845b55..39c6a9887 100644 --- a/docs/eloquent-models/schema-builder.txt +++ b/docs/eloquent-models/schema-builder.txt @@ -324,6 +324,8 @@ field: To learn more about these indexes, see :manual:`Index Properties ` in the {+server-docs-name+}. +.. _laravel-eloquent-geospatial-index: + Create a Geospatial Index ~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php new file mode 100644 index 000000000..40705102d --- /dev/null +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -0,0 +1,579 @@ +collection('movies') + ->insert(json_decode(file_get_contents(__DIR__ . '/sample_mflix.movies.json'), true)); + } + + protected function importTheaters(): void + { + $db = DB::connection('mongodb'); + + $db->collection('theaters') + ->insert(json_decode(file_get_contents(__DIR__ . '/sample_mflix.theaters.json'), true)); + + $db->collection('theaters') + ->raw() + ->createIndex(['location.geo' => '2dsphere']); + } + + protected function tearDown(): void + { + $db = DB::connection('mongodb'); + $db->collection('movies')->raw()->drop(); + $db->collection('theaters')->raw()->drop(); + + parent::tearDown(); + } + + public function testWhere(): void + { + // begin query where + $result = DB::connection('mongodb') + ->collection('movies') + ->where('imdb.rating', 9.3) + ->get(); + // end query where + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + + public function testOrWhere(): void + { + // begin query orWhere + $result = DB::connection('mongodb') + ->collection('movies') + ->where('year', 1955) + ->orWhere('title', 'Back to the Future') + ->get(); + // end query orWhere + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + + public function testAndWhere(): void + { + // begin query andWhere + $result = DB::connection('mongodb') + ->collection('movies') + ->where('imdb.rating', '>', 8.5) + ->where('year', '<', 1940) + ->get(); + // end query andWhere + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + + public function testWhereNot(): void + { + // begin query whereNot + $result = DB::connection('mongodb') + ->collection('movies') + ->whereNot('imdb.rating', '>', 2) + ->get(); + // end query whereNot + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + + public function testNestedLogical(): void + { + // begin query nestedLogical + $result = DB::connection('mongodb') + ->collection('movies') + ->where('imdb.rating', '>', 8.5) + ->where(function (Builder $query) { + return $query + ->where('year', 1986) + ->orWhere('year', 1996); + })->get(); + // end query nestedLogical + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + + public function testWhereBetween(): void + { + // begin query whereBetween + $result = DB::connection('mongodb') + ->collection('movies') + ->whereBetween('imdb.rating', [9, 9.5]) + ->get(); + // end query whereBetween + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + + public function testWhereNull(): void + { + // begin query whereNull + $result = DB::connection('mongodb') + ->collection('movies') + ->whereNull('runtime') + ->get(); + // end query whereNull + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + + public function testWhereIn(): void + { + // begin query whereIn + $result = DB::collection('movies') + ->whereIn('title', ['Toy Story', 'Shrek 2', 'Johnny English']) + ->get(); + // end query whereIn + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + + public function testWhereDate(): void + { + // begin query whereDate + $result = DB::connection('mongodb') + ->collection('movies') + ->whereDate('released', '2010-1-15') + ->get(); + // end query whereDate + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + + public function testLike(): void + { + // begin query like + $result = DB::collection('movies') + ->where('title', 'like', '%spider_man%') + ->get(); + // end query like + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + + public function testDistinct(): void + { + // begin query distinct + $result = DB::collection('movies') + ->distinct('year')->get(); + // end query distinct + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + + public function testGroupBy(): void + { + // begin query groupBy + $result = DB::collection('movies') + ->where('rated', 'G') + ->groupBy('runtime') + ->orderBy('runtime', 'asc') + ->get(['title']); + // end query groupBy + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + + public function testAggCount(): void + { + // begin aggregation count + $result = DB::collection('movies') + ->count(); + // end aggregation count + + $this->assertIsInt($result); + } + + public function testAggMax(): void + { + // begin aggregation max + $result = DB::collection('movies') + ->max('runtime'); + // end aggregation max + + $this->assertIsInt($result); + } + + public function testAggMin(): void + { + // begin aggregation min + $result = DB::collection('movies') + ->min('year'); + // end aggregation min + + $this->assertIsInt($result); + } + + public function testAggAvg(): void + { + // begin aggregation avg + $result = DB::collection('movies') + ->avg('imdb.rating'); + //->avg('year'); + // end aggregation avg + + $this->assertIsFloat($result); + } + + public function testAggSum(): void + { + // begin aggregation sum + $result = DB::collection('movies') + ->sum('imdb.votes'); + // end aggregation sum + + $this->assertIsInt($result); + } + + public function testAggWithFilter(): void + { + // begin aggregation with filter + $result = DB::collection('movies') + ->where('year', '>', 2000) + ->avg('imdb.rating'); + // end aggregation with filter + + $this->assertIsFloat($result); + } + + public function testOrderBy(): void + { + // begin query orderBy + $result = DB::collection('movies') + ->where('title', 'like', 'back to the future%') + ->orderBy('imdb.rating', 'desc') + ->get(); + // end query orderBy + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + + public function testSkip(): void + { + // begin query skip + $result = DB::collection('movies') + ->where('title', 'like', 'star trek%') + ->orderBy('year', 'asc') + ->skip(4) + ->get(); + // end query skip + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + + public function testProjection(): void + { + // begin query projection + $result = DB::collection('movies') + ->where('imdb.rating', '>', 8.5) + ->project([ + 'title' => 1, + 'cast' => ['$slice' => [1, 3]], + ]) + ->get(); + // end query projection + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + + public function testProjectionWithPagination(): void + { + // begin query projection with pagination + $resultsPerPage = 15; + $projectionFields = ['title', 'runtime', 'imdb.rating']; + + $result = DB::collection('movies') + ->orderBy('imdb.votes', 'desc') + ->paginate($resultsPerPage, $projectionFields); + // end query projection with pagination + + $this->assertInstanceOf(AbstractPaginator::class, $result); + } + + public function testExists(): void + { + // begin query exists + $result = DB::collection('movies') + ->exists('random_review', true); + // end query exists + + $this->assertIsBool($result); + } + + public function testAll(): void + { + // begin query all + $result = DB::collection('movies') + ->where('movies', 'all', ['title', 'rated', 'imdb.rating']) + ->get(); + // end query all + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + + public function testSize(): void + { + // begin query size + $result = DB::collection('movies') + ->where('directors', 'size', 5) + ->get(); + // end query size + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + + public function testType(): void + { + // begin query type + $result = DB::collection('movies') + ->where('released', 'type', 4) + ->get(); + // end query type + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + + public function testMod(): void + { + // begin query modulo + $result = DB::collection('movies') + ->where('year', 'mod', [2, 0]) + ->get(); + // end query modulo + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + + public function testWhereRegex(): void + { + // begin query whereRegex + $result = DB::connection('mongodb') + ->collection('movies') + ->where('title', 'REGEX', new Regex('^the lord of .*', 'i')) + ->get(); + // end query whereRegex + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + + public function testWhereRaw(): void + { + // begin query raw + $result = DB::collection('movies') + ->whereRaw([ + 'imdb.votes' => ['$gte' => 1000 ], + '$or' => [ + ['imdb.rating' => ['$gt' => 7]], + ['directors' => ['$in' => [ 'Yasujiro Ozu', 'Sofia Coppola', 'Federico Fellini' ]]], + ], + ])->get(); + // end query raw + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + + public function testElemMatch(): void + { + // begin query elemMatch + $result = DB::collection('movies') + ->where('writers', 'elemMatch', ['$in' => ['Maya Forbes', 'Eric Roth']]) + ->get(); + // end query elemMatch + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + + public function testCursorTimeout(): void + { + // begin query cursor timeout + $result = DB::collection('movies') + ->timeout(2) // value in seconds + ->where('year', 2001) + ->get(); + // end query cursor timeout + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + + public function testNear(): void + { + $this->importTheaters(); + + // begin query near + $results = DB::collection('theaters') + ->where('location.geo', 'near', [ + '$geometry' => [ + 'type' => 'Point', + 'coordinates' => [ + -86.6423, + 33.6054, + ], + ], + '$maxDistance' => 50, + ])->get(); + // end query near + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $results); + } + + public function testGeoWithin(): void + { + // begin query geoWithin + $results = DB::collection('theaters') + ->where('location.geo', 'geoWithin', [ + '$geometry' => [ + 'type' => 'Polygon', + 'coordinates' => [ + [ + [-72, 40], + [-74, 41], + [-72, 39], + [-72, 40], + ], + ], + ], + ])->get(); + // end query geoWithin + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $results); + } + + public function testGeoIntersects(): void + { + // begin query geoIntersects + $results = DB::collection('theaters') + ->where('location.geo', 'geoIntersects', [ + '$geometry' => [ + 'type' => 'LineString', + 'coordinates' => [ + [-73.600525, 40.74416], + [-72.600525, 40.74416], + ], + ], + ])->get(); + // end query geoIntersects + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $results); + } + + public function testGeoNear(): void + { + $this->importTheaters(); + + // begin query geoNear + $results = DB::collection('theaters')->raw( + function (Collection $collection) { + return $collection->aggregate([ + [ + '$geoNear' => [ + 'near' => [ + 'type' => 'Point', + 'coordinates' => [-118.34, 34.10], + ], + 'distanceField' => 'dist.calculated', + 'maxDistance' => 500, + 'includeLocs' => 'dist.location', + 'spherical' => true, + ], + ], + ]); + }, + )->toArray(); + // end query geoNear + + $this->assertIsArray($results); + $this->assertSame(8900, $results[0]['theaterId']); + } + + public function testUpsert(): void + { + // begin upsert + $result = DB::collection('movies') + ->where('title', 'Will Hunting') + ->update( + [ + 'plot' => 'An autobiographical movie', + 'year' => 1998, + 'writers' => [ 'Will Hunting' ], + ], + ['upsert' => true], + ); + // end upsert + + $this->assertIsInt($result); + } + + public function testIncrement(): void + { + // begin increment + $result = DB::collection('movies') + ->where('title', 'Field of Dreams') + ->increment('imdb.votes', 3000); + // end increment + + $this->assertIsInt($result); + } + + public function testDecrement(): void + { + // begin decrement + $result = DB::collection('movies') + ->where('title', 'Sharknado') + ->decrement('imdb.rating', 0.2); + // end decrement + + $this->assertIsInt($result); + } + + public function testPush(): void + { + // begin push + $result = DB::collection('movies') + ->where('title', 'Office Space') + ->push('cast', 'Gary Cole'); + // end push + + $this->assertIsInt($result); + } + + public function testPull(): void + { + // begin pull + $result = DB::collection('movies') + ->where('title', 'Iron Man') + ->pull('genres', 'Adventure'); + // end pull + + $this->assertIsInt($result); + } + + public function testUnset(): void + { + // begin unset + $result = DB::collection('movies') + ->where('title', 'Final Accord') + ->unset('tomatoes.viewer'); + // end unset + + $this->assertIsInt($result); + } +} diff --git a/docs/includes/query-builder/sample_mflix.movies.json b/docs/includes/query-builder/sample_mflix.movies.json new file mode 100644 index 000000000..57873754e --- /dev/null +++ b/docs/includes/query-builder/sample_mflix.movies.json @@ -0,0 +1,196 @@ +[ + { + "genres": [ + "Short" + ], + "runtime": 1, + "cast": [ + "Charles Kayser", + "John Ott" + ], + "title": "Blacksmith Scene", + "directors": [ + "William K.L. Dickson" + ], + "rated": "UNRATED", + "year": 1893, + "imdb": { + "rating": 6.2, + "votes": 1189, + "id": 5 + }, + "tomatoes": { + "viewer": { + "rating": 3, + "numReviews": 184, + "meter": 32 + } + } + }, + { + "genres": [ + "Short", + "Western" + ], + "runtime": 11, + "cast": [ + "A.C. Abadie", + "Gilbert M. 'Broncho Billy' Anderson", + "George Barnes", + "Justus D. Barnes" + ], + "title": "The Great Train Robbery", + "directors": [ + "Edwin S. Porter" + ], + "rated": "TV-G", + "year": 1903, + "imdb": { + "rating": 7.4, + "votes": 9847, + "id": 439 + }, + "tomatoes": { + "viewer": { + "rating": 3.7, + "numReviews": 2559, + "meter": 75 + } + } + }, + { + "genres": [ + "Short", + "Drama", + "Fantasy" + ], + "runtime": 14, + "rated": "UNRATED", + "cast": [ + "Martin Fuller", + "Mrs. William Bechtel", + "Walter Edwin", + "Ethel Jewett" + ], + "title": "The Land Beyond the Sunset", + "directors": [ + "Harold M. Shaw" + ], + "writers": [ + "Dorothy G. Shore" + ], + "year": 1912, + "imdb": { + "rating": 7.1, + "votes": 448, + "id": 488 + }, + "tomatoes": { + "viewer": { + "rating": 3.7, + "numReviews": 53, + "meter": 67 + } + } + }, + { + "genres": [ + "Short", + "Drama" + ], + "runtime": 14, + "cast": [ + "Frank Powell", + "Grace Henderson", + "James Kirkwood", + "Linda Arvidson" + ], + "title": "A Corner in Wheat", + "directors": [ + "D.W. Griffith" + ], + "rated": "G", + "year": 1909, + "imdb": { + "rating": 6.6, + "votes": 1375, + "id": 832 + }, + "tomatoes": { + "viewer": { + "rating": 3.6, + "numReviews": 109, + "meter": 73 + } + } + }, + { + "genres": [ + "Animation", + "Short", + "Comedy" + ], + "runtime": 7, + "cast": [ + "Winsor McCay" + ], + "title": "Winsor McCay, the Famous Cartoonist of the N.Y. Herald and His Moving Comics", + "directors": [ + "Winsor McCay", + "J. Stuart Blackton" + ], + "writers": [ + "Winsor McCay (comic strip \"Little Nemo in Slumberland\")", + "Winsor McCay (screenplay)" + ], + "year": 1911, + "imdb": { + "rating": 7.3, + "votes": 1034, + "id": 1737 + }, + "tomatoes": { + "viewer": { + "rating": 3.4, + "numReviews": 89, + "meter": 47 + } + } + }, + { + "genres": [ + "Comedy", + "Fantasy", + "Romance" + ], + "runtime": 118, + "cast": [ + "Meg Ryan", + "Hugh Jackman", + "Liev Schreiber", + "Breckin Meyer" + ], + "title": "Kate & Leopold", + "directors": [ + "James Mangold" + ], + "writers": [ + "Steven Rogers (story)", + "James Mangold (screenplay)", + "Steven Rogers (screenplay)" + ], + "year": 2001, + "imdb": { + "rating": 6.3, + "votes": 59951, + "id": 35423 + }, + "tomatoes": { + "viewer": { + "rating": 3, + "numReviews": 189426, + "meter": 62 + } + } + } +] diff --git a/docs/includes/query-builder/sample_mflix.theaters.json b/docs/includes/query-builder/sample_mflix.theaters.json new file mode 100644 index 000000000..b8d55381c --- /dev/null +++ b/docs/includes/query-builder/sample_mflix.theaters.json @@ -0,0 +1,39 @@ +[ + { + "theaterId": 1000, + "location": { + "address": { + "street1": "340 W Market", + "city": "Bloomington", + "state": "MN", + "zipcode": "55425" + }, + "geo": { + "type": "Point", + "coordinates": [ + -93.24565, + 44.85466 + ] + } + } + }, + { + "theaterId": 8900, + "location": { + "address": { + "street1": "6801 Hollywood Blvd", + "street2": null, + "city": "Hollywood", + "state": "CA", + "zipcode": "90028" + }, + "geo": { + "type": "Point", + "coordinates": [ + -118.340261, + 34.102593 + ] + } + } + } +] diff --git a/docs/query-builder.txt b/docs/query-builder.txt index 55b5762e4..9650df09b 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -9,590 +9,1116 @@ Query Builder :values: tutorial .. meta:: - :keywords: php framework, odm, code example + :keywords: code example, aggregation -The database driver plugs right into the original query builder. +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol -When using MongoDB connections, you will be able to build fluent queries to -perform database operations. +Overview +-------- -For your convenience, there is a ``collection`` alias for ``table`` and -other MongoDB specific operators/operations. +In this guide, you can learn how to use the {+odm-short+} extension of +the Laravel query builder to work with a MongoDB database. The query builder +lets you use a single syntax and fluent interface to write queries for any +supported database. -.. code-block:: php - - $books = DB::collection('books')->get(); - - $hungerGames = - DB::collection('books') - ->where('name', 'Hunger Games') - ->first(); - -If you are familiar with `Eloquent Queries `__, -there is the same functionality. - -Available operations --------------------- - -**Retrieving all models** - -.. code-block:: php - - $users = User::all(); - -**Retrieving a record by primary key** - -.. code-block:: php - - $user = User::find('517c43667db388101e00000f'); - -**Where** - -.. code-block:: php - - $posts = - Post::where('author.name', 'John') - ->take(10) - ->get(); - -**OR Statements** - -.. code-block:: php - - $posts = - Post::where('votes', '>', 0) - ->orWhere('is_approved', true) - ->get(); - -**AND statements** - -.. code-block:: php - - $users = - User::where('age', '>', 18) - ->where('name', '!=', 'John') - ->get(); - -**NOT statements** - -.. code-block:: php - - $users = User::whereNot('age', '>', 18)->get(); - -**whereIn** - -.. code-block:: php +.. note:: - $users = User::whereIn('age', [16, 18, 20])->get(); + {+odm-short+} extends Laravel's query builder and Eloquent ORM, which can + run similar database operations. To learn more about retrieving documents + by using Eloquent models, see :ref:`laravel-fundamentals-retrieve`. -When using ``whereNotIn`` objects will be returned if the field is -non-existent. Combine with ``whereNotNull('age')`` to omit those documents. +Laravel provides a **facade** to access the query builder class ``DB``, which +lets you perform database operations. Facades, which are static interfaces to +classes, make the syntax more concise, avoid runtime errors, and improve +testability. -**whereBetween** +{+odm-short+} aliases the ``DB`` method ``table()`` as the ``collection()`` +method. Chain methods to specify commands and any constraints. Then, chain +the ``get()`` method at the end to run the methods and retrieve the results. +The following example shows the syntax of a query builder call: .. code-block:: php - $posts = Post::whereBetween('votes', [1, 100])->get(); + DB::collection('') + // chain methods by using the "->" object operator + ->get(); -**whereNull** +This guide provides examples of the following types of query builder operations: + +- :ref:`laravel-retrieve-query-builder` +- :ref:`laravel-modify-results-query-builder` +- :ref:`laravel-mongodb-read-query-builder` +- :ref:`laravel-mongodb-write-query-builder` + +Before You Get Started +---------------------- + +To run the code examples in this guide, complete the +:ref:`Quick Start ` tutorial to configure a web +application, load sample datasets into your MongoDB deployment, and +run the example code from a controller method. + +To perform read and write operations by using the query builder, import the +``Illuminate\Support\Facades\DB`` facade and compose your query. + +.. _laravel-retrieve-query-builder: + +Retrieve Matching Documents +--------------------------- + +This section includes query builder examples for read operations in the +following operator categories: + +- :ref:`Where method ` +- :ref:`Logical conditionals ` +- :ref:`Ranges and type checks ` +- :ref:`Pattern searches ` +- :ref:`Retrieve distinct values ` +- :ref:`Aggregations ` + +.. _laravel-query-builder-where-example: + +Where Method Example +~~~~~~~~~~~~~~~~~~~~ + +The following example shows how to use the ``where()`` query +builder method to retrieve documents from the ``movies`` collection +that contain an ``imdb.rating`` field value of exactly ``9.3``. Click the +:guilabel:`{+code-output-label+}` button to see the results returned +by the query: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query where + :end-before: end query where + + .. output:: + :language: json + :visible: false + + [ + { "title": "Cosmos", + "year": 1980, + "runtime": 60, + "imdb": { + "rating": 9.3, + "votes": 17174, + "id": 81846 + }, + "plot": "Astronomer Carl Sagan leads us on an engaging guided tour of the various elements and cosmological theories of the universe.", + ... + }, + { "title": "The Shawshank Redemption", + "year": 1994, + "runtime": 142, + "imdb": { + "rating": 9.3, + "votes": 1521105, + "id": 111161 + }, + "plot": "Two imprisoned men bond over a number of years, finding solace and eventual redemption through acts of common decency.", + ... + }, + { "title": "The Real Miyagi", + "year": 2015, + "runtime": 90, + "imdb": { + "rating": 9.3, + "votes": 41, + "id": 2313306 + }, + "plot": "The life of the greatest karate master of a generation.", + ... + } + ] + +.. _laravel-query-builder-logical-operations: + +Logical Conditional Operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The examples in this section show the query builder syntax you +can use to perform the following logical conditional operations: + +- :ref:`Logical OR to match one or more conditions ` +- :ref:`Logical AND to match all conditions ` +- :ref:`Logical NOT to match the negation of the condition ` +- :ref:`Nested logical operator groups ` + +.. _laravel-query-builder-logical-or: + +Logical OR Example +^^^^^^^^^^^^^^^^^^ + +The following example shows how to chain the ``orWhere()`` +query builder method to retrieve documents from the +``movies`` collection that either match the ``year`` +value of ``1955`` or match the ``title`` value ``"Back to the Future"``: + +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query orWhere + :end-before: end query orWhere + +.. _laravel-query-builder-logical-and: + +Logical AND Example +^^^^^^^^^^^^^^^^^^^ + +The following example shows how to chain the ``where()`` +query builder method to retrieve documents from the +``movies`` collection that match both an ``imdb.rating`` +value greater than ``8.5`` and a ``year`` value of less than +``1940``: + +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query andWhere + :end-before: end query andWhere + +.. _laravel-query-builder-logical-not: + +Logical NOT Example +^^^^^^^^^^^^^^^^^^^ + +The following example shows how to call the ``whereNot()`` +query builder method to retrieve documents from the +``movies`` collection that match documents that do not have an ``imdb.rating`` +value greater than ``2``. This is equivalent to matching all documents +that have an ``imdb.rating`` of less than or equal to ``2``: + +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query whereNot + :end-before: end query whereNot + +.. _laravel-query-builder-logical-nested: + +Nested Logical Operator Group Example +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following example shows how to chain the ``where()`` +query builder method to retrieve documents from the +``movies`` collection that match both of the following +conditions. This example passes a closure as the first +parameter of the ``where()`` query builder method to group +the logical OR group: + +- ``imdb.rating`` value is greater than ``8.5`` +- ``year`` value is either ``1986`` or ``1996`` + +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query nestedLogical + :end-before: end query nestedLogical + +.. _laravel-query-builder-range-type: + +Ranges and Type Checks +~~~~~~~~~~~~~~~~~~~~~~ + +The examples in this section show the query builder syntax you can use to +match values by using the following range queries and type check operations: + +- :ref:`Values within a numerical range ` +- :ref:`Null or missing values ` +- :ref:`One or more values of a set ` +- :ref:`Match dates ` +- :ref:`Match a text pattern ` -.. code-block:: php +.. _laravel-query-builder-wherebetween: - $users = User::whereNull('age')->get(); +Numerical Range Example +^^^^^^^^^^^^^^^^^^^^^^^ -**whereDate** +The following example shows how to use the ``whereBetween()`` +query builder method to retrieve documents from the +``movies`` collection that contain an ``imdb.rating`` value +between ``9`` and ``9.5``: -.. code-block:: php +.. io-code-block:: + :copyable: true - $users = User::whereDate('birthday', '2021-5-12')->get(); + .. input:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query whereBetween + :end-before: end query whereBetween + + .. output:: + :language: none + :visible: false + + [ + { "title" "The Godfather", "imdb": { "rating": 9.2, "votes": 1038358, "id": 68646 }, ... }, + { "title": "Hollywood", "imdb": { "rating": 9.1, "votes": 511,"id": 80230 }, ... }, + { "title": "Cosmos", "imdb": { "rating": 9.3, "votes": 17174, "id": 81846 }, ... }, + ... + ] -The usage is the same as ``whereMonth`` / ``whereDay`` / ``whereYear`` / ``whereTime`` +.. _laravel-query-builder-null: + +Null or Missing Values Example +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following example shows how to use the ``whereNull()`` +query builder method to retrieve documents from the +``movies`` collection that omit a ``runtime`` value +or field: + +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query whereNull + :end-before: end query whereNull -**Advanced wheres** +.. _laravel-query-builder-wherein: -.. code-block:: php +One or More Values of a Set Example +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following example shows how to use the ``whereIn()`` +query builder method to retrieve documents from the +``movies`` collection that match at least one of the +``title`` values in the specified set: + +.. io-code-block:: + :copyable: true - $users = - User::where('name', 'John') - ->orWhere(function ($query) { - return $query - ->where('votes', '>', 100) - ->where('title', '<>', 'Admin'); - })->get(); + .. input:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query whereIn + :end-before: end query whereIn -**orderBy** + .. output:: + :language: json + :visible: false -.. code-block:: php + [ + { "title": "Toy Story", "year": 1995, "runtime": 81, ... }, + { "title": "Johnny English", "year": 2003, "runtime": 87, ... }, + { "title": "Shrek 2", "year" 2004, "runtime": 93, ... }, + ... + ] - $users = User::orderBy('age', 'desc')->get(); +.. _laravel-query-builder-wheredate: -**Offset & Limit (skip & take)** +Match Dates Example +^^^^^^^^^^^^^^^^^^^ -.. code-block:: php +The following example shows how to use the ``whereDate()`` +query builder method to retrieve documents from the +``movies`` collection that match the specified date of +``2010-1-15`` in the ``released`` field: - $users = - User::skip(10) - ->take(5) - ->get(); +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query whereDate + :end-before: end query whereDate + +.. _laravel-query-builder-pattern: -**groupBy** +Text Pattern Match Example +~~~~~~~~~~~~~~~~~~~~~~~~~~ -Selected columns that are not grouped will be aggregated with the ``$last`` -function. +The following example shows how to use the ``like`` query operator +with the ``where()`` query builder method to retrieve documents from the +``movies`` collection by using a specified text pattern. + +Text patterns can contain text mixed with the following +wildcard characters: + +- ``%`` which matches zero or more characters +- ``_`` which matches a single character + +.. io-code-block:: + :copyable: true + + .. input:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query like + :end-before: end query like + + .. output:: + :language: json + :visible: false + + [ + { "title": "Kiss of the Spider Woman", ... }, + { "title": "Spider-Man", ... }, + { "title": "Spider-Man 2", ...}, + ... + ] + +.. _laravel-query-builder-distinct: + +Retrieve Distinct Values +~~~~~~~~~~~~~~~~~~~~~~~~ + +The following example shows how to use the ``distinct()`` +query builder method to retrieve all the different values +of the ``year`` field for documents in the ``movies`` collections. + +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query distinct + :end-before: end query distinct + +.. _laravel-query-builder-aggregations: + +Aggregations +~~~~~~~~~~~~ + +The examples in this section show the query builder syntax you +can use to perform **aggregations**. Aggregations are operations +that compute values from a set of query result data. You can use +aggregations to compute and return the following information: + +- :ref:`Results grouped by common field values ` +- :ref:`Count the number of results ` +- :ref:`Maximum value of a field ` +- :ref:`Minimum value of a field ` +- :ref:`Average value of a field ` +- :ref:`Summed value of a field ` +- :ref:`Aggregate matched results ` + +.. _laravel-query-builder-aggregation-groupby: + +Results Grouped by Common Field Values Example +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following example shows how to use the ``groupBy()`` query builder method +to retrieve document data grouped by shared values of the ``runtime`` field. +This example chains the following operations to match documents from the +``movies`` collection that contain a ``rated`` value of ``G`` and include the +``title`` field of one movie for each distinct ``runtime`` value: + +- Match only documents that contain a ``rated`` field value of ``"G"`` by + using the ``where()`` method +- Group data by the distinct values of the ``runtime`` field, which is + assigned the ``_id`` field, by using the ``groupBy()`` method +- Sort the groups by the ``runtime`` field by using the ``orderBy()`` method +- Return ``title`` data from the last document in the grouped result by + specifying it in the ``get()`` method + +.. tip:: + + The ``groupBy()`` method calls the MongoDB ``$group`` aggregation operator + and ``$last`` accumulator operator. To learn more about these operators, see + :manual:`$group (aggregation) ` + in the {+server-docs-name+}. + +.. io-code-block:: + :copyable: true + + .. input:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query groupBy + :end-before: end query groupBy + + .. output:: + :language: json + :visible: false + + [ + ... + { + "_id": { "runtime": 64 }, + "runtime": 64, + "title": "Stitch! The Movie" + }, + { + "_id": { "runtime": 67 }, + "runtime": 67, + "title": "Bartok the Magnificent" + }, + { + "_id": { "runtime":68 }, + "runtime": 68, + "title": "Mickey's Twice Upon a Christmas" + }, + ... + ] + +.. _laravel-query-builder-aggregation-count: + +Number of Results Example +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following example shows how to use the ``count()`` +query builder method to return the number of documents +contained in the ``movies`` collection: + +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin aggregation count + :end-before: end aggregation count + +.. _laravel-query-builder-aggregation-max: + +Maximum Value of a Field Example +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following example shows how to use the ``max()`` +query builder method to return the highest numerical +value of the ``runtime`` field from the entire +``movies`` collection: + +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin aggregation max + :end-before: end aggregation max + +.. _laravel-query-builder-aggregation-min: + +Minimum Value of a Field Example +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following example shows how to use the ``min()`` +query builder method to return the lowest numerical +value of the ``year`` field from the entire ``movies`` +collection: + +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin aggregation min + :end-before: end aggregation min + +.. _laravel-query-builder-aggregation-avg: + +Average Value of a Field Example +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following example shows how to use the ``avg()`` +query builder method to return the numerical average, or +arithmetic mean, of the ``imdb.rating`` values from +the entire ``movies`` collection. + +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin aggregation avg + :end-before: end aggregation avg + +.. _laravel-query-builder-aggregation-sum: + +Summed Value of a Field Example +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following example shows how to use the ``sum()`` +query builder method to return the numerical total of +the ``imdb.votes`` values from the entire ``movies`` +collection: + + +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin aggregation sum + :end-before: end aggregation sum + +.. _laravel-query-builder-aggregate-matched: + +Aggregate Matched Results Example +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following example shows how to aggregate data +from results that match a query. The query matches all +movies after the year ``2000`` and computes the average +value of ``imdb.rating`` of those matches by using the +``avg()`` method: -.. code-block:: php +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin aggregation with filter + :end-before: end aggregation with filter - $users = - Users::groupBy('title') - ->get(['title', 'name']); +.. _laravel-modify-results-query-builder: -**Distinct** +Modify Query Results +-------------------- -Distinct requires a field for which to return the distinct values. +This section includes query builder examples for the +following functions that modify the order and format +of query results: + +- :ref:`Order results by the value of a field ` +- :ref:`Omit a specified number of results ` +- :ref:`Show a subset of fields and array values in the results ` +- :ref:`Paginate the results ` + +.. _laravel-query-builder-orderby: + +Order Results Example +~~~~~~~~~~~~~~~~~~~~~ + +The following example shows how to use the ``orderBy()`` +query builder method to arrange the results that match +the filter specified in the ``title`` field by the +``imdb.rating`` value in descending order: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query orderBy + :end-before: end query orderBy + + .. output:: + :language: json + :visible: false + + [ + { "title": "Back to the Future", "imdb": { "rating":8.5,"votes":636511,"id":88763 }, ... }, + { "title": "Back to the Future Part II", "imdb": { "rating":7.8,"votes":292539,"id":96874 }, ... }, + { "title": "Back to the Future Part III", "imdb": {"rating":7.4,"votes":242390,"id":99088 }, ... }, + ... + ] + +.. _laravel-query-builder-skip: + +Omit a Specified Number of Results Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following example shows how to use the ``skip()`` query builder method to +omit the first four results that match the filter specified in the ``title`` +field, sorted by the ``year`` value in ascending order: + +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query skip + :end-before: end query skip + +.. _laravel-query-builder-project: + +Show a Subset of Fields and Array Values in the Results Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following example shows how to use the ``project()`` +query builder method to match documents that contain an +``imdb.rating`` value higher than ``8.5`` and return +only the following field values: + +- Title of the movie in the ``title`` +- Second through fourth values of the ``cast`` array field, if they exist +- Document ``_id`` field, which is automatically included + +.. io-code-block:: + :copyable: true + + .. input:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query projection + :end-before: end query projection + + .. output:: + :language: json + :visible: false + + [ + { + "_id": { ... }, + "title": "City Lights" + "cast": [ + "Florence Lee", + "Harry Myers", + "Al Ernest Garcia" + ], + }, + { + "_id": { ... }, + "title": "Modern Times", + "cast": [ + "Paulette Goddard", + "Henry Bergman", + "Tiny Sandford" + ] + }, + { + "_id": { ... }, + "title": "Casablanca" + "cast": [ + "Ingrid Bergman", + "Paul Henreid", + "Claude Rains" + ], + }, + ... + ] + +.. _laravel-query-builder-paginate: + +Paginate the Results Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. code-block:: php +The following example shows how to use the ``paginate()`` query builder method +to divide the entire ``movie`` collection into discrete result sets of 15 +documents. The example also includes a sort order to arrange the results by +the ``imdb.votes`` field in descending order and a projection that includes +only specific fields in the results. - $users = User::distinct()->get(['name']); +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query projection with pagination + :end-before: end query projection with pagination - // Equivalent to: - $users = User::distinct('name')->get(); +To learn more about pagination, see +`Paginating Query Builder Results `__ +in the Laravel documentation. -Distinct can be combined with **where**: +.. _laravel-mongodb-read-query-builder: -.. code-block:: php +Retrieve Data by Using MongoDB Operations +----------------------------------------- - $users = - User::where('active', true) - ->distinct('name') - ->get(); +This section includes query builder examples that show how +to use the following MongoDB-specific query operations: -**Like** +- :ref:`Match documents that contain a field ` +- :ref:`Match documents that contain all specified fields ` +- :ref:`Match documents that contain a specific number of elements in an array ` +- :ref:`Match documents that contain a particular data type in a field ` +- :ref:`Match documents that contain a computed modulo value ` +- :ref:`Match documents that match a regular expression ` +- :ref:`Run MongoDB Query API operations ` +- :ref:`Match documents that contain array elements ` +- :ref:`Specify a cursor timeout ` +- :ref:`Match locations by using geospatial searches ` -.. code-block:: php +.. _laravel-query-builder-exists: - $spamComments = Comment::where('body', 'like', '%spam%')->get(); +Contains a Field Example +~~~~~~~~~~~~~~~~~~~~~~~~ -.. _laravel-query-builder-aggregates: +The following example shows how to use the ``exists()`` +query builder method to match documents that contain the +field ``random_review``: -**Aggregation** +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query exists + :end-before: end query exists -**Aggregations are only available for MongoDB versions greater than 2.2.x** +To learn more about this query operator, see +:manual:`$exists ` +in the {+server-docs-name+}. -.. code-block:: php +.. _laravel-query-builder-all: - $total = Product::count(); - $price = Product::max('price'); - $price = Product::min('price'); - $price = Product::avg('price'); - $total = Product::sum('price'); - -Aggregations can be combined with **where**: +Contains All Fields Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. code-block:: php +The following example shows how to use the ``all`` query +operator with the ``where()`` query builder method to match +documents that contain all the specified fields: - $sold = Orders::where('sold', true)->sum('price'); +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query all + :end-before: end query all -Aggregations can be also used on sub-documents: +To learn more about this query operator, see +:manual:`$all ` +in the {+server-docs-name+}. -.. code-block:: php +.. _laravel-query-builder-size: - $total = Order::max('suborder.price'); +Match Array Size Example +~~~~~~~~~~~~~~~~~~~~~~~~ -.. note:: +The following example shows how to pass the ``size`` +query operator with the ``where()`` query builder +method to match documents that contain a ``directors`` +field that contains an array of exactly five elements: - This aggregation only works with single sub-documents (like ``EmbedsOne``) - not subdocument arrays (like ``EmbedsMany``). +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query size + :end-before: end query size -**Incrementing/Decrementing the value of a column** +To learn more about this query operator, see +:manual:`$size ` +in the {+server-docs-name+}. -Perform increments or decrements (default 1) on specified attributes: +.. _laravel-query-builder-type: -.. code-block:: php +Match Data Type Example +~~~~~~~~~~~~~~~~~~~~~~~ - Cat::where('name', 'Kitty')->increment('age'); +The following example shows how to pass the ``type`` +query operator with the ``where()`` query builder +method to match documents that contain a type ``4`` value, +which corresponds to an array data type, in the +``released`` field. - Car::where('name', 'Toyota')->decrement('weight', 50); +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query type + :end-before: end query type -The number of updated objects is returned: +To learn more about the type codes and query operator, see +:manual:`$type ` +in the {+server-docs-name+}. -.. code-block:: php +.. _laravel-query-builder-mod: - $count = User::increment('age'); +Match a Value Computed with Modulo Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You may also specify more columns to update: +The following example shows how to pass the ``mod`` +query operator with the ``where()`` query builder +method to match documents by using the expression +``year % 2 == 0``, which matches even values for +the ``year`` field: -.. code-block:: php +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query modulo + :end-before: end query modulo - Cat::where('age', 3) - ->increment('age', 1, ['group' => 'Kitty Club']); +To learn more about this query operator, see +:manual:`$mod ` +in the {+server-docs-name+}. - Car::where('weight', 300) - ->decrement('weight', 100, ['latest_change' => 'carbon fiber']); +.. _laravel-query-builder-regex: -MongoDB-specific operators +Match a Regular Expression ~~~~~~~~~~~~~~~~~~~~~~~~~~ -In addition to the Laravel Eloquent operators, all available MongoDB query -operators can be used with ``where``: +The following example shows how to pass the ``REGEX`` +query operator with the ``where()`` query builder +method to match documents that contain a ``title`` +field that matches the specified regular expression: -.. code-block:: php - - User::where($fieldName, $operator, $value)->get(); +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query whereRegex + :end-before: end query whereRegex -It generates the following MongoDB filter: +To learn more about regular expression queries in MongoDB, see +:manual:`$regex ` +in the {+server-docs-name+}. -.. code-block:: ts +.. _laravel-query-builder-whereRaw: - { $fieldName: { $operator: $value } } +Run MongoDB Query API Operations Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -**Exists** +The following example shows how to use the ``whereRaw()`` +query builder method to run a query operation written by +using the MongoDB Query API syntax: -Matches documents that have the specified field. - -.. code-block:: php +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query raw + :end-before: end query raw - User::where('age', 'exists', true)->get(); +The following code shows the equivalent MongoDB Query API syntax: -**All** - -Matches arrays that contain all elements specified in the query. +.. code-block:: -.. code-block:: php + db.movies.find({ + "imdb.votes": { $gte: 1000 }, + $or: [{ + imdb.rating: { $gt: 7 }, + directors: { $in: [ "Yasujiro Ozu", "Sofia Coppola", "Federico Fellini" ] } + }]}); - User::where('roles', 'all', ['moderator', 'author'])->get(); +To learn more about the MongoDB Query API, see +:manual:`MongoDB Query API ` in the {+server-docs-name+}. -**Size** +.. _laravel-query-builder-elemMatch: -Selects documents if the array field is a specified size. +Match Array Elements Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. code-block:: php +The following example shows how to pass the ``elemMatch`` +query operator with the ``where()`` query builder +method to match documents that contain an array element +that matches at least one of the conditions in the +specified query: - Post::where('tags', 'size', 3)->get(); +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query elemMatch + :end-before: end query elemMatch -**Regex** +To learn more about regular expression queries in MongoDB, see +the :manual:`$elemMatch operator ` +in the {+server-docs-name+}. -Selects documents where values match a specified regular expression. +.. _laravel-query-builder-cursor-timeout: -.. code-block:: php +Specify Cursor Timeout Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - use MongoDB\BSON\Regex; +The following example shows how to use the ``timeout()`` method +to specify a maximum duration to wait for cursor operations to complete. - User::where('name', 'regex', new Regex('.*doe', 'i'))->get(); +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query cursor timeout + :end-before: end query cursor timeout .. note:: - You can also use the Laravel regexp operations. These will automatically - convert your regular expression string to a ``MongoDB\BSON\Regex`` object. - -.. code-block:: php - - User::where('name', 'regexp', '/.*doe/i')->get(); - -The inverse of regexp: - -.. code-block:: php - - User::where('name', 'not regexp', '/.*doe/i')->get(); + This setting specifies a ``maxTimeMS`` value in seconds instead of + milliseconds. To learn more about the ``maxTimeMS`` value, see + `MongoDB\Collection::find() `__ + in the PHP Library documentation. -**ElemMatch** +.. _laravel-query-builder-geospatial: -The :manual:`$elemMatch ` operator -matches documents that contain an array field with at least one element that -matches all the specified query criteria. +Match Locations by Using Geospatial Operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The following query matches only those documents where the results array -contains at least one element that is both greater than or equal to 80 and -is less than 85: +The examples in this section show the query builder syntax you +can use to perform geospatial queries on GeoJSON or coordinate +pair data to retrieve the following types of locations: -.. code-block:: php +- :ref:`Near a position ` +- :ref:`Within a the boundary of a GeoJSON object ` +- :ref:`Intersecting a GeoJSON object ` +- :ref:`Proximity data for nearby matches ` - User::where('results', 'elemMatch', ['gte' => 80, 'lt' => 85])->get(); +.. important:: -A closure can be used to create more complex sub-queries. + To perform GeoJSON queries in MongoDB, you must create either ``2d`` or + ``2dsphere`` index on the collection. To learn how to create geospatial + indexes, see the :ref:`laravel-eloquent-geospatial-index` section in the + Schema Builder guide. -The following query matches only those documents where the results array -contains at least one element with both product equal to "xyz" and score -greater than or equal to 8: +To learn more about GeoJSON objects that MongoDB supports, +see :manual:`GeoJSON Objects ` +in the {+server-docs-name+}. -.. code-block:: php +.. _laravel-query-builder-geospatial-near: - User::where('results', 'elemMatch', function (Builder $builder) { - $builder - ->where('product', 'xyz') - ->andWhere('score', '>', 50); - })->get(); +Near a Position Example +~~~~~~~~~~~~~~~~~~~~~~~ -**Type** +The following example shows how to use the ``near`` query operator +with the ``where()`` query builder method to match documents that +contain a location that is up to ``50`` meters from a GeoJSON Point +object: -Selects documents if a field is of the specified type. For more information -check: :manual:`$type ` in the -MongoDB Server documentation. +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query near + :end-before: end query near -.. code-block:: php +To learn more about this operator, see +:manual:`$near operator ` +in the {+server-docs-name+}. - User::where('age', 'type', 2)->get(); +.. _laravel-query-builder-geospatial-geoWithin: -**Mod** +Within an Area Example +~~~~~~~~~~~~~~~~~~~~~~ -Performs a modulo operation on the value of a field and selects documents with -a specified result. +The following example shows how to use the ``geoWithin`` +query operator with the ``where()`` +query builder method to match documents that contain a +location within the bounds of the specified ``Polygon`` +GeoJSON object: -.. code-block:: php +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query geoWithin + :end-before: end query geoWithin - User::where('age', 'mod', [10, 0])->get(); +.. _laravel-query-builder-geospatial-geoIntersects: -MongoDB-specific Geo operations +Intersecting a Geometry Example ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -**Near** - -.. code-block:: php - - $bars = Bar::where('location', 'near', [ - '$geometry' => [ - 'type' => 'Point', - 'coordinates' => [ - -0.1367563, // longitude - 51.5100913, // latitude - ], - ], - '$maxDistance' => 50, - ])->get(); - -**GeoWithin** - -.. code-block:: php - - $bars = Bar::where('location', 'geoWithin', [ - '$geometry' => [ - 'type' => 'Polygon', - 'coordinates' => [ - [ - [-0.1450383, 51.5069158], - [-0.1367563, 51.5100913], - [-0.1270247, 51.5013233], - [-0.1450383, 51.5069158], - ], - ], - ], - ])->get(); - -**GeoIntersects** - -.. code-block:: php - - $bars = Bar::where('location', 'geoIntersects', [ - '$geometry' => [ - 'type' => 'LineString', - 'coordinates' => [ - [-0.144044, 51.515215], - [-0.129545, 51.507864], - ], - ], - ])->get(); - -**GeoNear** - -You can make a ``geoNear`` query on MongoDB. -You can omit specifying the automatic fields on the model. -The returned instance is a collection, so you can call the `Collection `__ operations. -Make sure that your model has a ``location`` field, and a -`2ndSphereIndex `__. -The data in the ``location`` field must be saved as `GeoJSON `__. -The ``location`` points must be saved as `WGS84 `__ -reference system for geometry calculation. That means that you must -save ``longitude and latitude``, in that order specifically, and to find near -with calculated distance, you ``must do the same way``. +The following example shows how to use the ``geoInstersects`` +query operator with the ``where()`` query builder method to +match documents that contain a location that intersects with +the specified ``LineString`` GeoJSON object: -.. code-block:: +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query geoIntersects + :end-before: end query geoIntersects - Bar::find("63a0cd574d08564f330ceae2")->update( - [ - 'location' => [ - 'type' => 'Point', - 'coordinates' => [ - -0.1367563, - 51.5100913 - ] - ] - ] - ); - $bars = Bar::raw(function ($collection) { - return $collection->aggregate([ - [ - '$geoNear' => [ - "near" => [ "type" => "Point", "coordinates" => [-0.132239, 51.511874] ], - "distanceField" => "dist.calculated", - "minDistance" => 0, - "maxDistance" => 6000, - "includeLocs" => "dist.location", - "spherical" => true, - ] - ] - ]); - }); - -Inserts, updates and deletes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. _laravel-query-builder-geospatial-geoNear: -Inserting, updating and deleting records works just like the original Eloquent. -Please check `Laravel Docs' Eloquent section `__. +Proximity Data for Nearby Matches Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Here, only the MongoDB-specific operations are specified. +The following example shows how to use the ``geoNear`` aggregation operator +with the ``raw()`` query builder method to perform an aggregation that returns +metadata, such as proximity information for each match: -MongoDB specific operations -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query geoNear + :end-before: end query geoNear -**Raw Expressions** +To learn more about this aggregation operator, see +:manual:`$geoNear operator ` +in the {+server-docs-name+}. -These expressions will be injected directly into the query. +.. _laravel-mongodb-write-query-builder: -.. code-block:: php +Write Data by Using MongoDB Write Operations +-------------------------------------------- - User::whereRaw([ - 'age' => ['$gt' => 30, '$lt' => 40], - ])->get(); +This section includes query builder examples that show how to use the +following MongoDB-specific write operations: - User::whereRaw([ - '$where' => '/.*123.*/.test(this.field)', - ])->get(); +- :ref:`Upsert a document ` +- :ref:`Increment a numerical value ` +- :ref:`Decrement a numerical value ` +- :ref:`Add an array element ` +- :ref:`Remove a value from an array ` +- :ref:`Remove a field from a document ` - User::whereRaw([ - '$where' => '/.*123.*/.test(this["hyphenated-field"])', - ])->get(); +.. _laravel-mongodb-query-builder-upsert: -You can also perform raw expressions on the internal MongoCollection object. -If this is executed on the model class, it will return a collection of models. +Upsert a Document Example +~~~~~~~~~~~~~~~~~~~~~~~~~ -If this is executed on the query builder, it will return the original response. +The following example shows how to use the ``update()`` query builder method +and ``upsert`` option to update the matching document or insert one with the +specified data if it does not exist. When you set the ``upsert`` option to +``true`` and the document does not exist, the command inserts both the data +and the ``title`` field and value specified in the ``where()`` query operation: -**Cursor timeout** +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin upsert + :end-before: end upsert -To prevent ``MongoCursorTimeout`` exceptions, you can manually set a timeout -value that will be applied to the cursor: +The ``update()`` query builder method returns the number of documents that the +operation updated or inserted. -.. code-block:: php +.. _laravel-mongodb-query-builder-increment: - DB::collection('users')->timeout(-1)->get(); +Increment a Numerical Value Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -**Upsert** +The following example shows how to use the ``increment()`` +query builder method to add ``3000`` to the value of +the ``imdb.votes`` field in the matched document: -Update or insert a document. Other options for the update method can be -passed directly to the native update method. +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin increment + :end-before: end increment -.. code-block:: php +The ``increment()`` query builder method returns the number of documents that the +operation updated. - // Query Builder - DB::collection('users') - ->where('name', 'John') - ->update($data, ['upsert' => true]); +.. _laravel-mongodb-query-builder-decrement: - // Eloquent - $user->update($data, ['upsert' => true]); +Decrement a Numerical Value Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -**Projections** +The following example shows how to use the ``decrement()`` query builder +method to subtract ``0.2`` from the value of the ``imdb.rating`` field in the +matched document: -You can apply projections to your queries using the ``project`` method. +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin decrement + :end-before: end decrement -.. code-block:: php +The ``decrement()`` query builder method returns the number of documents that the +operation updated. - DB::collection('items') - ->project(['tags' => ['$slice' => 1]]) - ->get(); +.. _laravel-mongodb-query-builder-push: - DB::collection('items') - ->project(['tags' => ['$slice' => [3, 7]]]) - ->get(); - -**Projections with Pagination** - -.. code-block:: php - - $limit = 25; - $projections = ['id', 'name']; - - DB::collection('items') - ->paginate($limit, $projections); - -**Push** - -Add items to an array. - -.. code-block:: php - - DB::collection('users') - ->where('name', 'John') - ->push('items', 'boots'); - - $user->push('items', 'boots'); - -.. code-block:: php - - DB::collection('users') - ->where('name', 'John') - ->push('messages', [ - 'from' => 'Jane Doe', - 'message' => 'Hi John', - ]); - - $user->push('messages', [ - 'from' => 'Jane Doe', - 'message' => 'Hi John', - ]); - -If you **DON'T** want duplicate items, set the third parameter to ``true``: - -.. code-block:: php - - DB::collection('users') - ->where('name', 'John') - ->push('items', 'boots', true); - - $user->push('items', 'boots', true); - -**Pull** - -Remove an item from an array. - -.. code-block:: php - - DB::collection('users') - ->where('name', 'John') - ->pull('items', 'boots'); +Add an Array Element Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - $user->pull('items', 'boots'); +The following example shows how to use the ``push()`` query builder method to +add ``"Gary Cole"`` to the ``cast`` array field in the matched document: -.. code-block:: php +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin push + :end-before: end push - DB::collection('users') - ->where('name', 'John') - ->pull('messages', [ - 'from' => 'Jane Doe', - 'message' => 'Hi John', - ]); +The ``push()`` query builder method returns the number of documents that the +operation updated. - $user->pull('messages', [ - 'from' => 'Jane Doe', - 'message' => 'Hi John', - ]); +.. _laravel-mongodb-query-builder-pull: -**Unset** +Remove an Array Element Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Remove one or more fields from a document. +The following example shows how to use the ``pull()`` query builder method +to remove the ``"Adventure"`` value from the ``genres`` field from the document +matched by the query: -.. code-block:: php +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin pull + :end-before: end pull - DB::collection('users') - ->where('name', 'John') - ->unset('note'); +The ``pull()`` query builder method returns the number of documents that the +operation updated. - $user->unset('note'); +.. _laravel-mongodb-query-builder-unset: - $user->save(); +Remove a Field Example +~~~~~~~~~~~~~~~~~~~~~~ -Using the native ``unset`` on models will work as well: +The following example shows how to use the ``unset()`` query builder method +to remove the ``tomatoes.viewer`` field and value from the document matched +by the query: -.. code-block:: php +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin unset + :end-before: end unset - unset($user['note']); - unset($user->node); +The ``unset()`` query builder method returns the number of documents that the +operation updated. diff --git a/docs/retrieve.txt b/docs/retrieve.txt index b607d3d4f..1447d20a0 100644 --- a/docs/retrieve.txt +++ b/docs/retrieve.txt @@ -43,7 +43,7 @@ sample data and creating the following files in your Laravel web application: - ``browse_movies.blade.php`` file, which contains HTML code to display the results of database operations -The following sections describe how to edit the files in your Laravel application to run +The following sections describe how to edit the files in your Laravel application to run the find operation code examples and view the expected output. .. _laravel-retrieve-matching: @@ -51,41 +51,37 @@ the find operation code examples and view the expected output. Retrieve Documents that Match a Query ------------------------------------- -You can retrieve documents that match a set of criteria by passing a query filter to the ``where()`` -method. A query filter specifies field value requirements and instructs the find operation -to only return documents that meet these requirements. To run the query, call the ``where()`` -method on an Eloquent model or query builder that represents your collection. +You can use Laravel's Eloquent object-relational mapper (ORM) to create models +that represent MongoDB collections and chain methods on them to specify +query criteria. -You can use one of the following ``where()`` method calls to build a query: - -- ``where('', )``: builds a query that matches documents in which the - target field has the exact specified value +To retrieve documents that match a set of criteria, pass a query filter to the +``where()`` method. -- ``where('', '', )``: builds a query that matches - documents in which the target field's value meets the comparison criteria +A query filter specifies field value requirements and instructs the find +operation to return only documents that meet these requirements. -After building your query with the ``where()`` method, use the ``get()`` method to -retrieve the query results. +You can use Laravel's Eloquent object-relational mapper (ORM) to create models +that represent MongoDB collections. To retrieve documents from a collection, +call the ``where()`` method on the collection's corresponding Eloquent model. -To apply multiple sets of criteria to the find operation, you can chain a series -of ``where()`` methods together. - -.. tip:: +You can use one of the following ``where()`` method calls to build a query: - To learn more about other query methods in {+odm-short+}, see the :ref:`laravel-query-builder` - page. +- ``where('', )`` builds a query that matches documents in + which the target field has the exact specified value -.. _laravel-retrieve-eloquent: +- ``where('', '', )`` builds a query + that matches documents in which the target field's value meets the comparison + criteria -Use Eloquent Models to Retrieve Documents -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +To apply multiple sets of criteria to the find operation, you can chain a series +of ``where()`` methods together. -You can use Laravel's Eloquent object-relational mapper (ORM) to create models that represent -MongoDB collections. To retrieve documents from a collection, call the ``where()`` method -on the collection's corresponding Eloquent model. +After building your query with the ``where()`` method, chain the ``get()`` +method to retrieve the query results. -This example calls two ``where()`` methods on the ``Movie`` Eloquent model to retrieve -documents that meet the following criteria: +This example calls two ``where()`` methods on the ``Movie`` Eloquent model to +retrieve documents that meet the following criteria: - ``year`` field has a value of ``2010`` - ``imdb.rating`` nested field has a value greater than ``8.5`` @@ -122,7 +118,7 @@ documents that meet the following criteria: $movies = Movie::where('year', 2010) ->where('imdb.rating', '>', 8.5) ->get(); - + return view('browse_movies', [ 'movies' => $movies ]); @@ -149,132 +145,8 @@ documents that meet the following criteria: Plot: A documentary on Brazilian Formula One racing driver Ayrton Senna, who won the F1 world championship three times before his death at age 34. -.. _laravel-retrieve-query-builder: - -Use Laravel Queries to Retrieve Documents -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can use Laravel's database query builder to run find operations instead of using Eloquent -models. To run the database query, import the ``DB`` facade into your controller file and use -Laravel's query builder syntax. - -This example uses Laravel's query builder to retrieve documents in which the value -of the ``imdb.votes`` nested field is ``350``. - -.. tabs:: - - .. tab:: Query Syntax - :tabid: query-syntax - - Use the following syntax to specify the query: - - .. code-block:: php - - $movies = DB::connection('mongodb') - ->collection('movies') - ->where('imdb.votes', 350) - ->get(); - - .. tab:: Controller Method - :tabid: controller - - To see the query results in the ``browse_movies`` view, edit the ``show()`` function - in the ``MovieController.php`` file to resemble the following code: - - .. io-code-block:: - :copyable: true - - .. input:: - :language: php - - class MovieController - { - public function show() - { - $movies = DB::connection('mongodb') - ->collection('movies') - ->where('imdb.votes', 350) - ->get(); - - return view('browse_movies', [ - 'movies' => $movies - ]); - } - } - - .. output:: - :language: none - :visible: false - - Title: Murder in New Hampshire: The Pamela Wojas Smart Story - Year: 1991 - Runtime: 100 - IMDB Rating: 5.9 - IMDB Votes: 350 - Plot: Pamela Smart knows exactly what she wants and is willing to do - anything to get it. She is fed up with teaching, and her marriage offers - little excitement. Looking for a way out she applies ... - - Title: Ah Fu - Year: 2000 - Runtime: 105 - IMDB Rating: 6.6 - IMDB Votes: 350 - Plot: After a 13-year imprisonment in Hong Kong, a kickboxer challenges the - current champion in order to restore his honor. - - Title: Bandage - Year: 2010 - Runtime: 119 - IMDB Rating: 7 - IMDB Votes: 350 - Plot: Four boys have their friendship and musical talents tested in the ever - changing worlds of the music industry and real life in 1990s Japan. - - Title: Great Migrations - Year: 2010 - Runtime: 45 - IMDB Rating: 8.2 - IMDB Votes: 350 - Plot: Great Migrations takes viewers on the epic journeys animals undertake to - ensure the survival of their species. - - Then, make the following changes to your Laravel Quick Start application: - - - Import the ``DB`` facade into your ``MovieController.php`` file by adding the - ``use Illuminate\Support\Facades\DB`` use statement - - Replace the contents of your ``browse_movies.blade.php`` file with the following code: - - .. code-block:: php - - - - - Browse Movies - - -

Movies

- - @forelse ($movies as $movie) -

- Title: {{ $movie['title'] }}
- Year: {{ $movie['year'] }}
- Runtime: {{ $movie['runtime'] }}
- IMDB Rating: {{ $movie['imdb']['rating'] }}
- IMDB Votes: {{ $movie['imdb']['votes'] }}
- Plot: {{ $movie['plot'] }}
-

- @empty -

No results

- @endforelse - - - - - .. note:: - - Since the Laravel query builder returns data as an array rather than as instances of the Eloquent model class, - the view accesses the fields by using the array syntax instead of the ``->`` object operator. +To learn how to query by using the Laravel query builder instead of the +Eloquent ORM, see the :ref:`laravel-query-builder` page. .. _laravel-retrieve-all: @@ -295,10 +167,10 @@ Use the following syntax to run a find operation that matches all documents: .. warning:: The ``movies`` collection in the Atlas sample dataset contains a large amount of data. - Retrieving and displaying all documents in this collection might cause your web - application to time out. - - To avoid this issue, specify a document limit by using the ``take()`` method. For + Retrieving and displaying all documents in this collection might cause your web + application to time out. + + To avoid this issue, specify a document limit by using the ``take()`` method. For more information about ``take()``, see the :ref:`laravel-modify-find` section of this guide. @@ -462,7 +334,7 @@ field. IMDB Votes: 620 Plot: A documentary of black art. -.. tip:: +.. tip:: To learn more about sorting, see the following resources: From 10f44bf280b32c35931340b54da1aa6dbf2671d1 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Mon, 8 Apr 2024 16:42:14 -0400 Subject: [PATCH 228/446] DOCSP-35976: Delete One usage example (#2821) Adds a usage example page demonstrating how to delete one document from a collection --------- Co-authored-by: norareidy --- .../includes/usage-examples/DeleteOneTest.php | 40 +++++++++++ docs/usage-examples.txt | 1 + docs/usage-examples/deleteOne.txt | 69 +++++++++++++++++++ 3 files changed, 110 insertions(+) create mode 100644 docs/includes/usage-examples/DeleteOneTest.php create mode 100644 docs/usage-examples/deleteOne.txt diff --git a/docs/includes/usage-examples/DeleteOneTest.php b/docs/includes/usage-examples/DeleteOneTest.php new file mode 100644 index 000000000..1a2acd4e0 --- /dev/null +++ b/docs/includes/usage-examples/DeleteOneTest.php @@ -0,0 +1,40 @@ + 'Quiz Show', + 'runtime' => 133, + ], + ]); + + // begin-delete-one + $deleted = Movie::where('title', 'Quiz Show') + ->orderBy('_id') + ->limit(1) + ->delete(); + + echo 'Deleted documents: ' . $deleted; + // end-delete-one + + $this->assertEquals(1, $deleted); + $this->expectOutputString('Deleted documents: 1'); + } +} diff --git a/docs/usage-examples.txt b/docs/usage-examples.txt index 2bcd9ac58..32e876fa7 100644 --- a/docs/usage-examples.txt +++ b/docs/usage-examples.txt @@ -73,3 +73,4 @@ calls the controller function and returns the result to a web interface. /usage-examples/findOne /usage-examples/updateOne + /usage-examples/deleteOne diff --git a/docs/usage-examples/deleteOne.txt b/docs/usage-examples/deleteOne.txt new file mode 100644 index 000000000..762cfd405 --- /dev/null +++ b/docs/usage-examples/deleteOne.txt @@ -0,0 +1,69 @@ +.. _laravel-delete-one-usage: + +================= +Delete a Document +================= + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: delete one, remove, code example + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +You can delete a document in a collection by retrieving a single Eloquent model and calling +the ``delete()`` method, or by calling ``delete()`` directly on a query builder. + +To delete a document, pass a query filter to the ``where()`` method, sort the matching documents, +and call the ``limit()`` method to retrieve only the first document. Then, delete this matching +document by calling the ``delete()`` method. + +Example +------- + +This usage example performs the following actions: + +- Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the + ``sample_mflix`` database +- Deletes 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 ``'Quiz Show'`` +- ``orderBy()``: sorts matched documents by their ascending ``_id`` values +- ``limit()``: retrieves only the first matching document +- ``delete()``: deletes the retrieved document + +.. io-code-block:: + :copyable: true + + .. input:: ../includes/usage-examples/DeleteOneTest.php + :start-after: begin-delete-one + :end-before: end-delete-one + :language: php + :dedent: + + .. output:: + :language: console + :visible: false + + Deleted 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 deleting documents with {+odm-short+}, see the `Deleting Models + `__ section of the + Laravel documentation. + + For more information about query filters, see the :ref:`laravel-retrieve-matching` section of + the Read Operations guide. + From d0e6fb496842fe54729d058c029c41f116adf7ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 9 Apr 2024 19:57:56 +0200 Subject: [PATCH 229/446] Fix and test MongoDB failed queue provider --- src/Queue/Failed/MongoFailedJobProvider.php | 40 ++++- .../Failed/MongoFailedJobProviderTest.php | 150 ++++++++++++++++++ 2 files changed, 186 insertions(+), 4 deletions(-) create mode 100644 tests/Queue/Failed/MongoFailedJobProviderTest.php diff --git a/src/Queue/Failed/MongoFailedJobProvider.php b/src/Queue/Failed/MongoFailedJobProvider.php index 0525c272e..b7a05075c 100644 --- a/src/Queue/Failed/MongoFailedJobProvider.php +++ b/src/Queue/Failed/MongoFailedJobProvider.php @@ -5,6 +5,7 @@ namespace MongoDB\Laravel\Queue\Failed; use Carbon\Carbon; +use DateTimeInterface; use Exception; use Illuminate\Queue\Failed\DatabaseFailedJobProvider; use MongoDB\BSON\UTCDateTime; @@ -55,16 +56,16 @@ public function all() /** * Get a single failed job. * - * @param mixed $id + * @param string $id * - * @return object + * @return object|null */ public function find($id) { $job = $this->getTable()->find($id); if (! $job) { - return; + return null; } $job['id'] = (string) $job['_id']; @@ -75,7 +76,7 @@ public function find($id) /** * Delete a single failed job from storage. * - * @param mixed $id + * @param string $id * * @return bool */ @@ -83,4 +84,35 @@ public function forget($id) { return $this->getTable()->where('_id', $id)->delete() > 0; } + + /** + * Get the IDs of all of the failed jobs. + * + * @param string|null $queue + * + * @return array + */ + public function ids($queue = null) + { + return $this->getTable() + ->when($queue !== null, static fn ($query) => $query->where('queue', $queue)) + ->orderBy('_id', 'desc') + ->pluck('_id') + ->all(); + } + + /** + * Prune all entries older than the given date. + * + * @param DateTimeInterface $before + * + * @return int + */ + public function prune(DateTimeInterface $before) + { + return $this + ->getTable() + ->where('failed_at', '<', $before) + ->delete(); + } } diff --git a/tests/Queue/Failed/MongoFailedJobProviderTest.php b/tests/Queue/Failed/MongoFailedJobProviderTest.php new file mode 100644 index 000000000..f113428ec --- /dev/null +++ b/tests/Queue/Failed/MongoFailedJobProviderTest.php @@ -0,0 +1,150 @@ +collection('failed_jobs') + ->raw() + ->insertMany(array_map(static fn ($i) => [ + '_id' => new ObjectId(sprintf('%024d', $i)), + 'connection' => 'mongodb', + 'queue' => $i % 2 ? 'default' : 'other', + 'failed_at' => new UTCDateTime(Date::now()->subHours($i)), + ], range(1, 5))); + } + + public function tearDown(): void + { + DB::connection('mongodb') + ->collection('failed_jobs') + ->raw() + ->drop(); + + parent::tearDown(); + } + + public function testLog(): void + { + $provider = $this->getProvider(); + + $provider->log('mongodb', 'default', '{"foo":"bar"}', new OutOfBoundsException('This is the error')); + + $ids = $provider->ids(); + + $this->assertCount(6, $ids); + + $inserted = $provider->find($ids[0]); + + $this->assertSame('mongodb', $inserted->connection); + $this->assertSame('default', $inserted->queue); + $this->assertSame('{"foo":"bar"}', $inserted->payload); + $this->assertStringContainsString('OutOfBoundsException: This is the error', $inserted->exception); + $this->assertInstanceOf(ObjectId::class, $inserted->_id); + $this->assertSame((string) $inserted->_id, $inserted->id); + } + + public function testCount(): void + { + $provider = $this->getProvider(); + + $this->assertEquals(5, $provider->count()); + $this->assertEquals(3, $provider->count('mongodb', 'default')); + $this->assertEquals(2, $provider->count('mongodb', 'other')); + } + + public function testAll(): void + { + $all = $this->getProvider()->all(); + + $this->assertCount(5, $all); + $this->assertEquals(new ObjectId(sprintf('%024d', 5)), $all[0]->_id); + $this->assertEquals(sprintf('%024d', 5), $all[0]->id, 'id field is added for compatibility with DatabaseFailedJobProvider'); + } + + public function testFindAndForget(): void + { + $provider = $this->getProvider(); + + $id = sprintf('%024d', 2); + $found = $provider->find($id); + + $this->assertIsObject($found, 'The job is found'); + $this->assertEquals(new ObjectId($id), $found->_id); + $this->assertObjectHasProperty('failed_at', $found); + + // Delete the job + $result = $provider->forget($id); + + $this->assertTrue($result, 'forget return true when the job have been deleted'); + $this->assertNull($provider->find($id), 'the job have been deleted'); + + // Delete the same job again + $result = $provider->forget($id); + + $this->assertFalse($result, 'forget return false when the job does not exist'); + + $this->assertCount(4, $provider->ids(), 'Other jobs are kept'); + } + + public function testIds(): void + { + $ids = $this->getProvider()->ids(); + + $this->assertCount(5, $ids); + $this->assertEquals(new ObjectId(sprintf('%024d', 5)), $ids[0]); + } + + public function testIdsFilteredByQuery(): void + { + $ids = $this->getProvider()->ids('other'); + + $this->assertCount(2, $ids); + $this->assertEquals(new ObjectId(sprintf('%024d', 4)), $ids[0]); + } + + public function testFlush(): void + { + $provider = $this->getProvider(); + + $this->assertEquals(5, $provider->count()); + + $provider->flush(4); + + $this->assertEquals(3, $provider->count()); + } + + public function testPrune(): void + { + $provider = $this->getProvider(); + + $this->assertEquals(5, $provider->count()); + + $result = $provider->prune(Date::now()->subHours(4)); + + $this->assertEquals(2, $result); + $this->assertEquals(3, $provider->count()); + } + + private function getProvider(): MongoFailedJobProvider + { + return new MongoFailedJobProvider(DB::getFacadeRoot(), '', 'failed_jobs'); + } +} From d3eb2357b2beb078c78c6a2517e14a386192b977 Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Wed, 10 Apr 2024 13:26:24 +0200 Subject: [PATCH 230/446] Add docs team as code owner (#2840) --- .github/CODEOWNERS | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 067d4a1b3..3fe0077e4 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1 +1,2 @@ * @mongodb/dbx-php +/docs @mongodb/docs-drivers-team From c4a0305593236c5aecc6ca0a87f09ef6c44e5d1f Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Wed, 10 Apr 2024 14:12:48 +0200 Subject: [PATCH 231/446] Enable auto-merge in merge-up pull requests (#2843) --- .github/workflows/merge-up.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/merge-up.yml b/.github/workflows/merge-up.yml index 215c2d9ac..bdd4cfefa 100644 --- a/.github/workflows/merge-up.yml +++ b/.github/workflows/merge-up.yml @@ -28,3 +28,4 @@ jobs: with: ref: ${{ github.ref_name }} branchNamePattern: '.' + enableAutoMerge: true From 9fbe1efdc9fdb9bfdecaa29959cf3a8f8a065729 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 15 Apr 2024 13:24:39 +0200 Subject: [PATCH 232/446] Update src/Queue/Failed/MongoFailedJobProvider.php --- src/Queue/Failed/MongoFailedJobProvider.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Queue/Failed/MongoFailedJobProvider.php b/src/Queue/Failed/MongoFailedJobProvider.php index b7a05075c..cf72688e2 100644 --- a/src/Queue/Failed/MongoFailedJobProvider.php +++ b/src/Queue/Failed/MongoFailedJobProvider.php @@ -90,7 +90,7 @@ public function forget($id) * * @param string|null $queue * - * @return array + * @return list */ public function ids($queue = null) { From 79df46521202c5a0f48ef591b340310fe871d195 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Mon, 15 Apr 2024 09:06:21 -0400 Subject: [PATCH 233/446] DOCSP-35968: Transactions docs (#2847) * DOCSP-35968: Transactions docs --- docs/feature-compatibility.txt | 2 +- .../fundamentals/transactions/Account.php | 13 ++ .../transactions/TransactionsTest.php | 144 +++++++++++++++ docs/query-builder.txt | 2 +- docs/transactions.txt | 165 +++++++++++++----- 5 files changed, 281 insertions(+), 45 deletions(-) create mode 100644 docs/includes/fundamentals/transactions/Account.php create mode 100644 docs/includes/fundamentals/transactions/TransactionsTest.php diff --git a/docs/feature-compatibility.txt b/docs/feature-compatibility.txt index b4f0406f3..bbb5767e1 100644 --- a/docs/feature-compatibility.txt +++ b/docs/feature-compatibility.txt @@ -136,7 +136,7 @@ The following Eloquent methods are not supported in {+odm-short+}: - *Unsupported* * - Grouping - - Partially supported, use :ref:`Aggregation Builders `. + - Partially supported, use :ref:`Aggregations `. * - Limit and Offset - ✓ diff --git a/docs/includes/fundamentals/transactions/Account.php b/docs/includes/fundamentals/transactions/Account.php new file mode 100644 index 000000000..72b903a50 --- /dev/null +++ b/docs/includes/fundamentals/transactions/Account.php @@ -0,0 +1,13 @@ + 223344, + 'balance' => 5000, + ], + [ + 'number' => 776655, + 'balance' => 100, + ], + ]); + + // begin transaction callback + DB::transaction(function () { + $transferAmount = 200; + + $sender = Account::where('number', 223344)->first(); + $sender->balance -= $transferAmount; + $sender->save(); + + $receiver = Account::where('number', 776655)->first(); + $receiver->balance += $transferAmount; + $receiver->save(); + }); + // end transaction callback + + $sender = Account::where('number', 223344)->first(); + $receiver = Account::where('number', 776655)->first(); + + $this->assertEquals(4800, $sender->balance); + $this->assertEquals(300, $receiver->balance); + } + + public function testTransactionCommit(): void + { + require_once __DIR__ . '/Account.php'; + + Account::truncate(); + + Account::insert([ + [ + 'number' => 223344, + 'balance' => 5000, + ], + [ + 'number' => 776655, + 'balance' => 100, + ], + ]); + + // begin commit transaction + DB::beginTransaction(); + $oldAccount = Account::where('number', 223344)->first(); + + $newAccount = Account::where('number', 776655)->first(); + $newAccount->balance += $oldAccount->balance; + $newAccount->save(); + + $oldAccount->delete(); + DB::commit(); + // end commit transaction + + $acct1 = Account::where('number', 223344)->first(); + $acct2 = Account::where('number', 776655)->first(); + + $this->assertNull($acct1); + $this->assertEquals(5100, $acct2->balance); + } + + public function testTransactionRollback(): void + { + require_once __DIR__ . '/Account.php'; + + Account::truncate(); + Account::insert([ + [ + 'number' => 223344, + 'balance' => 200, + ], + [ + 'number' => 776655, + 'balance' => 0, + ], + [ + 'number' => 990011, + 'balance' => 0, + ], + ]); + + // begin rollback transaction + DB::beginTransaction(); + + $sender = Account::where('number', 223344)->first(); + $receiverA = Account::where('number', 776655)->first(); + $receiverB = Account::where('number', 990011)->first(); + + $amountA = 100; + $amountB = 200; + + $sender->balance -= $amountA; + $receiverA->balance += $amountA; + + $sender->balance -= $amountB; + $receiverB->balance += $amountB; + + if ($sender->balance < 0) { + // insufficient balance, roll back the transaction + DB::rollback(); + } else { + DB::commit(); + } + + // end rollback transaction + + $sender = Account::where('number', 223344)->first(); + $receiverA = Account::where('number', 776655)->first(); + $receiverB = Account::where('number', 990011)->first(); + + $this->assertEquals(200, $sender->balance); + $this->assertEquals(0, $receiverA->balance); + $this->assertEquals(0, $receiverB->balance); + } +} diff --git a/docs/query-builder.txt b/docs/query-builder.txt index 9650df09b..5249e2911 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -878,7 +878,7 @@ specified query: :end-before: end query elemMatch To learn more about regular expression queries in MongoDB, see -the :manual:`$elemMatch operator ` +the :manual:`$elemMatch operator ` in the {+server-docs-name+}. .. _laravel-query-builder-cursor-timeout: diff --git a/docs/transactions.txt b/docs/transactions.txt index ee70f8c8b..3cb3c2c5b 100644 --- a/docs/transactions.txt +++ b/docs/transactions.txt @@ -9,71 +9,150 @@ Transactions :values: tutorial .. meta:: - :keywords: php framework, odm, code example + :keywords: php framework, odm, rollback, commit, callback, code example, acid, atomic, consistent, isolated, durable -MongoDB transactions require the following software and topology: +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to perform a **transaction** in MongoDB by +using the {+odm-long+}. Transactions let you run a sequence of write operations +that update the data only after the transaction is committed. + +If the transaction fails, the PHP library that manages MongoDB operations +for {+odm-short+} ensures that MongoDB discards all the changes made within +the transaction before they become visible. This property of transactions +that ensures that all changes within a transaction are either applied or +discarded is called **atomicity**. + +MongoDB performs write operations on single documents atomically. If you +need atomicity in write operations on multiple documents or data consistency +across multiple documents for your operations, run them in a multi-document +transaction. + +Multi-document transactions are **ACID compliant** because MongoDB +guarantees that the data in your transaction operations remains consistent, +even if the driver encounters unexpected errors. + +Learn how to perform transactions in the following sections of this guide: + +- :ref:`laravel-transaction-requirements` +- :ref:`laravel-transaction-callback` +- :ref:`laravel-transaction-commit` +- :ref:`laravel-transaction-rollback` + +.. tip:: + + To learn more about transactions in MongoDB, see :manual:`Transactions ` + in the {+server-docs-name+}. + +.. _laravel-transaction-requirements: + +Requirements and Limitations +---------------------------- + +To perform transactions in MongoDB, you must use the following MongoDB +version and topology: - MongoDB version 4.0 or later - A replica set deployment or sharded cluster -You can find more information :manual:`in the MongoDB docs ` +MongoDB server and {+odm-short+} have the following limitations: -.. code-block:: php +- In MongoDB versions 4.2 and earlier, write operations performed within a + transaction must be on existing collections. In MongoDB versions 4.4 and + later, the server automatically creates collections as necessary when + you perform write operations in a transaction. To learn more about this + limitation, see :manual:`Create Collections and Indexes in a Transaction ` + in the {+server-docs-name+}. +- MongoDB does not support nested transactions. If you attempt to start a + transaction within another one, the extension raises a ``RuntimeException``. + To learn more about this limitation, see :manual:`Transactions and Sessions ` + in the {+server-docs-name+}. +- The {+odm-long+} does not support the database testing traits + ``Illuminate\Foundation\Testing\DatabaseTransactions`` and ``Illuminate\Foundation\Testing\RefreshDatabase``. + As a workaround, you can create migrations with the ``Illuminate\Foundation\Testing\DatabaseMigrations`` + trait to reset the database after each test. - DB::transaction(function () { - User::create(['name' => 'john', 'age' => 19, 'title' => 'admin', 'email' => 'john@example.com']); - DB::collection('users')->where('name', 'john')->update(['age' => 20]); - DB::collection('users')->where('name', 'john')->delete(); - }); +.. _laravel-transaction-callback: -.. code-block:: php +Run a Transaction in a Callback +------------------------------- + +This section shows how you can run a transaction in a callback. - // begin a transaction - DB::beginTransaction(); - User::create(['name' => 'john', 'age' => 19, 'title' => 'admin', 'email' => 'john@example.com']); - DB::collection('users')->where('name', 'john')->update(['age' => 20]); - DB::collection('users')->where('name', 'john')->delete(); +When using this method of running a transaction, all the code in the +callback method runs as a single transaction. - // commit changes - DB::commit(); +In the following example, the transaction consists of write operations that +transfer the funds from a bank account, represented by the ``Account`` model, +to another account: -To abort a transaction, call the ``rollBack`` method at any point during the transaction: +.. literalinclude:: /includes/fundamentals/transactions/TransactionsTest.php + :language: php + :dedent: + :start-after: begin transaction callback + :end-before: end transaction callback + +You can optionally pass the maximum number of times to retry a failed transaction as the second parameter as shown in the following code example: .. code-block:: php + :emphasize-lines: 4 - DB::beginTransaction(); - User::create(['name' => 'john', 'age' => 19, 'title' => 'admin', 'email' => 'john@example.com']); + DB::transaction(function() { + // transaction code + }, + retries: 5, + ); - // Abort the transaction, discarding any data created as part of it - DB::rollBack(); +.. _laravel-transaction-commit: +Begin and Commit a Transaction +------------------------------ -.. note:: +This section shows how to start and commit a transaction. - Transactions in MongoDB cannot be nested. DB::beginTransaction() function - will start new transactions in a new created or existing session and will - raise the RuntimeException when transactions already exist. See more in - MongoDB official docs :manual:`Transactions and Sessions `. +To use this method of starting and committing a transaction, call the +``DB::beginTransaction()`` method to start the transaction. Then, call the +``DB::commit()`` method to end the transaction, which applies all the updates +performed within the transaction. -.. code-block:: php +In the following example, the balance from the first account is moved to the +second account, after which the first account is deleted: - DB::beginTransaction(); - User::create(['name' => 'john', 'age' => 20, 'title' => 'admin']); +.. literalinclude:: /includes/fundamentals/transactions/TransactionsTest.php + :language: php + :dedent: + :emphasize-lines: 1,9 + :start-after: begin commit transaction + :end-before: end commit transaction - // This call to start a nested transaction will raise a RuntimeException - DB::beginTransaction(); - DB::collection('users')->where('name', 'john')->update(['age' => 20]); - DB::commit(); - DB::rollBack(); +.. _laravel-transaction-rollback: -Database Testing ----------------- +Roll Back a Transaction +----------------------- -For testing, the traits ``Illuminate\Foundation\Testing\DatabaseTransactions`` -and ``Illuminate\Foundation\Testing\RefreshDatabase`` are not yet supported. -Instead, create migrations and use the ``DatabaseMigrations`` trait to reset -the database after each test: +This section shows how to roll back a transaction. A rollback reverts all the +write operations performed within that transaction. This means that the +data is reverted to its state before the transaction. -.. code-block:: php +To perform the rollback, call the ``DB::rollback()`` function anytime before +the transaction is committed. + +In the following example, the transaction consists of write operations that +transfer funds from one account, represented by the ``Account`` model, to +multiple other accounts. If the sender account has insufficient funds, the +transaction is rolled back, and none of the models are updated: + +.. literalinclude:: /includes/fundamentals/transactions/TransactionsTest.php + :language: php + :dedent: + :emphasize-lines: 1,18,20 + :start-after: begin rollback transaction + :end-before: end rollback transaction - use Illuminate\Foundation\Testing\DatabaseMigrations; From 61368eff95400586fb31faa60c196c8ef03135c6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 15 Apr 2024 15:31:08 +0200 Subject: [PATCH 234/446] Update phpdoc --- CHANGELOG.md | 1 + src/Queue/Failed/MongoFailedJobProvider.php | 7 ++++--- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 382bee76a..55a84247e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,7 @@ All notable changes to this project will be documented in this file. * New aggregation pipeline builder by @GromNaN in [#2738](https://github.com/mongodb/laravel-mongodb/pull/2738) * Drop support for Composer 1.x by @GromNaN in [#2784](https://github.com/mongodb/laravel-mongodb/pull/2784) +* Fix `artisan query:retry` command by @GromNaN in [#2838](https://github.com/mongodb/laravel-mongodb/pull/2838) ## [4.2.0] - 2024-03-14 diff --git a/src/Queue/Failed/MongoFailedJobProvider.php b/src/Queue/Failed/MongoFailedJobProvider.php index cf72688e2..357f27ddc 100644 --- a/src/Queue/Failed/MongoFailedJobProvider.php +++ b/src/Queue/Failed/MongoFailedJobProvider.php @@ -8,6 +8,7 @@ use DateTimeInterface; use Exception; use Illuminate\Queue\Failed\DatabaseFailedJobProvider; +use MongoDB\BSON\ObjectId; use MongoDB\BSON\UTCDateTime; use function array_map; @@ -86,11 +87,11 @@ public function forget($id) } /** - * Get the IDs of all of the failed jobs. + * Get the IDs of all the failed jobs. * * @param string|null $queue * - * @return list + * @return list */ public function ids($queue = null) { @@ -102,7 +103,7 @@ public function ids($queue = null) } /** - * Prune all entries older than the given date. + * Prune all failed jobs older than the given date. * * @param DateTimeInterface $before * From 274b1c26be9c84829a25f2ae5d2eec1cd24de4e8 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Mon, 15 Apr 2024 13:51:55 -0400 Subject: [PATCH 235/446] 4.1 Write Operations (#2857) * DOCSP-35948: Fundamentals > Write operations --- docs/fundamentals.txt | 25 + .../read-operations.txt} | 7 +- docs/fundamentals/write-operations.txt | 616 ++++++++++++++++++ docs/includes/fact-orderby-id.rst | 6 + .../fundamentals/write-operations/Concert.php | 12 + .../write-operations/WriteOperationsTest.php | 518 +++++++++++++++ docs/index.txt | 5 +- 7 files changed, 1184 insertions(+), 5 deletions(-) create mode 100644 docs/fundamentals.txt rename docs/{retrieve.txt => fundamentals/read-operations.txt} (99%) create mode 100644 docs/fundamentals/write-operations.txt create mode 100644 docs/includes/fact-orderby-id.rst create mode 100644 docs/includes/fundamentals/write-operations/Concert.php create mode 100644 docs/includes/fundamentals/write-operations/WriteOperationsTest.php 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 1447d20a0..4ceafd460 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..242d4e941 --- /dev/null +++ b/docs/fundamentals/write-operations.txt @@ -0,0 +1,616 @@ +.. _laravel-fundamentals-write-ops: + +================ +Write Operations +================ + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :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: + :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` +- :ref:`laravel-fundamentals-modify-documents` +- :ref:`laravel-fundamentals-delete-documents` + +.. _laravel-fundamentals-write-sample-model: + +Sample Model +~~~~~~~~~~~~ + +The write operations in this guide reference the following Eloquent model class: + +.. 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. + +.. _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. + +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 an array of strings to the ``genre`` field +- Assigns a number to the ``ticketsSold`` field +- 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 + :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: + +.. 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 + +.. _laravel-fundamentals-modify-documents: + +Modify Documents +---------------- + +In this section, you can learn how to modify documents in your MongoDB +collection from your Laravel application. Use update operations to modify +existing documents or to insert a document if none match the search +criteria. + +You can persist changes on an instance of an Eloquent model or use +Eloquent's fluent syntax to chain an update operation on methods that +return a Laravel collection object. + +This section provides examples of the following update operations: + +- :ref:`Update a document ` +- :ref:`Update multiple documents ` +- :ref:`Update or insert in a single operation ` +- :ref:`Update arrays in a document ` + +.. _laravel-modify-documents-update-one: + +Update a Document Examples +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can update a document in the following ways: + +- Modify an instance of the model and save the changes by calling the ``save()`` + method. +- Chain methods to retrieve an instance of a model and perform updates on it + by calling the ``update()`` method. + +The following example shows how to update a document by modifying an instance +of the model and calling its ``save()`` method: + +.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php + :language: php + :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. + +If the operation fails, {+odm-short+} assigns the model instance a ``null`` value. + +The following example shows how to update a document by chaining methods to +retrieve and update the first matching document: + +.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php + :language: php + :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. + +.. include:: /includes/fact-orderby-id.rst + +When the ``update()`` method succeeds, the operation returns the number of +documents updated. + +If the retrieve part of the call does not match any documents, {+odm-short+} +returns the following error: + +.. code-block:: none + :copyable: false + + Error: Call to a member function update() on null + +.. _laravel-modify-documents-update-multiple: + +Update Multiple Documents Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To perform an update on one or more documents, chain the ``update()`` +method to the results of a method that retrieves the documents as a +Laravel collection object, such as ``where()``. + +The following example shows how to chain calls to retrieve matching documents +and update them: + +.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php + :language: php + :dedent: + :start-after: begin model update multiple + :end-before: end model update multiple + +When the ``update()`` method succeeds, the operation returns the number of +documents updated. + +If the retrieve part of the call does not match any documents in the +collection, {+odm-short+} returns the following error: + +.. code-block:: none + :copyable: false + + Error: Call to a member function update() on null + +.. _laravel-modify-documents-upsert: + +Update or Insert in a Single Operation +-------------------------------------- + +An **upsert** operation lets you perform an update or insert in a single +operation. This operation streamlines the task of updating a document or +inserting one if it does not exist. + +To specify an upsert in an ``update()`` method, set the ``upsert`` option to +``true`` as shown in the following code example: + +.. code-block:: php + :emphasize-lines: 4 + :copyable: false + + YourModel::where(/* match criteria */) + ->update( + [/* update data */], + ['upsert' => true]); + +When the ``update()`` method is chained to a query, it performs one of the +following actions: + +- If the query matches documents, the ``update()`` method modifies the matching + documents. +- If the query matches zero documents, the ``update()`` method inserts a + document that contains the update data and the equality match criteria data. + +Upsert Example +~~~~~~~~~~~~~~ + +This example shows how to pass the ``upsert`` option to the ``update()`` +method to perform an update or insert in a single operation. Click the +:guilabel:`VIEW OUTPUT` button to see the example document inserted when no +matching documents exist: + +.. io-code-block:: + + .. input:: /includes/fundamentals/write-operations/WriteOperationsTest.php + :language: php + :dedent: + :start-after: begin model upsert + :end-before: end model upsert + + .. output:: + :language: json + :visible: false + + { + "_id": "660c...", + "performer": "Jon Batiste", + "venue": "Radio City Music Hall", + "genres": [ + "R&B", + "soul" + ], + "ticketsSold": 4000, + "updated_at": ... + } + +.. _laravel-modify-documents-arrays: + +Update Arrays in a Document +--------------------------- + +In this section, you can see examples of the following operations that +update array values in a MongoDB document: + +- :ref:`Add values to an array ` +- :ref:`Remove values from an array ` +- :ref:`Update the value of an array element ` + +These examples modify the sample document created by the following insert +operation: + +.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php + :language: php + :dedent: + :start-after: begin array example document + :end-before: end array example document + +.. _laravel-modify-documents-add-array-values: + +Add Values to an Array Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section shows how to use the ``push()`` method to add values to an array +in a MongoDB document. You can pass one or more values to add and set the +optional parameter ``unique`` to ``true`` to skip adding any duplicate values +in the array. The following code example shows the structure of a ``push()`` +method call: + +.. code-block:: none + :copyable: false + + YourModel::where() + ->push( + , + [], // array or single value to add + unique: true); // whether to skip existing values + +The following example shows how to add the value ``"baroque"`` to +the ``genres`` array field of a matching document. Click the +:guilabel:`VIEW OUTPUT` button to see the updated document: + +.. io-code-block:: + + .. input:: /includes/fundamentals/write-operations/WriteOperationsTest.php + :language: php + :dedent: + :start-after: begin model array push + :end-before: end model array push + + .. output:: + :language: json + :visible: false + + { + "_id": "660eb...", + "performer": "Mitsuko Uchida", + "genres": [ + "classical", + "dance-pop", + + ], + "updated_at": ..., + "created_at": ... + } + + +.. _laravel-modify-documents-remove-array-values: + +Remove Values From an Array Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section shows how to use the ``pull()`` method to remove values from +an array in a MongoDB document. You can pass one or more values to remove +from the array. The following code example shows the structure of a +``pull()`` method call: + +.. code-block:: none + :copyable: false + + YourModel::where() + ->pull( + , + []); // array or single value to remove + +The following example shows how to remove array values ``"classical"`` and +``"dance-pop"`` from the ``genres`` array field. Click the +:guilabel:`VIEW OUTPUT` button to see the updated document: + +.. io-code-block:: + + .. input:: /includes/fundamentals/write-operations/WriteOperationsTest.php + :language: php + :dedent: + :start-after: begin model array pull + :end-before: end model array pull + + .. output:: + :language: json + :visible: false + + { + "_id": "660e...", + "performer": "Mitsuko Uchida", + "genres": [], + "updated_at": ..., + "created_at": ... + } + + +.. _laravel-modify-documents-update-array-values: + +Update the Value of an Array Element Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section shows how to use the ``$`` positional operator to update specific +array elements in a MongoDB document. The ``$`` operator represents the first +array element that matches the query. The following code example shows the +structure of a positional operator update call on a single matching document: + + +.. note:: + + Currently, {+odm-short+} offers this operation only on the ``DB`` facade + and not on the Eloquent ORM. + +.. code-block:: none + :copyable: false + + DB::connection('mongodb') + ->getCollection() + ->updateOne( + , + ['$set' => ['.$' => ]]); + + +The following example shows how to replace the array value ``"dance-pop"`` +with ``"contemporary"`` in the ``genres`` array field. Click the +:guilabel:`VIEW OUTPUT` button to see the updated document: + +.. io-code-block:: + + .. input:: /includes/fundamentals/write-operations/WriteOperationsTest.php + :language: php + :dedent: + :start-after: begin model array positional + :end-before: end model array positional + + .. output:: + :language: json + :visible: false + + { + "_id": "660e...", + "performer": "Mitsuko Uchida", + "genres": [ + "classical", + "contemporary" + ], + "updated_at": ..., + "created_at": ... + } + +To learn more about array update operators, see :manual:`Array Update Operators ` +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 ` +- :ref:`Delete multiple documents ` + +To learn about the Laravel features available in {+odm-short+} that modify +delete behavior, see the following sections: + +- :ref:`Soft delete `, which lets you mark + documents as deleted instead of removing them from the database +- :ref:`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``. + diff --git a/docs/includes/fact-orderby-id.rst b/docs/includes/fact-orderby-id.rst new file mode 100644 index 000000000..c2f9981e0 --- /dev/null +++ b/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 ` + glossary entry in the {+server-docs-name+}. diff --git a/docs/includes/fundamentals/write-operations/Concert.php b/docs/includes/fundamentals/write-operations/Concert.php new file mode 100644 index 000000000..69b36b9a5 --- /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..d577ef57b --- /dev/null +++ b/docs/includes/fundamentals/write-operations/WriteOperationsTest.php @@ -0,0 +1,518 @@ +performer = 'Mitsuko Uchida'; + $concert->venue = 'Carnegie Hall'; + $concert->genres = ['classical']; + $concert->ticketsSold = 2121; + $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', + 'genres' => [ 'rock', 'pop', 'blues' ], + 'ticketsSold' => 59527, + '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', + 'genres' => [ 'jazz', 'post-bop' ], + 'ticketsSold' => 5745, + 'performanceDate' => new UTCDateTime(Carbon::create(2025, 2, 12, 20, 0, 0, 'CET')), + ], + [ + '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')), + ], + ]; + + Concert::insert($data); + // end model insert many + + $results = Concert::get(); + + $this->assertEquals(2, count($results)); + } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function testModelUpdateSave(): void + { + require_once __DIR__ . '/Concert.php'; + Concert::truncate(); + + // insert the model + Concert::create([ + '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')), + ]); + + // begin model update one save + $concert = Concert::first(); + $concert->venue = 'Manchester Arena'; + $concert->ticketsSold = 9543; + $concert->save(); + // end model update one save + + $result = Concert::first(); + $this->assertInstanceOf(Concert::class, $result); + + $this->assertNotNull($result); + $this->assertEquals('Manchester Arena', $result->venue); + $this->assertEquals('Brad Mehldau', $result->performer); + $this->assertEquals(9543, $result->ticketsSold); + } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function testModelUpdateFluent(): void + { + require_once __DIR__ . '/Concert.php'; + Concert::truncate(); + + // insert the model + Concert::create([ + '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')), + ]); + + // begin model update one fluent + $concert = Concert::where(['performer' => 'Brad Mehldau']) + ->orderBy('_id') + ->first() + ->update(['venue' => 'Manchester Arena', 'ticketsSold' => 9543]); + // end model update one fluent + + $result = Concert::first(); + $this->assertInstanceOf(Concert::class, $result); + + $this->assertNotNull($result); + $this->assertEquals('Manchester Arena', $result->venue); + $this->assertEquals('Brad Mehldau', $result->performer); + $this->assertEquals(9543, $result->ticketsSold); + } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function testModelUpdateMultiple(): void + { + require_once __DIR__ . '/Concert.php'; + Concert::truncate(); + + // insert the model + Concert::create([ + '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')), + ]); + + Concert::create([ + 'performer' => 'The Rolling Stones', + 'venue' => 'Soldier Field', + 'genres' => [ 'rock', 'pop', 'blues' ], + 'ticketsSold' => 59527, + 'performanceDate' => Carbon::create(2024, 6, 30, 20, 0, 0, 'CDT'), + ]); + // begin model update multiple + Concert::whereIn('venue', ['Philharmonie de Paris', 'Soldier Field']) + ->update(['venue' => 'Concertgebouw', 'ticketsSold' => 0]); + // end model update multiple + + $results = Concert::get(); + + foreach ($results as $result) { + $this->assertInstanceOf(Concert::class, $result); + + $this->assertNotNull($result); + $this->assertEquals('Concertgebouw', $result->venue); + $this->assertEquals(0, $result->ticketsSold); + } + } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function testModelUpsert(): void + { + require_once __DIR__ . '/Concert.php'; + Concert::truncate(); + + // begin model upsert + Concert::where(['performer' => 'Jon Batiste', 'venue' => 'Radio City Music Hall']) + ->update( + ['genres' => ['R&B', 'soul'], 'ticketsSold' => 4000], + ['upsert' => true], + ); + // end model upsert + + $result = Concert::first(); + + $this->assertInstanceOf(Concert::class, $result); + $this->assertEquals('Jon Batiste', $result->performer); + $this->assertEquals(4000, $result->ticketsSold); + } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function testModelPushArray(): void + { + require_once __DIR__ . '/Concert.php'; + Concert::truncate(); + + // begin array example document + Concert::create([ + 'performer' => 'Mitsuko Uchida', + 'genres' => ['classical', 'dance-pop'], + ]); + // end array example document + + // begin model array push + Concert::where('performer', 'Mitsuko Uchida') + ->push( + 'genres', + ['baroque'], + ); + // end model array push + + $result = Concert::first(); + + $this->assertInstanceOf(Concert::class, $result); + $this->assertContains('baroque', $result->genres); + } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function testModelPullArray(): void + { + require_once __DIR__ . '/Concert.php'; + Concert::truncate(); + + Concert::create([ + 'performer' => 'Mitsuko Uchida', + 'genres' => [ 'classical', 'dance-pop' ], + ]); + + // begin model array pull + Concert::where('performer', 'Mitsuko Uchida') + ->pull( + 'genres', + ['dance-pop', 'classical'], + ); + // end model array pull + + $result = Concert::first(); + + $this->assertInstanceOf(Concert::class, $result); + $this->assertEmpty($result->genres); + } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function testModelPositional(): void + { + require_once __DIR__ . '/Concert.php'; + Concert::truncate(); + + Concert::create([ + 'performer' => 'Mitsuko Uchida', + 'genres' => [ 'classical', 'dance-pop' ], + ]); + + // begin model array positional + $match = ['performer' => 'Mitsuko Uchida', 'genres' => 'dance-pop']; + $update = ['$set' => ['genres.$' => 'contemporary']]; + + DB::connection('mongodb') + ->getCollection('concerts') + ->updateOne($match, $update); + // end model array positional + + $result = Concert::first(); + + $this->assertInstanceOf(Concert::class, $result); + $this->assertContains('classical', $result->genres); + $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()); + } +} diff --git a/docs/index.txt b/docs/index.txt index af09ee013..9f6b76483 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -16,7 +16,7 @@ Laravel MongoDB /quick-start /usage-examples Release Notes - /retrieve + /fundamentals /eloquent-models /query-builder /user-authentication @@ -61,7 +61,8 @@ Fundamentals To learn how to perform the following tasks by using {+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` From 6cd08a1511aac57f1948e5ab37725259356c1921 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Mon, 15 Apr 2024 15:20:10 -0400 Subject: [PATCH 236/446] DOCSP-35973: Delete Many usage example (#2837) * DOCSP-35973: Delete Many usage example --- .../usage-examples/DeleteManyTest.php | 42 ++++++++++++ docs/usage-examples.txt | 1 + docs/usage-examples/deleteMany.txt | 68 +++++++++++++++++++ 3 files changed, 111 insertions(+) create mode 100644 docs/includes/usage-examples/DeleteManyTest.php create mode 100644 docs/usage-examples/deleteMany.txt diff --git a/docs/includes/usage-examples/DeleteManyTest.php b/docs/includes/usage-examples/DeleteManyTest.php new file mode 100644 index 000000000..5050f952e --- /dev/null +++ b/docs/includes/usage-examples/DeleteManyTest.php @@ -0,0 +1,42 @@ + 'Train Pulling into a Station', + 'year' => 1896, + ], + [ + 'title' => 'The Ball Game', + 'year' => 1898, + ], + ]); + + // begin-delete-many + $deleted = Movie::where('year', '<=', 1910) + ->delete(); + + echo 'Deleted documents: ' . $deleted; + // end-delete-many + + $this->assertEquals(2, $deleted); + $this->expectOutputString('Deleted documents: 2'); + } +} diff --git a/docs/usage-examples.txt b/docs/usage-examples.txt index 32e876fa7..24eae454f 100644 --- a/docs/usage-examples.txt +++ b/docs/usage-examples.txt @@ -74,3 +74,4 @@ calls the controller function and returns the result to a web interface. /usage-examples/findOne /usage-examples/updateOne /usage-examples/deleteOne + /usage-examples/deleteMany diff --git a/docs/usage-examples/deleteMany.txt b/docs/usage-examples/deleteMany.txt new file mode 100644 index 000000000..ec80f1140 --- /dev/null +++ b/docs/usage-examples/deleteMany.txt @@ -0,0 +1,68 @@ +.. _laravel-delete-many-usage: + +========================= +Delete Multiple Documents +========================= + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: delete many, remove, code example + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +You can delete multiple documents in a collection by calling the ``delete()`` method on an +object collection or a query builder. + +To delete multiple documents, pass a query filter to the ``where()`` method. Then, delete the +matching documents by calling the ``delete()`` method. + +Example +------- + +This usage example performs the following actions: + +- Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the + ``sample_mflix`` database +- Deletes documents from the ``movies`` collection that match a query filter +- Prints the number of deleted documents + +The example calls the following methods on the ``Movie`` model: + +- ``where()``: matches documents in which the value of the ``year`` field is less than or + equal to ``1910``. +- ``delete()``: deletes the retrieved documents. This method returns the number of documents + that were successfully deleted. + +.. io-code-block:: + :copyable: true + + .. input:: ../includes/usage-examples/DeleteManyTest.php + :start-after: begin-delete-many + :end-before: end-delete-many + :language: php + :dedent: + + .. output:: + :language: console + :visible: false + + Deleted documents: 7 + +To learn how to edit your Laravel application to run the usage example, see the +:ref:`Usage Examples landing page `. + +.. tip:: + + To learn more about deleting documents with {+odm-short+}, see the :ref:`laravel-fundamentals-delete-documents` + section of the Write Operations guide. + + For more information about query filters, see the :ref:`laravel-retrieve-matching` section of + the Read Operations guide. + From 93727cdae0034ab63b07b803d54ad641ac2e4b0e Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Mon, 15 Apr 2024 17:35:42 -0400 Subject: [PATCH 237/446] DOCSP-35934: databases and collections (#2816) * DOCSP-35934: db and coll * add sections * small fixes * CC and DBX feedback * tech review fixes and CC suggestions * small fixes --- docs/eloquent-models/schema-builder.txt | 4 + docs/fundamentals/database-collection.txt | 179 ++++++++++++++++++++++ 2 files changed, 183 insertions(+) create mode 100644 docs/fundamentals/database-collection.txt diff --git a/docs/eloquent-models/schema-builder.txt b/docs/eloquent-models/schema-builder.txt index 39c6a9887..c6c7e64cc 100644 --- a/docs/eloquent-models/schema-builder.txt +++ b/docs/eloquent-models/schema-builder.txt @@ -54,6 +54,10 @@ your database schema by running methods included in the ``Schema`` facade. The following sections explain how to author a migration class when you use a MongoDB database and how to run them. +Modifying databases and collections from within a migration provides a +controlled approach that ensures consistency, version control, and reversibility in your +application. + Create a Migration Class ~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/fundamentals/database-collection.txt b/docs/fundamentals/database-collection.txt new file mode 100644 index 000000000..db74b045b --- /dev/null +++ b/docs/fundamentals/database-collection.txt @@ -0,0 +1,179 @@ +.. _laravel-db-coll: + +========================= +Databases and Collections +========================= + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: php framework, odm + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to use {+odm-short+} to access +and manage MongoDB databases and collections. + +MongoDB organizes data in a hierarchical structure. A MongoDB +deployment contains one or more **databases**, and each database +contains one or more **collections**. In each collection, MongoDB stores +data as **documents** that contain field-and-value pairs. In +{+odm-short+}, you can access documents through Eloquent models. + +To learn more about the document data format, +see :manual:`Documents ` in the Server manual. + +.. _laravel-access-db: + +Specify the Database in a Connection Configuration +-------------------------------------------------- + +You can specify a database name that a connection uses in your +application's ``config/database.php`` file. The ``connections`` property +in this file stores all of your database connection information, such as +your connection string, database name, and optionally, authentication +details. After you specify a database connection, you can perform +database-level operations and access collections that the database +contains. + +If you set the database name in the ``database`` property to the name of a +nonexistent database, Laravel still makes a valid connection. When you +insert any data into a collection in the database, the server creates it +automatically. + +The following example shows how to set a default database connection and +create a database connection to the ``animals`` database in the +``config/database.php`` file by setting the ``dsn`` and ``database`` properties: + +.. code-block:: php + :emphasize-lines: 1,8 + + 'default' => 'mongodb', + + 'connections' => [ + + 'mongodb' => [ + 'driver' => 'mongodb', + 'dsn' => 'mongodb://localhost:27017/', + 'database' => 'animals', + ], ... + ] + +When you set a default database connection, {+odm-short+} uses that +connection for operations, but you can specify multiple database connections +in your ``config/database.php`` file. + +The following example shows how to specify multiple database connections +(``mongodb`` and ``mongodb_alt``) to access the ``animals`` and +``plants`` databases: + +.. code-block:: php + + 'connections' => [ + + 'mongodb' => [ + 'driver' => 'mongodb', + 'dsn' => 'mongodb://localhost:27017/', + 'database' => 'animals', + ], + + 'mongodb_alt' => [ + 'driver' => 'mongodb', + 'dsn' => 'mongodb://localhost:27017/', + 'database' => 'plants', + ] + + ], ... + +.. note:: + + The MongoDB PHP driver reuses the same connection when + you create two clients with the same connection string. There is no + overhead in using two connections for two distinct databases, so you + do not need to optimize your connections. + +If your application contains multiple database connections and you want +to store your model in a database other than the default, override the +``$connection`` property in your ``Model`` class. + +The following example shows how to override the ``$connection`` property +on the ``Flower`` model class to use the ``mongodb_alt`` connection. +This directs {+odm-short+} to store the model in the ``flowers`` +collection of the ``plants`` database, instead of in the default database: + +.. code-block:: php + + class Flower extends Model + { + protected $connection = 'mongodb_alt'; + } + +.. _laravel-access-coll: + +Access a Collection +------------------- + +When you create model class that extends +``MongoDB\Laravel\Eloquent\Model``, {+odm-short+} stores the model data +in a collection with a name formatted as the snake case plural form of your +model class name. + +For example, if you create a model class called ``Flower``, +Laravel applies the model to the ``flowers`` collection in the database. + +.. tip:: + + To learn how to specify a different collection name in your model class, see the + :ref:`laravel-model-customize-collection-name` section of the Eloquent + Model Class guide. + +We generally recommend that you use the Eloquent ORM to access a collection +for code readability and maintainability. The following +example specifies a find operation by using the ``Flower`` class, so +Laravel retrieves results from the ``flowers`` collection: + +.. code-block:: php + + Flower::where('name', 'Water Lily')->get() + +If you are unable to accomplish your operation by using an Eloquent +model, you can access the query builder by calling the ``collection()`` +method on the ``DB`` facade. The following example shows the same query +as in the preceding example, but the query is constructed by using the +``DB::collection()`` method: + +.. code-block:: php + + DB::connection('mongodb') + ->collection('flowers') + ->where('name', 'Water Lily') + ->get() + +List Collections +---------------- + +To see information about each of the collections in a database, call the +``listCollections()`` method. + +The following example accesses a database connection, then +calls the ``listCollections()`` method to retrieve information about the +collections in the database: + +.. code-block:: php + + $collections = DB::connection('mongodb')->getMongoDB()->listCollections(); + +Create and Drop Collections +--------------------------- + +To learn how to create and drop collections, see the +:ref:`laravel-eloquent-migrations` section in the Schema Builder guide. From 6e5e49f575a92d33744f754b42d99528fcf8d02d Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Mon, 15 Apr 2024 17:53:33 -0400 Subject: [PATCH 238/446] Add toc changes for db and coll docs (#2863) --- docs/fundamentals.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/fundamentals.txt b/docs/fundamentals.txt index 041388350..f9e26b772 100644 --- a/docs/fundamentals.txt +++ b/docs/fundamentals.txt @@ -15,11 +15,13 @@ Fundamentals :titlesonly: :maxdepth: 1 + /fundamentals/database-collection /fundamentals/read-operations /fundamentals/write-operations Learn how to use the {+odm-long+} to perform the following tasks: +- :ref:`Manage Databases and Collections ` - :ref:`Read Operations ` - :ref:`Write Operations ` From 00d39319bbb49ef29982c0b6863ac11387bcdb18 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Mon, 15 Apr 2024 22:17:49 -0400 Subject: [PATCH 239/446] DOCSP-35982: Count usage example (#2850) * DOCSP-35982: Count usage example --- docs/includes/usage-examples/CountTest.php | 42 ++++++++++++++++ docs/usage-examples.txt | 1 + docs/usage-examples/count.txt | 57 ++++++++++++++++++++++ 3 files changed, 100 insertions(+) create mode 100644 docs/includes/usage-examples/CountTest.php create mode 100644 docs/usage-examples/count.txt diff --git a/docs/includes/usage-examples/CountTest.php b/docs/includes/usage-examples/CountTest.php new file mode 100644 index 000000000..ecf53db47 --- /dev/null +++ b/docs/includes/usage-examples/CountTest.php @@ -0,0 +1,42 @@ + 'Young Mr. Lincoln', + 'genres' => ['Biography', 'Drama'], + ], + [ + 'title' => 'Million Dollar Mermaid', + 'genres' => ['Biography', 'Drama', 'Musical'], + ], + ]); + + // begin-count + $count = Movie::where('genres', 'Biography') + ->count(); + + echo 'Number of documents: ' . $count; + // end-count + + $this->assertEquals(2, $count); + $this->expectOutputString('Number of documents: 2'); + } +} diff --git a/docs/usage-examples.txt b/docs/usage-examples.txt index 24eae454f..a4015031a 100644 --- a/docs/usage-examples.txt +++ b/docs/usage-examples.txt @@ -75,3 +75,4 @@ calls the controller function and returns the result to a web interface. /usage-examples/updateOne /usage-examples/deleteOne /usage-examples/deleteMany + /usage-examples/count diff --git a/docs/usage-examples/count.txt b/docs/usage-examples/count.txt new file mode 100644 index 000000000..dc3720fc0 --- /dev/null +++ b/docs/usage-examples/count.txt @@ -0,0 +1,57 @@ +.. _laravel-count-usage: + +=============== +Count Documents +=============== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: total, code example + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +You can count the number of documents returned by a query by calling the ``where()`` and +``count()`` methods on a collection of models or a query builder. + +To return the number of documents that match a filter, pass the query filter to the ``where()`` +method and call the ``count()`` method. + +Example +------- + +This usage example performs the following actions: + +- Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the + ``sample_mflix`` database +- Counts the documents from the ``movies`` collection that match a query filter +- Prints the matching document count + +The example calls the following methods on the ``Movie`` model: + +- ``where()``: Matches documents in which the value of the ``genres`` field includes ``"Biography"``. +- ``count()``: Counts the number of matching documents. This method returns an integer value. + +.. io-code-block:: + + .. input:: ../includes/usage-examples/CountTest.php + :start-after: begin-count + :end-before: end-count + :language: php + :dedent: + + .. output:: + :language: console + :visible: false + + Matching documents: 1267 + + +To learn how to edit your Laravel application to run the usage example, see the +:ref:`Usage Examples landing page `. From 1a6b596057a032417e647df791de3e552940155f Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Mon, 15 Apr 2024 22:29:36 -0400 Subject: [PATCH 240/446] DOCSP-35972: Distinct values usage example (#2846) * DOCSP-35972: Distinct values usage example --- docs/includes/usage-examples/DistinctTest.php | 59 ++++++++++++++++ docs/usage-examples.txt | 2 + docs/usage-examples/distinct.txt | 67 +++++++++++++++++++ 3 files changed, 128 insertions(+) create mode 100644 docs/includes/usage-examples/DistinctTest.php create mode 100644 docs/usage-examples/distinct.txt diff --git a/docs/includes/usage-examples/DistinctTest.php b/docs/includes/usage-examples/DistinctTest.php new file mode 100644 index 000000000..0b7812241 --- /dev/null +++ b/docs/includes/usage-examples/DistinctTest.php @@ -0,0 +1,59 @@ + 'Marie Antoinette', + 'directors' => ['Sofia Coppola'], + 'imdb' => [ + 'rating' => 6.4, + 'votes' => 74350, + ], + ], + [ + 'title' => 'Somewhere', + 'directors' => ['Sofia Coppola'], + 'imdb' => [ + 'rating' => 6.4, + 'votes' => 33753, + ], + ], + [ + 'title' => 'Lost in Translation', + 'directors' => ['Sofia Coppola'], + 'imdb' => [ + 'rating' => 7.8, + 'votes' => 298747, + ], + ], + ]); + + // begin-distinct + $ratings = Movie::where('directors', 'Sofia Coppola') + ->select('imdb.rating') + ->distinct() + ->get(); + + echo $ratings; + // end-distinct + + $this->expectOutputString('[[6.4],[7.8]]'); + } +} diff --git a/docs/usage-examples.txt b/docs/usage-examples.txt index a4015031a..fbe5eaae6 100644 --- a/docs/usage-examples.txt +++ b/docs/usage-examples.txt @@ -76,3 +76,5 @@ calls the controller function and returns the result to a web interface. /usage-examples/deleteOne /usage-examples/deleteMany /usage-examples/count + /usage-examples/distinct + \ No newline at end of file diff --git a/docs/usage-examples/distinct.txt b/docs/usage-examples/distinct.txt new file mode 100644 index 000000000..8765bea1b --- /dev/null +++ b/docs/usage-examples/distinct.txt @@ -0,0 +1,67 @@ +.. _laravel-distinct-usage: + +============================== +Retrieve Distinct Field Values +============================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: unique, different, code example + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +You can retrieve distinct field values of documents in a collection by calling the ``distinct()`` +method on an object collection or a query builder. + +To retrieve distinct field values, pass a query filter to the ``where()`` method and a field name +to the ``select()`` method. Then, call ``distinct()`` to return the unique values of the selected +field in documents that match the query filter. + +Example +------- + +This usage example performs the following actions: + +- Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the + ``sample_mflix`` database +- Retrieves distinct field values of documents from the ``movies`` collection that match a query filter +- Prints the distinct values + +The example calls the following methods on the ``Movie`` model: + +- ``where()``: matches documents in which the value of the ``directors`` field includes ``'Sofia Coppola'``. +- ``select()``: retrieves the matching documents' ``imdb.rating`` field values. +- ``distinct()``: accesses the unique values of the ``imdb.rating`` field among the matching + documents. This method returns a list of values. +- ``get()``: retrieves the query results. + +.. io-code-block:: + :copyable: true + + .. input:: ../includes/usage-examples/DistinctTest.php + :start-after: begin-distinct + :end-before: end-distinct + :language: php + :dedent: + + .. output:: + :language: console + :visible: false + + [[5.6],[6.4],[7.2],[7.8]] + +To learn how to edit your Laravel application to run the usage example, see the +:ref:`Usage Examples landing page `. + +.. tip:: + + For more information about query filters, see the :ref:`laravel-retrieve-matching` section of + the Read Operations guide. + From 2f929ddfde015157357be3b6a0a213e06aaac316 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Mon, 15 Apr 2024 22:44:35 -0400 Subject: [PATCH 241/446] DOCSP-35978: Insert multiple usage example (#2849) * DOCSP-35978: Insert multiple usage example --- .../usage-examples/InsertManyTest.php | 46 ++++++++++++++ docs/usage-examples.txt | 2 +- docs/usage-examples/insertMany.txt | 63 +++++++++++++++++++ 3 files changed, 110 insertions(+), 1 deletion(-) create mode 100644 docs/includes/usage-examples/InsertManyTest.php create mode 100644 docs/usage-examples/insertMany.txt diff --git a/docs/includes/usage-examples/InsertManyTest.php b/docs/includes/usage-examples/InsertManyTest.php new file mode 100644 index 000000000..e1bf4539a --- /dev/null +++ b/docs/includes/usage-examples/InsertManyTest.php @@ -0,0 +1,46 @@ + 'Anatomy of a Fall', + 'release_date' => new UTCDateTime(new DateTimeImmutable('2023-08-23')), + ], + [ + 'title' => 'The Boy and the Heron', + 'release_date' => new UTCDateTime(new DateTimeImmutable('2023-12-08')), + ], + [ + 'title' => 'Passages', + 'release_date' => new UTCDateTime(new DateTimeImmutable('2023-06-28')), + ], + ]); + + echo 'Insert operation success: ' . ($success ? 'yes' : 'no'); + // end-insert-many + + $this->assertTrue($success); + $this->expectOutputString('Insert operation success: yes'); + } +} diff --git a/docs/usage-examples.txt b/docs/usage-examples.txt index fbe5eaae6..899655924 100644 --- a/docs/usage-examples.txt +++ b/docs/usage-examples.txt @@ -72,9 +72,9 @@ calls the controller function and returns the result to a web interface. :maxdepth: 1 /usage-examples/findOne + /usage-examples/insertMany /usage-examples/updateOne /usage-examples/deleteOne /usage-examples/deleteMany /usage-examples/count /usage-examples/distinct - \ No newline at end of file diff --git a/docs/usage-examples/insertMany.txt b/docs/usage-examples/insertMany.txt new file mode 100644 index 000000000..bf771aa8d --- /dev/null +++ b/docs/usage-examples/insertMany.txt @@ -0,0 +1,63 @@ +.. _laravel-insert-many-usage: + +========================= +Insert Multiple Documents +========================= + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: insert many, add, create, bulk, code example + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +You can insert multiple documents into a collection by calling the ``insert()`` +method on an Eloquent model or a query builder. + +To insert multiple documents, call the ``insert()`` method and specify the new documents +as an array inside the method call. Each array entry contains a single document's field +values. + +Example +------- + +This usage example performs the following actions: + +- Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the + ``sample_mflix`` database +- Inserts documents into the ``movies`` collection +- Prints the result of the insert operation + +The example calls the ``insert()`` method to insert documents that represent movies released +in 2023. This method returns a value of ``1`` if the operation is successful, and it throws +an exception if the operation is unsuccessful. + +.. io-code-block:: + :copyable: true + + .. input:: ../includes/usage-examples/InsertManyTest.php + :start-after: begin-insert-many + :end-before: end-insert-many + :language: php + :dedent: + + .. output:: + :language: console + :visible: false + + Insert operation success: yes + +To learn how to edit your Laravel application to run the usage example, see the +:ref:`Usage Examples landing page `. + +.. tip:: + + To learn more about insert operations, see the :ref:`laravel-fundamentals-insert-documents` section + of the Write Operations guide. + From f83541dcf266d6e78bafba2c21192dfc9ce04600 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Thu, 18 Apr 2024 10:42:15 -0400 Subject: [PATCH 242/446] DOCSP-35954: cleanup (#2878) * DOCSP-35954: cleanup * CC suggestion --- docs/index.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/index.txt b/docs/index.txt index 9f6b76483..e1331f6a2 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -61,6 +61,7 @@ Fundamentals To learn how to perform the following tasks by using {+odm-short+}, see the following content: +- :ref:`Manage Databases and Collections ` - :ref:`laravel-fundamentals-read-ops` - :ref:`laravel-fundamentals-write-ops` - :ref:`laravel-eloquent-models` @@ -75,6 +76,12 @@ Issues & Help Learn how to report bugs, contribute to the library, and find more resources in the :ref:`laravel-issues-and-help` section. +Feature Compatibility +--------------------- + +Learn about Laravel features that {+odm-short+} supports in the +:ref:`laravel-feature-compat` section. + Compatibility ------------- From 8bc235c6e1ce5f6cd7363105768b4fbf41bb56a3 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Thu, 18 Apr 2024 19:08:16 -0400 Subject: [PATCH 243/446] DOCSP-35937 aggregations builder 4.3 (#2876) * DOCSP-35937: aggregation builder page --- docs/fundamentals.txt | 2 + docs/fundamentals/aggregation-builder.txt | 515 ++++++++++++++++++ .../aggregation/AggregationsBuilderTest.php | 135 +++++ docs/index.txt | 1 + 4 files changed, 653 insertions(+) create mode 100644 docs/fundamentals/aggregation-builder.txt create mode 100644 docs/includes/fundamentals/aggregation/AggregationsBuilderTest.php diff --git a/docs/fundamentals.txt b/docs/fundamentals.txt index f9e26b772..291947c5f 100644 --- a/docs/fundamentals.txt +++ b/docs/fundamentals.txt @@ -18,10 +18,12 @@ Fundamentals /fundamentals/database-collection /fundamentals/read-operations /fundamentals/write-operations + /fundamentals/aggregation-builder Learn how to use the {+odm-long+} to perform the following tasks: - :ref:`Manage Databases and Collections ` - :ref:`Read Operations ` - :ref:`Write Operations ` +- :ref:`Create Aggregation Pipelines by Using the Aggregation Builder ` diff --git a/docs/fundamentals/aggregation-builder.txt b/docs/fundamentals/aggregation-builder.txt new file mode 100644 index 000000000..0fc55bcf4 --- /dev/null +++ b/docs/fundamentals/aggregation-builder.txt @@ -0,0 +1,515 @@ +.. _laravel-aggregation-builder: + +=================== +Aggregation Builder +=================== + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :keywords: code example, pipeline, expression + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to perform aggregations and construct +pipelines by using the {+odm-short+} aggregation builder. The aggregation +builder lets you use a type-safe syntax to construct a MongoDB +**aggregation pipeline**. + +An aggregation pipeline is a data processing pipeline that sequentially +performs transformations and computations on data from the MongoDB database, +then outputs the results as a new document or set of documents. + +An aggregation pipeline is composed of **aggregation stages**. Aggregation +stages use operators to process input data and produce data that the next +stage uses as its input. + +The {+odm-short+} aggregation builder lets you build aggregation stages and +aggregation pipelines. The following sections show examples of how to use the +aggregation builder to create the stages of an aggregation pipeline: + +- :ref:`laravel-add-aggregation-dependency` +- :ref:`laravel-build-aggregation` +- :ref:`laravel-create-custom-operator-factory` + +.. tip:: + + The aggregation builder feature is available only in {+odm-short+} versions + 4.3 and later. To learn more about running aggregations without using the + aggregation builder, see :ref:`laravel-query-builder-aggregations` in the + Query Builder guide. + +.. _laravel-add-aggregation-dependency: + +Add the Aggregation Builder Dependency +-------------------------------------- + +The aggregation builder is part of the {+agg-builder-package-name+} package. +You must add this package as a dependency to your project to use it. Run the +following command to add the aggregation builder dependency to your +application: + +.. code-block:: bash + + composer require {+agg-builder-package-name+}:{+agg-builder-version+} + +When the installation completes, verify that the ``composer.json`` file +includes the following line in the ``require`` object: + +.. code-block:: json + + "{+agg-builder-package-name+}": "{+agg-builder-version+}", + +.. _laravel-build-aggregation: + +Create an Aggregation Pipeline +------------------------------ + +To start an aggregation pipeline, call the ``Model::aggregate()`` method. +Then, chain the aggregation stage methods in the sequence you want them to +run. + +The aggregation builder includes the following namespaces that you can import +to build aggregation stages: + +- ``MongoDB\Builder\Accumulator`` +- ``MongoDB\Builder\Expression`` +- ``MongoDB\Builder\Query`` +- ``MongoDB\Builder\Type`` + +.. tip:: + + To learn more about builder classes, see the `mongodb/mongodb-php-builder `__ + GitHub repository. + +This section features the following examples, which show how to use common +aggregation stages and combine stages to build an aggregation pipeline: + +- :ref:`laravel-aggregation-match-stage-example` +- :ref:`laravel-aggregation-group-stage-example` +- :ref:`laravel-aggregation-sort-stage-example` +- :ref:`laravel-aggregation-project-stage-example` +- :ref:`laravel-aggregation-pipeline-example` + +To learn more about MongoDB aggregation operators, see +:manual:`Aggregation Stages ` in +the {+server-docs-name+}. + +Sample Documents +~~~~~~~~~~~~~~~~ + +The following examples run aggregation pipelines on a collection represented +by the ``User`` model. You can add the sample data by running the following +``insert()`` method: + +.. literalinclude:: /includes/fundamentals/aggregation/AggregationsBuilderTest.php + :language: php + :dedent: + :start-after: begin aggregation builder sample data + :end-before: end aggregation builder sample data + +.. _laravel-aggregation-match-stage-example: + +Match Stage Example +~~~~~~~~~~~~~~~~~~~ + +You can chain the ``match()`` method to your aggregation pipeline to specify +a query filter. If you omit this stage, the ``aggregate()`` method outputs +all the documents in the model's collection for the following stage. + +This aggregation stage is often placed first to retrieve the data by using +available indexes and reduce the amount of data the subsequent stages process. + +.. tip:: + + If you omit the ``match()`` method, the aggregation pipeline matches all + documents in the collection that correspond to the model before other + aggregation stages. + +This example constructs a query filter for a **match** aggregation stage by +using the ``MongoDB\Builder\Query`` builder. The match stage includes the the +following criteria: + +- Returns results that match either of the query filters by using the + ``Query::or()`` function +- Matches documents that contain an ``occupation`` field with a value of + ``"designer"`` by using the ``Query::query()`` and ``Query::eq()`` functions +- Matches documents that contain a ``name`` field with a value of + ``"Eliud Nkosana"`` by using the ``Query::query()`` and ``Query::eq()`` + functions + +Click the :guilabel:`{+code-output-label+}` button to see the documents +returned by running the code: + +.. io-code-block:: + + .. input:: /includes/fundamentals/aggregation/AggregationsBuilderTest.php + :language: php + :dedent: + :start-after: begin aggregation match stage + :end-before: end aggregation match stage + + .. output:: + :language: json + :visible: false + + [ + { + "_id": ..., + "name": "Janet Doe", + "occupation": "designer", + "birthday": { + "$date": { + "$numberLong": "541728000000" + } + } + }, + { + "_id": ..., + "name": "Eliud Nkosana", + "occupation": "engineer", + "birthday": { + "$date": { + "$numberLong": "449884800000" + } + } + }, + { + "_id": ..., + "name": "Ellis Lee", + "occupation": "designer", + "birthday": { + "$date": { + "$numberLong": "834019200000" + } + } + } + ] + +.. tip:: + + The ``Query::or()`` function corresponds to the ``$or`` MongoDB query operator. + To learn more about this operator, see :manual:`$or ` + in the {+server-docs-name+}. + +.. _laravel-aggregation-group-stage-example: + +Group Stage Example +~~~~~~~~~~~~~~~~~~~ + +You can chain the ``group()`` method to your aggregation pipeline to modify the +structure of the data by performing calculations and grouping it by common +field values. + +This aggregation stage is often placed immediately after a match stage to +reduce the data subsequent stages process. + +This example uses the ``MongoDB\Builder\Expression`` builder to define the group keys in a +**group** aggregation stage. The group stage specifies the following grouping +behavior: + +- Sets the value of the group key, represented by the ``_id`` field, to the + field value defined by the ``Expression`` builder +- References the document values in the ``occupation`` field by calling the + ``Expression::fieldPath()`` function + +Click the :guilabel:`{+code-output-label+}` button to see the documents +returned by running the code: + +.. io-code-block:: + + .. input:: /includes/fundamentals/aggregation/AggregationsBuilderTest.php + :language: php + :dedent: + :start-after: begin aggregation group stage + :end-before: end aggregation group stage + + .. output:: + :language: json + :visible: false + + [ + { "_id": "engineer" }, + { "_id": "designer" } + ] + +.. tip:: + + This example stage performs a similar task as the ``distinct()`` query + builder method. To learn more about the ``distinct()`` method, see the + :ref:`laravel-distinct-usage` usage example. + +.. _laravel-aggregation-sort-stage-example: + +Sort Stage Example +~~~~~~~~~~~~~~~~~~ + +You can chain the ``sort()`` method to your aggregation pipeline to specify +the documents' output order. + +You can add this aggregation stage anywhere in the pipeline. It is often +placed after the group stage since it can depend on the grouped data. We +recommend placing the sort stage as late as possible in the pipeline to limit +the data it processes. + +To specify an sort, set the field value to the ``Sort::Asc`` enum for an +ascending sort or the ``Sort::Desc`` enum for a descending sort. + +This example shows a ``sort()`` aggregation pipeline stage that sorts the +documents by the ``name`` field to ``Sort::Desc``, corresponding to reverse +alphabetical order. Click the :guilabel:`{+code-output-label+}` button to see +the documents returned by running the code: + +.. io-code-block:: + + .. input:: /includes/fundamentals/aggregation/AggregationsBuilderTest.php + :language: php + :dedent: + :start-after: begin aggregation sort stage + :end-before: end aggregation sort stage + + .. output:: + :language: json + :visible: false + + [ + { + "_id": ..., + "name": "Janet Doe", + "occupation": "designer", + "birthday": { + "$date": { + "$numberLong": "541728000000" + } + } + }, + { + "_id": ..., + "name": "Francois Soma", + "occupation": "engineer", + "birthday": { + "$date": { + "$numberLong": "886377600000" + } + } + }, + { + "_id": ..., + "name": "Ellis Lee", + "occupation": "designer", + "birthday": { + "$date": { + "$numberLong": "834019200000" + } + } + }, + { + "_id": ..., + "name": "Eliud Nkosana", + "occupation": "engineer", + "birthday": { + "$date": { + "$numberLong": "449884800000" + } + } + }, + { + "_id": ..., + "name": "Bran Steafan", + "occupation": "engineer", + "birthday": { + "$date": { + "$numberLong": "894326400000" + } + } + }, + { + "_id": ..., + "name": "Alda Gröndal", + "occupation": "engineer", + "birthday": { + "$date": { + "$numberLong": "1009843200000" + } + } + } + ] + +.. _laravel-aggregation-project-stage-example: + +Project Stage Example +~~~~~~~~~~~~~~~~~~~~~ + +You can chain the ``project()`` method to your aggregation pipeline to specify +which fields from the documents to display by this stage. + +To specify fields to include, pass the name of a field and a truthy value, +such as ``1`` or ``true``. All other fields are omitted from the output. + +Alternatively, to specify fields to exclude, pass each field name and +a falsy value, such as ``0`` or ``false``. All other fields are included in +the output. + +.. tip:: + + When you specify fields to include, the ``_id`` field is included by default. + To exclude the ``_id`` field, explicitly exclude it in the projection stage. + +This example shows how to use the ``project()`` method aggregation stage to +include only the ``name`` field and exclude all other fields from the output. +Click the :guilabel:`{+code-output-label+}` button to see the data returned by +running the code: + +.. io-code-block:: + + .. input:: /includes/fundamentals/aggregation/AggregationsBuilderTest.php + :language: php + :dedent: + :start-after: begin aggregation project stage + :end-before: end aggregation project stage + + .. output:: + :language: json + :visible: false + + [ + { "name": "Alda Gröndal" }, + { "name": "Francois Soma" }, + { "name": "Janet Doe" }, + { "name": "Eliud Nkosana" }, + { "name": "Bran Steafan" }, + { "name": "Ellis Lee" } + ] + + +.. _laravel-aggregation-pipeline-example: + +Aggregation Pipeline Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This aggregation pipeline example chains multiple stages. Each stage runs +on the output retrieved from each preceding stage. In this example, the +stages perform the following operations sequentially: + +- Add the ``birth_year`` field to the documents and set the value to the year + extracted from the ``birthday`` field. +- Group the documents by the value of the ``occupation`` field and compute + the average value of ``birth_year`` for each group by using the + ``Accumulator::avg()`` function. Assign to result of the computation to + the ``birth_year_avg`` field. +- Sort the documents by the group key field in ascending order. +- Create the ``profession`` field from the value of the group key field, + include the ``birth_year_avg`` field, and omit the ``_id`` field. + +Click the :guilabel:`{+code-output-label+}` button to see the data returned by +running the code: + +.. io-code-block:: + + .. input:: /includes/fundamentals/aggregation/AggregationsBuilderTest.php + :language: php + :dedent: + :start-after: begin pipeline example + :end-before: end pipeline example + + .. output:: + :language: json + :visible: false + + [ + { + "birth_year_avg": 1991.5, + "profession": "designer" + }, + { + "birth_year_avg": 1995.5, + "profession": "engineer" + } + ] + +.. note:: + + Since this pipeline omits the ``match()`` stage, the input for the initial + stage consists of all the documents in the collection. + +.. _laravel-create-custom-operator-factory: + +Create a Custom Operator Factory +-------------------------------- + +When using the aggregation builder to create an aggregation pipeline, you +can define operations or stages in a **custom operator factory**. A custom +operator factory is a function that returns expressions or stages of an +aggregation pipeline. You can create these functions to improve code +readability and reuse. + +This example shows how to create and use a custom operator factory that +returns expressions that extract the year from a specified date field. + +The following function accepts the name of a field that contains a date +and returns an expression that extracts the year from the date: + +.. literalinclude:: /includes/fundamentals/aggregation/AggregationsBuilderTest.php + :language: php + :dedent: + :start-after: start custom operator factory function + :end-before: end custom operator factory function + +The example aggregation pipeline includes the following stages: + +- ``addFields()``, which calls the custom operator factory function to extract + the year from the ``birthday`` field and assign it to the ``birth_year`` field +- ``project()``, which includes only the ``name`` and ``birth_year`` fields in + its output + +Click the :guilabel:`{+code-output-label+}` button to see the data returned by +running the code: + +.. io-code-block:: + + .. input:: /includes/fundamentals/aggregation/AggregationsBuilderTest.php + :language: php + :dedent: + :start-after: begin custom operator factory usage + :end-before: end custom operator factory usage + + .. output:: + :language: json + :visible: false + + [ + { + "name": "Alda Gröndal", + "birth_year": 2002 + }, + { + "name": "Francois Soma", + "birth_year": 1998 + }, + { + "name": "Janet Doe", + "birth_year": 1987 + }, + { + "name": "Eliud Nkosana", + "birth_year": 1984 + }, + { + "name": "Bran Steafan", + "birth_year": 1998 + }, + { + "name": "Ellis Lee", + "birth_year": 1996 + } + ] + diff --git a/docs/includes/fundamentals/aggregation/AggregationsBuilderTest.php b/docs/includes/fundamentals/aggregation/AggregationsBuilderTest.php new file mode 100644 index 000000000..4880ee75f --- /dev/null +++ b/docs/includes/fundamentals/aggregation/AggregationsBuilderTest.php @@ -0,0 +1,135 @@ + 'Alda Gröndal', 'occupation' => 'engineer', 'birthday' => new UTCDateTime(new DateTimeImmutable('2002-01-01'))], + ['name' => 'Francois Soma', 'occupation' => 'engineer', 'birthday' => new UTCDateTime(new DateTimeImmutable('1998-02-02'))], + ['name' => 'Janet Doe', 'occupation' => 'designer', 'birthday' => new UTCDateTime(new DateTimeImmutable('1987-03-03'))], + ['name' => 'Eliud Nkosana', 'occupation' => 'engineer', 'birthday' => new UTCDateTime(new DateTimeImmutable('1984-04-04'))], + ['name' => 'Bran Steafan', 'occupation' => 'engineer', 'birthday' => new UTCDateTime(new DateTimeImmutable('1998-05-05'))], + ['name' => 'Ellis Lee', 'occupation' => 'designer', 'birthday' => new UTCDateTime(new DateTimeImmutable('1996-06-06'))], + ]); + // end aggregation builder sample data + } + + public function testAggregationBuilderMatchStage(): void + { + // begin aggregation match stage + $pipeline = User::aggregate() + ->match(Query::or( + Query::query(occupation: Query::eq('designer')), + Query::query(name: Query::eq('Eliud Nkosana')), + )); + $result = $pipeline->get(); + // end aggregation match stage + + $this->assertEquals(3, $result->count()); + } + + public function testAggregationBuilderGroupStage(): void + { + // begin aggregation group stage + $pipeline = User::aggregate() + ->group(_id: Expression::fieldPath('occupation')); + $result = $pipeline->get(); + // end aggregation group stage + + $this->assertEquals(2, $result->count()); + } + + public function testAggregationBuilderSortStage(): void + { + // begin aggregation sort stage + $pipeline = User::aggregate() + ->sort(name: Sort::Desc); + $result = $pipeline->get(); + // end aggregation sort stage + + $this->assertEquals(6, $result->count()); + $this->assertEquals('Janet Doe', $result->first()['name']); + } + + public function testAggregationBuilderProjectStage(): void + { + // begin aggregation project stage + $pipeline = User::aggregate() + ->project(_id: 0, name: 1); + $result = $pipeline->get(); + // end aggregation project stage + + $this->assertEquals(6, $result->count()); + $this->assertNotNull($result->first()['name']); + $this->assertArrayNotHasKey('_id', $result->first()); + } + + public function testAggregationBuilderPipeline(): void + { + // begin pipeline example + $pipeline = User::aggregate() + ->addFields( + birth_year: Expression::year( + Expression::dateFieldPath('birthday'), + ), + ) + ->group( + _id: Expression::fieldPath('occupation'), + birth_year_avg: Accumulator::avg(Expression::numberFieldPath('birth_year')), + ) + ->sort(_id: Sort::Asc) + ->project(profession: Expression::fieldPath('_id'), birth_year_avg: 1, _id: 0); + // end pipeline example + + $result = $pipeline->get(); + + $this->assertEquals(2, $result->count()); + $this->assertNotNull($result->first()['birth_year_avg']); + } + + // phpcs:disable Squiz.Commenting.FunctionComment.WrongStyle + // phpcs:disable Squiz.WhiteSpace.FunctionSpacing.After + // start custom operator factory function + public function yearFromField(string $dateFieldName): YearOperator + { + return Expression::year( + Expression::dateFieldPath($dateFieldName), + ); + } + // end custom operator factory function + // phpcs:enable + + public function testCustomOperatorFactory(): void + { + // begin custom operator factory usage + $pipeline = User::aggregate() + ->addFields(birth_year: $this->yearFromField('birthday')) + ->project(_id: 0, name: 1, birth_year: 1); + // end custom operator factory usage + + $result = $pipeline->get(); + + $this->assertEquals(6, $result->count()); + $this->assertNotNull($result->first()['birth_year']); + } +} diff --git a/docs/index.txt b/docs/index.txt index 9f6b76483..327854255 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -65,6 +65,7 @@ see the following content: - :ref:`laravel-fundamentals-write-ops` - :ref:`laravel-eloquent-models` - :ref:`laravel-query-builder` +- :ref:`laravel-aggregation-builder` - :ref:`laravel-user-authentication` - :ref:`laravel-queues` - :ref:`laravel-transactions` From 01dd49f5cb5d383ccc8e396c212e9964909b3a41 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Thu, 18 Apr 2024 16:16:56 -0700 Subject: [PATCH 244/446] DOCSP-35980: Insert One usage example (#2826) * DOCSP-35980: Insert One usage example --- .../includes/usage-examples/InsertOneTest.php | 35 +++++++++ docs/usage-examples.txt | 1 + docs/usage-examples/insertOne.txt | 73 +++++++++++++++++++ 3 files changed, 109 insertions(+) create mode 100644 docs/includes/usage-examples/InsertOneTest.php create mode 100644 docs/usage-examples/insertOne.txt diff --git a/docs/includes/usage-examples/InsertOneTest.php b/docs/includes/usage-examples/InsertOneTest.php new file mode 100644 index 000000000..15eadf419 --- /dev/null +++ b/docs/includes/usage-examples/InsertOneTest.php @@ -0,0 +1,35 @@ + 'Marriage Story', + 'year' => 2019, + 'runtime' => 136, + ]); + + echo $movie->toJson(); + // end-insert-one + + $this->assertInstanceOf(Movie::class, $movie); + $this->expectOutputRegex('/^{"title":"Marriage Story","year":2019,"runtime":136,"updated_at":".{27}","created_at":".{27}","_id":"[a-z0-9]{24}"}$/'); + } +} diff --git a/docs/usage-examples.txt b/docs/usage-examples.txt index 899655924..43994905d 100644 --- a/docs/usage-examples.txt +++ b/docs/usage-examples.txt @@ -74,6 +74,7 @@ calls the controller function and returns the result to a web interface. /usage-examples/findOne /usage-examples/insertMany /usage-examples/updateOne + /usage-examples/insertOne /usage-examples/deleteOne /usage-examples/deleteMany /usage-examples/count diff --git a/docs/usage-examples/insertOne.txt b/docs/usage-examples/insertOne.txt new file mode 100644 index 000000000..785bf2578 --- /dev/null +++ b/docs/usage-examples/insertOne.txt @@ -0,0 +1,73 @@ +.. _laravel-insert-one-usage: + +================= +Insert a Document +================= + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: insert one, add one, code example + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +You can insert a document into a collection by calling the ``create()`` method on +an Eloquent model or query builder. + +To insert a document, pass the data you need to insert as a document containing +the fields and values to the ``create()`` method. + +Example +------- + +This usage example performs the following actions: + +- Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the + ``sample_mflix`` database +- Inserts a document into the ``movies`` collection + +The example calls the ``create()`` method to insert a document that contains the following +information: + +- ``title`` value of ``"Marriage Story"`` +- ``year`` value of ``2019`` +- ``runtime`` value of ``136`` + +.. io-code-block:: + :copyable: true + + .. input:: ../includes/usage-examples/InsertOneTest.php + :start-after: begin-insert-one + :end-before: end-insert-one + :language: php + :dedent: + + .. output:: + :language: json + :visible: false + + { + "title": "Marriage Story", + "year": 2019, + "runtime": 136, + "updated_at": "...", + "created_at": "...", + "_id": "..." + } + +To learn how to edit your Laravel application to run the usage example, see the +:ref:`Usage Examples landing page `. + +.. tip:: + + You can also use the ``save()`` or ``insert()`` methods to insert a document into a collection. + To learn more about insert operations, see the :ref:`laravel-fundamentals-insert-documents` section + of the Write Operations guide. + + From 26d96329cc5148ecf224c8df748c28c359a69519 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Thu, 18 Apr 2024 17:13:25 -0700 Subject: [PATCH 245/446] DOCSP-35975: Update many usage example (#2836) * DOCSP-35975: Update many usage example --- .../usage-examples/UpdateManyTest.php | 48 +++++++++++++ docs/usage-examples.txt | 3 +- docs/usage-examples/deleteOne.txt | 1 + docs/usage-examples/findOne.txt | 5 +- docs/usage-examples/updateMany.txt | 67 +++++++++++++++++++ docs/usage-examples/updateOne.txt | 5 +- 6 files changed, 124 insertions(+), 5 deletions(-) create mode 100644 docs/includes/usage-examples/UpdateManyTest.php create mode 100644 docs/usage-examples/updateMany.txt diff --git a/docs/includes/usage-examples/UpdateManyTest.php b/docs/includes/usage-examples/UpdateManyTest.php new file mode 100644 index 000000000..49a77dd95 --- /dev/null +++ b/docs/includes/usage-examples/UpdateManyTest.php @@ -0,0 +1,48 @@ + 'Hollywood', + 'imdb' => [ + 'rating' => 9.1, + 'votes' => 511, + ], + ], + [ + 'title' => 'The Shawshank Redemption', + 'imdb' => [ + 'rating' => 9.3, + 'votes' => 1513145, + ], + ], + ]); + + // begin-update-many + $updates = Movie::where('imdb.rating', '>', 9.0) + ->update(['acclaimed' => true]); + + echo 'Updated documents: ' . $updates; + // end-update-many + + $this->assertEquals(2, $updates); + $this->expectOutputString('Updated documents: 2'); + } +} diff --git a/docs/usage-examples.txt b/docs/usage-examples.txt index 43994905d..4a33e18cd 100644 --- a/docs/usage-examples.txt +++ b/docs/usage-examples.txt @@ -72,9 +72,10 @@ calls the controller function and returns the result to a web interface. :maxdepth: 1 /usage-examples/findOne + /usage-examples/insertOne /usage-examples/insertMany /usage-examples/updateOne - /usage-examples/insertOne + /usage-examples/updateMany /usage-examples/deleteOne /usage-examples/deleteMany /usage-examples/count diff --git a/docs/usage-examples/deleteOne.txt b/docs/usage-examples/deleteOne.txt index 762cfd405..3f934b273 100644 --- a/docs/usage-examples/deleteOne.txt +++ b/docs/usage-examples/deleteOne.txt @@ -32,6 +32,7 @@ This usage example performs the following actions: - Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the ``sample_mflix`` database - Deletes a document from the ``movies`` collection that matches a query filter +- Prints the number of deleted documents The example calls the following methods on the ``Movie`` model: diff --git a/docs/usage-examples/findOne.txt b/docs/usage-examples/findOne.txt index 39fde3d56..2a66726d1 100644 --- a/docs/usage-examples/findOne.txt +++ b/docs/usage-examples/findOne.txt @@ -19,8 +19,9 @@ Example This usage example performs the following actions: - Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the - ``sample_mflix`` database. -- Retrieves a document from the ``movies`` collection that matches a query filter. + ``sample_mflix`` database +- Retrieves a document from the ``movies`` collection that matches a query filter +- Prints the retrieved document The example calls the following methods on the ``Movie`` model: diff --git a/docs/usage-examples/updateMany.txt b/docs/usage-examples/updateMany.txt new file mode 100644 index 000000000..3a7482336 --- /dev/null +++ b/docs/usage-examples/updateMany.txt @@ -0,0 +1,67 @@ +.. _laravel-update-one-usage: + +========================= +Update Multiple Documents +========================= + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: update many, modify, code example + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +You can update multiple documents in a collection by calling the ``update()`` method +on a query builder. + +Pass a query filter to the ``where()`` method to retrieve documents that meet a +set of criteria. Then, update the matching documents 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 documents from the ``movies`` collection that match a query filter +- Prints the number of updated documents + +The example calls the following methods on the ``Movie`` model: + +- ``where()``: matches documents in which the value of the ``imdb.rating`` nested field + is greater than ``9``. +- ``update()``: updates the matching documents by adding an ``acclaimed`` field and setting + its value to ``true``. This method returns the number of documents that were successfully + updated. + +.. io-code-block:: + :copyable: true + + .. input:: ../includes/usage-examples/UpdateManyTest.php + :start-after: begin-update-many + :end-before: end-update-many + :language: php + :dedent: + + .. output:: + :language: console + :visible: false + + Updated documents: 20 + +To learn how to edit your Laravel application to run the usage example, see the +:ref:`Usage Examples landing page `. + +.. tip:: + + To learn more about updating data with {+odm-short+}, see the :ref:`laravel-fundamentals-modify-documents` + section of the Write Operations guide. + diff --git a/docs/usage-examples/updateOne.txt b/docs/usage-examples/updateOne.txt index f60bd3bad..12aec17ff 100644 --- a/docs/usage-examples/updateOne.txt +++ b/docs/usage-examples/updateOne.txt @@ -30,8 +30,9 @@ 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. + ``sample_mflix`` database +- Updates a document from the ``movies`` collection that matches a query filter +- Prints the number of updated documents The example calls the following methods on the ``Movie`` model: From 839b411c917898e9e0fd3177adc645c886dd6729 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Thu, 18 Apr 2024 17:23:49 -0700 Subject: [PATCH 246/446] DOCSP-35983: Run command usage example (#2852) * DOCSP-35983: Run command usage example --- .../usage-examples/RunCommandTest.php | 29 ++++++++++ docs/usage-examples.txt | 1 + docs/usage-examples/runCommand.txt | 53 +++++++++++++++++++ 3 files changed, 83 insertions(+) create mode 100644 docs/includes/usage-examples/RunCommandTest.php create mode 100644 docs/usage-examples/runCommand.txt diff --git a/docs/includes/usage-examples/RunCommandTest.php b/docs/includes/usage-examples/RunCommandTest.php new file mode 100644 index 000000000..cd6e34696 --- /dev/null +++ b/docs/includes/usage-examples/RunCommandTest.php @@ -0,0 +1,29 @@ +command(['listCollections' => 1]); + + foreach ($cursor as $coll) { + echo $coll['name'] . "
\n"; + } + + // end-command + + $this->assertNotNull($cursor); + $this->assertInstanceOf(Cursor::class, $cursor); + $this->expectOutputRegex('/
/'); + } +} diff --git a/docs/usage-examples.txt b/docs/usage-examples.txt index 4a33e18cd..be29ee9ac 100644 --- a/docs/usage-examples.txt +++ b/docs/usage-examples.txt @@ -80,3 +80,4 @@ calls the controller function and returns the result to a web interface. /usage-examples/deleteMany /usage-examples/count /usage-examples/distinct + /usage-examples/runCommand diff --git a/docs/usage-examples/runCommand.txt b/docs/usage-examples/runCommand.txt new file mode 100644 index 000000000..51f0cca83 --- /dev/null +++ b/docs/usage-examples/runCommand.txt @@ -0,0 +1,53 @@ +.. _laravel-run-command-usage: + +============= +Run a Command +============= + +You can run a MongoDB command directly on a database by calling the ``command()`` +method on a database connection instance. + +To run a command, call the ``command()`` method and pass it a document that +contains the command and its parameters. + +Example +------- + +This usage example performs the following actions on the database connection +instance that uses the ``sample_mflix`` database: + +- Creates a database connection instance that references the ``sample_mflix`` + database +- Specifies a command to retrieve a list of collections and views in the + ``sample_mflix`` database +- Prints the value of the ``name`` field of each result returned by the command + +The example calls the ``command()`` method to run the ``listCollections`` command. This method +returns a cursor that contains a result document for each collection in the database. + +.. io-code-block:: + + .. input:: ../includes/usage-examples/RunCommandTest.php + :start-after: begin-command + :end-before: end-command + :language: php + :dedent: + + .. output:: + :language: console + :visible: false + + sessions + movies + theaters + comments + embedded_movies + users + +To learn how to edit your Laravel application to run the usage example, see the +:ref:`Usage Examples landing page `. + +.. tip:: + + To learn more about running MongoDB database commands, see + :manual:`Database Commands ` in the {+server-docs-name+}. From 21c9ca45f0c5d8598e733912ae9582cce1432993 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Fri, 19 Apr 2024 09:53:38 -0400 Subject: [PATCH 247/446] DOCSP-35962: sorts (#2879) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * DOCSP-35962: sorts * add note about params * CC suggestion * move to test * Add fixtures to the tests * JT PR fix to link and update code --------- Co-authored-by: Jérôme Tamarelle --- docs/fundamentals/read-operations.txt | 145 +++++++++++++++--- .../fundamentals/read-operations/Movie.php | 12 ++ .../read-operations/ReadOperationsTest.php | 97 ++++++++++++ 3 files changed, 229 insertions(+), 25 deletions(-) create mode 100644 docs/includes/fundamentals/read-operations/Movie.php create mode 100644 docs/includes/fundamentals/read-operations/ReadOperationsTest.php diff --git a/docs/fundamentals/read-operations.txt b/docs/fundamentals/read-operations.txt index 4ceafd460..44eba023f 100644 --- a/docs/fundamentals/read-operations.txt +++ b/docs/fundamentals/read-operations.txt @@ -94,11 +94,11 @@ retrieve documents that meet the following criteria: Use the following syntax to specify the query: - .. code-block:: php - - $movies = Movie::where('year', 2010) - ->where('imdb.rating', '>', 8.5) - ->get(); + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-query + :end-before: end-query .. tab:: Controller Method :tabid: controller @@ -188,6 +188,8 @@ method: - :ref:`laravel-skip-limit` uses the ``skip()`` method to set the number of documents to skip and the ``take()`` method to set the total number of documents to return +- :ref:`laravel-sort` uses the ``orderBy()`` method to return query + results in a specified order based on field values - :ref:`laravel-retrieve-one` uses the ``first()`` method to return the first document that matches the query filter @@ -207,12 +209,11 @@ documents. Use the following syntax to specify the query: - .. code-block:: php - - $movies = Movie::where('year', 1999) - ->skip(2) - ->take(3) - ->get(); + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-skip-limit + :end-before: end-skip-limit .. tab:: Controller Method :tabid: controller @@ -269,6 +270,105 @@ documents. Plot: A sci-fi update of the famous 6th Century poem. In a beseiged land, Beowulf must battle against the hideous creature Grendel and his vengeance seeking mother. +.. _laravel-sort: + +Sort Query Results +~~~~~~~~~~~~~~~~~~ + +To order query results based on the values of specified fields, use the ``where()`` method +followed by the ``orderBy()`` method. + +You can set an **ascending** or **descending** sort direction on +results. By default, the ``orderBy()`` method sets an ascending sort on +the supplied field name, but you can explicitly specify an ascending +sort by passing ``'asc'`` as the second parameter. To +specify a descending sort, pass ``'desc'`` as the second parameter. + +If your documents contain duplicate values in a specific field, you can +handle the tie by specifying additional fields to sort on. This ensures consistent +results if the additional fields contain unique values. + +This example queries for documents in which the value of the ``countries`` field contains +``'Indonesia'`` and orders results first by an ascending sort on the +``year`` field, then a descending sort on the ``title`` field. + +.. tabs:: + + .. tab:: Query Syntax + :tabid: query-syntax + + Use the following syntax to specify the query: + + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-sort + :end-before: end-sort + + .. tab:: Controller Method + :tabid: controller + + To see the query results in the ``browse_movies`` view, edit the ``show()`` function + in the ``MovieController.php`` file to resemble the following code: + + .. io-code-block:: + :copyable: true + + .. input:: + :language: php + + class MovieController + { + public function show() + { + $movies = Movie::where('countries', 'Indonesia') + ->orderBy('year') + ->orderBy('title', 'desc') + ->get(); + + return view('browse_movies', [ + 'movies' => $movies + ]); + } + } + + .. output:: + :language: none + :visible: false + + Title: Joni's Promise + Year: 2005 + Runtime: 83 + IMDB Rating: 7.6 + IMDB Votes: 702 + Plot: A film delivery man promises ... + + Title: Gie + Year: 2005 + Runtime: 147 + IMDB Rating: 7.5 + IMDB Votes: 470 + Plot: Soe Hok Gie is an activist who lived in the sixties ... + + Title: Requiem from Java + Year: 2006 + Runtime: 120 + IMDB Rating: 6.6 + IMDB Votes: 316 + Plot: Setyo (Martinus Miroto) and Siti (Artika Sari Dewi) + are young married couple ... + + ... + +.. tip:: + + To learn more about sorting, see the following resources: + + - :manual:`Natural order ` + in the Server manual glossary + - `Ordering, Grouping, Limit and Offset `__ + in the Laravel documentation + .. _laravel-retrieve-one: Return the First Result @@ -292,11 +392,11 @@ field. Use the following syntax to specify the query: - .. code-block:: php - - $movies = Movie::where('runtime', 30) - ->orderBy('_id') - ->first(); + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-first + :end-before: end-first .. tab:: Controller Method :tabid: controller @@ -314,12 +414,12 @@ field. { public function show() { - $movies = Movie::where('runtime', 30) + $movie = Movie::where('runtime', 30) ->orderBy('_id') ->first(); return view('browse_movies', [ - 'movies' => $movies + 'movies' => $movie ]); } } @@ -337,10 +437,5 @@ field. .. tip:: - To learn more about sorting, see the following resources: - - - :manual:`Natural order ` - in the Server manual glossary - - `Ordering, Grouping, Limit and Offset `__ - in the Laravel documentation - + To learn more about the ``orderBy()`` method, see the + :ref:`laravel-sort` section of this guide. diff --git a/docs/includes/fundamentals/read-operations/Movie.php b/docs/includes/fundamentals/read-operations/Movie.php new file mode 100644 index 000000000..728a066de --- /dev/null +++ b/docs/includes/fundamentals/read-operations/Movie.php @@ -0,0 +1,12 @@ + 2010, 'imdb' => ['rating' => 9]], + ['year' => 2010, 'imdb' => ['rating' => 9.5]], + ['year' => 2010, 'imdb' => ['rating' => 7]], + ['year' => 1999, 'countries' => ['Indonesia', 'Canada'], 'title' => 'Title 1'], + ['year' => 1999, 'countries' => ['Indonesia'], 'title' => 'Title 2'], + ['year' => 1999, 'countries' => ['Indonesia'], 'title' => 'Title 3'], + ['year' => 1999, 'countries' => ['Indonesia'], 'title' => 'Title 4'], + ['year' => 1999, 'countries' => ['Canada'], 'title' => 'Title 5'], + ['year' => 1999, 'runtime' => 30], + ]); + } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function testFindFilter(): void + { + // start-query + $movies = Movie::where('year', 2010) + ->where('imdb.rating', '>', 8.5) + ->get(); + // end-query + + $this->assertNotNull($movies); + $this->assertCount(2, $movies); + } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function testSkipLimit(): void + { + // start-skip-limit + $movies = Movie::where('year', 1999) + ->skip(2) + ->take(3) + ->get(); + // end-skip-limit + + $this->assertNotNull($movies); + $this->assertCount(3, $movies); + } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function testSort(): void + { + // start-sort + $movies = Movie::where('countries', 'Indonesia') + ->orderBy('year') + ->orderBy('title', 'desc') + ->get(); + // end-sort + + $this->assertNotNull($movies); + $this->assertCount(4, $movies); + } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function testFirst(): void + { + // start-first + $movie = Movie::where('runtime', 30) + ->orderBy('_id') + ->first(); + // end-first + + $this->assertNotNull($movie); + $this->assertInstanceOf(Movie::class, $movie); + } +} From d0978a80f92fb3ea0f752f86994e883ca46c7544 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 22 Apr 2024 13:29:07 +0200 Subject: [PATCH 248/446] PHPORM-99 Implement optimized lock and cache (#2877) Fix fo PHPORM-99 In theory, we can use DatabaseStore and DatabaseLock. But various issues prove the changing nature of their implementation, based on new features in the query builder, make this feature unstable for MongoDB users. fix #2718, fix #2609 By introducing dedicated drivers, we can optimize the implementation to use the mongodb library directly instead of the subset of features provided by Laravel query builder. Usage: # config/cache.php return [ 'stores' => [ 'mongodb' => [ 'driver' => 'mongodb', 'connection' => 'mongodb', 'collection' => 'cache', 'lock_connection' => 'mongodb', 'lock_collection' => 'cache_locks', 'lock_lottery' => [2, 100], 'lock_timeout' => '86400', ] ] ] Cache: // Store any value into the cache. The value is serialized in MongoDB Cache::set('foo', [1, 2, 3]); // Read the value dump(Cache::get('foo')); // Clear the cache Cache::flush(); Lock: // Get an unique lock. It's very important to keep this object in memory // so that the lock can be released. $lock = Cache::lock('foo'); $lock->block(10); // Wait 10 seconds before throwing an exception if the lock isn't released // Any time-consuming task sleep(5); // Release the lock $lock->release(); --- CHANGELOG.md | 1 + composer.json | 3 +- src/Cache/MongoLock.php | 134 +++++++++++++ src/Cache/MongoStore.php | 296 ++++++++++++++++++++++++++++ src/MongoDBServiceProvider.php | 26 +++ tests/Cache/MongoCacheStoreTest.php | 231 ++++++++++++++++++++++ tests/Cache/MongoLockTest.php | 99 ++++++++++ tests/TestCase.php | 6 + 8 files changed, 795 insertions(+), 1 deletion(-) create mode 100644 src/Cache/MongoLock.php create mode 100644 src/Cache/MongoStore.php create mode 100644 tests/Cache/MongoCacheStoreTest.php create mode 100644 tests/Cache/MongoLockTest.php diff --git a/CHANGELOG.md b/CHANGELOG.md index 55a84247e..f653604ea 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ All notable changes to this project will be documented in this file. * New aggregation pipeline builder by @GromNaN in [#2738](https://github.com/mongodb/laravel-mongodb/pull/2738) * Drop support for Composer 1.x by @GromNaN in [#2784](https://github.com/mongodb/laravel-mongodb/pull/2784) * Fix `artisan query:retry` command by @GromNaN in [#2838](https://github.com/mongodb/laravel-mongodb/pull/2838) +* Add `mongodb` cache and lock drivers by @GromNaN in [#2877](https://github.com/mongodb/laravel-mongodb/pull/2877) ## [4.2.0] - 2024-03-14 diff --git a/composer.json b/composer.json index 51c7e1e43..8c038819e 100644 --- a/composer.json +++ b/composer.json @@ -25,10 +25,11 @@ "php": "^8.1", "ext-mongodb": "^1.15", "composer-runtime-api": "^2.0.0", - "illuminate/support": "^10.0|^11", + "illuminate/cache": "^10.36|^11", "illuminate/container": "^10.0|^11", "illuminate/database": "^10.30|^11", "illuminate/events": "^10.0|^11", + "illuminate/support": "^10.0|^11", "mongodb/mongodb": "^1.15" }, "require-dev": { diff --git a/src/Cache/MongoLock.php b/src/Cache/MongoLock.php new file mode 100644 index 000000000..105a3df40 --- /dev/null +++ b/src/Cache/MongoLock.php @@ -0,0 +1,134 @@ + [ + ['$lte' => ['$expiration', $this->currentTime()]], + ['$eq' => ['$owner', $this->owner]], + ], + ]; + $result = $this->collection->findOneAndUpdate( + ['_id' => $this->name], + [ + [ + '$set' => [ + 'owner' => [ + '$cond' => [ + 'if' => $isExpiredOrAlreadyOwned, + 'then' => $this->owner, + 'else' => '$owner', + ], + ], + 'expiration' => [ + '$cond' => [ + 'if' => $isExpiredOrAlreadyOwned, + 'then' => $this->expiresAt(), + 'else' => '$expiration', + ], + ], + ], + ], + ], + [ + 'upsert' => true, + 'returnDocument' => FindOneAndUpdate::RETURN_DOCUMENT_AFTER, + 'projection' => ['owner' => 1], + ], + ); + + if (random_int(1, $this->lottery[1]) <= $this->lottery[0]) { + $this->collection->deleteMany(['expiration' => ['$lte' => $this->currentTime()]]); + } + + return $result['owner'] === $this->owner; + } + + /** + * Release the lock. + */ + #[Override] + public function release(): bool + { + $result = $this->collection + ->deleteOne([ + '_id' => $this->name, + 'owner' => $this->owner, + ]); + + return $result->getDeletedCount() > 0; + } + + /** + * Releases this lock in disregard of ownership. + */ + #[Override] + public function forceRelease(): void + { + $this->collection->deleteOne([ + '_id' => $this->name, + ]); + } + + /** + * Returns the owner value written into the driver for this lock. + */ + #[Override] + protected function getCurrentOwner(): ?string + { + return $this->collection->findOne( + [ + '_id' => $this->name, + 'expiration' => ['$gte' => $this->currentTime()], + ], + ['projection' => ['owner' => 1]], + )['owner'] ?? null; + } + + /** + * Get the UNIX timestamp indicating when the lock should expire. + */ + private function expiresAt(): int + { + $lockTimeout = $this->seconds > 0 ? $this->seconds : $this->defaultTimeoutInSeconds; + + return $this->currentTime() + $lockTimeout; + } +} diff --git a/src/Cache/MongoStore.php b/src/Cache/MongoStore.php new file mode 100644 index 000000000..4a01c9161 --- /dev/null +++ b/src/Cache/MongoStore.php @@ -0,0 +1,296 @@ +collection = $this->connection->getCollection($this->collectionName); + } + + /** + * Get a lock instance. + * + * @param string $name + * @param int $seconds + * @param string|null $owner + */ + #[Override] + public function lock($name, $seconds = 0, $owner = null): MongoLock + { + return new MongoLock( + ($this->lockConnection ?? $this->connection)->getCollection($this->lockCollectionName), + $this->prefix . $name, + $seconds, + $owner, + $this->lockLottery, + $this->defaultLockTimeoutInSeconds, + ); + } + + /** + * Restore a lock instance using the owner identifier. + */ + #[Override] + public function restoreLock($name, $owner): MongoLock + { + return $this->lock($name, 0, $owner); + } + + /** + * Store an item in the cache for a given number of seconds. + * + * @param string $key + * @param mixed $value + * @param int $seconds + */ + #[Override] + public function put($key, $value, $seconds): bool + { + $result = $this->collection->updateOne( + [ + '_id' => $this->prefix . $key, + ], + [ + '$set' => [ + 'value' => $this->serialize($value), + 'expiration' => $this->currentTime() + $seconds, + ], + ], + [ + 'upsert' => true, + + ], + ); + + return $result->getUpsertedCount() > 0 || $result->getModifiedCount() > 0; + } + + /** + * Store an item in the cache if the key doesn't exist. + * + * @param string $key + * @param mixed $value + * @param int $seconds + */ + public function add($key, $value, $seconds): bool + { + $result = $this->collection->updateOne( + [ + '_id' => $this->prefix . $key, + ], + [ + [ + '$set' => [ + 'value' => [ + '$cond' => [ + 'if' => ['$lte' => ['$expiration', $this->currentTime()]], + 'then' => $this->serialize($value), + 'else' => '$value', + ], + ], + 'expiration' => [ + '$cond' => [ + 'if' => ['$lte' => ['$expiration', $this->currentTime()]], + 'then' => $this->currentTime() + $seconds, + 'else' => '$expiration', + ], + ], + ], + ], + ], + ['upsert' => true], + ); + + return $result->getUpsertedCount() > 0 || $result->getModifiedCount() > 0; + } + + /** + * Retrieve an item from the cache by key. + * + * @param string $key + */ + #[Override] + public function get($key): mixed + { + $result = $this->collection->findOne( + ['_id' => $this->prefix . $key], + ['projection' => ['value' => 1, 'expiration' => 1]], + ); + + if (! $result) { + return null; + } + + if ($result['expiration'] <= $this->currentTime()) { + $this->forgetIfExpired($key); + + return null; + } + + return $this->unserialize($result['value']); + } + + /** + * Increment the value of an item in the cache. + * + * @param string $key + * @param int|float $value + */ + #[Override] + public function increment($key, $value = 1): int|float|false + { + $this->forgetIfExpired($key); + + $result = $this->collection->findOneAndUpdate( + [ + '_id' => $this->prefix . $key, + 'expiration' => ['$gte' => $this->currentTime()], + ], + [ + '$inc' => ['value' => $value], + ], + [ + 'returnDocument' => FindOneAndUpdate::RETURN_DOCUMENT_AFTER, + ], + ); + + if (! $result) { + return false; + } + + if ($result['expiration'] <= $this->currentTime()) { + $this->forgetIfExpired($key); + + return false; + } + + return $result['value']; + } + + /** + * Decrement the value of an item in the cache. + * + * @param string $key + * @param int|float $value + */ + #[Override] + public function decrement($key, $value = 1): int|float|false + { + return $this->increment($key, -1 * $value); + } + + /** + * Store an item in the cache indefinitely. + * + * @param string $key + * @param mixed $value + */ + #[Override] + public function forever($key, $value): bool + { + return $this->put($key, $value, self::TEN_YEARS_IN_SECONDS); + } + + /** + * Remove an item from the cache. + * + * @param string $key + */ + #[Override] + public function forget($key): bool + { + $result = $this->collection->deleteOne([ + '_id' => $this->prefix . $key, + ]); + + return $result->getDeletedCount() > 0; + } + + /** + * Remove an item from the cache if it is expired. + * + * @param string $key + */ + public function forgetIfExpired($key): bool + { + $result = $this->collection->deleteOne([ + '_id' => $this->prefix . $key, + 'expiration' => ['$lte' => $this->currentTime()], + ]); + + return $result->getDeletedCount() > 0; + } + + public function flush(): bool + { + $this->collection->deleteMany([]); + + return true; + } + + public function getPrefix(): string + { + return $this->prefix; + } + + private function serialize($value): string|int|float + { + // Don't serialize numbers, so they can be incremented + if (is_int($value) || is_float($value)) { + return $value; + } + + return serialize($value); + } + + private function unserialize($value): mixed + { + if (! is_string($value) || ! str_contains($value, ';')) { + return $value; + } + + return unserialize($value); + } +} diff --git a/src/MongoDBServiceProvider.php b/src/MongoDBServiceProvider.php index d7af0c714..50c042230 100644 --- a/src/MongoDBServiceProvider.php +++ b/src/MongoDBServiceProvider.php @@ -4,10 +4,16 @@ namespace MongoDB\Laravel; +use Illuminate\Cache\CacheManager; +use Illuminate\Cache\Repository; +use Illuminate\Foundation\Application; use Illuminate\Support\ServiceProvider; +use MongoDB\Laravel\Cache\MongoStore; use MongoDB\Laravel\Eloquent\Model; use MongoDB\Laravel\Queue\MongoConnector; +use function assert; + class MongoDBServiceProvider extends ServiceProvider { /** @@ -34,6 +40,26 @@ public function register() }); }); + // Add cache and lock drivers. + $this->app->resolving('cache', function (CacheManager $cache) { + $cache->extend('mongodb', function (Application $app, array $config): Repository { + // The closure is bound to the CacheManager + assert($this instanceof CacheManager); + + $store = new MongoStore( + $app['db']->connection($config['connection'] ?? null), + $config['collection'] ?? 'cache', + $this->getPrefix($config), + $app['db']->connection($config['lock_connection'] ?? $config['connection'] ?? null), + $config['lock_collection'] ?? ($config['collection'] ?? 'cache') . '_locks', + $config['lock_lottery'] ?? [2, 100], + $config['lock_timeout'] ?? 86400, + ); + + return $this->repository($store, $config); + }); + }); + // Add connector for queue support. $this->app->resolving('queue', function ($queue) { $queue->addConnector('mongodb', function () { diff --git a/tests/Cache/MongoCacheStoreTest.php b/tests/Cache/MongoCacheStoreTest.php new file mode 100644 index 000000000..4ee97e75a --- /dev/null +++ b/tests/Cache/MongoCacheStoreTest.php @@ -0,0 +1,231 @@ +getCollection($this->getCacheCollectionName()) + ->drop(); + + parent::tearDown(); + } + + public function testGetNullWhenItemDoesNotExist() + { + $store = $this->getStore(); + $this->assertNull($store->get('foo')); + } + + public function testValueCanStoreNewCache() + { + $store = $this->getStore(); + + $store->put('foo', 'bar', 60); + + $this->assertSame('bar', $store->get('foo')); + } + + public function testPutOperationShouldNotStoreExpired() + { + $store = $this->getStore(); + + $store->put('foo', 'bar', 0); + + $this->assertDatabaseMissing($this->getCacheCollectionName(), ['_id' => $this->withCachePrefix('foo')]); + } + + public function testValueCanUpdateExistCache() + { + $store = $this->getStore(); + + $store->put('foo', 'bar', 60); + $store->put('foo', 'new-bar', 60); + + $this->assertSame('new-bar', $store->get('foo')); + } + + public function testValueCanUpdateExistCacheInTransaction() + { + $store = $this->getStore(); + + $store->put('foo', 'bar', 60); + + // Transactions are not used in MongoStore + DB::beginTransaction(); + $store->put('foo', 'new-bar', 60); + DB::commit(); + + $this->assertSame('new-bar', $store->get('foo')); + } + + public function testAddOperationShouldNotStoreExpired() + { + $store = $this->getStore(); + + $result = $store->add('foo', 'bar', 0); + + $this->assertFalse($result); + $this->assertDatabaseMissing($this->getCacheCollectionName(), ['_id' => $this->withCachePrefix('foo')]); + } + + public function testAddOperationCanStoreNewCache() + { + $store = $this->getStore(); + + $result = $store->add('foo', 'bar', 60); + + $this->assertTrue($result); + $this->assertSame('bar', $store->get('foo')); + } + + public function testAddOperationShouldNotUpdateExistCache() + { + $store = $this->getStore(); + + $store->add('foo', 'bar', 60); + $result = $store->add('foo', 'new-bar', 60); + + $this->assertFalse($result); + $this->assertSame('bar', $store->get('foo')); + } + + public function testAddOperationShouldNotUpdateExistCacheInTransaction() + { + $store = $this->getStore(); + + $store->add('foo', 'bar', 60); + + DB::beginTransaction(); + $result = $store->add('foo', 'new-bar', 60); + DB::commit(); + + $this->assertFalse($result); + $this->assertSame('bar', $store->get('foo')); + } + + public function testAddOperationCanUpdateIfCacheExpired() + { + $store = $this->getStore(); + + $this->insertToCacheTable('foo', 'bar', 0); + $result = $store->add('foo', 'new-bar', 60); + + $this->assertTrue($result); + $this->assertSame('new-bar', $store->get('foo')); + } + + public function testAddOperationCanUpdateIfCacheExpiredInTransaction() + { + $store = $this->getStore(); + + $this->insertToCacheTable('foo', 'bar', 0); + + DB::beginTransaction(); + $result = $store->add('foo', 'new-bar', 60); + DB::commit(); + + $this->assertTrue($result); + $this->assertSame('new-bar', $store->get('foo')); + } + + public function testGetOperationReturnNullIfExpired() + { + $store = $this->getStore(); + + $this->insertToCacheTable('foo', 'bar', 0); + + $result = $store->get('foo'); + + $this->assertNull($result); + } + + public function testGetOperationCanDeleteExpired() + { + $store = $this->getStore(); + + $this->insertToCacheTable('foo', 'bar', 0); + + $store->get('foo'); + + $this->assertDatabaseMissing($this->getCacheCollectionName(), ['_id' => $this->withCachePrefix('foo')]); + } + + public function testForgetIfExpiredOperationCanDeleteExpired() + { + $store = $this->getStore(); + + $this->insertToCacheTable('foo', 'bar', 0); + + $store->forgetIfExpired('foo'); + + $this->assertDatabaseMissing($this->getCacheCollectionName(), ['_id' => $this->withCachePrefix('foo')]); + } + + public function testForgetIfExpiredOperationShouldNotDeleteUnExpired() + { + $store = $this->getStore(); + + $store->put('foo', 'bar', 60); + + $store->forgetIfExpired('foo'); + + $this->assertDatabaseHas($this->getCacheCollectionName(), ['_id' => $this->withCachePrefix('foo')]); + } + + public function testIncrementDecrement() + { + $store = $this->getStore(); + $this->assertFalse($store->increment('foo', 10)); + $this->assertFalse($store->decrement('foo', 10)); + + $store->put('foo', 3.5, 60); + $this->assertSame(13.5, $store->increment('foo', 10)); + $this->assertSame(12.0, $store->decrement('foo', 1.5)); + $store->forget('foo'); + + $this->insertToCacheTable('foo', 10, -5); + $this->assertFalse($store->increment('foo', 5)); + } + + protected function getStore(): Repository + { + $repository = Cache::store('mongodb'); + assert($repository instanceof Repository); + + return $repository; + } + + protected function getCacheCollectionName(): string + { + return config('cache.stores.mongodb.collection'); + } + + protected function withCachePrefix(string $key): string + { + return config('cache.prefix') . $key; + } + + protected function insertToCacheTable(string $key, $value, $ttl = 60) + { + DB::connection('mongodb') + ->getCollection($this->getCacheCollectionName()) + ->insertOne([ + '_id' => $this->withCachePrefix($key), + 'value' => $value, + 'expiration' => Carbon::now()->addSeconds($ttl)->getTimestamp(), + ]); + } +} diff --git a/tests/Cache/MongoLockTest.php b/tests/Cache/MongoLockTest.php new file mode 100644 index 000000000..d08ee899c --- /dev/null +++ b/tests/Cache/MongoLockTest.php @@ -0,0 +1,99 @@ +getCollection('foo_cache_locks')->drop(); + + parent::tearDown(); + } + + public function testLockCanBeAcquired() + { + $lock = $this->getCache()->lock('foo'); + $this->assertTrue($lock->get()); + $this->assertTrue($lock->get()); + + $otherLock = $this->getCache()->lock('foo'); + $this->assertFalse($otherLock->get()); + + $lock->release(); + + $otherLock = $this->getCache()->lock('foo'); + $this->assertTrue($otherLock->get()); + $this->assertTrue($otherLock->get()); + + $otherLock->release(); + } + + public function testLockCanBeForceReleased() + { + $lock = $this->getCache()->lock('foo'); + $this->assertTrue($lock->get()); + + $otherLock = $this->getCache()->lock('foo'); + $otherLock->forceRelease(); + $this->assertTrue($otherLock->get()); + + $otherLock->release(); + } + + public function testExpiredLockCanBeRetrieved() + { + $lock = $this->getCache()->lock('foo'); + $this->assertTrue($lock->get()); + DB::table('foo_cache_locks')->update(['expiration' => now()->subDays(1)->getTimestamp()]); + + $otherLock = $this->getCache()->lock('foo'); + $this->assertTrue($otherLock->get()); + + $otherLock->release(); + } + + public function testOwnedByCurrentProcess() + { + $lock = $this->getCache()->lock('foo'); + $this->assertFalse($lock->isOwnedByCurrentProcess()); + + $lock->acquire(); + $this->assertTrue($lock->isOwnedByCurrentProcess()); + + $otherLock = $this->getCache()->lock('foo'); + $this->assertFalse($otherLock->isOwnedByCurrentProcess()); + } + + public function testRestoreLock() + { + $lock = $this->getCache()->lock('foo'); + $lock->acquire(); + $this->assertInstanceOf(MongoLock::class, $lock); + + $owner = $lock->owner(); + + $resoredLock = $this->getCache()->restoreLock('foo', $owner); + $this->assertTrue($resoredLock->isOwnedByCurrentProcess()); + + $resoredLock->release(); + $this->assertFalse($resoredLock->isOwnedByCurrentProcess()); + } + + private function getCache(): Repository + { + $repository = Cache::driver('mongodb'); + + $this->assertInstanceOf(Repository::class, $repository); + + return $repository; + } +} diff --git a/tests/TestCase.php b/tests/TestCase.php index 9f3a76e00..e2be67a04 100644 --- a/tests/TestCase.php +++ b/tests/TestCase.php @@ -75,6 +75,12 @@ protected function getEnvironmentSetUp($app) $app['config']->set('auth.providers.users.model', User::class); $app['config']->set('cache.driver', 'array'); + $app['config']->set('cache.stores.mongodb', [ + 'driver' => 'mongodb', + 'connection' => 'mongodb', + 'collection' => 'foo_cache', + ]); + $app['config']->set('queue.default', 'database'); $app['config']->set('queue.connections.database', [ 'driver' => 'mongodb', From 19bb87fad8014dac705af5d8640dfb5140d6d337 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Mon, 22 Apr 2024 13:17:55 -0400 Subject: [PATCH 249/446] DOCSP-35938: Connection Guide docs (#2881) * DOCSP-35938: Connect to MongoDB docs --- docs/fundamentals.txt | 4 +- docs/fundamentals/connection.txt | 25 ++ .../connection/connect-to-mongodb.txt | 355 ++++++++++++++++++ .../includes/figures/connection_uri_parts.png | Bin 0 -> 9609 bytes docs/index.txt | 3 +- 5 files changed, 385 insertions(+), 2 deletions(-) create mode 100644 docs/fundamentals/connection.txt create mode 100644 docs/fundamentals/connection/connect-to-mongodb.txt create mode 100644 docs/includes/figures/connection_uri_parts.png diff --git a/docs/fundamentals.txt b/docs/fundamentals.txt index f9e26b772..004930ad2 100644 --- a/docs/fundamentals.txt +++ b/docs/fundamentals.txt @@ -15,13 +15,15 @@ Fundamentals :titlesonly: :maxdepth: 1 + /fundamentals/connection /fundamentals/database-collection /fundamentals/read-operations /fundamentals/write-operations Learn how to use the {+odm-long+} to perform the following tasks: -- :ref:`Manage Databases and Collections ` +- :ref:`Configure Your MongoDB Connection ` +- :ref:`Databases and Collections ` - :ref:`Read Operations ` - :ref:`Write Operations ` diff --git a/docs/fundamentals/connection.txt b/docs/fundamentals/connection.txt new file mode 100644 index 000000000..b1d11c58a --- /dev/null +++ b/docs/fundamentals/connection.txt @@ -0,0 +1,25 @@ +.. _laravel-fundamentals-connection: + +=========== +Connections +=========== + +.. toctree:: + + /fundamentals/connection/connect-to-mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Overview +-------- + +Learn how to set up a connection from your Laravel application to a MongoDB +deployment and specify the connection behavior by using {+odm-short+} in the +following sections: + +- :ref:`laravel-connect-to-mongodb` + diff --git a/docs/fundamentals/connection/connect-to-mongodb.txt b/docs/fundamentals/connection/connect-to-mongodb.txt new file mode 100644 index 000000000..7de96ad76 --- /dev/null +++ b/docs/fundamentals/connection/connect-to-mongodb.txt @@ -0,0 +1,355 @@ +.. _laravel-connect-to-mongodb: + +================ +Connection Guide +================ + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, seedlist, dsn, data source name + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to connect your Laravel application to a +MongoDB instance or replica set deployment by using {+odm-short+}. + +This guide includes the following sections: + +- :ref:`Connection URI `, which explains connection + URIs and their constituent parts +- :ref:`laravel-database-config`, which explains how to set up your MongoDB + database connection for your Laravel app. +- :ref:`Connection Example `, which provides + examples that show how to connect to MongoDB by using an Atlas connection + string. +- :ref:`laravel-other-ways-to-connect` describes ways to connect to MongoDB + deployments that are not hosted on Atlas. + +.. _laravel-connection-uri: + +Connection URI +-------------- + +A **connection URI**, also known as a connection string, specifies how +{+odm-short+} connects to MongoDB and how to behave while connected. + +Parts of a Connection URI +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following figure explains each part of a sample connection URI: + +.. figure:: /includes/figures/connection_uri_parts.png + :alt: Parts of a connection URI + +In this connection URI, ``mongodb+srv`` is the protocol, which uses the +:manual:`DNS Seed List Connection Format ` +for greater flexibility in your deployment and the ability to change the +servers in rotation without reconfiguring clients. + +If the machine that hosts your MongoDB deployment does not support this +feature, use protocol for the +:manual:`Standard Connection String Format ` +instead. + +If you use a password-based authentication, the part of the connection +string after the protocol contains your username and password. Replace the +placeholder for ``user`` with your username and ``pass`` with your password. +If you use an authentication mechanism that does not require a username +and password, omit this part of the connection URI. + +The part of the connection string after the credentials specifies your MongoDB +instance's hostname or IP address and port. The preceding example uses +``sample.host`` as the hostname and ``27017`` as the port. Replace these values +to point to your MongoDB instance. + +The last part of the connection string specifies connection and authentication +options. In the example, we set the following connection options and values: + +- ``maxPoolSize=20`` +- ``w=majority`` + +.. _laravel-database-config: + +Laravel Database Connection Configuration +------------------------------------------ + +{+odm-short+} lets you configure your MongoDB database connection in the +``config/database.php`` Laravel application file. You can specify the following +connection details in this file: + +- ``default``, which specifies the database connection to use when unspecified +- ``connections``, which contains database connection information to access + one or more databases from your application + +You can use the following code in the configuration file to set the default +connection to a corresponding ``mongodb`` entry in the ``connections`` array: + +.. code-block:: php + + 'default' => 'mongodb', + +For a MongoDB database connection, you can specify the following details: + +.. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - Setting + - Description + + * - ``driver`` + - Specifies the database driver to use for the connection. + + * - ``dsn`` + - The data source name (DSN) that specifies the MongoDB connection URI. + + * - ``host`` + - | Specifies the network address and port of one or more MongoDB nodes + in a deployment. You can use this setting instead of the ``dsn`` + setting. + | To specify a single host, pass the hostname and port as a string as + shown in the following example: + + .. code-block:: php + :copyable: false + + 'host' => 'myhost.example.com:27017', + + | To specify multiple hosts, pass them in an array as shown in the + following example:: + + .. code-block:: php + :copyable: false + + 'host' => ['node1.example.com:27017', 'node2.example.com:27017', 'node3.example.com:27017'], + + .. note:: + + This option does not accept hosts that use the DNS seedlist + connection format. + + * - ``database`` + - Specifies the name of the MongoDB database to read and write to. + + * - ``username`` + - Specifies your database user's username credential to authenticate + with MongoDB. + + * - ``password`` + - Specifies your database user's password credential to authenticate + with MongoDB. + + * - ``options`` + - Specifies connection options to pass to MongoDB that determine the + connection behavior. + + * - ``driverOptions`` + - Specifies options specific to pass to the MongoDB PHP Library driver + that determine the driver behavior for that connection. + +.. note:: + + You can specify the following settings in the ``dsn`` configuration + as parameters in your MongoDB connection string instead of as array items: + + - ``host`` + - ``username`` + - ``password`` + - ``options`` and ``driverOptions``, which are specified by the option name + +The following example shows how you can specify your MongoDB connection details +in the ``connections`` array item: + +.. code-block:: php + :caption: Example config/database.php MongoDB connection configuration + + 'connections' => [ + 'mongodb' => [ + 'driver' => 'mongodb', + 'dsn' => 'mongodb+srv//myUser:myPass123@sample.host:27017/', + 'database' => 'sample_mflix', + 'options' => [ + 'maxPoolSize' => 20, + 'w' => 'majority', + ], + 'driverOptions' => [ + 'serverApi' => 1, + ], + ], + // ... + ], + +The following sections provide common ways of specifying MongoDB connections. + +.. _laravel-atlas-connection-example: + +Connection Example +------------------ + +This section shows how to configure your Laravel application's DSN by using a +MongoDB Atlas connection string. + +To add your MongoDB DSN to your Laravel application, make the following changes: + +- Add the DSN as an environment variable in your project's ``.env`` environment + configuration file. Set the variable value to your Atlas connection string. +- Add a connection entry for your MongoDB connection in the ``connections`` + array of your ``config/database.php`` configuration file. Set the ``dsn`` + value of the connection entry to reference the environment variable that + contains your DSN. + +The following examples show how to specify ``"mongodb+srv://myUser:myPass123@mongodb0.example.com/"`` +as the connection string in the relevant configuration files: + +.. code-block:: bash + :caption: Sample .env environment configuration + + DB_URI="mongodb+srv://myUser:myPass123@mongodb0.example.com/" + +.. code-block:: php + :caption: Sample config/database.php connection entry + :emphasize-lines: 3 + + 'connections' => [ + 'mongodb' => [ + 'dsn' => env('DB_URI'), // uses the value of the DB_URI environment variable + 'driver' => 'mongodb', + 'database' => 'sample_mflix', + // ... + ], + // ... + ] + +.. tip:: + + To retrieve your Atlas connection string, follow the + :ref:`Create a Connection String ` + step of the Quick Start tutorial. + +.. _laravel-other-ways-to-connect: + +Other Ways to Connect to MongoDB +-------------------------------- + +The following sections show you how to connect to a single MongoDB server +instance or a replica set not hosted on MongoDB Atlas. + +.. _laravel-connect-localhost: + +Connect to a MongoDB Server on Your Local Machine +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section shows an example connection string you can use when running a +Laravel application and MongoDB server from the same machine, such as your +local development environment. + +To connect your application to a MongoDB instance hosted on the same machine, +you must complete the following tasks: + +- Download, install, and run the MongoDB server. +- Obtain the IP address and port on which your MongoDB server is running. If + you use the default settings of a local installation of MongoDB server, + the IP address is ``127.0.0.1``, and the port is ``27017``. +- Set up your ``config/database.php`` connection to reference the environment + variable ``DB_URI`` for the value of the ``dsn``, as shown in the + :ref:`laravel-atlas-connection-example` section. + +The following example shows a sample connection string that you can add to the +``.env`` file if your application connects to a MongoDB server running on the +default IP address and port: + +.. code-block:: php + :caption: Sample .env environment configuration to connect to a local MongoDB server. + + DB_URI="mongodb://127.0.0.1:27017/"; + +To learn how to download and install MongoDB server, see +:manual:`Install MongoDB Community Edition ` +in the {+server-docs-name+}. + +.. _laravel-connect-replica-set: + +Connect to a Replica Set +~~~~~~~~~~~~~~~~~~~~~~~~ + +A MongoDB replica set deployment is a group of connected instances, or nodes, +where the nodes store the same data set. This configuration of instances +provides data redundancy and high data availability. + +To connect to a replica set deployment, specify each node's hostname and port +number, separated by commas, and the replica set name as the value of the +``replicaSet`` parameter in the connection string. + +This example, which shows the connection string you can add to your +Laravel application's ``.env`` file to connect to a replica set, uses the +following sample values: + +- ``host1``, ``host2``, and ``host3`` as the hostnames of the MongoDB nodes +- ``27017`` as the port on which MongoDB runs on those hosts +- ``myRS`` as the configured name of the replica set +- ``myUser`` and ``myPass123`` as the credentials of a database user + +.. code-block:: bash + + DB_URI="mongodb://myUser:myPass123@host1:27017,host2:27017,host3:27017/?replicaSet=myRS" + +When connecting to a replica set, the library that {+odm-short+} uses to manage +connections with MongoDB performs the following actions unless otherwise +specified: + +- Discovers all replica set members when given the address of any one member. +- Sends operations to the appropriate member, such as instructions + to write against the **primary** node. To learn more about the replica + set primary, see :manual:`Replica Set Primary ` + in the {+server-docs-name+}. + +.. tip:: + + You are required to specify only one host to connect to a replica set. + However, to ensure connectivity when the selected host is unavailable, + provide the full list of hosts. + +To learn more about setting up a MongoDB replica set, see +:manual:`Deploy a Replica Set ` in the +{+server-docs-name+}. + +Direct Connection +````````````````` + +To force operations to run on a specific node in a MongoDB replica set, +specify the connection information for the node in the connection string and +the ``directConnection`` parameter with a ``true`` value. + +Direct connections include the following limitations: + +- DNS seed list connection format connection strings cannot be used. +- Write operations fail when the specified host is not the primary. +- When the host is not the primary, you must specify the ``secondary`` read + preference in your connection options. To learn more about this limitation, see the + :manual:`secondary read preference entry ` + in the {+server-docs-name+}. + +The following example shows the connection string you can add to your +Laravel application's ``.env`` file to establish a direct connection to a +secondary node in a MongoDB replica set. The example uses the following sample +values: + +- ``host2`` as the hostname of the secondary node +- ``27017`` as the port on which the MongoDB node listens on + +.. code-block:: bash + :caption: Sample .env environment configuration to enable a direct connection + + DB_URI="mongodb://host2:27017/?directConnection=true&readPreference=secondary" + + diff --git a/docs/includes/figures/connection_uri_parts.png b/docs/includes/figures/connection_uri_parts.png new file mode 100644 index 0000000000000000000000000000000000000000..d57165511438d2730a511d8d24f44a7bafda3dab GIT binary patch literal 9609 zcmd6NXEYp6xVI$#kcQ+h2o}*xl;~Cs!Rn%S646#!tg_J)BKop=7gmcX(XAT2tP;Hw z?6S>Jmw^PxqYn%X{8)?z!)Ln3*%}`OPzPo_U_%neca-Aks&)kBEqfNL7>-bcl%l zf#25G9^AXlznaU$+!ilCD(h$v5&5ta5q$Db2A0TQ&AJ21f-;$w^UCQF8HcjgF4i)YN?W@Bm1X4aW`)jF2O zWe$Fl@4WmO;5mF*HbXdws&nqS7_D`E18=YknA-OC?w+e%^#_}ZzXUA^wK^U*N&UaW zShY+<%EhsE1O(dO(D~^;j2iXex$zh1DnB6XWU%&ORziT#TX#yy((rbmWr_46Za(G5)o{V70_uvjEe6RvJjj!6w^Z^pUjW-9 zn>x%P)yK2l@`3987KuudevbT{R_e`Lu5Kp3HM16`<$iWTpRK&QvD6F{Y`w3zj^;5X zb!iQV>%0gWGqH{oFJq6~^fi?x+)Br02O9jRiV-N&oX5CA#t=$?`NakdJp_0{UvPSg(+FaFQ7IO}(bue`xW^#v|o+VRW|4{X1i zzGK}`X&!PeDXF}~3i_E&D*>BWG-#v)7B`iRehDAfm)W=ntjuomP*-2wZeiL^ zIL_8&DpPN{M0}6(8)2LrAwmBJPuNuw?o769lFJ&NyI=K0*75>cwcwSl+j^4erDXK@ zzz~7ZY_Xe%kz@wcSAW@NQt)EO_*NA-gjnxwF^UGp%`IzWN+^`^M}0ui5<9O{&A)dB zw>}6KF>R^QO5rBhBAm0d<4N9?IH^5`#byE1pfV~?I|UDje|plCWEgc&wb2ov%?HqqwY*8P^T33x-pt@xp4IxC@pdlE zoo2E*CyIg2RWt@6VgYA2UhVf!WHGh+U_?PpY2$-Ra56|OwX_*$9aeO5>P)Y>87&@A zawwz+^XAFh77SI=%^=A-fM181i$!1IK~M4q`ljBR{=1c!vPzo5lXOX+yv=;M++*A^ zihJt%&IT*k|2#0^ftoxFK9&;p4g5qeAlDIhnOt#WUpy!D-tq}+qI#ZlJ4H;^A%6{!Md#jz~XAcC(|`aE!&1}$uT;2Tia8`&kXv{bjOdb-s>I`53ECnX|J}* zJ!{CrpV#b9@@uLf4qmjBsUFe52oAxaGP6v#W?P`X(!vpQ?}&Vho2O(PGI5J}j3j+C zj?A(_3CyN49T=Il8GGeo8~OxMnaU~e@1vuQX%LLaWr>^3PXJJf0KP&|pn{Meo$o6CfC*r4Bmz|D1xv&j! z@87?z5f`NFPGohsAs>@@CE|>|%R@xL=+f`?p`Rr~}0fI@ge{k7sd6=r5f#aiGTiNqns7 zJdg<({InTl7rUY=ixa!p&B#hmFGZVJag9g`V|wTCm1d2c-x<--0V@J_L2S^Fn@ubd$U$+Y88iPa_tBW>e4K89m``^m zK+(nm_|`Gdp93^Wrzwi`d6TcBxUBn4m=?tsT+Y?OEvLzOw)(EYWKv!~`z46N?Tp)+ zTf1-k1+AzLX#XW10l0s&(1)np_rcNe)&vi$nWfmqNg9e1NT7M7Uue~6+dXriuVc=jn<7H7(sS9>8 z^ec{MN!QaSsUrp!%Ogt06P#1eh~==FSe*5Z?EZ_5=~yJ|*A@Ba2vb1#=|dQHjqimR zA&(1`79DQCZPvgCJyfVPaC?_L%J@$IsTOt|9A~ zgwcdF#R5JmN8%w`1WPfI@P=8BuAq)ppH5^%h!7%|*7d%TvUAK&@3-*!GD&Y!hl2TM z?t#|2aLz8lMVR%@x;|%UjcL_fWyo{WG&WTiA@w|m$eq}lbU7Z7Afk(+k2WxWafBND=alRjVskIZ^53;^_25 z`{lF?*|&Xzwz2j&I?IBxhSPc;XS1Z}Z$+a?P7vD69at<&;tS~eK9rVT?+lI37Zmv` zeU3=l6~V*Ci_r&(KHE~gBPNd}Vw6K101ex=baK6Lr|BR`4sQnZG_MeK#HRy5C6=FB}~ zVJ2Pl3vJDuvoDE;3+k1?5hWk|QD|wOpQh^BYlLcpbHcRz*G``w+Iph{1l4D|4-O~% zoC({FuT3cm{H@w%MHP#>l1kEy|kgqg@HS_`9YiG6vuLVO$MW{2T&dMucT?1H zk_yXXU-KI5p2@7AW@J@K3}MKgsdx6DA4>=MVoGRyXFcBGbjDJ3(?CLpb%jryXAy7s z&lj~NU=*fRUUGeQxHN-~opAnQRqP@q<^3~*!d*s4*D?*Dwb^#7pr^Xuj}`QG#Ue6{+FyLvv=ax77}m;$D-RX>P_#Vr3aNB(J2`5K=6}w1 zkzLAJIcX>9P`$I%pApXGY$Oz0v-sEybLppIyrPEUZB(1Z&e(&ThSN#I27S}@7$f*( zz*kfR|9Guy(;K+Q`^H0T9FU_Z*}TpMk1g7z>~>64ijHia3kl$hrvpM8C9MhRQz8;x zG_=GbXWSoa9}m9te+lA~hVWH&=QrUxfp(1~#cyP)(Jk3e%e?ai+z7=G8$_1?2TfW9 z7^DfN;C~^isdDLOf#`U|$`{L> z(L(c-LihT1sHVgMw)C3>>~X7|{15Ca@5yRUJ&5c_Yc7@gqFzkY@(xY>GI7_QaI;lSX;@Eq9v9ql3A8y|OKskFA*~XJm z66o{MF^hdAl9LI4q1F3uc-9~n-(W4h4mrB2WYPJ=6B2RASEWbVfzeKJz%tz3>jaeQ z?}GV%ViY3nZrDI|RrHHjDpf@u|E7q(k;c6i9xs{+r#o+@wE*{z7_^Wr>n`rRrv3Ky zBk+-1yHLN)#_DI^@1r7w3%G|`$KY%+x%kXC*Yuy>_O5=(7S<4oi(SZ0nE!GeO$D`L z61$lb-KIjZOc|Ig>biQ0cF*gO#2uu9ky))Jf0wis3Qh3-X&8eE;~3}*D>$s-1<3M% z+zD^s3{NH@7@X}dQP&XJPr^p-LTcDdz>znEQ2D$heGVY^fT5Q9?=qYn^Gz(UAzmn_~z z8p^45&hQygbx)-##J_G^7*SWDs@^hy`z8A=PKT@i{9p=8F>>+@Q&RGMi)4j0?96_o z6U@$1R}lMnSph&fSr2XZrvhmdl*rl31oeh;xl$|E`;M-nGOCN|kkmj$ZdKm+_XrRJ zdZgc!Lc@kcaUzsO7~4xdVG={Hb4q3nUaw7a56yd&ja)L66P!AMVw{ebg@j}5KFTDq zh)I`P{a$nxU7Fn}eV{ut9~oX)`D&@o0b)TrE@w08mLvN#c5gL_Eec{bcf9aGqo9Ar zykxHFUQjYt?5Yr>jE34<0Zkf(JM@lA0pQ2l1gfTVaB*!2k`%Zia^UnEJ#_Tf0A9~p z`S1jx_7LODjEqOs`vMb=+)MrDRCg9iAQ=0nyypg_K$BiCQt*o>TD0M0Bcndg2G;e* zy57Jj|D+-2L~7#d&Gz})e4e5a4+rL;a0&`cA|07^5XGa^X!R zn+@o}?S5xF`UO(UP>Z>DwHk*%)AciafwMl2had=!;=1yXLllcEC=y(_tT|kFdD|AQ zxuv;cWMhU;G3-7)x-f#zi};_G>};w~5+{&j!}493KTfmKep8eT4@#P9@{ALznQ+qc zuiGgH5oF@~kF7p63^?wx$GKYUrtP(KVDV+!1^knK4|$m~RpMw``%f-`thGw|<*6qB z-cO9Fpge)IqFbogbpB+dVm|^$`6uPbmQ3M!AEqaV=rw@QxtE?x2=)5@uPbj%-!Bxd zAJcD;ReT|z=dKP)N2$Ky0nLA}*J1|czHLSdH1_({EzF!I)<8F?Dun{E#W!C7Zm^8E z0r|j{u8ps&pHL$_BVK9Homv4^^^8yKTff2TFh6J$X{h6n88w8;hsgp*6Tky<(7;5Z zhTAdsfI1zhA}Sq3UH(r(r7ycvum{0-)=Ui3t0gQ}w|T~7rVAGwYho)vOs=AkrQ#{- z3wj+A40KDR+*MBl!>cspxp_?WM*`+v3r73!+B{D?!ZZBn7L@aN%v;A*)0&}8F>h&LO{hILO zi|k;!vF`XiNH+DsW^mTM;sze+=YlupU5~!#Pb+*P!j;9RB9p*UV=MVkmdxxM)m03p zC>xd5sfZN=^9Pe$0^RPz_1XCzXL+F#S*VF*{E}d5UN>Bz)bq3s_Qldz=@cl8xEIeB z5K;^e^$Mu@J-&7Q5qOZ}&FEW@s(6&%o7B3i#PDH7ArN0RmigzMjC{Xw<4RM%I$ zkv7f79BIsjt!XY|TaCxzkpiZZrp@b~rG`uf)$emC&1&UlBcm^$=;-ZI&uNIdt%;4U zUVx+L0Ryj?9OR~njZM*8Iy*H0J+x2D0nCa$5?kwaaz$p4I{3amK2b`XOe`Tzx+C47 z#I4`8Vn*j0+yKLwmCWdOh`*Rglk1?K@YCgIll94c^-nhPL$_i+if&e@-J+~3Zuj@N z`^v=kdZ~*YojKIDO%a65H58UX710M zQ}{G;EFr7LU3F|Ed62qgPft;_==GYo4vd{JER9g*Qu4a>p>axRT2_ zPxZO>5ouuD*=lL__fv2KH)x~^TsLFrNdrAZ@9TaZW^#Xj($Riv9fP65f5N-Z(TRIp z60bl>BW0Xk8)DPTsL>l#7 z;JL63%Is2cOWG`XnJev?^J5SP7MJhwKhK~2e?sH^A29Zj&~Yp%zqcs2Svk`6gG905@r4k+o-7$S(Bw zCCL01kZ9{X-h7AwQ{?ytKD(CO*o>YD26&S8YR_Fl>tI0NSY+89phNn9i6V!Ni@XFm z6aMFfc#VM@9AH!1V5W6vx`W#4(igI-b3<1pTaC7cb6Gy#Lvx}SXRxWj|2^gW9jPAa zHl?8)S-p?qY=PFe30(b%@|*lsZj0-dy?MSt9d*->`W}xdIAR_gypCz5E-*H4Jr4Uh zj*(4>sn9_E9p4ZztCEtH`f+H9{xgum-)G$T-17DHtMwp5cfW!~PkFdZR587=m}dIK zc_`NY#5hL1v_t|Z(T}_{td)6c{VgIiGG`LX>9g_F>lBQwugVO|UUHnr4f}op;3F^JObrvX5p(F>vYyos zJ+jf{$sL;K^Bc>bPzTlUn%Z7|Utd)jp&mcs!3{^>9qfRe8=ju=;IcvXs#(MUuGuA! z{4j5%?OaYLbq(eD!9!zf=BE)#k};;M_iWB$QsU^-(^f>|FtbFJaXAx+^_>N`Qr8hQ zWi)X}^k_?QxWbTEQw|PwG|f`$=dg5Lm*OqES)xtyWjp$|PVL?o=p?#592Mc-GUjB~ zY0R=erhtULDg(4Tbnf&$|2n1*CU9 zv;aBq2?+^xCzX}jP(N~%RQ+|6{v#ea64jcbeaN_dV{5Ah0kmAY0VU`+ijxz#!I15V z63S#2<6dH8p?a8b{tQ(*#YJf<6m+5N*S1atee#(UM0syuJ=J9!%Ss;dX)lD%uE*y$v8&O7 zG8;a1S&tup_dRlLyWg{}Ly5cfq`+>PgBA2sO`XoRi#W4hXs-h*oTTbev*5BZha*~Z;FWS;UsZrsC-=_i;^Q;+V&vdDJBN&Hn>Z2) z&&wZew2m*#1A8`Y`F$z^R<4nZEl~d){h!q^)j}(*(G@ROMjn3y1#FBnMv5MdaHjMl zWE^-1nOFBbVo~M5{))jC{TZc2qgeX3^QR&UQ^xnW{Fl-I8!zU_2J}3+j&;K8kixNG ztw{}i>H^XA!l&dduB+S1vD^Nw$u@I^_}p9D%%rlF%;#DyJ_7XN`jLRw!-Q?deEpnc zv2#vw>7SDOV#88zCcp&l^%h@vi2wxX!mzU)~4yAums3(L! z7U|tseXl)C&8U)nG3rWlCiHcBZxX|KVy+8eRVEn{{vNmVXq{)`3D<%e;J@I9k+k~+ zcZb#1AFfw3fkyMf|BBqT`=+5%&Yr0H_I|kyn@Gsxh)9oeti#;yILutc)+tpZ&^r4+?YEW;YC8a1(=8XZP)fJXSpSyZVZ!-OwR@4D^-pyoUOwmeL{t0r~(juC_806z<_>6Cj-%k z^T|N@G~s28y@;cTR|{7ii`uo%tVXvb|;=8p`wgT5W%VdNYZ#n@OaLp0 z#JI7Ap?kH+L@ELK?8eu=_ZjS%6Aa6kGj>gwctFVz_>JyT@mn1S$Vc_E|znmIE0=6AfM;`iN)?#PVVlV}QHB{aLKP$M$I!0jO( z2?SsSfJ>PQ+V~TR8kHe7#tol%oF)@H3KzP)T#xca&TKcOuT?^arVgRjnVwR^w$*z9 z93WAWWGgL4o3Yo}bNgSm=w1uXy8EsX7<+z|9%!ecLcR#;{X#o{`c5qgaffM>8=4Ap z_I>NLNb z)q?G&>*|0U6Bhg?65Z1QUV9|gKa>fGjwyRDJUc8AHsQ|pFC1z6SKS=-c}gzdEAHZf z){n?>w=_|;FSgN%h#PQTPt0gGzhHAh-Ro(GXlaxrlhzRA%yYYRa_P!0d47EdAgv;? zoEz{@b>y+$=0uky2P`V<6>$;G$Fsl$rS*Jr)_{a_SjEF=~GzDe*8WG!vlrPX< zqUEY#faibs??Deqp5p0A?jNE*1Fr5U`1XLGRJ65fosVrjx)BWX`tJ_xsaDHLjfLW~ zV^Ph=>Z5mwu7g~f>5*aCgvmcG#myF8e${w&XK7d}?RN4G>beGiEpR*8 z1%FGnAR@{NWtbAmg?XcrL-!k-ly*ujo5v1aQ3vyz67t$xho;q0!=g|=6Pek>1J8!j zG#fu5BD%hZVDa}(!9U->BrM8OisXYnXPz!79wdndcx{I*QFw_M`X~%1WG~AWa3r6d z05UNuV}@g+KdtW&-Mr)m9VFGtTb@l5hOcM~57C;7{%cF4qFBo6{fSooV2c~%@OG;L zf289smjlt~K=MSElS2LY$Q^}Iy8SV(X0-v~#Zjus0jPK4yhzivoobAeG^$f}KgfmX zce>8Jl$%I?Pl3gwlj(&DUqiFi8s+8X)@yyJ1>7feuToq}`X14qR2@`d_aLrky9z*W z4Y{>#^Nq<+cUS(D$Fo(EX7i@EEI!d^J5(}~LF2x;9^6)n!lMO&l((2|(mG;OR;O*& zhp_HCL@o~9{{6XWiw2mV4N`wZAoZ~Je$RjhyG$yBHav3?1qZYR?PNomC6LrxjMTo?(nC6BwF|IPS3Q!T?Y0J^A63fR_@cPcp8m@{UJGVN zQ$kN_;dh7VQ_@@;ZFA9|fm4y{!|vBv{ViDq1_4$;iN3F}@_nUWRZZ{G?CN6j-hPx~ zyOkof+L#;~T?i(8j=x~>Q8PX47Qf*}AsRzuGy83wGOg|seKvH544K93iFy;gQNxuo zkqrRu5SbwNJ4KxOh>5CuIh(3l_Qn4D{rumr`w88Uz@#np?M}pw{u7OgqNYNb{QIE) E06j{~lK=n! literal 0 HcmV?d00001 diff --git a/docs/index.txt b/docs/index.txt index e1331f6a2..88aee9d65 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -61,7 +61,8 @@ Fundamentals To learn how to perform the following tasks by using {+odm-short+}, see the following content: -- :ref:`Manage Databases and Collections ` +- :ref:`laravel-fundamentals-connection` +- :ref:`laravel-db-coll` - :ref:`laravel-fundamentals-read-ops` - :ref:`laravel-fundamentals-write-ops` - :ref:`laravel-eloquent-models` From eea4950c8477bc2fb1f9926972cff79ee0ba72aa Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Mon, 22 Apr 2024 13:44:05 -0400 Subject: [PATCH 250/446] DOCSP-35941 connection options (#2892) * DOCSP-35941: Connection Options docs --- docs/fundamentals.txt | 9 +- docs/fundamentals/connection.txt | 8 +- .../connection/connection-options.txt | 349 ++++++++++++++++++ 3 files changed, 357 insertions(+), 9 deletions(-) create mode 100644 docs/fundamentals/connection/connection-options.txt diff --git a/docs/fundamentals.txt b/docs/fundamentals.txt index 004930ad2..250e82efa 100644 --- a/docs/fundamentals.txt +++ b/docs/fundamentals.txt @@ -22,8 +22,7 @@ Fundamentals Learn how to use the {+odm-long+} to perform the following tasks: -- :ref:`Configure Your MongoDB Connection ` -- :ref:`Databases and Collections ` -- :ref:`Read Operations ` -- :ref:`Write Operations ` - +- :ref:`laravel-fundamentals-connection` +- :ref:`laravel-db-coll` +- :ref:`laravel-fundamentals-read-ops` +- :ref:`laravel-fundamentals-write-ops` diff --git a/docs/fundamentals/connection.txt b/docs/fundamentals/connection.txt index b1d11c58a..17b849ae9 100644 --- a/docs/fundamentals/connection.txt +++ b/docs/fundamentals/connection.txt @@ -7,6 +7,7 @@ Connections .. toctree:: /fundamentals/connection/connect-to-mongodb + /fundamentals/connection/connection-options .. contents:: On this page :local: @@ -17,9 +18,8 @@ Connections Overview -------- -Learn how to set up a connection from your Laravel application to a MongoDB -deployment and specify the connection behavior by using {+odm-short+} in the -following sections: +Learn how to use {+odm-short+} to set up a connection to a MongoDB deployment +and specify connection behavior in the following sections: - :ref:`laravel-connect-to-mongodb` - +- :ref:`laravel-fundamentals-connection-options` diff --git a/docs/fundamentals/connection/connection-options.txt b/docs/fundamentals/connection/connection-options.txt new file mode 100644 index 000000000..9d873a406 --- /dev/null +++ b/docs/fundamentals/connection/connection-options.txt @@ -0,0 +1,349 @@ +.. _laravel-fundamentals-connection-options: + +================== +Connection Options +================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, data source name, dsn, authentication, configuration, options, driverOptions + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn about connection, authentication, and driver +options and how to specify them in your Laravel application's database +connection configuration. Connection options are passed to the {+php-library+}, +which manages your database connections. + +To learn more about the {+php-library+}, see the +`{+php-library+} documentation `__. + +This guide covers the following topics: + +- :ref:`laravel-connection-auth-options` +- :ref:`laravel-driver-options` + +.. _laravel-connection-auth-options: + +Connection and Authentication Options +------------------------------------- + +Learn how to add common connection and authentication options to your +configuration file in the following sections: + +- :ref:`laravel-connection-auth-example` +- :ref:`laravel-connection-auth-descriptions` + +.. _laravel-connection-auth-example: + +Add Connection and Authentication Options +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can specify connection or authentication options in your Laravel web +application's ``config/database.php`` configuration file by using one of the +following methods: + +- Add the setting and value as an array item in the ``options`` array item. +- Append the setting and value as a query string parameter on the connection + string specified in the ``dsn`` array item. + +To specify an option in the ``options`` array, add its name and value as an +array item, as shown in the following example: + +.. code-block:: php + :emphasize-lines: 6-10 + + 'connections' => [ + 'mongodb' => [ + 'dsn' => 'mongodb+srv://mongodb0.example.com/', + 'driver' => 'mongodb', + 'database' => 'sample_mflix', + 'options' => [ + 'appName' => 'myLaravelApp', + 'compressors' => 'zlib', + 'zlibCompressionLevel' => 7, + ], + ], + ], + +To specify options as parameters in the connection string, use the following +query string syntax formatting: + +- Add the question mark character, ``?``, to separate the host information + from the parameters. +- Add the options by formatting them as `` + + + tests/Ticket/*.php + diff --git a/src/Eloquent/HybridRelations.php b/src/Eloquent/HybridRelations.php index 5c058f50f..be20327ee 100644 --- a/src/Eloquent/HybridRelations.php +++ b/src/Eloquent/HybridRelations.php @@ -226,7 +226,7 @@ public function morphTo($name = null, $type = null, $id = null, $ownerKey = null $this->newQuery(), $this, $id, - $ownerKey ?: $this->getKeyName(), + $ownerKey, $type, $name, ); diff --git a/src/Relations/MorphTo.php b/src/Relations/MorphTo.php index 1eff5e53b..692991372 100644 --- a/src/Relations/MorphTo.php +++ b/src/Relations/MorphTo.php @@ -17,7 +17,7 @@ public function addConstraints() // or has many relationships, we need to actually query on the primary key // of the related models matching on the foreign key that's on a parent. $this->query->where( - $this->ownerKey, + $this->ownerKey ?? $this->getForeignKeyName(), '=', $this->getForeignKeyFrom($this->parent), ); diff --git a/tests/Ticket/GH2783Test.php b/tests/Ticket/GH2783Test.php new file mode 100644 index 000000000..73324ddc0 --- /dev/null +++ b/tests/Ticket/GH2783Test.php @@ -0,0 +1,75 @@ + 'Lorem ipsum']); + $user = GH2783User::create(['username' => 'jsmith']); + + $imageWithPost = GH2783Image::create(['uri' => 'http://example.com/post.png']); + $imageWithPost->imageable()->associate($post)->save(); + + $imageWithUser = GH2783Image::create(['uri' => 'http://example.com/user.png']); + $imageWithUser->imageable()->associate($user)->save(); + + $queriedImageWithPost = GH2783Image::with('imageable')->find($imageWithPost->getKey()); + $this->assertInstanceOf(GH2783Post::class, $queriedImageWithPost->imageable); + $this->assertEquals($post->_id, $queriedImageWithPost->imageable->getKey()); + + $queriedImageWithUser = GH2783Image::with('imageable')->find($imageWithUser->getKey()); + $this->assertInstanceOf(GH2783User::class, $queriedImageWithUser->imageable); + $this->assertEquals($user->username, $queriedImageWithUser->imageable->getKey()); + } +} + +class GH2783Image extends Model +{ + protected $connection = 'mongodb'; + protected $fillable = ['uri']; + + public function imageable(): MorphTo + { + return $this->morphTo(__FUNCTION__, 'imageable_type', 'imageable_id'); + } +} + +class GH2783Post extends Model +{ + protected $connection = 'mongodb'; + protected $fillable = ['text']; + + public function image(): MorphOne + { + return $this->morphOne(GH2783Image::class, 'imageable'); + } +} + +class GH2783User extends Model +{ + protected $connection = 'mongodb'; + protected $fillable = ['username']; + protected $primaryKey = 'username'; + + public function image(): MorphOne + { + return $this->morphOne(GH2783Image::class, 'imageable'); + } +} From 0a143cc31601417ff07290afa7b7a700f6f8d144 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Fri, 28 Jun 2024 12:52:23 -0400 Subject: [PATCH 298/446] DOCSP-41010: Fix transactions code example (#3016) --- docs/transactions.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/transactions.txt b/docs/transactions.txt index 5ef3df19d..89562c795 100644 --- a/docs/transactions.txt +++ b/docs/transactions.txt @@ -99,7 +99,8 @@ to another account: :start-after: begin transaction callback :end-before: end transaction callback -You can optionally pass the maximum number of times to retry a failed transaction as the second parameter as shown in the following code example: +You can optionally pass the maximum number of times to retry a failed transaction +as the second parameter, as shown in the following code example: .. code-block:: php :emphasize-lines: 4 @@ -107,7 +108,7 @@ You can optionally pass the maximum number of times to retry a failed transactio DB::transaction(function() { // transaction code }, - retries: 5, + attempts: 5, ); .. _laravel-transaction-commit: From ffacc6b48b7f8e08006a27e323e587976dfa67ea Mon Sep 17 00:00:00 2001 From: MongoDB PHP Bot <162451593+mongodb-php-bot@users.noreply.github.com> Date: Fri, 28 Jun 2024 19:07:09 +0200 Subject: [PATCH 299/446] DOCSP-41010: Fix transactions code example (#3016) (#3020) Co-authored-by: Nora Reidy --- docs/transactions.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/transactions.txt b/docs/transactions.txt index 5ef3df19d..89562c795 100644 --- a/docs/transactions.txt +++ b/docs/transactions.txt @@ -99,7 +99,8 @@ to another account: :start-after: begin transaction callback :end-before: end transaction callback -You can optionally pass the maximum number of times to retry a failed transaction as the second parameter as shown in the following code example: +You can optionally pass the maximum number of times to retry a failed transaction +as the second parameter, as shown in the following code example: .. code-block:: php :emphasize-lines: 4 @@ -107,7 +108,7 @@ You can optionally pass the maximum number of times to retry a failed transactio DB::transaction(function() { // transaction code }, - retries: 5, + attempts: 5, ); .. _laravel-transaction-commit: From 89463b05cf46e8dc52d4edc65f2beae989175b4f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 8 Jul 2024 16:59:05 +0200 Subject: [PATCH 300/446] Create DocumentModel trait to enable MongoDB on any 3rd party model class (#2580) * Create DocumentModel trait to enable MongoDB on any 3rd party model class * Use the trait for every test model * Add method Model::isDocumentModel to check when model classes can be used with MongoDB * Refactor the User class to extend Laravel's User class --- CHANGELOG.md | 8 +- phpstan-baseline.neon | 4 +- src/Auth/User.php | 23 +- src/Eloquent/DocumentModel.php | 749 ++++++++++++++++++++++++++ src/Eloquent/HybridRelations.php | 22 +- src/Eloquent/Model.php | 757 +-------------------------- src/Helpers/QueriesRelationships.php | 2 +- src/Relations/BelongsToMany.php | 7 +- src/Relations/EmbedsMany.php | 5 +- src/Relations/EmbedsOneOrMany.php | 11 +- src/Relations/MorphToMany.php | 20 +- tests/Eloquent/ModelTest.php | 62 +++ tests/ModelTest.php | 17 +- tests/Models/Address.php | 11 +- tests/Models/Birthday.php | 11 +- tests/Models/Book.php | 14 +- tests/Models/CastObjectId.php | 6 +- tests/Models/Casting.php | 6 +- tests/Models/Client.php | 13 +- tests/Models/Experience.php | 13 +- tests/Models/Group.php | 13 +- tests/Models/Guarded.php | 13 +- tests/Models/HiddenAnimal.php | 8 +- tests/Models/IdIsBinaryUuid.php | 13 +- tests/Models/IdIsInt.php | 14 +- tests/Models/IdIsString.php | 13 +- tests/Models/Item.php | 13 +- tests/Models/Label.php | 13 +- tests/Models/Location.php | 13 +- tests/Models/Photo.php | 13 +- tests/Models/Role.php | 13 +- tests/Models/Scoped.php | 13 +- tests/Models/Skill.php | 13 +- tests/Models/Soft.php | 14 +- tests/Models/SqlBook.php | 6 +- tests/Models/SqlRole.php | 4 +- tests/Models/SqlUser.php | 4 +- tests/Models/User.php | 14 +- tests/RelationsTest.php | 1 - tests/TransactionTest.php | 4 +- 40 files changed, 1086 insertions(+), 887 deletions(-) create mode 100644 src/Eloquent/DocumentModel.php create mode 100644 tests/Eloquent/ModelTest.php diff --git a/CHANGELOG.md b/CHANGELOG.md index 0345701b8..0a0a120f2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,9 +1,13 @@ # Changelog All notable changes to this project will be documented in this file. -## [4.5.0] - upcoming +## [4.6.0] - upcoming -* Add GridFS integration for Laravel File Storage by @GromNaN in [#2984](https://github.com/mongodb/laravel-mongodb/pull/2985) +* Add `DocumentTrait` to use any 3rd party model with MongoDB @GromNaN in [#2580](https://github.com/mongodb/laravel-mongodb/pull/2580) + +## [4.5.0] - 2024-06-20 + +* Add GridFS integration for Laravel File Storage by @GromNaN in [#2985](https://github.com/mongodb/laravel-mongodb/pull/2985) ## [4.4.0] - 2024-05-31 diff --git a/phpstan-baseline.neon b/phpstan-baseline.neon index fdef24410..e85adb7d2 100644 --- a/phpstan-baseline.neon +++ b/phpstan-baseline.neon @@ -7,12 +7,12 @@ parameters: - message: "#^Method Illuminate\\\\Database\\\\Eloquent\\\\Model\\:\\:push\\(\\) invoked with 3 parameters, 0 required\\.$#" - count: 2 + count: 3 path: src/Relations/BelongsToMany.php - message: "#^Method Illuminate\\\\Database\\\\Eloquent\\\\Model\\:\\:push\\(\\) invoked with 3 parameters, 0 required\\.$#" - count: 2 + count: 6 path: src/Relations/MorphToMany.php - diff --git a/src/Auth/User.php b/src/Auth/User.php index d14aa4822..a58a898ad 100644 --- a/src/Auth/User.php +++ b/src/Auth/User.php @@ -4,22 +4,13 @@ namespace MongoDB\Laravel\Auth; -use Illuminate\Auth\Authenticatable; -use Illuminate\Auth\MustVerifyEmail; -use Illuminate\Auth\Passwords\CanResetPassword; -use Illuminate\Contracts\Auth\Access\Authorizable as AuthorizableContract; -use Illuminate\Contracts\Auth\Authenticatable as AuthenticatableContract; -use Illuminate\Contracts\Auth\CanResetPassword as CanResetPasswordContract; -use Illuminate\Foundation\Auth\Access\Authorizable; -use MongoDB\Laravel\Eloquent\Model; +use Illuminate\Foundation\Auth\User as BaseUser; +use MongoDB\Laravel\Eloquent\DocumentModel; -class User extends Model implements - AuthenticatableContract, - AuthorizableContract, - CanResetPasswordContract +class User extends BaseUser { - use Authenticatable; - use Authorizable; - use CanResetPassword; - use MustVerifyEmail; + use DocumentModel; + + protected $primaryKey = '_id'; + protected $keyType = 'string'; } diff --git a/src/Eloquent/DocumentModel.php b/src/Eloquent/DocumentModel.php new file mode 100644 index 000000000..15c33ef16 --- /dev/null +++ b/src/Eloquent/DocumentModel.php @@ -0,0 +1,749 @@ +attributes)) { + $value = $this->attributes['_id']; + } + + // Convert ObjectID to string. + if ($value instanceof ObjectID) { + return (string) $value; + } + + if ($value instanceof Binary) { + return (string) $value->getData(); + } + + return $value; + } + + /** @inheritdoc */ + public function getQualifiedKeyName() + { + return $this->getKeyName(); + } + + /** @inheritdoc */ + public function fromDateTime($value) + { + // If the value is already a UTCDateTime instance, we don't need to parse it. + if ($value instanceof UTCDateTime) { + return $value; + } + + // Let Eloquent convert the value to a DateTime instance. + if (! $value instanceof DateTimeInterface) { + $value = parent::asDateTime($value); + } + + return new UTCDateTime($value); + } + + /** @inheritdoc */ + protected function asDateTime($value) + { + // Convert UTCDateTime instances to Carbon. + if ($value instanceof UTCDateTime) { + return Date::instance($value->toDateTime()) + ->setTimezone(new DateTimeZone(date_default_timezone_get())); + } + + return parent::asDateTime($value); + } + + /** @inheritdoc */ + public function getDateFormat() + { + return $this->dateFormat ?: 'Y-m-d H:i:s'; + } + + /** @inheritdoc */ + public function freshTimestamp() + { + return new UTCDateTime(Date::now()); + } + + /** @inheritdoc */ + public function getTable() + { + return $this->collection ?? parent::getTable(); + } + + /** @inheritdoc */ + public function getAttribute($key) + { + if (! $key) { + return null; + } + + $key = (string) $key; + + // An unset attribute is null or throw an exception. + if (isset($this->unset[$key])) { + return $this->throwMissingAttributeExceptionIfApplicable($key); + } + + // Dot notation support. + if (str_contains($key, '.') && Arr::has($this->attributes, $key)) { + return $this->getAttributeValue($key); + } + + // This checks for embedded relation support. + // Ignore methods defined in the class Eloquent Model or in this trait. + if ( + method_exists($this, $key) + && ! method_exists(Model::class, $key) + && ! method_exists(DocumentModel::class, $key) + && ! $this->hasAttributeGetMutator($key) + ) { + return $this->getRelationValue($key); + } + + return parent::getAttribute($key); + } + + /** @inheritdoc */ + protected function transformModelValue($key, $value) + { + $value = parent::transformModelValue($key, $value); + // Casting attributes to any of date types, will convert that attribute + // to a Carbon or CarbonImmutable instance. + // @see Model::setAttribute() + if ($this->hasCast($key) && $value instanceof CarbonInterface) { + $value->settings(array_merge($value->getSettings(), ['toStringFormat' => $this->getDateFormat()])); + + // "date" cast resets the time to 00:00:00. + $castType = $this->getCasts()[$key]; + if (str_starts_with($castType, 'date:') || str_starts_with($castType, 'immutable_date:')) { + $value = $value->startOfDay(); + } + } + + return $value; + } + + /** @inheritdoc */ + protected function getCastType($key) + { + $castType = $this->getCasts()[$key]; + if ($this->isCustomDateTimeCast($castType) || $this->isImmutableCustomDateTimeCast($castType)) { + $this->setDateFormat(Str::after($castType, ':')); + } + + return parent::getCastType($key); + } + + /** @inheritdoc */ + protected function getAttributeFromArray($key) + { + $key = (string) $key; + + // Support keys in dot notation. + if (str_contains($key, '.')) { + return Arr::get($this->attributes, $key); + } + + return parent::getAttributeFromArray($key); + } + + /** @inheritdoc */ + public function setAttribute($key, $value) + { + $key = (string) $key; + + $casts = $this->getCasts(); + if (array_key_exists($key, $casts)) { + $castType = $this->getCastType($key); + $castOptions = Str::after($casts[$key], ':'); + + // Can add more native mongo type casts here. + $value = match ($castType) { + 'decimal' => $this->fromDecimal($value, $castOptions), + default => $value, + }; + } + + // Convert _id to ObjectID. + if ($key === '_id' && is_string($value)) { + $builder = $this->newBaseQueryBuilder(); + + $value = $builder->convertKey($value); + } + + // Support keys in dot notation. + if (str_contains($key, '.')) { + // Store to a temporary key, then move data to the actual key + parent::setAttribute('__LARAVEL_TEMPORARY_KEY__', $value); + + Arr::set($this->attributes, $key, $this->attributes['__LARAVEL_TEMPORARY_KEY__'] ?? null); + unset($this->attributes['__LARAVEL_TEMPORARY_KEY__']); + + return $this; + } + + // Setting an attribute cancels the unset operation. + unset($this->unset[$key]); + + return parent::setAttribute($key, $value); + } + + /** + * @param mixed $value + * + * @inheritdoc + */ + protected function asDecimal($value, $decimals) + { + // Convert BSON to string. + if ($this->isBSON($value)) { + if ($value instanceof Binary) { + $value = $value->getData(); + } elseif ($value instanceof Stringable) { + $value = (string) $value; + } else { + throw new MathException('BSON type ' . $value::class . ' cannot be converted to string'); + } + } + + return parent::asDecimal($value, $decimals); + } + + /** + * Change to mongo native for decimal cast. + * + * @param mixed $value + * @param int $decimals + * + * @return Decimal128 + */ + protected function fromDecimal($value, $decimals) + { + return new Decimal128($this->asDecimal($value, $decimals)); + } + + /** @inheritdoc */ + public function attributesToArray() + { + $attributes = parent::attributesToArray(); + + // Because the original Eloquent never returns objects, we convert + // MongoDB related objects to a string representation. This kind + // of mimics the SQL behaviour so that dates are formatted + // nicely when your models are converted to JSON. + foreach ($attributes as $key => &$value) { + if ($value instanceof ObjectID) { + $value = (string) $value; + } elseif ($value instanceof Binary) { + $value = (string) $value->getData(); + } + } + + return $attributes; + } + + /** @inheritdoc */ + public function getCasts() + { + return $this->casts; + } + + /** @inheritdoc */ + public function getDirty() + { + $dirty = parent::getDirty(); + + // The specified value in the $unset expression does not impact the operation. + if ($this->unset !== []) { + $dirty['$unset'] = $this->unset; + } + + return $dirty; + } + + /** @inheritdoc */ + public function originalIsEquivalent($key) + { + if (! array_key_exists($key, $this->original)) { + return false; + } + + // Calling unset on an attribute marks it as "not equivalent". + if (isset($this->unset[$key])) { + return false; + } + + $attribute = Arr::get($this->attributes, $key); + $original = Arr::get($this->original, $key); + + if ($attribute === $original) { + return true; + } + + if ($attribute === null) { + return false; + } + + if ($this->isDateAttribute($key)) { + $attribute = $attribute instanceof UTCDateTime ? $this->asDateTime($attribute) : $attribute; + $original = $original instanceof UTCDateTime ? $this->asDateTime($original) : $original; + + // Comparison on DateTimeInterface values + // phpcs:disable SlevomatCodingStandard.Operators.DisallowEqualOperators.DisallowedEqualOperator + return $attribute == $original; + } + + if ($this->hasCast($key, static::$primitiveCastTypes)) { + return $this->castAttribute($key, $attribute) === + $this->castAttribute($key, $original); + } + + return is_numeric($attribute) && is_numeric($original) + && strcmp((string) $attribute, (string) $original) === 0; + } + + /** @inheritdoc */ + public function offsetUnset($offset): void + { + $offset = (string) $offset; + + if (str_contains($offset, '.')) { + // Update the field in the subdocument + Arr::forget($this->attributes, $offset); + } else { + parent::offsetUnset($offset); + + // Force unsetting even if the attribute is not set. + // End user can optimize DB calls by checking if the attribute is set before unsetting it. + $this->unset[$offset] = true; + } + } + + /** @inheritdoc */ + public function offsetSet($offset, $value): void + { + parent::offsetSet($offset, $value); + + // Setting an attribute cancels the unset operation. + unset($this->unset[$offset]); + } + + /** + * Remove one or more fields. + * + * @deprecated Use unset() instead. + * + * @param string|string[] $columns + * + * @return void + */ + public function drop($columns) + { + $this->unset($columns); + } + + /** + * Remove one or more fields. + * + * @param string|string[] $columns + * + * @return void + */ + public function unset($columns) + { + $columns = Arr::wrap($columns); + + // Unset attributes + foreach ($columns as $column) { + $this->__unset($column); + } + } + + /** @inheritdoc */ + public function push() + { + $parameters = func_get_args(); + if ($parameters) { + $unique = false; + + if (count($parameters) === 3) { + [$column, $values, $unique] = $parameters; + } else { + [$column, $values] = $parameters; + } + + // Do batch push by default. + $values = Arr::wrap($values); + + $query = $this->setKeysForSaveQuery($this->newQuery()); + + $this->pushAttributeValues($column, $values, $unique); + + return $query->push($column, $values, $unique); + } + + return parent::push(); + } + + /** + * Remove one or more values from an array. + * + * @param string $column + * @param mixed $values + * + * @return mixed + */ + public function pull($column, $values) + { + // Do batch pull by default. + $values = Arr::wrap($values); + + $query = $this->setKeysForSaveQuery($this->newQuery()); + + $this->pullAttributeValues($column, $values); + + return $query->pull($column, $values); + } + + /** + * Append one or more values to the underlying attribute value and sync with original. + * + * @param string $column + * @param bool $unique + */ + protected function pushAttributeValues($column, array $values, $unique = false) + { + $current = $this->getAttributeFromArray($column) ?: []; + + foreach ($values as $value) { + // Don't add duplicate values when we only want unique values. + if ($unique && (! is_array($current) || in_array($value, $current))) { + continue; + } + + $current[] = $value; + } + + $this->attributes[$column] = $current; + + $this->syncOriginalAttribute($column); + } + + /** + * Remove one or more values to the underlying attribute value and sync with original. + * + * @param string $column + */ + protected function pullAttributeValues($column, array $values) + { + $current = $this->getAttributeFromArray($column) ?: []; + + if (is_array($current)) { + foreach ($values as $value) { + $keys = array_keys($current, $value); + + foreach ($keys as $key) { + unset($current[$key]); + } + } + } + + $this->attributes[$column] = array_values($current); + + $this->syncOriginalAttribute($column); + } + + /** @inheritdoc */ + public function getForeignKey() + { + return Str::snake(class_basename($this)) . '_' . ltrim($this->primaryKey, '_'); + } + + /** + * Set the parent relation. + */ + public function setParentRelation(Relation $relation) + { + $this->parentRelation = $relation; + } + + /** + * Get the parent relation. + */ + public function getParentRelation(): ?Relation + { + return $this->parentRelation ?? null; + } + + /** @inheritdoc */ + public function newEloquentBuilder($query) + { + return new Builder($query); + } + + /** @inheritdoc */ + public function qualifyColumn($column) + { + return $column; + } + + /** @inheritdoc */ + protected function newBaseQueryBuilder() + { + $connection = $this->getConnection(); + + return new QueryBuilder($connection, $connection->getQueryGrammar(), $connection->getPostProcessor()); + } + + /** @inheritdoc */ + protected function removeTableFromKey($key) + { + return $key; + } + + /** + * Get the queueable relationships for the entity. + * + * @return array + */ + public function getQueueableRelations() + { + $relations = []; + + foreach ($this->getRelationsWithoutParent() as $key => $relation) { + if (method_exists($this, $key)) { + $relations[] = $key; + } + + if ($relation instanceof QueueableCollection) { + foreach ($relation->getQueueableRelations() as $collectionValue) { + $relations[] = $key . '.' . $collectionValue; + } + } + + if ($relation instanceof QueueableEntity) { + foreach ($relation->getQueueableRelations() as $entityKey => $entityValue) { + $relations[] = $key . '.' . $entityValue; + } + } + } + + return array_unique($relations); + } + + /** + * Get loaded relations for the instance without parent. + * + * @return array + */ + protected function getRelationsWithoutParent() + { + $relations = $this->getRelations(); + + $parentRelation = $this->getParentRelation(); + if ($parentRelation) { + unset($relations[$parentRelation->getQualifiedForeignKeyName()]); + } + + return $relations; + } + + /** + * Checks if column exists on a table. As this is a document model, just return true. This also + * prevents calls to non-existent function Grammar::compileColumnListing(). + * + * @param string $key + * + * @return bool + */ + protected function isGuardableColumn($key) + { + return true; + } + + /** @inheritdoc */ + protected function addCastAttributesToArray(array $attributes, array $mutatedAttributes) + { + foreach ($this->getCasts() as $key => $castType) { + if (! Arr::has($attributes, $key) || Arr::has($mutatedAttributes, $key)) { + continue; + } + + $originalValue = Arr::get($attributes, $key); + + // Here we will cast the attribute. Then, if the cast is a date or datetime cast + // then we will serialize the date for the array. This will convert the dates + // to strings based on the date format specified for these Eloquent models. + $castValue = $this->castAttribute( + $key, + $originalValue, + ); + + // If the attribute cast was a date or a datetime, we will serialize the date as + // a string. This allows the developers to customize how dates are serialized + // into an array without affecting how they are persisted into the storage. + if ($castValue !== null && in_array($castType, ['date', 'datetime', 'immutable_date', 'immutable_datetime'])) { + $castValue = $this->serializeDate($castValue); + } + + if ($castValue !== null && ($this->isCustomDateTimeCast($castType) || $this->isImmutableCustomDateTimeCast($castType))) { + $castValue = $castValue->format(explode(':', $castType, 2)[1]); + } + + if ($castValue instanceof DateTimeInterface && $this->isClassCastable($key)) { + $castValue = $this->serializeDate($castValue); + } + + if ($castValue !== null && $this->isClassSerializable($key)) { + $castValue = $this->serializeClassCastableAttribute($key, $castValue); + } + + if ($this->isEnumCastable($key) && (! $castValue instanceof Arrayable)) { + $castValue = $castValue !== null ? $this->getStorableEnumValueFromLaravel11($this->getCasts()[$key], $castValue) : null; + } + + if ($castValue instanceof Arrayable) { + $castValue = $castValue->toArray(); + } + + Arr::set($attributes, $key, $castValue); + } + + return $attributes; + } + + /** + * Duplicate of {@see HasAttributes::getStorableEnumValue()} for Laravel 11 as the signature of the method has + * changed in a non-backward compatible way. + * + * @todo Remove this method when support for Laravel 10 is dropped. + */ + private function getStorableEnumValueFromLaravel11($expectedEnum, $value) + { + if (! $value instanceof $expectedEnum) { + throw new ValueError(sprintf('Value [%s] is not of the expected enum type [%s].', var_export($value, true), $expectedEnum)); + } + + return $value instanceof BackedEnum + ? $value->value + : $value->name; + } + + /** + * Is a value a BSON type? + * + * @param mixed $value + * + * @return bool + */ + protected function isBSON(mixed $value): bool + { + return $value instanceof Type; + } + + /** + * {@inheritDoc} + */ + public function save(array $options = []) + { + // SQL databases would use autoincrement the id field if set to null. + // Apply the same behavior to MongoDB with _id only, otherwise null would be stored. + if (array_key_exists('_id', $this->attributes) && $this->attributes['_id'] === null) { + unset($this->attributes['_id']); + } + + $saved = parent::save($options); + + // Clear list of unset fields + $this->unset = []; + + return $saved; + } + + /** + * {@inheritDoc} + */ + public function refresh() + { + parent::refresh(); + + // Clear list of unset fields + $this->unset = []; + + return $this; + } +} diff --git a/src/Eloquent/HybridRelations.php b/src/Eloquent/HybridRelations.php index be20327ee..8ca4ea289 100644 --- a/src/Eloquent/HybridRelations.php +++ b/src/Eloquent/HybridRelations.php @@ -7,7 +7,6 @@ use Illuminate\Database\Eloquent\Concerns\HasRelationships; use Illuminate\Database\Eloquent\Relations\MorphOne; use Illuminate\Support\Str; -use MongoDB\Laravel\Eloquent\Model as MongoDBModel; use MongoDB\Laravel\Helpers\EloquentBuilder; use MongoDB\Laravel\Relations\BelongsTo; use MongoDB\Laravel\Relations\BelongsToMany; @@ -20,7 +19,6 @@ use function array_pop; use function debug_backtrace; use function implode; -use function is_subclass_of; use function preg_split; use const DEBUG_BACKTRACE_IGNORE_ARGS; @@ -46,7 +44,7 @@ trait HybridRelations public function hasOne($related, $foreignKey = null, $localKey = null) { // Check if it is a relation with an original model. - if (! is_subclass_of($related, MongoDBModel::class)) { + if (! Model::isDocumentModel($related)) { return parent::hasOne($related, $foreignKey, $localKey); } @@ -75,7 +73,7 @@ public function hasOne($related, $foreignKey = null, $localKey = null) public function morphOne($related, $name, $type = null, $id = null, $localKey = null) { // Check if it is a relation with an original model. - if (! is_subclass_of($related, MongoDBModel::class)) { + if (! Model::isDocumentModel($related)) { return parent::morphOne($related, $name, $type, $id, $localKey); } @@ -102,7 +100,7 @@ public function morphOne($related, $name, $type = null, $id = null, $localKey = public function hasMany($related, $foreignKey = null, $localKey = null) { // Check if it is a relation with an original model. - if (! is_subclass_of($related, MongoDBModel::class)) { + if (! Model::isDocumentModel($related)) { return parent::hasMany($related, $foreignKey, $localKey); } @@ -131,7 +129,7 @@ public function hasMany($related, $foreignKey = null, $localKey = null) public function morphMany($related, $name, $type = null, $id = null, $localKey = null) { // Check if it is a relation with an original model. - if (! is_subclass_of($related, MongoDBModel::class)) { + if (! Model::isDocumentModel($related)) { return parent::morphMany($related, $name, $type, $id, $localKey); } @@ -171,7 +169,7 @@ public function belongsTo($related, $foreignKey = null, $ownerKey = null, $relat } // Check if it is a relation with an original model. - if (! is_subclass_of($related, MongoDBModel::class)) { + if (! Model::isDocumentModel($related)) { return parent::belongsTo($related, $foreignKey, $ownerKey, $relation); } @@ -242,7 +240,7 @@ public function morphTo($name = null, $type = null, $id = null, $ownerKey = null $ownerKey ??= $instance->getKeyName(); // Check if it is a relation with an original model. - if (! is_subclass_of($instance, MongoDBModel::class)) { + if (! Model::isDocumentModel($instance)) { return parent::morphTo($name, $type, $id, $ownerKey); } @@ -288,7 +286,7 @@ public function belongsToMany( } // Check if it is a relation with an original model. - if (! is_subclass_of($related, MongoDBModel::class)) { + if (! Model::isDocumentModel($related)) { return parent::belongsToMany( $related, $collection, @@ -367,7 +365,7 @@ public function morphToMany( } // Check if it is a relation with an original model. - if (! is_subclass_of($related, Model::class)) { + if (! Model::isDocumentModel($related)) { return parent::morphToMany( $related, $name, @@ -434,7 +432,7 @@ public function morphedByMany( ) { // If the related model is an instance of eloquent model class, leave pivot keys // as default. It's necessary for supporting hybrid relationship - if (is_subclass_of($related, Model::class)) { + if (Model::isDocumentModel($related)) { // For the inverse of the polymorphic many-to-many relations, we will change // the way we determine the foreign and other keys, as it is the opposite // of the morph-to-many method since we're figuring out these inverses. @@ -459,7 +457,7 @@ public function morphedByMany( /** @inheritdoc */ public function newEloquentBuilder($query) { - if ($this instanceof MongoDBModel) { + if (Model::isDocumentModel($this)) { return new Builder($query); } diff --git a/src/Eloquent/Model.php b/src/Eloquent/Model.php index f7b4f1f36..fcb9c4f04 100644 --- a/src/Eloquent/Model.php +++ b/src/Eloquent/Model.php @@ -4,63 +4,17 @@ namespace MongoDB\Laravel\Eloquent; -use BackedEnum; -use Carbon\CarbonInterface; -use DateTimeInterface; -use DateTimeZone; -use Illuminate\Contracts\Queue\QueueableCollection; -use Illuminate\Contracts\Queue\QueueableEntity; -use Illuminate\Contracts\Support\Arrayable; use Illuminate\Database\Eloquent\Model as BaseModel; -use Illuminate\Database\Eloquent\Relations\Relation; -use Illuminate\Support\Arr; -use Illuminate\Support\Exceptions\MathException; -use Illuminate\Support\Facades\Date; -use Illuminate\Support\Str; -use MongoDB\BSON\Binary; -use MongoDB\BSON\Decimal128; -use MongoDB\BSON\ObjectID; -use MongoDB\BSON\Type; -use MongoDB\BSON\UTCDateTime; -use MongoDB\Laravel\Query\Builder as QueryBuilder; -use Stringable; -use ValueError; +use MongoDB\Laravel\Auth\User; use function array_key_exists; -use function array_keys; -use function array_merge; -use function array_unique; -use function array_values; -use function class_basename; -use function count; -use function date_default_timezone_get; -use function explode; -use function func_get_args; -use function in_array; -use function is_array; -use function is_numeric; -use function is_string; -use function ltrim; -use function method_exists; -use function sprintf; -use function str_contains; -use function str_starts_with; -use function strcmp; -use function var_export; +use function class_uses_recursive; +use function is_object; +use function is_subclass_of; abstract class Model extends BaseModel { - use HybridRelations; - use EmbedsRelations; - - private const TEMPORARY_KEY = '__LARAVEL_TEMPORARY_KEY__'; - - /** - * The collection associated with the model. - * - * @var string - */ - protected $collection; + use DocumentModel; /** * The primary key for the model. @@ -76,699 +30,38 @@ abstract class Model extends BaseModel */ protected $keyType = 'string'; - /** - * The parent relation instance. - * - * @var Relation - */ - protected $parentRelation; - - /** - * List of field names to unset from the document on save. - * - * @var array{string, true} - */ - private array $unset = []; - - /** - * Custom accessor for the model's id. - * - * @param mixed $value - * - * @return mixed - */ - public function getIdAttribute($value = null) - { - // If we don't have a value for 'id', we will use the MongoDB '_id' value. - // This allows us to work with models in a more sql-like way. - if (! $value && array_key_exists('_id', $this->attributes)) { - $value = $this->attributes['_id']; - } - - // Convert ObjectID to string. - if ($value instanceof ObjectID) { - return (string) $value; - } - - if ($value instanceof Binary) { - return (string) $value->getData(); - } - - return $value; - } - - /** @inheritdoc */ - public function getQualifiedKeyName() - { - return $this->getKeyName(); - } - - /** @inheritdoc */ - public function fromDateTime($value) - { - // If the value is already a UTCDateTime instance, we don't need to parse it. - if ($value instanceof UTCDateTime) { - return $value; - } - - // Let Eloquent convert the value to a DateTime instance. - if (! $value instanceof DateTimeInterface) { - $value = parent::asDateTime($value); - } - - return new UTCDateTime($value); - } - - /** @inheritdoc */ - protected function asDateTime($value) - { - // Convert UTCDateTime instances to Carbon. - if ($value instanceof UTCDateTime) { - return Date::instance($value->toDateTime()) - ->setTimezone(new DateTimeZone(date_default_timezone_get())); - } - - return parent::asDateTime($value); - } - - /** @inheritdoc */ - public function getDateFormat() - { - return $this->dateFormat ?: 'Y-m-d H:i:s'; - } - - /** @inheritdoc */ - public function freshTimestamp() - { - return new UTCDateTime(Date::now()); - } - - /** @inheritdoc */ - public function getTable() - { - return $this->collection ?: parent::getTable(); - } - - /** @inheritdoc */ - public function getAttribute($key) - { - if (! $key) { - return null; - } - - $key = (string) $key; - - // An unset attribute is null or throw an exception. - if (isset($this->unset[$key])) { - return $this->throwMissingAttributeExceptionIfApplicable($key); - } - - // Dot notation support. - if (str_contains($key, '.') && Arr::has($this->attributes, $key)) { - return $this->getAttributeValue($key); - } - - // This checks for embedded relation support. - if ( - method_exists($this, $key) - && ! method_exists(self::class, $key) - && ! $this->hasAttributeGetMutator($key) - ) { - return $this->getRelationValue($key); - } - - return parent::getAttribute($key); - } - - /** @inheritdoc */ - protected function transformModelValue($key, $value) - { - $value = parent::transformModelValue($key, $value); - // Casting attributes to any of date types, will convert that attribute - // to a Carbon or CarbonImmutable instance. - // @see Model::setAttribute() - if ($this->hasCast($key) && $value instanceof CarbonInterface) { - $value->settings(array_merge($value->getSettings(), ['toStringFormat' => $this->getDateFormat()])); - - // "date" cast resets the time to 00:00:00. - $castType = $this->getCasts()[$key]; - if (str_starts_with($castType, 'date:') || str_starts_with($castType, 'immutable_date:')) { - $value = $value->startOfDay(); - } - } - - return $value; - } - - /** @inheritdoc */ - protected function getCastType($key) - { - $castType = $this->getCasts()[$key]; - if ($this->isCustomDateTimeCast($castType) || $this->isImmutableCustomDateTimeCast($castType)) { - $this->setDateFormat(Str::after($castType, ':')); - } - - return parent::getCastType($key); - } - - /** @inheritdoc */ - protected function getAttributeFromArray($key) - { - $key = (string) $key; - - // Support keys in dot notation. - if (str_contains($key, '.')) { - return Arr::get($this->attributes, $key); - } - - return parent::getAttributeFromArray($key); - } - - /** @inheritdoc */ - public function setAttribute($key, $value) - { - $key = (string) $key; - - $casts = $this->getCasts(); - if (array_key_exists($key, $casts)) { - $castType = $this->getCastType($key); - $castOptions = Str::after($casts[$key], ':'); - - // Can add more native mongo type casts here. - $value = match ($castType) { - 'decimal' => $this->fromDecimal($value, $castOptions), - default => $value, - }; - } - - // Convert _id to ObjectID. - if ($key === '_id' && is_string($value)) { - $builder = $this->newBaseQueryBuilder(); - - $value = $builder->convertKey($value); - } - - // Support keys in dot notation. - if (str_contains($key, '.')) { - // Store to a temporary key, then move data to the actual key - parent::setAttribute(self::TEMPORARY_KEY, $value); - - Arr::set($this->attributes, $key, $this->attributes[self::TEMPORARY_KEY] ?? null); - unset($this->attributes[self::TEMPORARY_KEY]); - - return $this; - } - - // Setting an attribute cancels the unset operation. - unset($this->unset[$key]); - - return parent::setAttribute($key, $value); - } - - /** - * @param mixed $value - * - * @inheritdoc - */ - protected function asDecimal($value, $decimals) - { - // Convert BSON to string. - if ($this->isBSON($value)) { - if ($value instanceof Binary) { - $value = $value->getData(); - } elseif ($value instanceof Stringable) { - $value = (string) $value; - } else { - throw new MathException('BSON type ' . $value::class . ' cannot be converted to string'); - } - } - - return parent::asDecimal($value, $decimals); - } + private static $documentModelClasses = [ + User::class => true, + ]; /** - * Change to mongo native for decimal cast. + * Indicates if the given model class is a MongoDB document model. + * It must be a subclass of {@see BaseModel} and use the + * {@see DocumentModel} trait. * - * @param mixed $value - * @param int $decimals - * - * @return Decimal128 + * @param class-string|object $class */ - protected function fromDecimal($value, $decimals) - { - return new Decimal128($this->asDecimal($value, $decimals)); - } - - /** @inheritdoc */ - public function attributesToArray() - { - $attributes = parent::attributesToArray(); - - // Because the original Eloquent never returns objects, we convert - // MongoDB related objects to a string representation. This kind - // of mimics the SQL behaviour so that dates are formatted - // nicely when your models are converted to JSON. - foreach ($attributes as $key => &$value) { - if ($value instanceof ObjectID) { - $value = (string) $value; - } elseif ($value instanceof Binary) { - $value = (string) $value->getData(); - } - } - - return $attributes; - } - - /** @inheritdoc */ - public function getCasts() + final public static function isDocumentModel(string|object $class): bool { - return $this->casts; - } - - /** @inheritdoc */ - public function getDirty() - { - $dirty = parent::getDirty(); - - // The specified value in the $unset expression does not impact the operation. - if ($this->unset !== []) { - $dirty['$unset'] = $this->unset; + if (is_object($class)) { + $class = $class::class; } - return $dirty; - } - - /** @inheritdoc */ - public function originalIsEquivalent($key) - { - if (! array_key_exists($key, $this->original)) { - return false; + if (array_key_exists($class, self::$documentModelClasses)) { + return self::$documentModelClasses[$class]; } - // Calling unset on an attribute marks it as "not equivalent". - if (isset($this->unset[$key])) { - return false; + // We know all child classes of this class are document models. + if (is_subclass_of($class, self::class)) { + return self::$documentModelClasses[$class] = true; } - $attribute = Arr::get($this->attributes, $key); - $original = Arr::get($this->original, $key); - - if ($attribute === $original) { - return true; + // Document models must be subclasses of Laravel's base model class. + if (! is_subclass_of($class, BaseModel::class)) { + return self::$documentModelClasses[$class] = false; } - if ($attribute === null) { - return false; - } - - if ($this->isDateAttribute($key)) { - $attribute = $attribute instanceof UTCDateTime ? $this->asDateTime($attribute) : $attribute; - $original = $original instanceof UTCDateTime ? $this->asDateTime($original) : $original; - - // Comparison on DateTimeInterface values - // phpcs:disable SlevomatCodingStandard.Operators.DisallowEqualOperators.DisallowedEqualOperator - return $attribute == $original; - } - - if ($this->hasCast($key, static::$primitiveCastTypes)) { - return $this->castAttribute($key, $attribute) === - $this->castAttribute($key, $original); - } - - return is_numeric($attribute) && is_numeric($original) - && strcmp((string) $attribute, (string) $original) === 0; - } - - /** @inheritdoc */ - public function offsetUnset($offset): void - { - $offset = (string) $offset; - - if (str_contains($offset, '.')) { - // Update the field in the subdocument - Arr::forget($this->attributes, $offset); - } else { - parent::offsetUnset($offset); - - // Force unsetting even if the attribute is not set. - // End user can optimize DB calls by checking if the attribute is set before unsetting it. - $this->unset[$offset] = true; - } - } - - /** @inheritdoc */ - public function offsetSet($offset, $value): void - { - parent::offsetSet($offset, $value); - - // Setting an attribute cancels the unset operation. - unset($this->unset[$offset]); - } - - /** - * Remove one or more fields. - * - * @deprecated Use unset() instead. - * - * @param string|string[] $columns - * - * @return void - */ - public function drop($columns) - { - $this->unset($columns); - } - - /** - * Remove one or more fields. - * - * @param string|string[] $columns - * - * @return void - */ - public function unset($columns) - { - $columns = Arr::wrap($columns); - - // Unset attributes - foreach ($columns as $column) { - $this->__unset($column); - } - } - - /** @inheritdoc */ - public function push() - { - $parameters = func_get_args(); - if ($parameters) { - $unique = false; - - if (count($parameters) === 3) { - [$column, $values, $unique] = $parameters; - } else { - [$column, $values] = $parameters; - } - - // Do batch push by default. - $values = Arr::wrap($values); - - $query = $this->setKeysForSaveQuery($this->newQuery()); - - $this->pushAttributeValues($column, $values, $unique); - - return $query->push($column, $values, $unique); - } - - return parent::push(); - } - - /** - * Remove one or more values from an array. - * - * @param string $column - * @param mixed $values - * - * @return mixed - */ - public function pull($column, $values) - { - // Do batch pull by default. - $values = Arr::wrap($values); - - $query = $this->setKeysForSaveQuery($this->newQuery()); - - $this->pullAttributeValues($column, $values); - - return $query->pull($column, $values); - } - - /** - * Append one or more values to the underlying attribute value and sync with original. - * - * @param string $column - * @param bool $unique - */ - protected function pushAttributeValues($column, array $values, $unique = false) - { - $current = $this->getAttributeFromArray($column) ?: []; - - foreach ($values as $value) { - // Don't add duplicate values when we only want unique values. - if ($unique && (! is_array($current) || in_array($value, $current))) { - continue; - } - - $current[] = $value; - } - - $this->attributes[$column] = $current; - - $this->syncOriginalAttribute($column); - } - - /** - * Remove one or more values to the underlying attribute value and sync with original. - * - * @param string $column - */ - protected function pullAttributeValues($column, array $values) - { - $current = $this->getAttributeFromArray($column) ?: []; - - if (is_array($current)) { - foreach ($values as $value) { - $keys = array_keys($current, $value); - - foreach ($keys as $key) { - unset($current[$key]); - } - } - } - - $this->attributes[$column] = array_values($current); - - $this->syncOriginalAttribute($column); - } - - /** @inheritdoc */ - public function getForeignKey() - { - return Str::snake(class_basename($this)) . '_' . ltrim($this->primaryKey, '_'); - } - - /** - * Set the parent relation. - */ - public function setParentRelation(Relation $relation) - { - $this->parentRelation = $relation; - } - - /** - * Get the parent relation. - * - * @return Relation - */ - public function getParentRelation() - { - return $this->parentRelation; - } - - /** @inheritdoc */ - public function newEloquentBuilder($query) - { - return new Builder($query); - } - - /** @inheritdoc */ - public function qualifyColumn($column) - { - return $column; - } - - /** @inheritdoc */ - protected function newBaseQueryBuilder() - { - $connection = $this->getConnection(); - - return new QueryBuilder($connection, $connection->getQueryGrammar(), $connection->getPostProcessor()); - } - - /** @inheritdoc */ - protected function removeTableFromKey($key) - { - return $key; - } - - /** - * Get the queueable relationships for the entity. - * - * @return array - */ - public function getQueueableRelations() - { - $relations = []; - - foreach ($this->getRelationsWithoutParent() as $key => $relation) { - if (method_exists($this, $key)) { - $relations[] = $key; - } - - if ($relation instanceof QueueableCollection) { - foreach ($relation->getQueueableRelations() as $collectionValue) { - $relations[] = $key . '.' . $collectionValue; - } - } - - if ($relation instanceof QueueableEntity) { - foreach ($relation->getQueueableRelations() as $entityKey => $entityValue) { - $relations[] = $key . '.' . $entityValue; - } - } - } - - return array_unique($relations); - } - - /** - * Get loaded relations for the instance without parent. - * - * @return array - */ - protected function getRelationsWithoutParent() - { - $relations = $this->getRelations(); - - $parentRelation = $this->getParentRelation(); - if ($parentRelation) { - unset($relations[$parentRelation->getQualifiedForeignKeyName()]); - } - - return $relations; - } - - /** - * Checks if column exists on a table. As this is a document model, just return true. This also - * prevents calls to non-existent function Grammar::compileColumnListing(). - * - * @param string $key - * - * @return bool - */ - protected function isGuardableColumn($key) - { - return true; - } - - /** @inheritdoc */ - protected function addCastAttributesToArray(array $attributes, array $mutatedAttributes) - { - foreach ($this->getCasts() as $key => $castType) { - if (! Arr::has($attributes, $key) || Arr::has($mutatedAttributes, $key)) { - continue; - } - - $originalValue = Arr::get($attributes, $key); - - // Here we will cast the attribute. Then, if the cast is a date or datetime cast - // then we will serialize the date for the array. This will convert the dates - // to strings based on the date format specified for these Eloquent models. - $castValue = $this->castAttribute( - $key, - $originalValue, - ); - - // If the attribute cast was a date or a datetime, we will serialize the date as - // a string. This allows the developers to customize how dates are serialized - // into an array without affecting how they are persisted into the storage. - if ($castValue !== null && in_array($castType, ['date', 'datetime', 'immutable_date', 'immutable_datetime'])) { - $castValue = $this->serializeDate($castValue); - } - - if ($castValue !== null && ($this->isCustomDateTimeCast($castType) || $this->isImmutableCustomDateTimeCast($castType))) { - $castValue = $castValue->format(explode(':', $castType, 2)[1]); - } - - if ($castValue instanceof DateTimeInterface && $this->isClassCastable($key)) { - $castValue = $this->serializeDate($castValue); - } - - if ($castValue !== null && $this->isClassSerializable($key)) { - $castValue = $this->serializeClassCastableAttribute($key, $castValue); - } - - if ($this->isEnumCastable($key) && (! $castValue instanceof Arrayable)) { - $castValue = $castValue !== null ? $this->getStorableEnumValueFromLaravel11($this->getCasts()[$key], $castValue) : null; - } - - if ($castValue instanceof Arrayable) { - $castValue = $castValue->toArray(); - } - - Arr::set($attributes, $key, $castValue); - } - - return $attributes; - } - - /** - * Duplicate of {@see HasAttributes::getStorableEnumValue()} for Laravel 11 as the signature of the method has - * changed in a non-backward compatible way. - * - * @todo Remove this method when support for Laravel 10 is dropped. - */ - private function getStorableEnumValueFromLaravel11($expectedEnum, $value) - { - if (! $value instanceof $expectedEnum) { - throw new ValueError(sprintf('Value [%s] is not of the expected enum type [%s].', var_export($value, true), $expectedEnum)); - } - - return $value instanceof BackedEnum - ? $value->value - : $value->name; - } - - /** - * Is a value a BSON type? - * - * @param mixed $value - * - * @return bool - */ - protected function isBSON(mixed $value): bool - { - return $value instanceof Type; - } - - /** - * {@inheritDoc} - */ - public function save(array $options = []) - { - // SQL databases would use autoincrement the id field if set to null. - // Apply the same behavior to MongoDB with _id only, otherwise null would be stored. - if (array_key_exists('_id', $this->attributes) && $this->attributes['_id'] === null) { - unset($this->attributes['_id']); - } - - $saved = parent::save($options); - - // Clear list of unset fields - $this->unset = []; - - return $saved; - } - - /** - * {@inheritDoc} - */ - public function refresh() - { - parent::refresh(); - - // Clear list of unset fields - $this->unset = []; - - return $this; + // Document models must use the DocumentModel trait. + return self::$documentModelClasses[$class] = array_key_exists(DocumentModel::class, class_uses_recursive($class)); } } diff --git a/src/Helpers/QueriesRelationships.php b/src/Helpers/QueriesRelationships.php index b1234124b..933b6ec32 100644 --- a/src/Helpers/QueriesRelationships.php +++ b/src/Helpers/QueriesRelationships.php @@ -54,7 +54,7 @@ public function has($relation, $operator = '>=', $count = 1, $boolean = 'and', ? // If this is a hybrid relation then we can not use a normal whereExists() query that relies on a subquery // We need to use a `whereIn` query - if ($this->getModel() instanceof Model || $this->isAcrossConnections($relation)) { + if (Model::isDocumentModel($this->getModel()) || $this->isAcrossConnections($relation)) { return $this->addHybridHas($relation, $operator, $count, $boolean, $callback); } diff --git a/src/Relations/BelongsToMany.php b/src/Relations/BelongsToMany.php index 8ff311f3f..b68c79d4c 100644 --- a/src/Relations/BelongsToMany.php +++ b/src/Relations/BelongsToMany.php @@ -9,6 +9,7 @@ use Illuminate\Database\Eloquent\Model; use Illuminate\Database\Eloquent\Relations\BelongsToMany as EloquentBelongsToMany; use Illuminate\Support\Arr; +use MongoDB\Laravel\Eloquent\Model as DocumentModel; use function array_diff; use function array_keys; @@ -125,7 +126,7 @@ public function sync($ids, $detaching = true) // First we need to attach any of the associated models that are not currently // in this joining table. We'll spin through the given IDs, checking to see // if they exist in the array of current ones, and if not we will insert. - $current = match ($this->parent instanceof \MongoDB\Laravel\Eloquent\Model) { + $current = match (\MongoDB\Laravel\Eloquent\Model::isDocumentModel($this->parent)) { true => $this->parent->{$this->relatedPivotKey} ?: [], false => $this->parent->{$this->relationName} ?: [], }; @@ -201,7 +202,7 @@ public function attach($id, array $attributes = [], $touch = true) } // Attach the new ids to the parent model. - if ($this->parent instanceof \MongoDB\Laravel\Eloquent\Model) { + if (\MongoDB\Laravel\Eloquent\Model::isDocumentModel($this->parent)) { $this->parent->push($this->relatedPivotKey, (array) $id, true); } else { $instance = new $this->related(); @@ -232,7 +233,7 @@ public function detach($ids = [], $touch = true) $ids = (array) $ids; // Detach all ids from the parent model. - if ($this->parent instanceof \MongoDB\Laravel\Eloquent\Model) { + if (DocumentModel::isDocumentModel($this->parent)) { $this->parent->pull($this->relatedPivotKey, $ids); } else { $value = $this->parent->{$this->relationName} diff --git a/src/Relations/EmbedsMany.php b/src/Relations/EmbedsMany.php index 2d68af70b..be7039506 100644 --- a/src/Relations/EmbedsMany.php +++ b/src/Relations/EmbedsMany.php @@ -10,7 +10,6 @@ use Illuminate\Pagination\Paginator; use MongoDB\BSON\ObjectID; use MongoDB\Driver\Exception\LogicException; -use MongoDB\Laravel\Eloquent\Model as MongoDBModel; use function array_key_exists; use function array_values; @@ -231,9 +230,9 @@ public function detach($ids = []) /** * Save alias. * - * @return MongoDBModel + * @return Model */ - public function attach(MongoDBModel $model) + public function attach(Model $model) { return $this->save($model); } diff --git a/src/Relations/EmbedsOneOrMany.php b/src/Relations/EmbedsOneOrMany.php index 56fc62041..9c83aa299 100644 --- a/src/Relations/EmbedsOneOrMany.php +++ b/src/Relations/EmbedsOneOrMany.php @@ -7,10 +7,11 @@ use Illuminate\Database\Eloquent\Builder; use Illuminate\Database\Eloquent\Collection; use Illuminate\Database\Eloquent\Model as EloquentModel; +use Illuminate\Database\Eloquent\Model; use Illuminate\Database\Eloquent\Relations\Relation; use Illuminate\Database\Query\Expression; use MongoDB\Driver\Exception\LogicException; -use MongoDB\Laravel\Eloquent\Model; +use MongoDB\Laravel\Eloquent\Model as DocumentModel; use Throwable; use function array_merge; @@ -46,6 +47,14 @@ abstract class EmbedsOneOrMany extends Relation */ public function __construct(Builder $query, Model $parent, Model $related, string $localKey, string $foreignKey, string $relation) { + if (! DocumentModel::isDocumentModel($parent)) { + throw new LogicException('Parent model must be a document model.'); + } + + if (! DocumentModel::isDocumentModel($related)) { + throw new LogicException('Related model must be a document model.'); + } + parent::__construct($query, $parent); $this->related = $related; diff --git a/src/Relations/MorphToMany.php b/src/Relations/MorphToMany.php index 163e7e67f..f11d25473 100644 --- a/src/Relations/MorphToMany.php +++ b/src/Relations/MorphToMany.php @@ -77,7 +77,7 @@ public function addEagerConstraints(array $models) protected function setWhere() { if ($this->getInverse()) { - if ($this->parent instanceof \MongoDB\Laravel\Eloquent\Model) { + if (\MongoDB\Laravel\Eloquent\Model::isDocumentModel($this->parent)) { $ids = $this->extractIds((array) $this->parent->{$this->table}); $this->query->whereIn($this->relatedKey, $ids); @@ -86,7 +86,7 @@ protected function setWhere() ->whereIn($this->foreignPivotKey, (array) $this->parent->{$this->parentKey}); } } else { - match ($this->parent instanceof \MongoDB\Laravel\Eloquent\Model) { + match (\MongoDB\Laravel\Eloquent\Model::isDocumentModel($this->parent)) { true => $this->query->whereIn($this->relatedKey, (array) $this->parent->{$this->relatedPivotKey}), false => $this->query ->whereIn($this->getQualifiedForeignPivotKeyName(), (array) $this->parent->{$this->parentKey}), @@ -140,7 +140,7 @@ public function sync($ids, $detaching = true) // in this joining table. We'll spin through the given IDs, checking to see // if they exist in the array of current ones, and if not we will insert. if ($this->getInverse()) { - $current = match ($this->parent instanceof \MongoDB\Laravel\Eloquent\Model) { + $current = match (\MongoDB\Laravel\Eloquent\Model::isDocumentModel($this->parent)) { true => $this->parent->{$this->table} ?: [], false => $this->parent->{$this->relationName} ?: [], }; @@ -151,7 +151,7 @@ public function sync($ids, $detaching = true) $current = $this->extractIds($current); } } else { - $current = match ($this->parent instanceof \MongoDB\Laravel\Eloquent\Model) { + $current = match (\MongoDB\Laravel\Eloquent\Model::isDocumentModel($this->parent)) { true => $this->parent->{$this->relatedPivotKey} ?: [], false => $this->parent->{$this->relationName} ?: [], }; @@ -213,7 +213,7 @@ public function attach($id, array $attributes = [], $touch = true) if ($this->getInverse()) { // Attach the new ids to the parent model. - if ($this->parent instanceof \MongoDB\Laravel\Eloquent\Model) { + if (\MongoDB\Laravel\Eloquent\Model::isDocumentModel($this->parent)) { $this->parent->push($this->table, [ [ $this->relatedPivotKey => $model->{$this->relatedKey}, @@ -236,7 +236,7 @@ public function attach($id, array $attributes = [], $touch = true) ], true); // Attach the new ids to the parent model. - if ($this->parent instanceof \MongoDB\Laravel\Eloquent\Model) { + if (\MongoDB\Laravel\Eloquent\Model::isDocumentModel($this->parent)) { $this->parent->push($this->relatedPivotKey, (array) $id, true); } else { $this->addIdToParentRelationData($id); @@ -257,7 +257,7 @@ public function attach($id, array $attributes = [], $touch = true) $query->push($this->foreignPivotKey, $this->parent->{$this->parentKey}); // Attach the new ids to the parent model. - if ($this->parent instanceof \MongoDB\Laravel\Eloquent\Model) { + if (\MongoDB\Laravel\Eloquent\Model::isDocumentModel($this->parent)) { foreach ($id as $item) { $this->parent->push($this->table, [ [ @@ -281,7 +281,7 @@ public function attach($id, array $attributes = [], $touch = true) ], true); // Attach the new ids to the parent model. - if ($this->parent instanceof \MongoDB\Laravel\Eloquent\Model) { + if (\MongoDB\Laravel\Eloquent\Model::isDocumentModel($this->parent)) { $this->parent->push($this->relatedPivotKey, $id, true); } else { foreach ($id as $item) { @@ -324,7 +324,7 @@ public function detach($ids = [], $touch = true) ]; } - if ($this->parent instanceof \MongoDB\Laravel\Eloquent\Model) { + if (\MongoDB\Laravel\Eloquent\Model::isDocumentModel($this->parent)) { $this->parent->pull($this->table, $data); } else { $value = $this->parent->{$this->relationName} @@ -341,7 +341,7 @@ public function detach($ids = [], $touch = true) $query->pull($this->foreignPivotKey, $this->parent->{$this->parentKey}); } else { // Remove the relation from the parent. - if ($this->parent instanceof \MongoDB\Laravel\Eloquent\Model) { + if (\MongoDB\Laravel\Eloquent\Model::isDocumentModel($this->parent)) { $this->parent->pull($this->relatedPivotKey, $ids); } else { $value = $this->parent->{$this->relationName} diff --git a/tests/Eloquent/ModelTest.php b/tests/Eloquent/ModelTest.php new file mode 100644 index 000000000..b3ea0a532 --- /dev/null +++ b/tests/Eloquent/ModelTest.php @@ -0,0 +1,62 @@ +assertSame($expected, Model::isDocumentModel($classOrObject)); + } + + public static function provideDocumentModelClasses(): Generator + { + // Test classes + yield [false, SqlBook::class]; + yield [true, Casting::class]; + yield [true, Book::class]; + + // Provided by the Laravel MongoDB package. + yield [true, User::class]; + + // Instances of objects + yield [false, new SqlBook()]; + yield [true, new Book()]; + + // Anonymous classes + yield [ + true, + new class extends Model { + }, + ]; + yield [ + true, + new class extends BaseModel { + use DocumentModel; + }, + ]; + yield [ + false, + new class { + use DocumentModel; + }, + ]; + yield [ + false, + new class extends BaseModel { + }, + ]; + } +} diff --git a/tests/ModelTest.php b/tests/ModelTest.php index 73374ce57..9d2b58b6e 100644 --- a/tests/ModelTest.php +++ b/tests/ModelTest.php @@ -58,7 +58,7 @@ public function tearDown(): void public function testNewModel(): void { $user = new User(); - $this->assertInstanceOf(Model::class, $user); + $this->assertTrue(Model::isDocumentModel($user)); $this->assertInstanceOf(Connection::class, $user->getConnection()); $this->assertFalse($user->exists); $this->assertEquals('users', $user->getTable()); @@ -234,8 +234,7 @@ public function testFind(): void $check = User::find($user->_id); $this->assertInstanceOf(User::class, $check); - - $this->assertInstanceOf(Model::class, $check); + $this->assertTrue(Model::isDocumentModel($check)); $this->assertTrue($check->exists); $this->assertEquals($user->_id, $check->_id); @@ -259,7 +258,7 @@ public function testGet(): void $users = User::get(); $this->assertCount(2, $users); $this->assertInstanceOf(EloquentCollection::class, $users); - $this->assertInstanceOf(Model::class, $users[0]); + $this->assertInstanceOf(User::class, $users[0]); } public function testFirst(): void @@ -271,7 +270,7 @@ public function testFirst(): void $user = User::first(); $this->assertInstanceOf(User::class, $user); - $this->assertInstanceOf(Model::class, $user); + $this->assertTrue(Model::isDocumentModel($user)); $this->assertEquals('John Doe', $user->name); } @@ -299,7 +298,7 @@ public function testCreate(): void $user = User::create(['name' => 'Jane Poe']); $this->assertInstanceOf(User::class, $user); - $this->assertInstanceOf(Model::class, $user); + $this->assertTrue(Model::isDocumentModel($user)); $this->assertTrue($user->exists); $this->assertEquals('Jane Poe', $user->name); @@ -872,13 +871,13 @@ public function testRaw(): void return $collection->find(['age' => 35]); }); $this->assertInstanceOf(EloquentCollection::class, $users); - $this->assertInstanceOf(Model::class, $users[0]); + $this->assertInstanceOf(User::class, $users[0]); $user = User::raw(function (Collection $collection) { return $collection->findOne(['age' => 35]); }); - $this->assertInstanceOf(Model::class, $user); + $this->assertTrue(Model::isDocumentModel($user)); $count = User::raw(function (Collection $collection) { return $collection->count(); @@ -1008,7 +1007,7 @@ public function testFirstOrCreate(): void $user = User::firstOrCreate(['name' => $name]); $this->assertInstanceOf(User::class, $user); - $this->assertInstanceOf(Model::class, $user); + $this->assertTrue(Model::isDocumentModel($user)); $this->assertTrue($user->exists); $this->assertEquals($name, $user->name); diff --git a/tests/Models/Address.php b/tests/Models/Address.php index b827dc85f..d94e31d24 100644 --- a/tests/Models/Address.php +++ b/tests/Models/Address.php @@ -4,12 +4,17 @@ namespace MongoDB\Laravel\Tests\Models; -use MongoDB\Laravel\Eloquent\Model as Eloquent; +use Illuminate\Database\Eloquent\Model; +use MongoDB\Laravel\Eloquent\DocumentModel; use MongoDB\Laravel\Relations\EmbedsMany; -class Address extends Eloquent +class Address extends Model { - protected $connection = 'mongodb'; + use DocumentModel; + + protected $primaryKey = '_id'; + protected $keyType = 'string'; + protected $connection = 'mongodb'; protected static $unguarded = true; public function addresses(): EmbedsMany diff --git a/tests/Models/Birthday.php b/tests/Models/Birthday.php index 4131357f6..65b703af1 100644 --- a/tests/Models/Birthday.php +++ b/tests/Models/Birthday.php @@ -4,17 +4,22 @@ namespace MongoDB\Laravel\Tests\Models; -use MongoDB\Laravel\Eloquent\Model as Eloquent; +use Illuminate\Database\Eloquent\Model; +use MongoDB\Laravel\Eloquent\DocumentModel; /** * @property string $name * @property string $birthday * @property string $time */ -class Birthday extends Eloquent +class Birthday extends Model { + use DocumentModel; + + protected $primaryKey = '_id'; + protected $keyType = 'string'; protected $connection = 'mongodb'; - protected $collection = 'birthday'; + protected string $collection = 'birthday'; protected $fillable = ['name', 'birthday']; protected $casts = ['birthday' => 'datetime']; diff --git a/tests/Models/Book.php b/tests/Models/Book.php index 70d566fe2..5bee76e5c 100644 --- a/tests/Models/Book.php +++ b/tests/Models/Book.php @@ -4,20 +4,24 @@ namespace MongoDB\Laravel\Tests\Models; +use Illuminate\Database\Eloquent\Model; use Illuminate\Database\Eloquent\Relations\BelongsTo; -use MongoDB\Laravel\Eloquent\Model as Eloquent; +use MongoDB\Laravel\Eloquent\DocumentModel; /** * @property string $title * @property string $author * @property array $chapters */ -class Book extends Eloquent +class Book extends Model { - protected $connection = 'mongodb'; - protected $collection = 'books'; + use DocumentModel; + + protected $primaryKey = 'title'; + protected $keyType = 'string'; + protected $connection = 'mongodb'; + protected string $collection = 'books'; protected static $unguarded = true; - protected $primaryKey = 'title'; public function author(): BelongsTo { diff --git a/tests/Models/CastObjectId.php b/tests/Models/CastObjectId.php index 2f4e7f5d5..d3d5571c4 100644 --- a/tests/Models/CastObjectId.php +++ b/tests/Models/CastObjectId.php @@ -5,11 +5,11 @@ namespace MongoDB\Laravel\Tests\Models; use MongoDB\Laravel\Eloquent\Casts\ObjectId; -use MongoDB\Laravel\Eloquent\Model as Eloquent; +use MongoDB\Laravel\Eloquent\Model; -class CastObjectId extends Eloquent +class CastObjectId extends Model { - protected $connection = 'mongodb'; + protected $connection = 'mongodb'; protected static $unguarded = true; protected $casts = [ 'oid' => ObjectId::class, diff --git a/tests/Models/Casting.php b/tests/Models/Casting.php index f44f08a62..d033cf444 100644 --- a/tests/Models/Casting.php +++ b/tests/Models/Casting.php @@ -5,12 +5,12 @@ namespace MongoDB\Laravel\Tests\Models; use MongoDB\Laravel\Eloquent\Casts\BinaryUuid; -use MongoDB\Laravel\Eloquent\Model as Eloquent; +use MongoDB\Laravel\Eloquent\Model; -class Casting extends Eloquent +class Casting extends Model { protected $connection = 'mongodb'; - protected $collection = 'casting'; + protected string $collection = 'casting'; protected $fillable = [ 'uuid', diff --git a/tests/Models/Client.php b/tests/Models/Client.php index 4e7e7ecc9..47fd91d03 100644 --- a/tests/Models/Client.php +++ b/tests/Models/Client.php @@ -4,15 +4,20 @@ namespace MongoDB\Laravel\Tests\Models; +use Illuminate\Database\Eloquent\Model; use Illuminate\Database\Eloquent\Relations\BelongsToMany; use Illuminate\Database\Eloquent\Relations\HasMany; use Illuminate\Database\Eloquent\Relations\MorphOne; -use MongoDB\Laravel\Eloquent\Model as Eloquent; +use MongoDB\Laravel\Eloquent\DocumentModel; -class Client extends Eloquent +class Client extends Model { - protected $connection = 'mongodb'; - protected $collection = 'clients'; + use DocumentModel; + + protected $primaryKey = '_id'; + protected $keyType = 'string'; + protected $connection = 'mongodb'; + protected string $collection = 'clients'; protected static $unguarded = true; public function users(): BelongsToMany diff --git a/tests/Models/Experience.php b/tests/Models/Experience.php index 2852ece5f..37a44e4d1 100644 --- a/tests/Models/Experience.php +++ b/tests/Models/Experience.php @@ -4,13 +4,18 @@ namespace MongoDB\Laravel\Tests\Models; +use Illuminate\Database\Eloquent\Model; use Illuminate\Database\Eloquent\Relations\MorphToMany; -use MongoDB\Laravel\Eloquent\Model as Eloquent; +use MongoDB\Laravel\Eloquent\DocumentModel; -class Experience extends Eloquent +class Experience extends Model { - protected $connection = 'mongodb'; - protected $collection = 'experiences'; + use DocumentModel; + + protected $primaryKey = '_id'; + protected $keyType = 'string'; + protected $connection = 'mongodb'; + protected string $collection = 'experiences'; protected static $unguarded = true; protected $casts = ['years' => 'int']; diff --git a/tests/Models/Group.php b/tests/Models/Group.php index eda017a03..689c6d599 100644 --- a/tests/Models/Group.php +++ b/tests/Models/Group.php @@ -4,13 +4,18 @@ namespace MongoDB\Laravel\Tests\Models; +use Illuminate\Database\Eloquent\Model; use Illuminate\Database\Eloquent\Relations\BelongsToMany; -use MongoDB\Laravel\Eloquent\Model as Eloquent; +use MongoDB\Laravel\Eloquent\DocumentModel; -class Group extends Eloquent +class Group extends Model { - protected $connection = 'mongodb'; - protected $collection = 'groups'; + use DocumentModel; + + protected $primaryKey = '_id'; + protected $keyType = 'string'; + protected $connection = 'mongodb'; + protected string $collection = 'groups'; protected static $unguarded = true; public function users(): BelongsToMany diff --git a/tests/Models/Guarded.php b/tests/Models/Guarded.php index 540d68996..9837e9222 100644 --- a/tests/Models/Guarded.php +++ b/tests/Models/Guarded.php @@ -4,11 +4,16 @@ namespace MongoDB\Laravel\Tests\Models; -use MongoDB\Laravel\Eloquent\Model as Eloquent; +use Illuminate\Database\Eloquent\Model; +use MongoDB\Laravel\Eloquent\DocumentModel; -class Guarded extends Eloquent +class Guarded extends Model { + use DocumentModel; + + protected $primaryKey = '_id'; + protected $keyType = 'string'; protected $connection = 'mongodb'; - protected $collection = 'guarded'; - protected $guarded = ['foobar', 'level1->level2']; + protected string $collection = 'guarded'; + protected $guarded = ['foobar', 'level1->level2']; } diff --git a/tests/Models/HiddenAnimal.php b/tests/Models/HiddenAnimal.php index 81e666d37..a47184fe7 100644 --- a/tests/Models/HiddenAnimal.php +++ b/tests/Models/HiddenAnimal.php @@ -4,6 +4,8 @@ namespace MongoDB\Laravel\Tests\Models; +use Illuminate\Database\Eloquent\Model; +use MongoDB\Laravel\Eloquent\DocumentModel; use MongoDB\Laravel\Eloquent\Model as Eloquent; use MongoDB\Laravel\Query\Builder; @@ -16,8 +18,12 @@ * @method static Builder truncate() * @method static Eloquent sole(...$parameters) */ -final class HiddenAnimal extends Eloquent +final class HiddenAnimal extends Model { + use DocumentModel; + + protected $primaryKey = '_id'; + protected $keyType = 'string'; protected $fillable = [ 'name', 'country', diff --git a/tests/Models/IdIsBinaryUuid.php b/tests/Models/IdIsBinaryUuid.php index 56ae89dca..2314b4b19 100644 --- a/tests/Models/IdIsBinaryUuid.php +++ b/tests/Models/IdIsBinaryUuid.php @@ -4,14 +4,19 @@ namespace MongoDB\Laravel\Tests\Models; +use Illuminate\Database\Eloquent\Model; use MongoDB\Laravel\Eloquent\Casts\BinaryUuid; -use MongoDB\Laravel\Eloquent\Model as Eloquent; +use MongoDB\Laravel\Eloquent\DocumentModel; -class IdIsBinaryUuid extends Eloquent +class IdIsBinaryUuid extends Model { - protected $connection = 'mongodb'; + use DocumentModel; + + protected $primaryKey = '_id'; + protected $keyType = 'string'; + protected $connection = 'mongodb'; protected static $unguarded = true; - protected $casts = [ + protected $casts = [ '_id' => BinaryUuid::class, ]; } diff --git a/tests/Models/IdIsInt.php b/tests/Models/IdIsInt.php index 1243fc217..1f8d1ba88 100644 --- a/tests/Models/IdIsInt.php +++ b/tests/Models/IdIsInt.php @@ -4,12 +4,16 @@ namespace MongoDB\Laravel\Tests\Models; -use MongoDB\Laravel\Eloquent\Model as Eloquent; +use Illuminate\Database\Eloquent\Model; +use MongoDB\Laravel\Eloquent\DocumentModel; -class IdIsInt extends Eloquent +class IdIsInt extends Model { - protected $keyType = 'int'; - protected $connection = 'mongodb'; + use DocumentModel; + + protected $primaryKey = '_id'; + protected $keyType = 'int'; + protected $connection = 'mongodb'; protected static $unguarded = true; - protected $casts = ['_id' => 'int']; + protected $casts = ['_id' => 'int']; } diff --git a/tests/Models/IdIsString.php b/tests/Models/IdIsString.php index ed89803ca..37ba1c424 100644 --- a/tests/Models/IdIsString.php +++ b/tests/Models/IdIsString.php @@ -4,11 +4,16 @@ namespace MongoDB\Laravel\Tests\Models; -use MongoDB\Laravel\Eloquent\Model as Eloquent; +use Illuminate\Database\Eloquent\Model; +use MongoDB\Laravel\Eloquent\DocumentModel; -class IdIsString extends Eloquent +class IdIsString extends Model { - protected $connection = 'mongodb'; + use DocumentModel; + + protected $primaryKey = '_id'; + protected $keyType = 'string'; + protected $connection = 'mongodb'; protected static $unguarded = true; - protected $casts = ['_id' => 'string']; + protected $casts = ['_id' => 'string']; } diff --git a/tests/Models/Item.php b/tests/Models/Item.php index 8aafc1446..bc0b29b7b 100644 --- a/tests/Models/Item.php +++ b/tests/Models/Item.php @@ -5,15 +5,20 @@ namespace MongoDB\Laravel\Tests\Models; use Carbon\Carbon; +use Illuminate\Database\Eloquent\Model; use Illuminate\Database\Eloquent\Relations\BelongsTo; use MongoDB\Laravel\Eloquent\Builder; -use MongoDB\Laravel\Eloquent\Model as Eloquent; +use MongoDB\Laravel\Eloquent\DocumentModel; /** @property Carbon $created_at */ -class Item extends Eloquent +class Item extends Model { - protected $connection = 'mongodb'; - protected $collection = 'items'; + use DocumentModel; + + protected $primaryKey = '_id'; + protected $keyType = 'string'; + protected $connection = 'mongodb'; + protected string $collection = 'items'; protected static $unguarded = true; public function user(): BelongsTo diff --git a/tests/Models/Label.php b/tests/Models/Label.php index 5bd1cf4da..b392184d7 100644 --- a/tests/Models/Label.php +++ b/tests/Models/Label.php @@ -4,18 +4,23 @@ namespace MongoDB\Laravel\Tests\Models; +use Illuminate\Database\Eloquent\Model; use Illuminate\Database\Eloquent\Relations\MorphToMany; -use MongoDB\Laravel\Eloquent\Model as Eloquent; +use MongoDB\Laravel\Eloquent\DocumentModel; /** * @property string $title * @property string $author * @property array $chapters */ -class Label extends Eloquent +class Label extends Model { - protected $connection = 'mongodb'; - protected $collection = 'labels'; + use DocumentModel; + + protected $primaryKey = '_id'; + protected $keyType = 'string'; + protected $connection = 'mongodb'; + protected string $collection = 'labels'; protected static $unguarded = true; protected $fillable = [ diff --git a/tests/Models/Location.php b/tests/Models/Location.php index e273fa455..9621d388f 100644 --- a/tests/Models/Location.php +++ b/tests/Models/Location.php @@ -4,11 +4,16 @@ namespace MongoDB\Laravel\Tests\Models; -use MongoDB\Laravel\Eloquent\Model as Eloquent; +use Illuminate\Database\Eloquent\Model; +use MongoDB\Laravel\Eloquent\DocumentModel; -class Location extends Eloquent +class Location extends Model { - protected $connection = 'mongodb'; - protected $collection = 'locations'; + use DocumentModel; + + protected $primaryKey = '_id'; + protected $keyType = 'string'; + protected $connection = 'mongodb'; + protected string $collection = 'locations'; protected static $unguarded = true; } diff --git a/tests/Models/Photo.php b/tests/Models/Photo.php index 74852dc28..ea3321337 100644 --- a/tests/Models/Photo.php +++ b/tests/Models/Photo.php @@ -4,13 +4,18 @@ namespace MongoDB\Laravel\Tests\Models; +use Illuminate\Database\Eloquent\Model; use Illuminate\Database\Eloquent\Relations\MorphTo; -use MongoDB\Laravel\Eloquent\Model as Eloquent; +use MongoDB\Laravel\Eloquent\DocumentModel; -class Photo extends Eloquent +class Photo extends Model { - protected $connection = 'mongodb'; - protected $collection = 'photos'; + use DocumentModel; + + protected $primaryKey = '_id'; + protected $keyType = 'string'; + protected $connection = 'mongodb'; + protected string $collection = 'photos'; protected static $unguarded = true; public function hasImage(): MorphTo diff --git a/tests/Models/Role.php b/tests/Models/Role.php index ab5eaa029..7d0dce7b1 100644 --- a/tests/Models/Role.php +++ b/tests/Models/Role.php @@ -4,13 +4,18 @@ namespace MongoDB\Laravel\Tests\Models; +use Illuminate\Database\Eloquent\Model; use Illuminate\Database\Eloquent\Relations\BelongsTo; -use MongoDB\Laravel\Eloquent\Model as Eloquent; +use MongoDB\Laravel\Eloquent\DocumentModel; -class Role extends Eloquent +class Role extends Model { - protected $connection = 'mongodb'; - protected $collection = 'roles'; + use DocumentModel; + + protected $primaryKey = '_id'; + protected $keyType = 'string'; + protected $connection = 'mongodb'; + protected string $collection = 'roles'; protected static $unguarded = true; public function user(): BelongsTo diff --git a/tests/Models/Scoped.php b/tests/Models/Scoped.php index d728b6bec..84b8b81f7 100644 --- a/tests/Models/Scoped.php +++ b/tests/Models/Scoped.php @@ -4,14 +4,19 @@ namespace MongoDB\Laravel\Tests\Models; +use Illuminate\Database\Eloquent\Model; use MongoDB\Laravel\Eloquent\Builder; -use MongoDB\Laravel\Eloquent\Model as Eloquent; +use MongoDB\Laravel\Eloquent\DocumentModel; -class Scoped extends Eloquent +class Scoped extends Model { + use DocumentModel; + + protected $primaryKey = '_id'; + protected $keyType = 'string'; protected $connection = 'mongodb'; - protected $collection = 'scoped'; - protected $fillable = ['name', 'favorite']; + protected string $collection = 'scoped'; + protected $fillable = ['name', 'favorite']; protected static function boot() { diff --git a/tests/Models/Skill.php b/tests/Models/Skill.php index 3b9a434ee..90c9455b9 100644 --- a/tests/Models/Skill.php +++ b/tests/Models/Skill.php @@ -4,13 +4,18 @@ namespace MongoDB\Laravel\Tests\Models; +use Illuminate\Database\Eloquent\Model; use Illuminate\Database\Eloquent\Relations\BelongsToMany; -use MongoDB\Laravel\Eloquent\Model as Eloquent; +use MongoDB\Laravel\Eloquent\DocumentModel; -class Skill extends Eloquent +class Skill extends Model { - protected $connection = 'mongodb'; - protected $collection = 'skills'; + use DocumentModel; + + protected $primaryKey = '_id'; + protected $keyType = 'string'; + protected $connection = 'mongodb'; + protected string $collection = 'skills'; protected static $unguarded = true; public function sqlUsers(): BelongsToMany diff --git a/tests/Models/Soft.php b/tests/Models/Soft.php index 763aafb41..549e63758 100644 --- a/tests/Models/Soft.php +++ b/tests/Models/Soft.php @@ -5,21 +5,25 @@ namespace MongoDB\Laravel\Tests\Models; use Carbon\Carbon; +use Illuminate\Database\Eloquent\Model; use MongoDB\Laravel\Eloquent\Builder; +use MongoDB\Laravel\Eloquent\DocumentModel; use MongoDB\Laravel\Eloquent\MassPrunable; -use MongoDB\Laravel\Eloquent\Model as Eloquent; use MongoDB\Laravel\Eloquent\SoftDeletes; /** @property Carbon $deleted_at */ -class Soft extends Eloquent +class Soft extends Model { + use DocumentModel; use SoftDeletes; use MassPrunable; - protected $connection = 'mongodb'; - protected $collection = 'soft'; + protected $primaryKey = '_id'; + protected $keyType = 'string'; + protected $connection = 'mongodb'; + protected string $collection = 'soft'; protected static $unguarded = true; - protected $casts = ['deleted_at' => 'datetime']; + protected $casts = ['deleted_at' => 'datetime']; public function prunable(): Builder { diff --git a/tests/Models/SqlBook.php b/tests/Models/SqlBook.php index babc984eb..228b6d3eb 100644 --- a/tests/Models/SqlBook.php +++ b/tests/Models/SqlBook.php @@ -17,10 +17,10 @@ class SqlBook extends EloquentModel { use HybridRelations; - protected $connection = 'sqlite'; - protected $table = 'books'; + protected $connection = 'sqlite'; + protected $table = 'books'; protected static $unguarded = true; - protected $primaryKey = 'title'; + protected $primaryKey = 'title'; public function author(): BelongsTo { diff --git a/tests/Models/SqlRole.php b/tests/Models/SqlRole.php index 17c01e819..1d4b542a5 100644 --- a/tests/Models/SqlRole.php +++ b/tests/Models/SqlRole.php @@ -17,8 +17,8 @@ class SqlRole extends EloquentModel { use HybridRelations; - protected $connection = 'sqlite'; - protected $table = 'roles'; + protected $connection = 'sqlite'; + protected $table = 'roles'; protected static $unguarded = true; public function user(): BelongsTo diff --git a/tests/Models/SqlUser.php b/tests/Models/SqlUser.php index 4cb77faa5..9b389ac08 100644 --- a/tests/Models/SqlUser.php +++ b/tests/Models/SqlUser.php @@ -20,8 +20,8 @@ class SqlUser extends EloquentModel { use HybridRelations; - protected $connection = 'sqlite'; - protected $table = 'users'; + protected $connection = 'sqlite'; + protected $table = 'users'; protected static $unguarded = true; public function books(): HasMany diff --git a/tests/Models/User.php b/tests/Models/User.php index 98f76d931..22048f282 100644 --- a/tests/Models/User.php +++ b/tests/Models/User.php @@ -11,12 +11,12 @@ use Illuminate\Contracts\Auth\Authenticatable as AuthenticatableContract; use Illuminate\Contracts\Auth\CanResetPassword as CanResetPasswordContract; use Illuminate\Database\Eloquent\Casts\Attribute; +use Illuminate\Database\Eloquent\Model; use Illuminate\Notifications\Notifiable; use Illuminate\Support\Str; use MongoDB\Laravel\Eloquent\Builder; -use MongoDB\Laravel\Eloquent\HybridRelations; +use MongoDB\Laravel\Eloquent\DocumentModel; use MongoDB\Laravel\Eloquent\MassPrunable; -use MongoDB\Laravel\Eloquent\Model as Eloquent; /** * @property string $_id @@ -30,22 +30,24 @@ * @property string $username * @property MemberStatus member_status */ -class User extends Eloquent implements AuthenticatableContract, CanResetPasswordContract +class User extends Model implements AuthenticatableContract, CanResetPasswordContract { + use DocumentModel; use Authenticatable; use CanResetPassword; - use HybridRelations; use Notifiable; use MassPrunable; + protected $primaryKey = '_id'; + protected $keyType = 'string'; protected $connection = 'mongodb'; - protected $casts = [ + protected $casts = [ 'birthday' => 'datetime', 'entry.date' => 'datetime', 'member_status' => MemberStatus::class, ]; - protected $fillable = [ + protected $fillable = [ 'name', 'email', 'title', diff --git a/tests/RelationsTest.php b/tests/RelationsTest.php index 368406feb..02efbc77b 100644 --- a/tests/RelationsTest.php +++ b/tests/RelationsTest.php @@ -331,7 +331,6 @@ public function testBelongsToManyAttachArray(): void $client1 = Client::create(['name' => 'Test 1'])->_id; $client2 = Client::create(['name' => 'Test 2'])->_id; - $user = User::where('name', '=', 'John Doe')->first(); $user->clients()->attach([$client1, $client2]); $this->assertCount(2, $user->clients); } diff --git a/tests/TransactionTest.php b/tests/TransactionTest.php index 1086171d7..3338c6832 100644 --- a/tests/TransactionTest.php +++ b/tests/TransactionTest.php @@ -40,7 +40,7 @@ public function testCreateWithCommit(): void $this->assertInstanceOf(User::class, $klinson); DB::commit(); - $this->assertInstanceOf(Model::class, $klinson); + $this->assertTrue(Model::isDocumentModel($klinson)); $this->assertTrue($klinson->exists); $this->assertEquals('klinson', $klinson->name); @@ -56,7 +56,7 @@ public function testCreateRollBack(): void $this->assertInstanceOf(User::class, $klinson); DB::rollBack(); - $this->assertInstanceOf(Model::class, $klinson); + $this->assertTrue(Model::isDocumentModel($klinson)); $this->assertTrue($klinson->exists); $this->assertEquals('klinson', $klinson->name); From cb3fa4ef27cbf65f8e0edbd7b632c7707ab3cb28 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Mon, 8 Jul 2024 11:38:52 -0400 Subject: [PATCH 301/446] DOCSP-38380: array reads (#3028) * DOCSP-38380: array reads * fix * NR PR fixes 1 * remove extra doc in test --- docs/fundamentals/read-operations.txt | 67 ++++++++++++++++--- .../read-operations/ReadOperationsTest.php | 31 +++++++++ 2 files changed, 90 insertions(+), 8 deletions(-) diff --git a/docs/fundamentals/read-operations.txt b/docs/fundamentals/read-operations.txt index 8025f0087..29437aa59 100644 --- a/docs/fundamentals/read-operations.txt +++ b/docs/fundamentals/read-operations.txt @@ -57,16 +57,13 @@ You can use Laravel's Eloquent object-relational mapper (ORM) to create models that represent MongoDB collections and chain methods on them to specify query criteria. -To retrieve documents that match a set of criteria, pass a query filter to the -``where()`` method. +To retrieve documents that match a set of criteria, call the ``where()`` +method on the collection's corresponding Eloquent model, then pass a query +filter to the method. A query filter specifies field value requirements and instructs the find operation to return only documents that meet these requirements. -You can use Laravel's Eloquent object-relational mapper (ORM) to create models -that represent MongoDB collections. To retrieve documents from a collection, -call the ``where()`` method on the collection's corresponding Eloquent model. - You can use one of the following ``where()`` method calls to build a query: - ``where('', )`` builds a query that matches documents in @@ -79,7 +76,7 @@ You can use one of the following ``where()`` method calls to build a query: To apply multiple sets of criteria to the find operation, you can chain a series of ``where()`` methods together. -After building your query with the ``where()`` method, chain the ``get()`` +After building your query by using the ``where()`` method, chain the ``get()`` method to retrieve the query results. This example calls two ``where()`` methods on the ``Movie`` Eloquent model to @@ -150,6 +147,60 @@ retrieve documents that meet the following criteria: To learn how to query by using the Laravel query builder instead of the Eloquent ORM, see the :ref:`laravel-query-builder` page. +Match Array Field Elements +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can specify a query filter to match array field elements when +retrieving documents. If your documents contain an array field, you can +match documents based on if the value contains all or some specified +array elements. + +You can use one of the following ``where()`` method calls to build a +query on an array field: + +- ``where('', )`` builds a query that matches documents in + which the array field value is exactly the specified array + +- ``where('', 'in', )`` builds a query + that matches documents in which the array field value contains one or + more of the specified array elements + +After building your query by using the ``where()`` method, chain the ``get()`` +method to retrieve the query results. + +Select from the following :guilabel:`Exact Array Match` and +:guilabel:`Element Match` tabs to view the query syntax for each pattern: + +.. tabs:: + + .. tab:: Exact Array Match + :tabid: exact-array + + This example retrieves documents in which the ``countries`` array is + exactly ``['Indonesia', 'Canada']``: + + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-exact-array + :end-before: end-exact-array + + .. tab:: Element Match + :tabid: element-match + + This example retrieves documents in which the ``countries`` array + contains one of the values in the array ``['Canada', 'Egypt']``: + + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-elem-match + :end-before: end-elem-match + +To learn how to query array fields by using the Laravel query builder instead of the +Eloquent ORM, see the :ref:`laravel-query-builder-elemMatch` section in +the Query Builder guide. + .. _laravel-retrieve-all: Retrieve All Documents in a Collection @@ -200,7 +251,7 @@ by the ``$search`` field in your query filter that you pass to the ``where()`` method. The ``$text`` operator performs a text search on the text-indexed fields. The ``$search`` field specifies the text to search for. -After building your query with the ``where()`` method, chain the ``get()`` +After building your query by using the ``where()`` method, chain the ``get()`` method to retrieve the query results. This example calls the ``where()`` method on the ``Movie`` Eloquent model to diff --git a/docs/includes/fundamentals/read-operations/ReadOperationsTest.php b/docs/includes/fundamentals/read-operations/ReadOperationsTest.php index a2080ec8f..c27680fb5 100644 --- a/docs/includes/fundamentals/read-operations/ReadOperationsTest.php +++ b/docs/includes/fundamentals/read-operations/ReadOperationsTest.php @@ -133,4 +133,35 @@ public function testTextRelevance(): void $this->assertCount(1, $movies); $this->assertEquals('this is a love story', $movies[0]->plot); } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function exactArrayMatch(): void + { + // start-exact-array + $movies = Movie::where('countries', ['Indonesia', 'Canada']) + ->get(); + // end-exact-array + + $this->assertNotNull($movies); + $this->assertCount(1, $movies); + $this->assertEquals('Title 1', $movies[0]->title); + } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function arrayElemMatch(): void + { + // start-elem-match + $movies = Movie::where('countries', 'in', ['Canada', 'Egypt']) + ->get(); + // end-elem-match + + $this->assertNotNull($movies); + $this->assertCount(2, $movies); + } } From f6ee9cc739285c2930974dafaba91af3eac341a1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 9 Jul 2024 09:44:27 +0200 Subject: [PATCH 302/446] Use PHPUnit's Attributes instead of annotation (#3035) --- tests/Casts/BinaryUuidTest.php | 3 ++- tests/Casts/ObjectIdTest.php | 3 ++- tests/ConnectionTest.php | 3 ++- tests/ModelTest.php | 5 +++-- tests/Query/BuilderTest.php | 7 ++++--- tests/QueryTest.php | 7 +++---- tests/Seeder/DatabaseSeeder.php | 7 +------ tests/TestCase.php | 12 +++--------- 8 files changed, 20 insertions(+), 27 deletions(-) diff --git a/tests/Casts/BinaryUuidTest.php b/tests/Casts/BinaryUuidTest.php index 2183c12fa..0d76c6927 100644 --- a/tests/Casts/BinaryUuidTest.php +++ b/tests/Casts/BinaryUuidTest.php @@ -8,6 +8,7 @@ use MongoDB\BSON\Binary; use MongoDB\Laravel\Tests\Models\Casting; use MongoDB\Laravel\Tests\TestCase; +use PHPUnit\Framework\Attributes\DataProvider; use function hex2bin; @@ -20,7 +21,7 @@ protected function setUp(): void Casting::truncate(); } - /** @dataProvider provideBinaryUuidCast */ + #[DataProvider('provideBinaryUuidCast')] public function testBinaryUuidCastModel(string $expectedUuid, string|Binary $saveUuid, Binary $queryUuid): void { Casting::create(['uuid' => $saveUuid]); diff --git a/tests/Casts/ObjectIdTest.php b/tests/Casts/ObjectIdTest.php index 8d3e9daf4..57201b4eb 100644 --- a/tests/Casts/ObjectIdTest.php +++ b/tests/Casts/ObjectIdTest.php @@ -8,6 +8,7 @@ use MongoDB\BSON\ObjectId; use MongoDB\Laravel\Tests\Models\CastObjectId; use MongoDB\Laravel\Tests\TestCase; +use PHPUnit\Framework\Attributes\DataProvider; class ObjectIdTest extends TestCase { @@ -18,7 +19,7 @@ protected function setUp(): void CastObjectId::truncate(); } - /** @dataProvider provideObjectIdCast */ + #[DataProvider('provideObjectIdCast')] public function testStoreObjectId(string|ObjectId $saveObjectId, ObjectId $queryObjectId): void { $stringObjectId = (string) $saveObjectId; diff --git a/tests/ConnectionTest.php b/tests/ConnectionTest.php index 83097973b..586452109 100644 --- a/tests/ConnectionTest.php +++ b/tests/ConnectionTest.php @@ -14,6 +14,7 @@ use MongoDB\Laravel\Connection; use MongoDB\Laravel\Query\Builder; use MongoDB\Laravel\Schema\Builder as SchemaBuilder; +use PHPUnit\Framework\Attributes\DataProvider; use function env; use function spl_object_hash; @@ -186,7 +187,7 @@ public static function dataConnectionConfig(): Generator ]; } - /** @dataProvider dataConnectionConfig */ + #[DataProvider('dataConnectionConfig')] public function testConnectionConfig(string $expectedUri, string $expectedDatabaseName, array $config): void { $connection = new Connection($config); diff --git a/tests/ModelTest.php b/tests/ModelTest.php index 9d2b58b6e..3c4cbd8df 100644 --- a/tests/ModelTest.php +++ b/tests/ModelTest.php @@ -28,6 +28,7 @@ use MongoDB\Laravel\Tests\Models\Soft; use MongoDB\Laravel\Tests\Models\SqlUser; use MongoDB\Laravel\Tests\Models\User; +use PHPUnit\Framework\Attributes\DataProvider; use PHPUnit\Framework\Attributes\TestWith; use function abs; @@ -370,7 +371,7 @@ public function testSoftDelete(): void $this->assertEquals(2, Soft::count()); } - /** @dataProvider provideId */ + #[DataProvider('provideId')] public function testPrimaryKey(string $model, $id, $expected, bool $expectedFound): void { $model::truncate(); @@ -755,7 +756,7 @@ public static function provideDate(): Generator yield 'DateTime date, time and ms before unix epoch' => [new DateTime('1965-08-08 04.08.37.324')]; } - /** @dataProvider provideDate */ + #[DataProvider('provideDate')] public function testDateInputs($date): void { // Test with create and standard property diff --git a/tests/Query/BuilderTest.php b/tests/Query/BuilderTest.php index 4076b3028..3ec933499 100644 --- a/tests/Query/BuilderTest.php +++ b/tests/Query/BuilderTest.php @@ -19,6 +19,7 @@ use MongoDB\Laravel\Query\Builder; use MongoDB\Laravel\Query\Grammar; use MongoDB\Laravel\Query\Processor; +use PHPUnit\Framework\Attributes\DataProvider; use PHPUnit\Framework\TestCase; use stdClass; @@ -29,7 +30,7 @@ class BuilderTest extends TestCase { - /** @dataProvider provideQueryBuilderToMql */ + #[DataProvider('provideQueryBuilderToMql')] public function testMql(array $expected, Closure $build): void { $builder = $build(self::getBuilder()); @@ -1298,7 +1299,7 @@ function (Builder $elemMatchQuery): void { } } - /** @dataProvider provideExceptions */ + #[DataProvider('provideExceptions')] public function testException($class, $message, Closure $build): void { $builder = self::getBuilder(); @@ -1396,7 +1397,7 @@ public static function provideExceptions(): iterable ]; } - /** @dataProvider getEloquentMethodsNotSupported */ + #[DataProvider('getEloquentMethodsNotSupported')] public function testEloquentMethodsNotSupported(Closure $callback) { $builder = self::getBuilder(); diff --git a/tests/QueryTest.php b/tests/QueryTest.php index 60645c985..2fd66bf70 100644 --- a/tests/QueryTest.php +++ b/tests/QueryTest.php @@ -12,6 +12,7 @@ use MongoDB\Laravel\Tests\Models\Birthday; use MongoDB\Laravel\Tests\Models\Scoped; use MongoDB\Laravel\Tests\Models\User; +use PHPUnit\Framework\Attributes\TestWith; use function str; @@ -662,10 +663,8 @@ public function testDelete(): void $this->assertEquals(0, User::count()); } - /** - * @testWith [0] - * [2] - */ + #[TestWith([0])] + #[TestWith([2])] public function testDeleteException(int $limit): void { $this->expectException(LogicException::class); diff --git a/tests/Seeder/DatabaseSeeder.php b/tests/Seeder/DatabaseSeeder.php index ef512b869..eade44a96 100644 --- a/tests/Seeder/DatabaseSeeder.php +++ b/tests/Seeder/DatabaseSeeder.php @@ -8,12 +8,7 @@ class DatabaseSeeder extends Seeder { - /** - * Run the database seeds. - * - * @return void - */ - public function run() + public function run(): void { $this->call(UserTableSeeder::class); } diff --git a/tests/TestCase.php b/tests/TestCase.php index e2be67a04..5f37ea170 100644 --- a/tests/TestCase.php +++ b/tests/TestCase.php @@ -21,10 +21,8 @@ class TestCase extends OrchestraTestCase * Get application providers. * * @param Application $app - * - * @return array */ - protected function getApplicationProviders($app) + protected function getApplicationProviders($app): array { $providers = parent::getApplicationProviders($app); @@ -37,10 +35,8 @@ protected function getApplicationProviders($app) * Get package providers. * * @param Application $app - * - * @return array */ - protected function getPackageProviders($app) + protected function getPackageProviders($app): array { return [ MongoDBServiceProvider::class, @@ -54,10 +50,8 @@ protected function getPackageProviders($app) * Define environment setup. * * @param Application $app - * - * @return void */ - protected function getEnvironmentSetUp($app) + protected function getEnvironmentSetUp($app): void { // reset base path to point to our package's src directory //$app['path.base'] = __DIR__ . '/../src'; From 65f0a6747688efe08dbdc33d5ccd11f94540de84 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 9 Jul 2024 14:37:48 +0200 Subject: [PATCH 303/446] Embedded paginator total override and accept Closure (#3027) Applies change from laravel/framework#46410 and laravel/framework#42429 --- CHANGELOG.md | 1 + src/Relations/EmbedsMany.php | 19 +++++++++++-------- tests/EmbeddedRelationsTest.php | 6 ++++++ 3 files changed, 18 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0a0a120f2..777a22304 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,7 @@ All notable changes to this project will be documented in this file. ## [4.6.0] - upcoming * Add `DocumentTrait` to use any 3rd party model with MongoDB @GromNaN in [#2580](https://github.com/mongodb/laravel-mongodb/pull/2580) +* Add support for Closure for Embed pagination @GromNaN in [#3027](https://github.com/mongodb/laravel-mongodb/pull/3027) ## [4.5.0] - 2024-06-20 diff --git a/src/Relations/EmbedsMany.php b/src/Relations/EmbedsMany.php index be7039506..72c77b598 100644 --- a/src/Relations/EmbedsMany.php +++ b/src/Relations/EmbedsMany.php @@ -4,6 +4,7 @@ namespace MongoDB\Laravel\Relations; +use Closure; use Illuminate\Database\Eloquent\Collection; use Illuminate\Database\Eloquent\Model; use Illuminate\Pagination\LengthAwarePaginator; @@ -18,6 +19,7 @@ use function is_array; use function method_exists; use function throw_if; +use function value; class EmbedsMany extends EmbedsOneOrMany { @@ -288,21 +290,22 @@ protected function associateExisting($model) } /** - * @param int|null $perPage - * @param array $columns - * @param string $pageName - * @param int|null $page + * @param int|Closure $perPage + * @param array|string $columns + * @param string $pageName + * @param int|null $page + * @param Closure|int|null $total * * @return \Illuminate\Contracts\Pagination\LengthAwarePaginator */ - public function paginate($perPage = null, $columns = ['*'], $pageName = 'page', $page = null) + public function paginate($perPage = null, $columns = ['*'], $pageName = 'page', $page = null, $total = null) { $page = $page ?: Paginator::resolveCurrentPage($pageName); - $perPage = $perPage ?: $this->related->getPerPage(); - $results = $this->getEmbedded(); $results = $this->toCollection($results); - $total = $results->count(); + $total = value($total) ?? $results->count(); + $perPage = $perPage ?: $this->related->getPerPage(); + $perPage = $perPage instanceof Closure ? $perPage($total) : $perPage; $start = ($page - 1) * $perPage; $sliced = $results->slice( diff --git a/tests/EmbeddedRelationsTest.php b/tests/EmbeddedRelationsTest.php index 2dd558679..00a84360c 100644 --- a/tests/EmbeddedRelationsTest.php +++ b/tests/EmbeddedRelationsTest.php @@ -925,6 +925,12 @@ public function testPaginateEmbedsMany() $results = $user->addresses()->paginate(2); $this->assertEquals(2, $results->count()); $this->assertEquals(3, $results->total()); + + // With Closures + $results = $user->addresses()->paginate(fn () => 3, page: 1, total: fn () => 5); + $this->assertEquals(3, $results->count()); + $this->assertEquals(5, $results->total()); + $this->assertEquals(3, $results->perPage()); } public function testGetQueueableRelationsEmbedsMany() From 179c6a6fe589d6721ca0d12072e0502de402b796 Mon Sep 17 00:00:00 2001 From: Jacques Florian Date: Tue, 9 Jul 2024 15:14:18 +0200 Subject: [PATCH 304/446] Add document version feature (#3021) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jérôme Tamarelle --- CHANGELOG.md | 5 +- src/Eloquent/HasSchemaVersion.php | 82 +++++++++++++++++++++++++++++++ tests/Models/SchemaVersion.php | 26 ++++++++++ tests/SchemaVersionTest.php | 58 ++++++++++++++++++++++ 4 files changed, 169 insertions(+), 2 deletions(-) create mode 100644 src/Eloquent/HasSchemaVersion.php create mode 100644 tests/Models/SchemaVersion.php create mode 100644 tests/SchemaVersionTest.php diff --git a/CHANGELOG.md b/CHANGELOG.md index 777a22304..5f2a2f9e5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,9 +1,10 @@ # Changelog All notable changes to this project will be documented in this file. -## [4.6.0] - upcoming +## [4.6.0] - 2024-07-09 -* Add `DocumentTrait` to use any 3rd party model with MongoDB @GromNaN in [#2580](https://github.com/mongodb/laravel-mongodb/pull/2580) +* Add `DocumentModel` trait to use any 3rd party model with MongoDB @GromNaN in [#2580](https://github.com/mongodb/laravel-mongodb/pull/2580) +* Add `HasSchemaVersion` trait to help implementing the [schema versioning pattern](https://www.mongodb.com/docs/manual/tutorial/model-data-for-schema-versioning/) @florianJacques in [#3021](https://github.com/mongodb/laravel-mongodb/pull/3021) * Add support for Closure for Embed pagination @GromNaN in [#3027](https://github.com/mongodb/laravel-mongodb/pull/3027) ## [4.5.0] - 2024-06-20 diff --git a/src/Eloquent/HasSchemaVersion.php b/src/Eloquent/HasSchemaVersion.php new file mode 100644 index 000000000..8849f655a --- /dev/null +++ b/src/Eloquent/HasSchemaVersion.php @@ -0,0 +1,82 @@ +getAttribute($model::getSchemaVersionKey()) === null) { + $model->setAttribute($model::getSchemaVersionKey(), $model->getModelSchemaVersion()); + } + }); + + static::retrieved(function (self $model) { + $version = $model->getSchemaVersion(); + + if ($version < $model->getModelSchemaVersion()) { + $model->migrateSchema($version); + $model->setAttribute($model::getSchemaVersionKey(), $model->getModelSchemaVersion()); + } + }); + } + + /** + * Get Current document version, fallback to 0 if not set + */ + public function getSchemaVersion(): int + { + return $this->{static::getSchemaVersionKey()} ?? 0; + } + + protected static function getSchemaVersionKey(): string + { + return 'schema_version'; + } + + protected function getModelSchemaVersion(): int + { + try { + return $this::SCHEMA_VERSION; + } catch (Error) { + throw new LogicException(sprintf('Constant %s::SCHEMA_VERSION is required when using HasSchemaVersion', $this::class)); + } + } +} diff --git a/tests/Models/SchemaVersion.php b/tests/Models/SchemaVersion.php new file mode 100644 index 000000000..cacfc3f65 --- /dev/null +++ b/tests/Models/SchemaVersion.php @@ -0,0 +1,26 @@ +age = 35; + } + } +} diff --git a/tests/SchemaVersionTest.php b/tests/SchemaVersionTest.php new file mode 100644 index 000000000..dfe2f5122 --- /dev/null +++ b/tests/SchemaVersionTest.php @@ -0,0 +1,58 @@ + 'Luc']); + $this->assertEmpty($document->getSchemaVersion()); + $document->save(); + + // The current schema version of the model is stored by default + $this->assertEquals(2, $document->getSchemaVersion()); + + // Test automatic migration + SchemaVersion::insert([ + ['name' => 'Vador', 'schema_version' => 1], + ]); + $document = SchemaVersion::where('name', 'Vador')->first(); + $this->assertEquals(2, $document->getSchemaVersion()); + $this->assertEquals(35, $document->age); + + $document->save(); + + // The migrated version is saved + $data = DB::connection('mongodb') + ->collection('documentVersion') + ->where('name', 'Vador') + ->get(); + + $this->assertEquals(2, $data[0]['schema_version']); + } + + public function testIncompleteImplementation(): void + { + $this->expectException(LogicException::class); + $this->expectExceptionMessage('::SCHEMA_VERSION is required when using HasSchemaVersion'); + $document = new class extends Model { + use HasSchemaVersion; + }; + + $document->save(); + } +} From 6cebcecd3bafe6fa79e98425b6a526a4e450466f Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 9 Jul 2024 14:56:04 -0400 Subject: [PATCH 305/446] DOCSP-41305: update compat table for 4.6 (#3036) --- docs/includes/framework-compatibility-laravel.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/includes/framework-compatibility-laravel.rst b/docs/includes/framework-compatibility-laravel.rst index 1ed23a46c..281e931ac 100644 --- a/docs/includes/framework-compatibility-laravel.rst +++ b/docs/includes/framework-compatibility-laravel.rst @@ -7,7 +7,7 @@ - Laravel 10.x - Laravel 9.x - * - 4.2 to 4.5 + * - 4.2 to 4.6 - ✓ - ✓ - From 1a1621a4d8b3b05d2e95afed546a08d34d16c3c9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 15 Jul 2024 14:05:58 +0200 Subject: [PATCH 306/446] Implement `Connection::getServerVersion` (#3043) --- CHANGELOG.md | 4 ++++ src/Connection.php | 11 +++++++++++ tests/ConnectionTest.php | 6 ++++++ 3 files changed, 21 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5f2a2f9e5..532d81a81 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,10 @@ # Changelog All notable changes to this project will be documented in this file. +## [4.9.0] - coming soon + +* Add `Connection::getServerVersion()` by @GromNaN in [#3043](https://github.com/mongodb/laravel-mongodb/pull/3043) + ## [4.6.0] - 2024-07-09 * Add `DocumentModel` trait to use any 3rd party model with MongoDB @GromNaN in [#2580](https://github.com/mongodb/laravel-mongodb/pull/2580) diff --git a/src/Connection.php b/src/Connection.php index 2ce5324ee..685e509b6 100644 --- a/src/Connection.php +++ b/src/Connection.php @@ -327,6 +327,17 @@ public function __call($method, $parameters) return $this->db->$method(...$parameters); } + /** + * Return the server version of one of the MongoDB servers: primary for + * replica sets and standalone, and the selected server for sharded clusters. + * + * @internal + */ + public function getServerVersion(): string + { + return $this->db->command(['buildInfo' => 1])->toArray()[0]['version']; + } + private static function getVersion(): string { return self::$version ?? self::lookupVersion(); diff --git a/tests/ConnectionTest.php b/tests/ConnectionTest.php index 586452109..ef0b746c3 100644 --- a/tests/ConnectionTest.php +++ b/tests/ConnectionTest.php @@ -299,4 +299,10 @@ public function testPingMethod() $instance = new Connection($config); $instance->ping(); } + + public function testServerVersion() + { + $version = DB::connection('mongodb')->getServerVersion(); + $this->assertIsString($version); + } } From 256a83028351bd783e6fccdefdd3485fc1dab6ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 15 Jul 2024 15:09:57 +0200 Subject: [PATCH 307/446] PHPORM-214 Implement `Schema\Builder::getTables` (#3044) --- CHANGELOG.md | 1 + src/Schema/Builder.php | 39 +++++++++++++++++++++++++++++++++++++++ tests/SchemaTest.php | 39 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 79 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 532d81a81..ae1bc0adc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,7 @@ All notable changes to this project will be documented in this file. ## [4.9.0] - coming soon * Add `Connection::getServerVersion()` by @GromNaN in [#3043](https://github.com/mongodb/laravel-mongodb/pull/3043) +* Add `Schema\Builder::getTables()` and `getTableListing` by @GromNaN in [#3044](https://github.com/mongodb/laravel-mongodb/pull/3044) ## [4.6.0] - 2024-07-09 diff --git a/src/Schema/Builder.php b/src/Schema/Builder.php index bfa0e4715..cc016a345 100644 --- a/src/Schema/Builder.php +++ b/src/Schema/Builder.php @@ -10,6 +10,8 @@ use function count; use function current; use function iterator_to_array; +use function sort; +use function usort; class Builder extends \Illuminate\Database\Schema\Builder { @@ -107,6 +109,43 @@ public function dropAllTables() } } + public function getTables() + { + $db = $this->connection->getMongoDB(); + $collections = []; + + foreach ($db->listCollectionNames() as $collectionName) { + $stats = $db->selectCollection($collectionName)->aggregate([ + ['$collStats' => ['storageStats' => ['scale' => 1]]], + ['$project' => ['storageStats.totalSize' => 1]], + ])->toArray(); + + $collections[] = [ + 'name' => $collectionName, + 'schema' => null, + 'size' => $stats[0]?->storageStats?->totalSize ?? null, + 'comment' => null, + 'collation' => null, + 'engine' => null, + ]; + } + + usort($collections, function ($a, $b) { + return $a['name'] <=> $b['name']; + }); + + return $collections; + } + + public function getTableListing() + { + $collections = iterator_to_array($this->connection->getMongoDB()->listCollectionNames()); + + sort($collections); + + return $collections; + } + /** @inheritdoc */ protected function createBlueprint($table, ?Closure $callback = null) { diff --git a/tests/SchemaTest.php b/tests/SchemaTest.php index 6e6248beb..88951233e 100644 --- a/tests/SchemaTest.php +++ b/tests/SchemaTest.php @@ -8,6 +8,8 @@ use Illuminate\Support\Facades\Schema; use MongoDB\Laravel\Schema\Blueprint; +use function count; + class SchemaTest extends TestCase { public function tearDown(): void @@ -377,6 +379,43 @@ public function testRenameColumn(): void $this->assertSame($check[2]['column'], $check2[2]['column']); } + public function testGetTables() + { + DB::connection('mongodb')->collection('newcollection')->insert(['test' => 'value']); + DB::connection('mongodb')->collection('newcollection_two')->insert(['test' => 'value']); + + $tables = Schema::getTables(); + $this->assertIsArray($tables); + $this->assertGreaterThanOrEqual(2, count($tables)); + $found = false; + foreach ($tables as $table) { + $this->assertArrayHasKey('name', $table); + $this->assertArrayHasKey('size', $table); + + if ($table['name'] === 'newcollection') { + $this->assertEquals(8192, $table['size']); + $found = true; + } + } + + if (! $found) { + $this->fail('Collection "newcollection" not found'); + } + } + + public function testGetTableListing() + { + DB::connection('mongodb')->collection('newcollection')->insert(['test' => 'value']); + DB::connection('mongodb')->collection('newcollection_two')->insert(['test' => 'value']); + + $tables = Schema::getTableListing(); + + $this->assertIsArray($tables); + $this->assertGreaterThanOrEqual(2, count($tables)); + $this->assertContains('newcollection', $tables); + $this->assertContains('newcollection_two', $tables); + } + protected function getIndex(string $collection, string $name) { $collection = DB::getCollection($collection); From c443240b16f7bd0dfd2471eab7e80462b24cbe66 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 16 Jul 2024 15:25:58 +0200 Subject: [PATCH 308/446] PHPORM-215 Implement Schema::getColumns and getIndexes (#3045) --- CHANGELOG.md | 3 +- src/Schema/Builder.php | 82 ++++++++++++++++++++++++++++++++++++++++++ tests/SchemaTest.php | 67 ++++++++++++++++++++++++++++++++++ 3 files changed, 151 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ae1bc0adc..4525b0848 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,8 @@ All notable changes to this project will be documented in this file. ## [4.9.0] - coming soon * Add `Connection::getServerVersion()` by @GromNaN in [#3043](https://github.com/mongodb/laravel-mongodb/pull/3043) -* Add `Schema\Builder::getTables()` and `getTableListing` by @GromNaN in [#3044](https://github.com/mongodb/laravel-mongodb/pull/3044) +* Add `Schema\Builder::getTables()` and `getTableListing()` by @GromNaN in [#3044](https://github.com/mongodb/laravel-mongodb/pull/3044) +* Add `Schema\Builder::getColumns()` and `getIndexes()` by @GromNaN in [#3045](https://github.com/mongodb/laravel-mongodb/pull/3045) ## [4.6.0] - 2024-07-09 diff --git a/src/Schema/Builder.php b/src/Schema/Builder.php index cc016a345..32fc9f482 100644 --- a/src/Schema/Builder.php +++ b/src/Schema/Builder.php @@ -6,11 +6,16 @@ use Closure; use MongoDB\Model\CollectionInfo; +use MongoDB\Model\IndexInfo; +use function array_keys; +use function assert; use function count; use function current; +use function implode; use function iterator_to_array; use function sort; +use function sprintf; use function usort; class Builder extends \Illuminate\Database\Schema\Builder @@ -146,6 +151,83 @@ public function getTableListing() return $collections; } + public function getColumns($table) + { + $stats = $this->connection->getMongoDB()->selectCollection($table)->aggregate([ + // Sample 1,000 documents to get a representative sample of the collection + ['$sample' => ['size' => 1_000]], + // Convert each document to an array of fields + ['$project' => ['fields' => ['$objectToArray' => '$$ROOT']]], + // Unwind to get one document per field + ['$unwind' => '$fields'], + // Group by field name, count the number of occurrences and get the types + [ + '$group' => [ + '_id' => '$fields.k', + 'total' => ['$sum' => 1], + 'types' => ['$addToSet' => ['$type' => '$fields.v']], + ], + ], + // Get the most seen field names + ['$sort' => ['total' => -1]], + // Limit to 1,000 fields + ['$limit' => 1_000], + // Sort by field name + ['$sort' => ['_id' => 1]], + ], [ + 'typeMap' => ['array' => 'array'], + 'allowDiskUse' => true, + ])->toArray(); + + $columns = []; + foreach ($stats as $stat) { + sort($stat->types); + $type = implode(', ', $stat->types); + $columns[] = [ + 'name' => $stat->_id, + 'type_name' => $type, + 'type' => $type, + 'collation' => null, + 'nullable' => $stat->_id !== '_id', + 'default' => null, + 'auto_increment' => false, + 'comment' => sprintf('%d occurrences', $stat->total), + 'generation' => $stat->_id === '_id' ? ['type' => 'objectId', 'expression' => null] : null, + ]; + } + + return $columns; + } + + public function getIndexes($table) + { + $indexes = $this->connection->getMongoDB()->selectCollection($table)->listIndexes(); + + $indexList = []; + foreach ($indexes as $index) { + assert($index instanceof IndexInfo); + $indexList[] = [ + 'name' => $index->getName(), + 'columns' => array_keys($index->getKey()), + 'primary' => $index->getKey() === ['_id' => 1], + 'type' => match (true) { + $index->isText() => 'text', + $index->is2dSphere() => '2dsphere', + $index->isTtl() => 'ttl', + default => 'default', + }, + 'unique' => $index->isUnique(), + ]; + } + + return $indexList; + } + + public function getForeignKeys($table) + { + return []; + } + /** @inheritdoc */ protected function createBlueprint($table, ?Closure $callback = null) { diff --git a/tests/SchemaTest.php b/tests/SchemaTest.php index 88951233e..1d99627ce 100644 --- a/tests/SchemaTest.php +++ b/tests/SchemaTest.php @@ -6,8 +6,11 @@ use Illuminate\Support\Facades\DB; use Illuminate\Support\Facades\Schema; +use MongoDB\BSON\Binary; +use MongoDB\BSON\UTCDateTime; use MongoDB\Laravel\Schema\Blueprint; +use function collect; use function count; class SchemaTest extends TestCase @@ -416,6 +419,70 @@ public function testGetTableListing() $this->assertContains('newcollection_two', $tables); } + public function testGetColumns() + { + $collection = DB::connection('mongodb')->collection('newcollection'); + $collection->insert(['text' => 'value', 'mixed' => ['key' => 'value']]); + $collection->insert(['date' => new UTCDateTime(), 'binary' => new Binary('binary'), 'mixed' => true]); + + $columns = Schema::getColumns('newcollection'); + $this->assertIsArray($columns); + $this->assertCount(5, $columns); + + $columns = collect($columns)->keyBy('name'); + + $columns->each(function ($column) { + $this->assertIsString($column['name']); + $this->assertEquals($column['type'], $column['type_name']); + $this->assertNull($column['collation']); + $this->assertIsBool($column['nullable']); + $this->assertNull($column['default']); + $this->assertFalse($column['auto_increment']); + $this->assertIsString($column['comment']); + }); + + $this->assertEquals('objectId', $columns->get('_id')['type']); + $this->assertEquals('objectId', $columns->get('_id')['generation']['type']); + $this->assertNull($columns->get('text')['generation']); + $this->assertEquals('string', $columns->get('text')['type']); + $this->assertEquals('date', $columns->get('date')['type']); + $this->assertEquals('binData', $columns->get('binary')['type']); + $this->assertEquals('bool, object', $columns->get('mixed')['type']); + $this->assertEquals('2 occurrences', $columns->get('mixed')['comment']); + + // Non-existent collection + $columns = Schema::getColumns('missing'); + $this->assertSame([], $columns); + } + + public function testGetIndexes() + { + Schema::create('newcollection', function (Blueprint $collection) { + $collection->index('mykey1'); + $collection->string('mykey2')->unique('unique_index'); + $collection->string('mykey3')->index(); + }); + $indexes = Schema::getIndexes('newcollection'); + $this->assertIsArray($indexes); + $this->assertCount(4, $indexes); + + $indexes = collect($indexes)->keyBy('name'); + + $indexes->each(function ($index) { + $this->assertIsString($index['name']); + $this->assertIsString($index['type']); + $this->assertIsArray($index['columns']); + $this->assertIsBool($index['unique']); + $this->assertIsBool($index['primary']); + }); + $this->assertTrue($indexes->get('_id_')['primary']); + $this->assertTrue($indexes->get('unique_index_1')['unique']); + + // Non-existent collection + $indexes = Schema::getIndexes('missing'); + $this->assertSame([], $indexes); + } + protected function getIndex(string $collection, string $name) { $collection = DB::getCollection($collection); From 7df42cd884d5d13ace8899867540aaa6eac81428 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Tue, 16 Jul 2024 11:08:35 -0400 Subject: [PATCH 309/446] DOCSP-38100: User authentication (#3034) Adds a page that explains how to authenticate users stored in MongoDB --- docs/includes/auth/AuthController.php | 38 ++++++++ docs/includes/auth/AuthUser.php | 22 +++++ docs/user-authentication.txt | 124 ++++++++++++++++++++++++-- 3 files changed, 177 insertions(+), 7 deletions(-) create mode 100644 docs/includes/auth/AuthController.php create mode 100644 docs/includes/auth/AuthUser.php diff --git a/docs/includes/auth/AuthController.php b/docs/includes/auth/AuthController.php new file mode 100644 index 000000000..c76552cbe --- /dev/null +++ b/docs/includes/auth/AuthController.php @@ -0,0 +1,38 @@ +validate([ + 'email' => 'required|email', + 'password' => 'required', + ]); + + if (Auth::attempt($request->only('email', 'password'))) { + return response()->json([ + 'user' => Auth::user(), + 'message' => 'Successfully logged in', + ]); + } + + throw ValidationException::withMessages([ + 'email' => ['The provided credentials are incorrect.'], + ]); + } + + public function logout() + { + Auth::logout(); + + return response()->json(['message' => 'Successfully logged out']); + } +} diff --git a/docs/includes/auth/AuthUser.php b/docs/includes/auth/AuthUser.php new file mode 100644 index 000000000..8b6a0f173 --- /dev/null +++ b/docs/includes/auth/AuthUser.php @@ -0,0 +1,22 @@ +`__ in the +Laravel documentation. + +Modify the User Model +--------------------- + +By default, Laravel generates the ``User`` Eloquent model in your ``App/Models`` +directory. To enable authentication for MongoDB users, your ``User`` model +must extend the ``MongoDB\Laravel\Auth\User`` class. + +To extend this class, navigate to your ``app/Models/User.php`` file and replace the +``use Illuminate\Foundation\Auth\User as Authenticatable`` statement with the following +code: + +.. code-block:: php + + use MongoDB\Laravel\Auth\User as Authenticatable; + +Next, ensure that your ``User`` class extends ``Authenticatable``, as shown in the following +code: + +.. code-block:: php + + class User extends Authenticatable + { + ... + } + +After configuring your ``User`` model, create a corresponding controller. To learn how to +create a controller, see the :ref:`laravel-auth-controller` section on this page. + +Example +~~~~~~~ + +The following code shows a ``User.php`` file that extends the ``MongoDB\Laravel\Auth\User`` +class: + +.. literalinclude:: /includes/auth/AuthUser.php + :language: php + :dedent: + +.. _laravel-auth-controller: + +Create the User Controller +-------------------------- + +To store functions that manage authentication, create an authentication controller for +your ``User`` model. + +Run the following command from your project root to create a controller: + +.. code-block:: php + + php artisan make:controller + +Example +~~~~~~~ + +The following command creates a controller file called ``AuthController.php``: + +.. code-block:: php + + php artisan make:controller AuthController + +The ``AuthController.php`` file can store ``login()`` and ``logout()`` functions to +manage user authentication, as shown in the following code: + +.. literalinclude:: /includes/auth/AuthController.php + :language: php + :dedent: + +Enable Password Reminders +------------------------- + +To add support for MongoDB-based password reminders, register the following service +provider in your application: + +.. code-block:: php + + MongoDB\Laravel\Auth\PasswordResetServiceProvider::class + +This service provider modifies the internal ``DatabaseReminderRepository`` +to enable password reminders. + +Example +~~~~~~~ + +The following code updates the ``providers.php`` file in the ``bootstrap`` directory +of a Laravel application to register the ``PasswordResetServiceProvider`` provider: .. code-block:: php + :emphasize-lines: 4 + + return [ + App\Providers\AppServiceProvider::class, + MongoDB\Laravel\MongoDBServiceProvider::class, + MongoDB\Laravel\Auth\PasswordResetServiceProvider::class + ]; - MongoDB\Laravel\Auth\PasswordResetServiceProvider::class, +Additional Information +---------------------- -This service provider will slightly modify the internal ``DatabaseReminderRepository`` -to add support for MongoDB based password reminders. +To learn more about user authentication, see `Authentication `__ +in the Laravel documentation. -If you don't use password reminders, you can omit this service provider. +To learn more about Eloquent models, see the :ref:`laravel-eloquent-model-class` guide. \ No newline at end of file From ebd28472cc4680e3890cf9d9e02670fe09f0efb5 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Tue, 16 Jul 2024 12:08:37 -0400 Subject: [PATCH 310/446] DOCSP-41472: txn learning byte link (#3048) * DOCSP-41472: txn learning byte link * wip * AS fix --- docs/transactions.txt | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/transactions.txt b/docs/transactions.txt index 89562c795..e85f06361 100644 --- a/docs/transactions.txt +++ b/docs/transactions.txt @@ -39,17 +39,21 @@ Multi-document transactions are **ACID compliant** because MongoDB guarantees that the data in your transaction operations remains consistent, even if the driver encounters unexpected errors. -Learn how to perform transactions in the following sections of this guide: +To learn more about transactions in MongoDB, see :manual:`Transactions ` +in the {+server-docs-name+}. + +This guide contains the following sections: - :ref:`laravel-transaction-requirements` - :ref:`laravel-transaction-callback` - :ref:`laravel-transaction-commit` - :ref:`laravel-transaction-rollback` -.. tip:: +.. tip:: Transactions Learning Byte - To learn more about transactions in MongoDB, see :manual:`Transactions ` - in the {+server-docs-name+}. + Practice using {+odm-short+} to perform transactions + in the `Laravel Transactions Learning Byte + `__. .. _laravel-transaction-requirements: @@ -156,4 +160,3 @@ transaction is rolled back, and none of the models are updated: :emphasize-lines: 1,18,20 :start-after: begin rollback transaction :end-before: end rollback transaction - From a62d4b91796b00c2cf46845bab9fd23cc0df6a97 Mon Sep 17 00:00:00 2001 From: Oleksand Bilyi Date: Tue, 16 Jul 2024 20:08:09 +0300 Subject: [PATCH 311/446] Add hasColumn/hasColumns method (#3001) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jérôme Tamarelle --- CHANGELOG.md | 3 ++- src/Schema/Builder.php | 28 ++++++++++++++++++++++------ tests/SchemaTest.php | 20 ++++++++++++++++++++ 3 files changed, 44 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4525b0848..e7e394001 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,11 +1,12 @@ # Changelog All notable changes to this project will be documented in this file. -## [4.9.0] - coming soon +## [4.7.0] - coming soon * Add `Connection::getServerVersion()` by @GromNaN in [#3043](https://github.com/mongodb/laravel-mongodb/pull/3043) * Add `Schema\Builder::getTables()` and `getTableListing()` by @GromNaN in [#3044](https://github.com/mongodb/laravel-mongodb/pull/3044) * Add `Schema\Builder::getColumns()` and `getIndexes()` by @GromNaN in [#3045](https://github.com/mongodb/laravel-mongodb/pull/3045) +* Add `Schema\Builder::hasColumn` and `hasColumns` method by @Alex-Belyi in [#3002](https://github.com/mongodb/laravel-mongodb/pull/3001) ## [4.6.0] - 2024-07-09 diff --git a/src/Schema/Builder.php b/src/Schema/Builder.php index 32fc9f482..29f089d7d 100644 --- a/src/Schema/Builder.php +++ b/src/Schema/Builder.php @@ -8,6 +8,7 @@ use MongoDB\Model\CollectionInfo; use MongoDB\Model\IndexInfo; +use function array_fill_keys; use function array_keys; use function assert; use function count; @@ -20,16 +21,31 @@ class Builder extends \Illuminate\Database\Schema\Builder { - /** @inheritdoc */ - public function hasColumn($table, $column) + /** + * Check if column exists in the collection schema. + * + * @param string $table + * @param string $column + */ + public function hasColumn($table, $column): bool { - return true; + return $this->hasColumns($table, [$column]); } - /** @inheritdoc */ - public function hasColumns($table, array $columns) + /** + * Check if columns exists in the collection schema. + * + * @param string $table + * @param string[] $columns + */ + public function hasColumns($table, array $columns): bool { - return true; + $collection = $this->connection->table($table); + + return $collection + ->where(array_fill_keys($columns, ['$exists' => true])) + ->project(['_id' => 1]) + ->exists(); } /** diff --git a/tests/SchemaTest.php b/tests/SchemaTest.php index 1d99627ce..e9d039fa7 100644 --- a/tests/SchemaTest.php +++ b/tests/SchemaTest.php @@ -382,6 +382,26 @@ public function testRenameColumn(): void $this->assertSame($check[2]['column'], $check2[2]['column']); } + public function testHasColumn(): void + { + DB::connection()->collection('newcollection')->insert(['column1' => 'value']); + + $this->assertTrue(Schema::hasColumn('newcollection', 'column1')); + $this->assertFalse(Schema::hasColumn('newcollection', 'column2')); + } + + public function testHasColumns(): void + { + // Insert documents with both column1 and column2 + DB::connection()->collection('newcollection')->insert([ + ['column1' => 'value1', 'column2' => 'value2'], + ['column1' => 'value3'], + ]); + + $this->assertTrue(Schema::hasColumns('newcollection', ['column1', 'column2'])); + $this->assertFalse(Schema::hasColumns('newcollection', ['column1', 'column3'])); + } + public function testGetTables() { DB::connection('mongodb')->collection('newcollection')->insert(['test' => 'value']); From acaba1ad51eeaa6f87ccb185682a294d4dea1c0c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Fri, 19 Jul 2024 10:30:27 +0200 Subject: [PATCH 312/446] PHPORM-114 Implement `Builder::upsert` (#3053) --- CHANGELOG.md | 3 ++- src/Query/Builder.php | 41 ++++++++++++++++++++++++++++++++++++++ tests/ModelTest.php | 34 +++++++++++++++++++++++++++++++ tests/QueryBuilderTest.php | 36 ++++++++++++++++++++++++++++++++- 4 files changed, 112 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e7e394001..73a4faa8b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,10 +3,11 @@ All notable changes to this project will be documented in this file. ## [4.7.0] - coming soon +* Add `Query\Builder::upsert()` method by @GromNaN in [#3052](https://github.com/mongodb/laravel-mongodb/pull/3052) * Add `Connection::getServerVersion()` by @GromNaN in [#3043](https://github.com/mongodb/laravel-mongodb/pull/3043) * Add `Schema\Builder::getTables()` and `getTableListing()` by @GromNaN in [#3044](https://github.com/mongodb/laravel-mongodb/pull/3044) * Add `Schema\Builder::getColumns()` and `getIndexes()` by @GromNaN in [#3045](https://github.com/mongodb/laravel-mongodb/pull/3045) -* Add `Schema\Builder::hasColumn` and `hasColumns` method by @Alex-Belyi in [#3002](https://github.com/mongodb/laravel-mongodb/pull/3001) +* Add `Schema\Builder::hasColumn` and `hasColumns` method by @Alex-Belyi in [#3001](https://github.com/mongodb/laravel-mongodb/pull/3001) ## [4.6.0] - 2024-07-09 diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 89faa4b17..1d4dcf153 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -725,6 +725,47 @@ public function update(array $values, array $options = []) return $this->performUpdate($values, $options); } + /** @inheritdoc */ + public function upsert(array $values, $uniqueBy, $update = null): int + { + if ($values === []) { + return 0; + } + + $this->applyBeforeQueryCallbacks(); + + $options = $this->inheritConnectionOptions(); + $uniqueBy = array_fill_keys((array) $uniqueBy, 1); + + // If no update fields are specified, all fields are updated + if ($update !== null) { + $update = array_fill_keys((array) $update, 1); + } + + $bulk = []; + + foreach ($values as $value) { + $filter = $operation = []; + foreach ($value as $key => $val) { + if (isset($uniqueBy[$key])) { + $filter[$key] = $val; + } + + if ($update === null || array_key_exists($key, $update)) { + $operation['$set'][$key] = $val; + } else { + $operation['$setOnInsert'][$key] = $val; + } + } + + $bulk[] = ['updateOne' => [$filter, $operation, ['upsert' => true]]]; + } + + $result = $this->collection->bulkWrite($bulk, $options); + + return $result->getInsertedCount() + $result->getUpsertedCount() + $result->getModifiedCount(); + } + /** @inheritdoc */ public function increment($column, $amount = 1, array $extra = [], array $options = []) { diff --git a/tests/ModelTest.php b/tests/ModelTest.php index 3c4cbd8df..57e49574f 100644 --- a/tests/ModelTest.php +++ b/tests/ModelTest.php @@ -143,6 +143,40 @@ public function testUpdate(): void $this->assertEquals('Hans Thomas', $check->fullname); } + public function testUpsert() + { + $result = User::upsert([ + ['email' => 'foo', 'name' => 'bar'], + ['name' => 'bar2', 'email' => 'foo2'], + ], ['email']); + + $this->assertSame(2, $result); + + $this->assertSame(2, $result); + $this->assertSame(2, User::count()); + $this->assertSame('bar', User::where('email', 'foo')->first()->name); + + // Update 1 document + $result = User::upsert([ + ['email' => 'foo', 'name' => 'bar2'], + ['name' => 'bar2', 'email' => 'foo2'], + ], 'email', ['name']); + + // Even if the same value is set for the 2nd document, the "updated_at" field is updated + $this->assertSame(2, $result); + $this->assertSame(2, User::count()); + $this->assertSame('bar2', User::where('email', 'foo')->first()->name); + + // If no update fields are specified, all fields are updated + $result = User::upsert([ + ['email' => 'foo', 'name' => 'bar3'], + ], 'email'); + + $this->assertSame(1, $result); + $this->assertSame(2, User::count()); + $this->assertSame('bar3', User::where('email', 'foo')->first()->name); + } + public function testManualStringId(): void { $user = new User(); diff --git a/tests/QueryBuilderTest.php b/tests/QueryBuilderTest.php index 4320e6a54..7924e02f3 100644 --- a/tests/QueryBuilderTest.php +++ b/tests/QueryBuilderTest.php @@ -11,6 +11,7 @@ use Illuminate\Support\LazyCollection; use Illuminate\Support\Str; use Illuminate\Testing\Assert; +use Illuminate\Tests\Database\DatabaseQueryBuilderTest; use InvalidArgumentException; use MongoDB\BSON\ObjectId; use MongoDB\BSON\Regex; @@ -588,7 +589,7 @@ public function testSubdocumentArrayAggregate() $this->assertEquals(12, DB::collection('items')->avg('amount.*.hidden')); } - public function testUpsert() + public function testUpdateWithUpsert() { DB::collection('items')->where('name', 'knife') ->update( @@ -607,6 +608,39 @@ public function testUpsert() $this->assertEquals(2, DB::collection('items')->count()); } + public function testUpsert() + { + /** @see DatabaseQueryBuilderTest::testUpsertMethod() */ + // Insert 2 documents + $result = DB::collection('users')->upsert([ + ['email' => 'foo', 'name' => 'bar'], + ['name' => 'bar2', 'email' => 'foo2'], + ], 'email', 'name'); + + $this->assertSame(2, $result); + $this->assertSame(2, DB::collection('users')->count()); + $this->assertSame('bar', DB::collection('users')->where('email', 'foo')->first()['name']); + + // Update 1 document + $result = DB::collection('users')->upsert([ + ['email' => 'foo', 'name' => 'bar2'], + ['name' => 'bar2', 'email' => 'foo2'], + ], 'email', 'name'); + + $this->assertSame(1, $result); + $this->assertSame(2, DB::collection('users')->count()); + $this->assertSame('bar2', DB::collection('users')->where('email', 'foo')->first()['name']); + + // If no update fields are specified, all fields are updated + $result = DB::collection('users')->upsert([ + ['email' => 'foo', 'name' => 'bar3'], + ], 'email'); + + $this->assertSame(1, $result); + $this->assertSame(2, DB::collection('users')->count()); + $this->assertSame('bar3', DB::collection('users')->where('email', 'foo')->first()['name']); + } + public function testUnset() { $id1 = DB::collection('users')->insertGetId(['name' => 'John Doe', 'note1' => 'ABC', 'note2' => 'DEF']); From f0716abf3631ef313514474aa040cf5bb6a501f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Fri, 19 Jul 2024 10:43:31 +0200 Subject: [PATCH 313/446] PHPORM-211 Fix unsetting property in embedded model (#3052) --- CHANGELOG.md | 1 + src/Relations/EmbedsOneOrMany.php | 9 ++++++- tests/EmbeddedRelationsTest.php | 45 ++++++++++++++++++++++--------- 3 files changed, 41 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 73a4faa8b..e8ba4e0f6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ All notable changes to this project will be documented in this file. * Add `Schema\Builder::getTables()` and `getTableListing()` by @GromNaN in [#3044](https://github.com/mongodb/laravel-mongodb/pull/3044) * Add `Schema\Builder::getColumns()` and `getIndexes()` by @GromNaN in [#3045](https://github.com/mongodb/laravel-mongodb/pull/3045) * Add `Schema\Builder::hasColumn` and `hasColumns` method by @Alex-Belyi in [#3001](https://github.com/mongodb/laravel-mongodb/pull/3001) +* Fix unsetting a field in an embedded model by @GromNaN in [#3052](https://github.com/mongodb/laravel-mongodb/pull/3052) ## [4.6.0] - 2024-07-09 diff --git a/src/Relations/EmbedsOneOrMany.php b/src/Relations/EmbedsOneOrMany.php index 9c83aa299..f18d3d526 100644 --- a/src/Relations/EmbedsOneOrMany.php +++ b/src/Relations/EmbedsOneOrMany.php @@ -15,8 +15,10 @@ use Throwable; use function array_merge; +use function assert; use function count; use function is_array; +use function str_starts_with; use function throw_if; abstract class EmbedsOneOrMany extends Relation @@ -392,7 +394,12 @@ public static function getUpdateValues($array, $prepend = '') $results = []; foreach ($array as $key => $value) { - $results[$prepend . $key] = $value; + if (str_starts_with($key, '$')) { + assert(is_array($value), 'Update operator value must be an array.'); + $results[$key] = static::getUpdateValues($value, $prepend); + } else { + $results[$prepend . $key] = $value; + } } return $results; diff --git a/tests/EmbeddedRelationsTest.php b/tests/EmbeddedRelationsTest.php index 00a84360c..22e6e8d08 100644 --- a/tests/EmbeddedRelationsTest.php +++ b/tests/EmbeddedRelationsTest.php @@ -10,12 +10,6 @@ use Mockery; use MongoDB\BSON\ObjectId; use MongoDB\Laravel\Tests\Models\Address; -use MongoDB\Laravel\Tests\Models\Book; -use MongoDB\Laravel\Tests\Models\Client; -use MongoDB\Laravel\Tests\Models\Group; -use MongoDB\Laravel\Tests\Models\Item; -use MongoDB\Laravel\Tests\Models\Photo; -use MongoDB\Laravel\Tests\Models\Role; use MongoDB\Laravel\Tests\Models\User; use function array_merge; @@ -25,14 +19,7 @@ class EmbeddedRelationsTest extends TestCase public function tearDown(): void { Mockery::close(); - User::truncate(); - Book::truncate(); - Item::truncate(); - Role::truncate(); - Client::truncate(); - Group::truncate(); - Photo::truncate(); } public function testEmbedsManySave() @@ -951,4 +938,36 @@ public function testGetQueueableRelationsEmbedsOne() $this->assertEquals(['father'], $user->getQueueableRelations()); $this->assertEquals([], $user->father->getQueueableRelations()); } + + public function testUnsetPropertyOnEmbed() + { + $user = User::create(['name' => 'John Doe']); + $user->addresses()->save(new Address(['city' => 'New York'])); + $user->addresses()->save(new Address(['city' => 'Tokyo'])); + + // Set property + $user->addresses->first()->city = 'Paris'; + $user->addresses->first()->save(); + + $user = User::where('name', 'John Doe')->first(); + $this->assertSame('Paris', $user->addresses->get(0)->city); + $this->assertSame('Tokyo', $user->addresses->get(1)->city); + + // Unset property + unset($user->addresses->first()->city); + $user->addresses->first()->save(); + + $user = User::where('name', 'John Doe')->first(); + $this->assertNull($user->addresses->get(0)->city); + $this->assertSame('Tokyo', $user->addresses->get(1)->city); + + // Unset and reset property + unset($user->addresses->get(1)->city); + $user->addresses->get(1)->city = 'Kyoto'; + $user->addresses->get(1)->save(); + + $user = User::where('name', 'John Doe')->first(); + $this->assertNull($user->addresses->get(0)->city); + $this->assertSame('Kyoto', $user->addresses->get(1)->city); + } } From 5c310941e258a2588f91832a51786c72816f4b54 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Fri, 19 Jul 2024 15:27:46 +0200 Subject: [PATCH 314/446] Set date for release 4.7.0 (#3054) --- CHANGELOG.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e8ba4e0f6..b4b539e13 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,13 +1,13 @@ # Changelog All notable changes to this project will be documented in this file. -## [4.7.0] - coming soon +## [4.7.0] - 2024-07-19 * Add `Query\Builder::upsert()` method by @GromNaN in [#3052](https://github.com/mongodb/laravel-mongodb/pull/3052) * Add `Connection::getServerVersion()` by @GromNaN in [#3043](https://github.com/mongodb/laravel-mongodb/pull/3043) * Add `Schema\Builder::getTables()` and `getTableListing()` by @GromNaN in [#3044](https://github.com/mongodb/laravel-mongodb/pull/3044) * Add `Schema\Builder::getColumns()` and `getIndexes()` by @GromNaN in [#3045](https://github.com/mongodb/laravel-mongodb/pull/3045) -* Add `Schema\Builder::hasColumn` and `hasColumns` method by @Alex-Belyi in [#3001](https://github.com/mongodb/laravel-mongodb/pull/3001) +* Add `Schema\Builder::hasColumn()` and `hasColumns()` method by @Alex-Belyi in [#3001](https://github.com/mongodb/laravel-mongodb/pull/3001) * Fix unsetting a field in an embedded model by @GromNaN in [#3052](https://github.com/mongodb/laravel-mongodb/pull/3052) ## [4.6.0] - 2024-07-09 From 994e9560d04958f4bac3b57cff332f9822aea5a0 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Fri, 19 Jul 2024 13:33:21 -0400 Subject: [PATCH 315/446] DOCSP-41241: Laravel Sanctum (#3050) * DOCSP-41241: Laravel Sanctum * apply phpcbf formatting * edits * code edit, change depth * feedback * edits * JM tech review 1 --------- Co-authored-by: norareidy Co-authored-by: rustagir --- docs/includes/auth/PersonalAccessToken.php | 16 ++++++ docs/user-authentication.txt | 62 ++++++++++++++++++++-- 2 files changed, 74 insertions(+), 4 deletions(-) create mode 100644 docs/includes/auth/PersonalAccessToken.php diff --git a/docs/includes/auth/PersonalAccessToken.php b/docs/includes/auth/PersonalAccessToken.php new file mode 100644 index 000000000..2a3c5e29c --- /dev/null +++ b/docs/includes/auth/PersonalAccessToken.php @@ -0,0 +1,16 @@ +`__ +in the Laravel Sanctum guide. + +.. _laravel-user-auth-reminders: + +Password Reminders +~~~~~~~~~~~~~~~~~~ To add support for MongoDB-based password reminders, register the following service provider in your application: @@ -111,7 +165,7 @@ This service provider modifies the internal ``DatabaseReminderRepository`` to enable password reminders. Example -~~~~~~~ +``````` The following code updates the ``providers.php`` file in the ``bootstrap`` directory of a Laravel application to register the ``PasswordResetServiceProvider`` provider: From 4943bcccd0542eb244ca59c50dfadfba578081de Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Fri, 19 Jul 2024 14:49:34 -0400 Subject: [PATCH 316/446] DOCSP-41306: schema version trait (#3051) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * DOCSP-41306: schema version trait * MW PR fixes 1 * add test wip * add tests * apply phpcbf formatting * JM tech review 1 * error * comment style * Fix test, expose 2 models, lock laravel version to avoid breaking change * JM tech review 2 * fixes * revert database v * JM tech review 3 * JM tech review 4 --------- Co-authored-by: rustagir Co-authored-by: Jérôme Tamarelle --- docs/eloquent-models/model-class.txt | 101 +++++++++++++++++- .../eloquent-models/PlanetSchemaVersion1.php | 10 ++ .../eloquent-models/PlanetSchemaVersion2.php | 26 +++++ .../eloquent-models/SchemaVersionTest.php | 54 ++++++++++ 4 files changed, 190 insertions(+), 1 deletion(-) create mode 100644 docs/includes/eloquent-models/PlanetSchemaVersion1.php create mode 100644 docs/includes/eloquent-models/PlanetSchemaVersion2.php create mode 100644 docs/includes/eloquent-models/SchemaVersionTest.php diff --git a/docs/eloquent-models/model-class.txt b/docs/eloquent-models/model-class.txt index f1d1fbdda..ad5565abe 100644 --- a/docs/eloquent-models/model-class.txt +++ b/docs/eloquent-models/model-class.txt @@ -33,6 +33,8 @@ to {+odm-short+} models: - :ref:`laravel-model-customize` explains several model class customizations. - :ref:`laravel-model-pruning` shows how to periodically remove models that you no longer need. +- :ref:`laravel-schema-versioning` shows how to implement model schema + versioning. .. _laravel-model-define: @@ -67,7 +69,6 @@ This model is stored in the ``planets`` MongoDB collection. To learn how to specify the database name that your Laravel application uses, :ref:`laravel-quick-start-connect-to-mongodb`. - .. _laravel-authenticatable-model: Extend the Authenticatable Model @@ -333,3 +334,101 @@ models that the prune action deletes: :emphasize-lines: 5,10,12 :dedent: +.. _laravel-schema-versioning: + +Create a Versioned Model Schema +------------------------------- + +You can implement a schema versioning pattern into your application by +using the ``HasSchemaVersion`` trait on an Eloquent model. You might +choose to implement a schema version to organize or standardize a +collection that contains data with different schemas. + +.. tip:: + + To learn more about schema versioning, see the :manual:`Model Data for + Schema Versioning ` + tutorial in the {+server-docs-name+}. + +To use this feature with models that use MongoDB as a database, add the +``MongoDB\Laravel\Eloquent\HasSchemaVersion`` import to your model. +Then, set the ``SCHEMA_VERSION`` constant to ``1`` to set the first +schema version on your collection. If your collection evolves to contain +multiple schemas, you can update the value of the ``SCHEMA_VERSION`` +constant in subsequent model classes. + +When creating your model, you can define the ``migrateSchema()`` method +to specify a migration to the current schema version upon retrieving a +model. In this method, you can specify the changes to make to an older +model to update it to match the current schema version. + +When you save a model that does not have a schema version +specified, the ``HasSchemaVersion`` trait assumes that it follows the +latest schema version. When you retrieve a model that does not contain +the ``schema_version`` field, the trait assumes that its schema version +is ``0`` and performs the migration. + +Schema Versioning Example +~~~~~~~~~~~~~~~~~~~~~~~~~ + +In this sample situation, you are working with a collection that was +first modeled by the following class: + +.. literalinclude:: /includes/eloquent-models/PlanetSchemaVersion1.php + :language: php + :dedent: + +Now, you want to implement a new schema version on the collection. +You can define the new model class with the following behavior: + +- Implements the ``HasSchemaVersion`` trait and sets the current + ``SCHEMA_VERSION`` to ``2`` + +- Defines the ``migrateSchema()`` method to migrate models in which the + schema version is less than ``2`` to have a ``galaxy`` field that has a value + of ``'Milky Way'`` + +.. literalinclude:: /includes/eloquent-models/PlanetSchemaVersion2.php + :language: php + :emphasize-lines: 10,12,20 + :dedent: + +In the ``"WASP-39 b"`` document in the following code, the +``schema_version`` field value is less than ``2``. When you retrieve the +document, {+odm-short+} adds the ``galaxy`` field and updates the schema +version to the current version, ``2``. + +The ``"Saturn"`` document does not contain the ``schema_version`` field, +so {+odm-short+} assigns it the current schema version upon saving. + +Finally, the code retrieves the models from the collection to +demonstrate the changes: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/eloquent-models/SchemaVersionTest.php + :language: php + :dedent: + :start-after: begin-schema-version + :end-before: end-schema-version + + .. output:: + :language: none + :visible: false + + [ + { + "_id": ..., + "name": "WASP-39 b", + "type": "gas", + "galaxy": "Milky Way", + "schema_version": 2, + }, + { + "_id": ..., + "name": "Saturn", + "type": "gas", + "schema_version": 2, + } + ] diff --git a/docs/includes/eloquent-models/PlanetSchemaVersion1.php b/docs/includes/eloquent-models/PlanetSchemaVersion1.php new file mode 100644 index 000000000..d4cbff71b --- /dev/null +++ b/docs/includes/eloquent-models/PlanetSchemaVersion1.php @@ -0,0 +1,10 @@ +galaxy = 'Milky Way'; + } + } +} diff --git a/docs/includes/eloquent-models/SchemaVersionTest.php b/docs/includes/eloquent-models/SchemaVersionTest.php new file mode 100644 index 000000000..7bf54f679 --- /dev/null +++ b/docs/includes/eloquent-models/SchemaVersionTest.php @@ -0,0 +1,54 @@ + 'WASP-39 b', + 'type' => 'gas', + 'schema_version' => 1, + ], + ]); + + // Saves a document with no specified schema version + $saturn = Planet::create([ + 'name' => 'Saturn', + 'type' => 'gas', + ]); + + // Retrieves both models from the collection + $planets = Planet::where('type', 'gas') + ->get(); + // end-schema-version + + $this->assertCount(2, $planets); + + $p1 = Planet::where('name', 'Saturn')->first(); + + $this->assertEquals(2, $p1->schema_version); + + $p2 = Planet::where('name', 'WASP-39 b')->first(); + + $this->assertEquals(2, $p2->schema_version); + $this->assertEquals('Milky Way', $p2->galaxy); + } +} From 172c6e3aeccf7062be79fd75ab1deca38b039ae9 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Fri, 19 Jul 2024 16:09:21 -0400 Subject: [PATCH 317/446] DOCSP-41628: v4.7 docs version update (#3058) --- docs/includes/framework-compatibility-laravel.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/includes/framework-compatibility-laravel.rst b/docs/includes/framework-compatibility-laravel.rst index 281e931ac..608560dd1 100644 --- a/docs/includes/framework-compatibility-laravel.rst +++ b/docs/includes/framework-compatibility-laravel.rst @@ -7,7 +7,7 @@ - Laravel 10.x - Laravel 9.x - * - 4.2 to 4.6 + * - 4.2 to 4.7 - ✓ - ✓ - From 4f2a8dfd08de21b68335fa9a420704940d644657 Mon Sep 17 00:00:00 2001 From: Dog <296404875@qq.com> Date: Mon, 22 Jul 2024 21:14:07 +0800 Subject: [PATCH 318/446] Added two methods incrementEach and decrementEach (#2550) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Add tests on incrementEach/decrementEach * Fix incrementEach to handle null values --------- Co-authored-by: Jérôme Tamarelle --- CHANGELOG.md | 4 +++ src/Query/Builder.php | 28 +++++++++++++++++++++ tests/QueryBuilderTest.php | 50 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 82 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index b4b539e13..e4108377c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,10 @@ # Changelog All notable changes to this project will be documented in this file. +## [4.8.0] - next + +* Add `Query\Builder::incrementEach()` and `decrementEach()` methods by @SmallRuralDog in [#2550](https://github.com/mongodb/laravel-mongodb/pull/2550) + ## [4.7.0] - 2024-07-19 * Add `Query\Builder::upsert()` method by @GromNaN in [#3052](https://github.com/mongodb/laravel-mongodb/pull/3052) diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 1d4dcf153..ddc2413d8 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -787,12 +787,40 @@ public function increment($column, $amount = 1, array $extra = [], array $option return $this->performUpdate($query, $options); } + public function incrementEach(array $columns, array $extra = [], array $options = []) + { + $stage['$addFields'] = $extra; + + // Not using $inc for each column, because it would fail if one column is null. + foreach ($columns as $column => $amount) { + $stage['$addFields'][$column] = [ + '$add' => [$amount, ['$ifNull' => ['$' . $column, 0]]], + ]; + } + + $options = $this->inheritConnectionOptions($options); + + return $this->performUpdate([$stage], $options); + } + /** @inheritdoc */ public function decrement($column, $amount = 1, array $extra = [], array $options = []) { return $this->increment($column, -1 * $amount, $extra, $options); } + /** @inheritdoc */ + public function decrementEach(array $columns, array $extra = [], array $options = []) + { + $decrement = []; + + foreach ($columns as $column => $amount) { + $decrement[$column] = -1 * $amount; + } + + return $this->incrementEach($decrement, $extra, $options); + } + /** @inheritdoc */ public function chunkById($count, callable $callback, $column = '_id', $alias = null) { diff --git a/tests/QueryBuilderTest.php b/tests/QueryBuilderTest.php index 7924e02f3..d819db5cd 100644 --- a/tests/QueryBuilderTest.php +++ b/tests/QueryBuilderTest.php @@ -998,4 +998,54 @@ public function testStringableColumn() $user = DB::collection('users')->where($ageColumn, 29)->first(); $this->assertEquals('John Doe', $user['name']); } + + public function testIncrementEach() + { + DB::collection('users')->insert([ + ['name' => 'John Doe', 'age' => 30, 'note' => 5], + ['name' => 'Jane Doe', 'age' => 10, 'note' => 6], + ['name' => 'Robert Roe', 'age' => null], + ]); + + DB::collection('users')->incrementEach([ + 'age' => 1, + 'note' => 2, + ]); + $user = DB::collection('users')->where('name', 'John Doe')->first(); + $this->assertEquals(31, $user['age']); + $this->assertEquals(7, $user['note']); + + $user = DB::collection('users')->where('name', 'Jane Doe')->first(); + $this->assertEquals(11, $user['age']); + $this->assertEquals(8, $user['note']); + + $user = DB::collection('users')->where('name', 'Robert Roe')->first(); + $this->assertSame(1, $user['age']); + $this->assertSame(2, $user['note']); + + DB::collection('users')->where('name', 'Jane Doe')->incrementEach([ + 'age' => 1, + 'note' => 2, + ], ['extra' => 'foo']); + + $user = DB::collection('users')->where('name', 'Jane Doe')->first(); + $this->assertEquals(12, $user['age']); + $this->assertEquals(10, $user['note']); + $this->assertEquals('foo', $user['extra']); + + $user = DB::collection('users')->where('name', 'John Doe')->first(); + $this->assertEquals(31, $user['age']); + $this->assertEquals(7, $user['note']); + $this->assertArrayNotHasKey('extra', $user); + + DB::collection('users')->decrementEach([ + 'age' => 1, + 'note' => 2, + ], ['extra' => 'foo']); + + $user = DB::collection('users')->where('name', 'John Doe')->first(); + $this->assertEquals(30, $user['age']); + $this->assertEquals(5, $user['note']); + $this->assertEquals('foo', $user['extra']); + } } From 979cf523f3a861a3a64672039d3cb813b88c66ca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 23 Jul 2024 16:18:49 +0200 Subject: [PATCH 319/446] PHPORM-219 Deprecate `Connection::collection()` and `Schema::collection()` (#3062) Use `table()` method instead, consistent with Laravel. Co-authored-by: Andreas Braun Co-authored-by: Rea Rustagi <85902999+rustagir@users.noreply.github.com> --- CHANGELOG.md | 1 + docs/fundamentals/database-collection.txt | 18 +- .../query-builder/QueryBuilderTest.php | 92 ++-- docs/query-builder.txt | 12 +- src/Connection.php | 16 +- src/Queue/MongoQueue.php | 4 +- src/Schema/Builder.php | 17 +- tests/AuthTest.php | 8 +- tests/ConnectionTest.php | 16 +- tests/GeospatialTest.php | 2 +- tests/QueryBuilderTest.php | 454 +++++++++--------- .../Failed/MongoFailedJobProviderTest.php | 4 +- tests/SchemaTest.php | 24 +- tests/SchemaVersionTest.php | 2 +- tests/Seeder/UserTableSeeder.php | 4 +- tests/TransactionTest.php | 56 +-- 16 files changed, 375 insertions(+), 355 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e4108377c..92a945c26 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,7 @@ All notable changes to this project will be documented in this file. ## [4.8.0] - next * Add `Query\Builder::incrementEach()` and `decrementEach()` methods by @SmallRuralDog in [#2550](https://github.com/mongodb/laravel-mongodb/pull/2550) +* Deprecate `Connection::collection()` and `Schema\Builder::collection()` methods by @GromNaN in [#3062](https://github.com/mongodb/laravel-mongodb/pull/3062) ## [4.7.0] - 2024-07-19 diff --git a/docs/fundamentals/database-collection.txt b/docs/fundamentals/database-collection.txt index 6b629d79e..ce67c3946 100644 --- a/docs/fundamentals/database-collection.txt +++ b/docs/fundamentals/database-collection.txt @@ -56,7 +56,7 @@ create a database connection to the ``animals`` database in the .. code-block:: php :emphasize-lines: 1,8 - + 'default' => 'mongodb', 'connections' => [ @@ -77,7 +77,7 @@ The following example shows how to specify multiple database connections ``plants`` databases: .. code-block:: php - + 'connections' => [ 'mongodb' => [ @@ -145,23 +145,29 @@ Laravel retrieves results from the ``flowers`` collection: Flower::where('name', 'Water Lily')->get() +.. note:: + + Starting in {+odm-short+} v4.8, the ``DB::collection()`` method + is deprecated. As shown in the following example, you can use the ``DB::table()`` + method to access a MongoDB collection. + If you are unable to accomplish your operation by using an Eloquent -model, you can access the query builder by calling the ``collection()`` +model, you can access the query builder by calling the ``table()`` method on the ``DB`` facade. The following example shows the same query as in the preceding example, but the query is constructed by using the -``DB::collection()`` method: +``DB::table()`` method: .. code-block:: php DB::connection('mongodb') - ->collection('flowers') + ->table('flowers') ->where('name', 'Water Lily') ->get() List Collections ---------------- -To see information about each of the collections in a database, call the +To see information about each of the collections in a database, call the ``listCollections()`` method. The following example accesses a database connection, then diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index a7d7a591e..a6a8c752d 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -21,7 +21,7 @@ protected function setUp(): void parent::setUp(); $db = DB::connection('mongodb'); - $db->collection('movies') + $db->table('movies') ->insert(json_decode(file_get_contents(__DIR__ . '/sample_mflix.movies.json'), true)); } @@ -29,10 +29,10 @@ protected function importTheaters(): void { $db = DB::connection('mongodb'); - $db->collection('theaters') + $db->table('theaters') ->insert(json_decode(file_get_contents(__DIR__ . '/sample_mflix.theaters.json'), true)); - $db->collection('theaters') + $db->table('theaters') ->raw() ->createIndex(['location.geo' => '2dsphere']); } @@ -40,8 +40,8 @@ protected function importTheaters(): void protected function tearDown(): void { $db = DB::connection('mongodb'); - $db->collection('movies')->raw()->drop(); - $db->collection('theaters')->raw()->drop(); + $db->table('movies')->raw()->drop(); + $db->table('theaters')->raw()->drop(); parent::tearDown(); } @@ -50,7 +50,7 @@ public function testWhere(): void { // begin query where $result = DB::connection('mongodb') - ->collection('movies') + ->table('movies') ->where('imdb.rating', 9.3) ->get(); // end query where @@ -62,7 +62,7 @@ public function testOrWhere(): void { // begin query orWhere $result = DB::connection('mongodb') - ->collection('movies') + ->table('movies') ->where('year', 1955) ->orWhere('title', 'Back to the Future') ->get(); @@ -75,7 +75,7 @@ public function testAndWhere(): void { // begin query andWhere $result = DB::connection('mongodb') - ->collection('movies') + ->table('movies') ->where('imdb.rating', '>', 8.5) ->where('year', '<', 1940) ->get(); @@ -88,7 +88,7 @@ public function testWhereNot(): void { // begin query whereNot $result = DB::connection('mongodb') - ->collection('movies') + ->table('movies') ->whereNot('imdb.rating', '>', 2) ->get(); // end query whereNot @@ -100,7 +100,7 @@ public function testNestedLogical(): void { // begin query nestedLogical $result = DB::connection('mongodb') - ->collection('movies') + ->table('movies') ->where('imdb.rating', '>', 8.5) ->where(function (Builder $query) { return $query @@ -116,7 +116,7 @@ public function testWhereBetween(): void { // begin query whereBetween $result = DB::connection('mongodb') - ->collection('movies') + ->table('movies') ->whereBetween('imdb.rating', [9, 9.5]) ->get(); // end query whereBetween @@ -128,7 +128,7 @@ public function testWhereNull(): void { // begin query whereNull $result = DB::connection('mongodb') - ->collection('movies') + ->table('movies') ->whereNull('runtime') ->get(); // end query whereNull @@ -139,7 +139,7 @@ public function testWhereNull(): void public function testWhereIn(): void { // begin query whereIn - $result = DB::collection('movies') + $result = DB::table('movies') ->whereIn('title', ['Toy Story', 'Shrek 2', 'Johnny English']) ->get(); // end query whereIn @@ -151,7 +151,7 @@ public function testWhereDate(): void { // begin query whereDate $result = DB::connection('mongodb') - ->collection('movies') + ->table('movies') ->whereDate('released', '2010-1-15') ->get(); // end query whereDate @@ -162,7 +162,7 @@ public function testWhereDate(): void public function testLike(): void { // begin query like - $result = DB::collection('movies') + $result = DB::table('movies') ->where('title', 'like', '%spider_man%') ->get(); // end query like @@ -173,7 +173,7 @@ public function testLike(): void public function testDistinct(): void { // begin query distinct - $result = DB::collection('movies') + $result = DB::table('movies') ->distinct('year')->get(); // end query distinct @@ -183,7 +183,7 @@ public function testDistinct(): void public function testGroupBy(): void { // begin query groupBy - $result = DB::collection('movies') + $result = DB::table('movies') ->where('rated', 'G') ->groupBy('runtime') ->orderBy('runtime', 'asc') @@ -196,7 +196,7 @@ public function testGroupBy(): void public function testAggCount(): void { // begin aggregation count - $result = DB::collection('movies') + $result = DB::table('movies') ->count(); // end aggregation count @@ -206,7 +206,7 @@ public function testAggCount(): void public function testAggMax(): void { // begin aggregation max - $result = DB::collection('movies') + $result = DB::table('movies') ->max('runtime'); // end aggregation max @@ -216,7 +216,7 @@ public function testAggMax(): void public function testAggMin(): void { // begin aggregation min - $result = DB::collection('movies') + $result = DB::table('movies') ->min('year'); // end aggregation min @@ -226,7 +226,7 @@ public function testAggMin(): void public function testAggAvg(): void { // begin aggregation avg - $result = DB::collection('movies') + $result = DB::table('movies') ->avg('imdb.rating'); // end aggregation avg @@ -236,7 +236,7 @@ public function testAggAvg(): void public function testAggSum(): void { // begin aggregation sum - $result = DB::collection('movies') + $result = DB::table('movies') ->sum('imdb.votes'); // end aggregation sum @@ -246,7 +246,7 @@ public function testAggSum(): void public function testAggWithFilter(): void { // begin aggregation with filter - $result = DB::collection('movies') + $result = DB::table('movies') ->where('year', '>', 2000) ->avg('imdb.rating'); // end aggregation with filter @@ -257,7 +257,7 @@ public function testAggWithFilter(): void public function testOrderBy(): void { // begin query orderBy - $result = DB::collection('movies') + $result = DB::table('movies') ->where('title', 'like', 'back to the future%') ->orderBy('imdb.rating', 'desc') ->get(); @@ -269,7 +269,7 @@ public function testOrderBy(): void public function testSkip(): void { // begin query skip - $result = DB::collection('movies') + $result = DB::table('movies') ->where('title', 'like', 'star trek%') ->orderBy('year', 'asc') ->skip(4) @@ -282,7 +282,7 @@ public function testSkip(): void public function testProjection(): void { // begin query projection - $result = DB::collection('movies') + $result = DB::table('movies') ->where('imdb.rating', '>', 8.5) ->project([ 'title' => 1, @@ -300,7 +300,7 @@ public function testProjectionWithPagination(): void $resultsPerPage = 15; $projectionFields = ['title', 'runtime', 'imdb.rating']; - $result = DB::collection('movies') + $result = DB::table('movies') ->orderBy('imdb.votes', 'desc') ->paginate($resultsPerPage, $projectionFields); // end query projection with pagination @@ -311,7 +311,7 @@ public function testProjectionWithPagination(): void public function testExists(): void { // begin query exists - $result = DB::collection('movies') + $result = DB::table('movies') ->exists('random_review', true); // end query exists @@ -321,7 +321,7 @@ public function testExists(): void public function testAll(): void { // begin query all - $result = DB::collection('movies') + $result = DB::table('movies') ->where('movies', 'all', ['title', 'rated', 'imdb.rating']) ->get(); // end query all @@ -332,7 +332,7 @@ public function testAll(): void public function testSize(): void { // begin query size - $result = DB::collection('movies') + $result = DB::table('movies') ->where('directors', 'size', 5) ->get(); // end query size @@ -343,7 +343,7 @@ public function testSize(): void public function testType(): void { // begin query type - $result = DB::collection('movies') + $result = DB::table('movies') ->where('released', 'type', 4) ->get(); // end query type @@ -354,7 +354,7 @@ public function testType(): void public function testMod(): void { // begin query modulo - $result = DB::collection('movies') + $result = DB::table('movies') ->where('year', 'mod', [2, 0]) ->get(); // end query modulo @@ -366,7 +366,7 @@ public function testWhereRegex(): void { // begin query whereRegex $result = DB::connection('mongodb') - ->collection('movies') + ->table('movies') ->where('title', 'REGEX', new Regex('^the lord of .*', 'i')) ->get(); // end query whereRegex @@ -377,7 +377,7 @@ public function testWhereRegex(): void public function testWhereRaw(): void { // begin query raw - $result = DB::collection('movies') + $result = DB::table('movies') ->whereRaw([ 'imdb.votes' => ['$gte' => 1000 ], '$or' => [ @@ -393,7 +393,7 @@ public function testWhereRaw(): void public function testElemMatch(): void { // begin query elemMatch - $result = DB::collection('movies') + $result = DB::table('movies') ->where('writers', 'elemMatch', ['$in' => ['Maya Forbes', 'Eric Roth']]) ->get(); // end query elemMatch @@ -404,7 +404,7 @@ public function testElemMatch(): void public function testCursorTimeout(): void { // begin query cursor timeout - $result = DB::collection('movies') + $result = DB::table('movies') ->timeout(2) // value in seconds ->where('year', 2001) ->get(); @@ -418,7 +418,7 @@ public function testNear(): void $this->importTheaters(); // begin query near - $results = DB::collection('theaters') + $results = DB::table('theaters') ->where('location.geo', 'near', [ '$geometry' => [ 'type' => 'Point', @@ -437,7 +437,7 @@ public function testNear(): void public function testGeoWithin(): void { // begin query geoWithin - $results = DB::collection('theaters') + $results = DB::table('theaters') ->where('location.geo', 'geoWithin', [ '$geometry' => [ 'type' => 'Polygon', @@ -459,7 +459,7 @@ public function testGeoWithin(): void public function testGeoIntersects(): void { // begin query geoIntersects - $results = DB::collection('theaters') + $results = DB::table('theaters') ->where('location.geo', 'geoIntersects', [ '$geometry' => [ 'type' => 'LineString', @@ -479,7 +479,7 @@ public function testGeoNear(): void $this->importTheaters(); // begin query geoNear - $results = DB::collection('theaters')->raw( + $results = DB::table('theaters')->raw( function (Collection $collection) { return $collection->aggregate([ [ @@ -506,7 +506,7 @@ function (Collection $collection) { public function testUpsert(): void { // begin upsert - $result = DB::collection('movies') + $result = DB::table('movies') ->where('title', 'Will Hunting') ->update( [ @@ -524,7 +524,7 @@ public function testUpsert(): void public function testIncrement(): void { // begin increment - $result = DB::collection('movies') + $result = DB::table('movies') ->where('title', 'Field of Dreams') ->increment('imdb.votes', 3000); // end increment @@ -535,7 +535,7 @@ public function testIncrement(): void public function testDecrement(): void { // begin decrement - $result = DB::collection('movies') + $result = DB::table('movies') ->where('title', 'Sharknado') ->decrement('imdb.rating', 0.2); // end decrement @@ -546,7 +546,7 @@ public function testDecrement(): void public function testPush(): void { // begin push - $result = DB::collection('movies') + $result = DB::table('movies') ->where('title', 'Office Space') ->push('cast', 'Gary Cole'); // end push @@ -557,7 +557,7 @@ public function testPush(): void public function testPull(): void { // begin pull - $result = DB::collection('movies') + $result = DB::table('movies') ->where('title', 'Iron Man') ->pull('genres', 'Adventure'); // end pull @@ -568,7 +568,7 @@ public function testPull(): void public function testUnset(): void { // begin unset - $result = DB::collection('movies') + $result = DB::table('movies') ->where('title', 'Final Accord') ->unset('tomatoes.viewer'); // end unset diff --git a/docs/query-builder.txt b/docs/query-builder.txt index 8b4be3245..041893e34 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -36,28 +36,28 @@ lets you perform database operations. Facades, which are static interfaces to classes, make the syntax more concise, avoid runtime errors, and improve testability. -{+odm-short+} aliases the ``DB`` method ``table()`` as the ``collection()`` -method. Chain methods to specify commands and any constraints. Then, chain +{+odm-short+} provides the ``DB`` method ``table()`` to access a collection. +Chain methods to specify commands and any constraints. Then, chain the ``get()`` method at the end to run the methods and retrieve the results. The following example shows the syntax of a query builder call: .. code-block:: php - DB::collection('') + DB::table('') // chain methods by using the "->" object operator ->get(); .. tip:: - Before using the ``DB::collection()`` method, ensure that you specify MongoDB as your application's + Before using the ``DB::table()`` method, ensure that you specify MongoDB as your application's default database connection. For instructions on setting the database connection, see the :ref:`laravel-quick-start-connect-to-mongodb` step in the Quick Start. If MongoDB is not your application's default database, you can use the ``DB::connection()`` method to specify a MongoDB connection. Pass the name of the connection to the ``connection()`` method, as shown in the following code: - + .. code-block:: php - + $connection = DB::connection('mongodb'); This guide provides examples of the following types of query builder operations: diff --git a/src/Connection.php b/src/Connection.php index 685e509b6..9b4cc26ed 100644 --- a/src/Connection.php +++ b/src/Connection.php @@ -22,7 +22,9 @@ use function is_array; use function preg_match; use function str_contains; +use function trigger_error; +use const E_USER_DEPRECATED; use const FILTER_FLAG_IPV6; use const FILTER_VALIDATE_IP; @@ -78,28 +80,32 @@ public function __construct(array $config) /** * Begin a fluent query against a database collection. * + * @deprecated since mongodb/laravel-mongodb 4.8, use the function table() instead + * * @param string $collection * * @return Query\Builder */ public function collection($collection) { - $query = new Query\Builder($this, $this->getQueryGrammar(), $this->getPostProcessor()); + @trigger_error('Since mongodb/laravel-mongodb 4.8, the method Connection::collection() is deprecated and will be removed in version 5.0. Use the table() method instead.', E_USER_DEPRECATED); - return $query->from($collection); + return $this->table($collection); } /** * Begin a fluent query against a database collection. * - * @param string $table - * @param string|null $as + * @param string $table The name of the MongoDB collection + * @param string|null $as Ignored. Not supported by MongoDB * * @return Query\Builder */ public function table($table, $as = null) { - return $this->collection($table); + $query = new Query\Builder($this, $this->getQueryGrammar(), $this->getPostProcessor()); + + return $query->from($table); } /** diff --git a/src/Queue/MongoQueue.php b/src/Queue/MongoQueue.php index eeac36c78..5b91afb6b 100644 --- a/src/Queue/MongoQueue.php +++ b/src/Queue/MongoQueue.php @@ -109,7 +109,7 @@ protected function releaseJobsThatHaveBeenReservedTooLong($queue) { $expiration = Carbon::now()->subSeconds($this->retryAfter)->getTimestamp(); - $reserved = $this->database->collection($this->table) + $reserved = $this->database->table($this->table) ->where('queue', $this->getQueue($queue)) ->whereNotNull('reserved_at') ->where('reserved_at', '<=', $expiration) @@ -140,7 +140,7 @@ protected function releaseJob($id, $attempts) /** @inheritdoc */ public function deleteReserved($queue, $id) { - $this->database->collection($this->table)->where('_id', $id)->delete(); + $this->database->table($this->table)->where('_id', $id)->delete(); } /** @inheritdoc */ diff --git a/src/Schema/Builder.php b/src/Schema/Builder.php index 29f089d7d..e31a1efe1 100644 --- a/src/Schema/Builder.php +++ b/src/Schema/Builder.php @@ -17,8 +17,11 @@ use function iterator_to_array; use function sort; use function sprintf; +use function trigger_error; use function usort; +use const E_USER_DEPRECATED; + class Builder extends \Illuminate\Database\Schema\Builder { /** @@ -75,23 +78,27 @@ public function hasTable($table) /** * Modify a collection on the schema. * + * @deprecated since mongodb/laravel-mongodb 4.8, use the function table() instead + * * @param string $collection * * @return void */ public function collection($collection, Closure $callback) { - $blueprint = $this->createBlueprint($collection); + @trigger_error('Since mongodb/laravel-mongodb 4.8, the method Schema\Builder::collection() is deprecated and will be removed in version 5.0. Use the function table() instead.', E_USER_DEPRECATED); - if ($callback) { - $callback($blueprint); - } + $this->table($collection, $callback); } /** @inheritdoc */ public function table($table, Closure $callback) { - $this->collection($table, $callback); + $blueprint = $this->createBlueprint($table); + + if ($callback) { + $callback($blueprint); + } } /** @inheritdoc */ diff --git a/tests/AuthTest.php b/tests/AuthTest.php index eadb9b1f4..61710bf74 100644 --- a/tests/AuthTest.php +++ b/tests/AuthTest.php @@ -20,7 +20,7 @@ public function tearDown(): void parent::setUp(); User::truncate(); - DB::collection('password_reset_tokens')->truncate(); + DB::table('password_reset_tokens')->truncate(); } public function testAuthAttempt() @@ -59,8 +59,8 @@ function ($actualUser, $actualToken) use ($user, &$token) { ), ); - $this->assertEquals(1, DB::collection('password_reset_tokens')->count()); - $reminder = DB::collection('password_reset_tokens')->first(); + $this->assertEquals(1, DB::table('password_reset_tokens')->count()); + $reminder = DB::table('password_reset_tokens')->first(); $this->assertEquals('john.doe@example.com', $reminder['email']); $this->assertNotNull($reminder['token']); $this->assertInstanceOf(UTCDateTime::class, $reminder['created_at']); @@ -78,6 +78,6 @@ function ($actualUser, $actualToken) use ($user, &$token) { }); $this->assertEquals('passwords.reset', $response); - $this->assertEquals(0, DB::collection('password_resets')->count()); + $this->assertEquals(0, DB::table('password_resets')->count()); } } diff --git a/tests/ConnectionTest.php b/tests/ConnectionTest.php index ef0b746c3..214050840 100644 --- a/tests/ConnectionTest.php +++ b/tests/ConnectionTest.php @@ -196,7 +196,7 @@ public function testConnectionConfig(string $expectedUri, string $expectedDataba $this->assertSame($expectedUri, (string) $client); $this->assertSame($expectedDatabaseName, $connection->getMongoDB()->getDatabaseName()); $this->assertSame('foo', $connection->getCollection('foo')->getCollectionName()); - $this->assertSame('foo', $connection->collection('foo')->raw()->getCollectionName()); + $this->assertSame('foo', $connection->table('foo')->raw()->getCollectionName()); } public function testConnectionWithoutConfiguredDatabase(): void @@ -220,7 +220,7 @@ public function testCollection() $collection = DB::connection('mongodb')->getCollection('unittest'); $this->assertInstanceOf(Collection::class, $collection); - $collection = DB::connection('mongodb')->collection('unittests'); + $collection = DB::connection('mongodb')->table('unittests'); $this->assertInstanceOf(Builder::class, $collection); $collection = DB::connection('mongodb')->table('unittests'); @@ -238,7 +238,7 @@ public function testPrefix() $connection = new Connection($config); $this->assertSame('prefix_foo', $connection->getCollection('foo')->getCollectionName()); - $this->assertSame('prefix_foo', $connection->collection('foo')->raw()->getCollectionName()); + $this->assertSame('prefix_foo', $connection->table('foo')->raw()->getCollectionName()); } public function testQueryLog() @@ -247,19 +247,19 @@ public function testQueryLog() $this->assertCount(0, DB::getQueryLog()); - DB::collection('items')->get(); + DB::table('items')->get(); $this->assertCount(1, DB::getQueryLog()); - DB::collection('items')->insert(['name' => 'test']); + DB::table('items')->insert(['name' => 'test']); $this->assertCount(2, DB::getQueryLog()); - DB::collection('items')->count(); + DB::table('items')->count(); $this->assertCount(3, DB::getQueryLog()); - DB::collection('items')->where('name', 'test')->update(['name' => 'test']); + DB::table('items')->where('name', 'test')->update(['name' => 'test']); $this->assertCount(4, DB::getQueryLog()); - DB::collection('items')->where('name', 'test')->delete(); + DB::table('items')->where('name', 'test')->delete(); $this->assertCount(5, DB::getQueryLog()); } diff --git a/tests/GeospatialTest.php b/tests/GeospatialTest.php index d5fc44d38..724bb580b 100644 --- a/tests/GeospatialTest.php +++ b/tests/GeospatialTest.php @@ -13,7 +13,7 @@ public function setUp(): void { parent::setUp(); - Schema::collection('locations', function ($collection) { + Schema::table('locations', function ($collection) { $collection->geospatial('location', '2dsphere'); }); diff --git a/tests/QueryBuilderTest.php b/tests/QueryBuilderTest.php index d819db5cd..e1d0ec7f2 100644 --- a/tests/QueryBuilderTest.php +++ b/tests/QueryBuilderTest.php @@ -38,80 +38,80 @@ class QueryBuilderTest extends TestCase { public function tearDown(): void { - DB::collection('users')->truncate(); - DB::collection('items')->truncate(); + DB::table('users')->truncate(); + DB::table('items')->truncate(); } public function testDeleteWithId() { - $user = DB::collection('users')->insertGetId([ + $user = DB::table('users')->insertGetId([ ['name' => 'Jane Doe', 'age' => 20], ]); $userId = (string) $user; - DB::collection('items')->insert([ + DB::table('items')->insert([ ['name' => 'one thing', 'user_id' => $userId], ['name' => 'last thing', 'user_id' => $userId], ['name' => 'another thing', 'user_id' => $userId], ['name' => 'one more thing', 'user_id' => $userId], ]); - $product = DB::collection('items')->first(); + $product = DB::table('items')->first(); $pid = (string) ($product['_id']); - DB::collection('items')->where('user_id', $userId)->delete($pid); + DB::table('items')->where('user_id', $userId)->delete($pid); - $this->assertEquals(3, DB::collection('items')->count()); + $this->assertEquals(3, DB::table('items')->count()); - $product = DB::collection('items')->first(); + $product = DB::table('items')->first(); $pid = $product['_id']; - DB::collection('items')->where('user_id', $userId)->delete($pid); + DB::table('items')->where('user_id', $userId)->delete($pid); - DB::collection('items')->where('user_id', $userId)->delete(md5('random-id')); + DB::table('items')->where('user_id', $userId)->delete(md5('random-id')); - $this->assertEquals(2, DB::collection('items')->count()); + $this->assertEquals(2, DB::table('items')->count()); } public function testCollection() { - $this->assertInstanceOf(Builder::class, DB::collection('users')); + $this->assertInstanceOf(Builder::class, DB::table('users')); } public function testGet() { - $users = DB::collection('users')->get(); + $users = DB::table('users')->get(); $this->assertCount(0, $users); - DB::collection('users')->insert(['name' => 'John Doe']); + DB::table('users')->insert(['name' => 'John Doe']); - $users = DB::collection('users')->get(); + $users = DB::table('users')->get(); $this->assertCount(1, $users); } public function testNoDocument() { - $items = DB::collection('items')->where('name', 'nothing')->get()->toArray(); + $items = DB::table('items')->where('name', 'nothing')->get()->toArray(); $this->assertEquals([], $items); - $item = DB::collection('items')->where('name', 'nothing')->first(); + $item = DB::table('items')->where('name', 'nothing')->first(); $this->assertNull($item); - $item = DB::collection('items')->where('_id', '51c33d8981fec6813e00000a')->first(); + $item = DB::table('items')->where('_id', '51c33d8981fec6813e00000a')->first(); $this->assertNull($item); } public function testInsert() { - DB::collection('users')->insert([ + DB::table('users')->insert([ 'tags' => ['tag1', 'tag2'], 'name' => 'John Doe', ]); - $users = DB::collection('users')->get(); + $users = DB::table('users')->get(); $this->assertCount(1, $users); $user = $users[0]; @@ -121,13 +121,13 @@ public function testInsert() public function testInsertGetId() { - $id = DB::collection('users')->insertGetId(['name' => 'John Doe']); + $id = DB::table('users')->insertGetId(['name' => 'John Doe']); $this->assertInstanceOf(ObjectId::class, $id); } public function testBatchInsert() { - DB::collection('users')->insert([ + DB::table('users')->insert([ [ 'tags' => ['tag1', 'tag2'], 'name' => 'Jane Doe', @@ -138,22 +138,22 @@ public function testBatchInsert() ], ]); - $users = DB::collection('users')->get(); + $users = DB::table('users')->get(); $this->assertCount(2, $users); $this->assertIsArray($users[0]['tags']); } public function testFind() { - $id = DB::collection('users')->insertGetId(['name' => 'John Doe']); + $id = DB::table('users')->insertGetId(['name' => 'John Doe']); - $user = DB::collection('users')->find($id); + $user = DB::table('users')->find($id); $this->assertEquals('John Doe', $user['name']); } public function testFindWithTimeout() { - $id = DB::collection('users')->insertGetId(['name' => 'John Doe']); + $id = DB::table('users')->insertGetId(['name' => 'John Doe']); $subscriber = new class implements CommandSubscriber { public function commandStarted(CommandStartedEvent $event) @@ -177,7 +177,7 @@ public function commandSucceeded(CommandSucceededEvent $event) DB::getMongoClient()->getManager()->addSubscriber($subscriber); try { - DB::collection('users')->timeout(1)->find($id); + DB::table('users')->timeout(1)->find($id); } finally { DB::getMongoClient()->getManager()->removeSubscriber($subscriber); } @@ -185,49 +185,49 @@ public function commandSucceeded(CommandSucceededEvent $event) public function testFindNull() { - $user = DB::collection('users')->find(null); + $user = DB::table('users')->find(null); $this->assertNull($user); } public function testCount() { - DB::collection('users')->insert([ + DB::table('users')->insert([ ['name' => 'Jane Doe'], ['name' => 'John Doe'], ]); - $this->assertEquals(2, DB::collection('users')->count()); + $this->assertEquals(2, DB::table('users')->count()); } public function testUpdate() { - DB::collection('users')->insert([ + DB::table('users')->insert([ ['name' => 'Jane Doe', 'age' => 20], ['name' => 'John Doe', 'age' => 21], ]); - DB::collection('users')->where('name', 'John Doe')->update(['age' => 100]); + DB::table('users')->where('name', 'John Doe')->update(['age' => 100]); - $john = DB::collection('users')->where('name', 'John Doe')->first(); - $jane = DB::collection('users')->where('name', 'Jane Doe')->first(); + $john = DB::table('users')->where('name', 'John Doe')->first(); + $jane = DB::table('users')->where('name', 'Jane Doe')->first(); $this->assertEquals(100, $john['age']); $this->assertEquals(20, $jane['age']); } public function testUpdateOperators() { - DB::collection('users')->insert([ + DB::table('users')->insert([ ['name' => 'Jane Doe', 'age' => 20], ['name' => 'John Doe', 'age' => 19], ]); - DB::collection('users')->where('name', 'John Doe')->update( + DB::table('users')->where('name', 'John Doe')->update( [ '$unset' => ['age' => 1], 'ageless' => true, ], ); - DB::collection('users')->where('name', 'Jane Doe')->update( + DB::table('users')->where('name', 'Jane Doe')->update( [ '$inc' => ['age' => 1], '$set' => ['pronoun' => 'she'], @@ -235,8 +235,8 @@ public function testUpdateOperators() ], ); - $john = DB::collection('users')->where('name', 'John Doe')->first(); - $jane = DB::collection('users')->where('name', 'Jane Doe')->first(); + $john = DB::table('users')->where('name', 'John Doe')->first(); + $jane = DB::table('users')->where('name', 'Jane Doe')->first(); $this->assertArrayNotHasKey('age', $john); $this->assertTrue($john['ageless']); @@ -248,31 +248,31 @@ public function testUpdateOperators() public function testDelete() { - DB::collection('users')->insert([ + DB::table('users')->insert([ ['name' => 'Jane Doe', 'age' => 20], ['name' => 'John Doe', 'age' => 25], ]); - DB::collection('users')->where('age', '<', 10)->delete(); - $this->assertEquals(2, DB::collection('users')->count()); + DB::table('users')->where('age', '<', 10)->delete(); + $this->assertEquals(2, DB::table('users')->count()); - DB::collection('users')->where('age', '<', 25)->delete(); - $this->assertEquals(1, DB::collection('users')->count()); + DB::table('users')->where('age', '<', 25)->delete(); + $this->assertEquals(1, DB::table('users')->count()); } public function testTruncate() { - DB::collection('users')->insert(['name' => 'John Doe']); - DB::collection('users')->insert(['name' => 'John Doe']); - $this->assertEquals(2, DB::collection('users')->count()); - $result = DB::collection('users')->truncate(); + DB::table('users')->insert(['name' => 'John Doe']); + DB::table('users')->insert(['name' => 'John Doe']); + $this->assertEquals(2, DB::table('users')->count()); + $result = DB::table('users')->truncate(); $this->assertTrue($result); - $this->assertEquals(0, DB::collection('users')->count()); + $this->assertEquals(0, DB::table('users')->count()); } public function testSubKey() { - DB::collection('users')->insert([ + DB::table('users')->insert([ [ 'name' => 'John Doe', 'address' => ['country' => 'Belgium', 'city' => 'Ghent'], @@ -283,14 +283,14 @@ public function testSubKey() ], ]); - $users = DB::collection('users')->where('address.country', 'Belgium')->get(); + $users = DB::table('users')->where('address.country', 'Belgium')->get(); $this->assertCount(1, $users); $this->assertEquals('John Doe', $users[0]['name']); } public function testInArray() { - DB::collection('items')->insert([ + DB::table('items')->insert([ [ 'tags' => ['tag1', 'tag2', 'tag3', 'tag4'], ], @@ -299,91 +299,91 @@ public function testInArray() ], ]); - $items = DB::collection('items')->where('tags', 'tag2')->get(); + $items = DB::table('items')->where('tags', 'tag2')->get(); $this->assertCount(2, $items); - $items = DB::collection('items')->where('tags', 'tag1')->get(); + $items = DB::table('items')->where('tags', 'tag1')->get(); $this->assertCount(1, $items); } public function testRaw() { - DB::collection('users')->insert([ + DB::table('users')->insert([ ['name' => 'Jane Doe', 'age' => 20], ['name' => 'John Doe', 'age' => 25], ]); - $cursor = DB::collection('users')->raw(function ($collection) { + $cursor = DB::table('users')->raw(function ($collection) { return $collection->find(['age' => 20]); }); $this->assertInstanceOf(Cursor::class, $cursor); $this->assertCount(1, $cursor->toArray()); - $collection = DB::collection('users')->raw(); + $collection = DB::table('users')->raw(); $this->assertInstanceOf(Collection::class, $collection); $collection = User::raw(); $this->assertInstanceOf(Collection::class, $collection); - $results = DB::collection('users')->whereRaw(['age' => 20])->get(); + $results = DB::table('users')->whereRaw(['age' => 20])->get(); $this->assertCount(1, $results); $this->assertEquals('Jane Doe', $results[0]['name']); } public function testPush() { - $id = DB::collection('users')->insertGetId([ + $id = DB::table('users')->insertGetId([ 'name' => 'John Doe', 'tags' => [], 'messages' => [], ]); - DB::collection('users')->where('_id', $id)->push('tags', 'tag1'); + DB::table('users')->where('_id', $id)->push('tags', 'tag1'); - $user = DB::collection('users')->find($id); + $user = DB::table('users')->find($id); $this->assertIsArray($user['tags']); $this->assertCount(1, $user['tags']); $this->assertEquals('tag1', $user['tags'][0]); - DB::collection('users')->where('_id', $id)->push('tags', 'tag2'); - $user = DB::collection('users')->find($id); + DB::table('users')->where('_id', $id)->push('tags', 'tag2'); + $user = DB::table('users')->find($id); $this->assertCount(2, $user['tags']); $this->assertEquals('tag2', $user['tags'][1]); // Add duplicate - DB::collection('users')->where('_id', $id)->push('tags', 'tag2'); - $user = DB::collection('users')->find($id); + DB::table('users')->where('_id', $id)->push('tags', 'tag2'); + $user = DB::table('users')->find($id); $this->assertCount(3, $user['tags']); // Add unique - DB::collection('users')->where('_id', $id)->push('tags', 'tag1', true); - $user = DB::collection('users')->find($id); + DB::table('users')->where('_id', $id)->push('tags', 'tag1', true); + $user = DB::table('users')->find($id); $this->assertCount(3, $user['tags']); $message = ['from' => 'Jane', 'body' => 'Hi John']; - DB::collection('users')->where('_id', $id)->push('messages', $message); - $user = DB::collection('users')->find($id); + DB::table('users')->where('_id', $id)->push('messages', $message); + $user = DB::table('users')->find($id); $this->assertIsArray($user['messages']); $this->assertCount(1, $user['messages']); $this->assertEquals($message, $user['messages'][0]); // Raw - DB::collection('users')->where('_id', $id)->push([ + DB::table('users')->where('_id', $id)->push([ 'tags' => 'tag3', 'messages' => ['from' => 'Mark', 'body' => 'Hi John'], ]); - $user = DB::collection('users')->find($id); + $user = DB::table('users')->find($id); $this->assertCount(4, $user['tags']); $this->assertCount(2, $user['messages']); - DB::collection('users')->where('_id', $id)->push([ + DB::table('users')->where('_id', $id)->push([ 'messages' => [ 'date' => new DateTime(), 'body' => 'Hi John', ], ]); - $user = DB::collection('users')->find($id); + $user = DB::table('users')->find($id); $this->assertCount(3, $user['messages']); } @@ -392,7 +392,7 @@ public function testPushRefuses2ndArgumentWhen1stIsAnArray() $this->expectException(InvalidArgumentException::class); $this->expectExceptionMessage('2nd argument of MongoDB\Laravel\Query\Builder::push() must be "null" when 1st argument is an array. Got "string" instead.'); - DB::collection('users')->push(['tags' => 'tag1'], 'tag2'); + DB::table('users')->push(['tags' => 'tag1'], 'tag2'); } public function testPull() @@ -400,47 +400,47 @@ public function testPull() $message1 = ['from' => 'Jane', 'body' => 'Hi John']; $message2 = ['from' => 'Mark', 'body' => 'Hi John']; - $id = DB::collection('users')->insertGetId([ + $id = DB::table('users')->insertGetId([ 'name' => 'John Doe', 'tags' => ['tag1', 'tag2', 'tag3', 'tag4'], 'messages' => [$message1, $message2], ]); - DB::collection('users')->where('_id', $id)->pull('tags', 'tag3'); + DB::table('users')->where('_id', $id)->pull('tags', 'tag3'); - $user = DB::collection('users')->find($id); + $user = DB::table('users')->find($id); $this->assertIsArray($user['tags']); $this->assertCount(3, $user['tags']); $this->assertEquals('tag4', $user['tags'][2]); - DB::collection('users')->where('_id', $id)->pull('messages', $message1); + DB::table('users')->where('_id', $id)->pull('messages', $message1); - $user = DB::collection('users')->find($id); + $user = DB::table('users')->find($id); $this->assertIsArray($user['messages']); $this->assertCount(1, $user['messages']); // Raw - DB::collection('users')->where('_id', $id)->pull(['tags' => 'tag2', 'messages' => $message2]); - $user = DB::collection('users')->find($id); + DB::table('users')->where('_id', $id)->pull(['tags' => 'tag2', 'messages' => $message2]); + $user = DB::table('users')->find($id); $this->assertCount(2, $user['tags']); $this->assertCount(0, $user['messages']); } public function testDistinct() { - DB::collection('items')->insert([ + DB::table('items')->insert([ ['name' => 'knife', 'type' => 'sharp'], ['name' => 'fork', 'type' => 'sharp'], ['name' => 'spoon', 'type' => 'round'], ['name' => 'spoon', 'type' => 'round'], ]); - $items = DB::collection('items')->distinct('name')->get()->toArray(); + $items = DB::table('items')->distinct('name')->get()->toArray(); sort($items); $this->assertCount(3, $items); $this->assertEquals(['fork', 'knife', 'spoon'], $items); - $types = DB::collection('items')->distinct('type')->get()->toArray(); + $types = DB::table('items')->distinct('type')->get()->toArray(); sort($types); $this->assertCount(2, $types); $this->assertEquals(['round', 'sharp'], $types); @@ -448,127 +448,127 @@ public function testDistinct() public function testCustomId() { - DB::collection('items')->insert([ + DB::table('items')->insert([ ['_id' => 'knife', 'type' => 'sharp', 'amount' => 34], ['_id' => 'fork', 'type' => 'sharp', 'amount' => 20], ['_id' => 'spoon', 'type' => 'round', 'amount' => 3], ]); - $item = DB::collection('items')->find('knife'); + $item = DB::table('items')->find('knife'); $this->assertEquals('knife', $item['_id']); - $item = DB::collection('items')->where('_id', 'fork')->first(); + $item = DB::table('items')->where('_id', 'fork')->first(); $this->assertEquals('fork', $item['_id']); - DB::collection('users')->insert([ + DB::table('users')->insert([ ['_id' => 1, 'name' => 'Jane Doe'], ['_id' => 2, 'name' => 'John Doe'], ]); - $item = DB::collection('users')->find(1); + $item = DB::table('users')->find(1); $this->assertEquals(1, $item['_id']); } public function testTake() { - DB::collection('items')->insert([ + DB::table('items')->insert([ ['name' => 'knife', 'type' => 'sharp', 'amount' => 34], ['name' => 'fork', 'type' => 'sharp', 'amount' => 20], ['name' => 'spoon', 'type' => 'round', 'amount' => 3], ['name' => 'spoon', 'type' => 'round', 'amount' => 14], ]); - $items = DB::collection('items')->orderBy('name')->take(2)->get(); + $items = DB::table('items')->orderBy('name')->take(2)->get(); $this->assertCount(2, $items); $this->assertEquals('fork', $items[0]['name']); } public function testSkip() { - DB::collection('items')->insert([ + DB::table('items')->insert([ ['name' => 'knife', 'type' => 'sharp', 'amount' => 34], ['name' => 'fork', 'type' => 'sharp', 'amount' => 20], ['name' => 'spoon', 'type' => 'round', 'amount' => 3], ['name' => 'spoon', 'type' => 'round', 'amount' => 14], ]); - $items = DB::collection('items')->orderBy('name')->skip(2)->get(); + $items = DB::table('items')->orderBy('name')->skip(2)->get(); $this->assertCount(2, $items); $this->assertEquals('spoon', $items[0]['name']); } public function testPluck() { - DB::collection('users')->insert([ + DB::table('users')->insert([ ['name' => 'Jane Doe', 'age' => 20], ['name' => 'John Doe', 'age' => 25], ]); - $age = DB::collection('users')->where('name', 'John Doe')->pluck('age')->toArray(); + $age = DB::table('users')->where('name', 'John Doe')->pluck('age')->toArray(); $this->assertEquals([25], $age); } public function testList() { - DB::collection('items')->insert([ + DB::table('items')->insert([ ['name' => 'knife', 'type' => 'sharp', 'amount' => 34], ['name' => 'fork', 'type' => 'sharp', 'amount' => 20], ['name' => 'spoon', 'type' => 'round', 'amount' => 3], ['name' => 'spoon', 'type' => 'round', 'amount' => 14], ]); - $list = DB::collection('items')->pluck('name')->toArray(); + $list = DB::table('items')->pluck('name')->toArray(); sort($list); $this->assertCount(4, $list); $this->assertEquals(['fork', 'knife', 'spoon', 'spoon'], $list); - $list = DB::collection('items')->pluck('type', 'name')->toArray(); + $list = DB::table('items')->pluck('type', 'name')->toArray(); $this->assertCount(3, $list); $this->assertEquals(['knife' => 'sharp', 'fork' => 'sharp', 'spoon' => 'round'], $list); - $list = DB::collection('items')->pluck('name', '_id')->toArray(); + $list = DB::table('items')->pluck('name', '_id')->toArray(); $this->assertCount(4, $list); $this->assertEquals(24, strlen(key($list))); } public function testAggregate() { - DB::collection('items')->insert([ + DB::table('items')->insert([ ['name' => 'knife', 'type' => 'sharp', 'amount' => 34], ['name' => 'fork', 'type' => 'sharp', 'amount' => 20], ['name' => 'spoon', 'type' => 'round', 'amount' => 3], ['name' => 'spoon', 'type' => 'round', 'amount' => 14], ]); - $this->assertEquals(71, DB::collection('items')->sum('amount')); - $this->assertEquals(4, DB::collection('items')->count('amount')); - $this->assertEquals(3, DB::collection('items')->min('amount')); - $this->assertEquals(34, DB::collection('items')->max('amount')); - $this->assertEquals(17.75, DB::collection('items')->avg('amount')); + $this->assertEquals(71, DB::table('items')->sum('amount')); + $this->assertEquals(4, DB::table('items')->count('amount')); + $this->assertEquals(3, DB::table('items')->min('amount')); + $this->assertEquals(34, DB::table('items')->max('amount')); + $this->assertEquals(17.75, DB::table('items')->avg('amount')); - $this->assertEquals(2, DB::collection('items')->where('name', 'spoon')->count('amount')); - $this->assertEquals(14, DB::collection('items')->where('name', 'spoon')->max('amount')); + $this->assertEquals(2, DB::table('items')->where('name', 'spoon')->count('amount')); + $this->assertEquals(14, DB::table('items')->where('name', 'spoon')->max('amount')); } public function testSubdocumentAggregate() { - DB::collection('items')->insert([ + DB::table('items')->insert([ ['name' => 'knife', 'amount' => ['hidden' => 10, 'found' => 3]], ['name' => 'fork', 'amount' => ['hidden' => 35, 'found' => 12]], ['name' => 'spoon', 'amount' => ['hidden' => 14, 'found' => 21]], ['name' => 'spoon', 'amount' => ['hidden' => 6, 'found' => 4]], ]); - $this->assertEquals(65, DB::collection('items')->sum('amount.hidden')); - $this->assertEquals(4, DB::collection('items')->count('amount.hidden')); - $this->assertEquals(6, DB::collection('items')->min('amount.hidden')); - $this->assertEquals(35, DB::collection('items')->max('amount.hidden')); - $this->assertEquals(16.25, DB::collection('items')->avg('amount.hidden')); + $this->assertEquals(65, DB::table('items')->sum('amount.hidden')); + $this->assertEquals(4, DB::table('items')->count('amount.hidden')); + $this->assertEquals(6, DB::table('items')->min('amount.hidden')); + $this->assertEquals(35, DB::table('items')->max('amount.hidden')); + $this->assertEquals(16.25, DB::table('items')->avg('amount.hidden')); } public function testSubdocumentArrayAggregate() { - DB::collection('items')->insert([ + DB::table('items')->insert([ ['name' => 'knife', 'amount' => [['hidden' => 10, 'found' => 3], ['hidden' => 5, 'found' => 2]]], [ 'name' => 'fork', @@ -582,22 +582,22 @@ public function testSubdocumentArrayAggregate() ['name' => 'teaspoon', 'amount' => []], ]); - $this->assertEquals(72, DB::collection('items')->sum('amount.*.hidden')); - $this->assertEquals(6, DB::collection('items')->count('amount.*.hidden')); - $this->assertEquals(1, DB::collection('items')->min('amount.*.hidden')); - $this->assertEquals(35, DB::collection('items')->max('amount.*.hidden')); - $this->assertEquals(12, DB::collection('items')->avg('amount.*.hidden')); + $this->assertEquals(72, DB::table('items')->sum('amount.*.hidden')); + $this->assertEquals(6, DB::table('items')->count('amount.*.hidden')); + $this->assertEquals(1, DB::table('items')->min('amount.*.hidden')); + $this->assertEquals(35, DB::table('items')->max('amount.*.hidden')); + $this->assertEquals(12, DB::table('items')->avg('amount.*.hidden')); } public function testUpdateWithUpsert() { - DB::collection('items')->where('name', 'knife') + DB::table('items')->where('name', 'knife') ->update( ['amount' => 1], ['upsert' => true], ); - $this->assertEquals(1, DB::collection('items')->count()); + $this->assertEquals(1, DB::table('items')->count()); Item::where('name', 'spoon') ->update( @@ -605,123 +605,123 @@ public function testUpdateWithUpsert() ['upsert' => true], ); - $this->assertEquals(2, DB::collection('items')->count()); + $this->assertEquals(2, DB::table('items')->count()); } public function testUpsert() { /** @see DatabaseQueryBuilderTest::testUpsertMethod() */ // Insert 2 documents - $result = DB::collection('users')->upsert([ + $result = DB::table('users')->upsert([ ['email' => 'foo', 'name' => 'bar'], ['name' => 'bar2', 'email' => 'foo2'], ], 'email', 'name'); $this->assertSame(2, $result); - $this->assertSame(2, DB::collection('users')->count()); - $this->assertSame('bar', DB::collection('users')->where('email', 'foo')->first()['name']); + $this->assertSame(2, DB::table('users')->count()); + $this->assertSame('bar', DB::table('users')->where('email', 'foo')->first()['name']); // Update 1 document - $result = DB::collection('users')->upsert([ + $result = DB::table('users')->upsert([ ['email' => 'foo', 'name' => 'bar2'], ['name' => 'bar2', 'email' => 'foo2'], ], 'email', 'name'); $this->assertSame(1, $result); - $this->assertSame(2, DB::collection('users')->count()); - $this->assertSame('bar2', DB::collection('users')->where('email', 'foo')->first()['name']); + $this->assertSame(2, DB::table('users')->count()); + $this->assertSame('bar2', DB::table('users')->where('email', 'foo')->first()['name']); // If no update fields are specified, all fields are updated - $result = DB::collection('users')->upsert([ + $result = DB::table('users')->upsert([ ['email' => 'foo', 'name' => 'bar3'], ], 'email'); $this->assertSame(1, $result); - $this->assertSame(2, DB::collection('users')->count()); - $this->assertSame('bar3', DB::collection('users')->where('email', 'foo')->first()['name']); + $this->assertSame(2, DB::table('users')->count()); + $this->assertSame('bar3', DB::table('users')->where('email', 'foo')->first()['name']); } public function testUnset() { - $id1 = DB::collection('users')->insertGetId(['name' => 'John Doe', 'note1' => 'ABC', 'note2' => 'DEF']); - $id2 = DB::collection('users')->insertGetId(['name' => 'Jane Doe', 'note1' => 'ABC', 'note2' => 'DEF']); + $id1 = DB::table('users')->insertGetId(['name' => 'John Doe', 'note1' => 'ABC', 'note2' => 'DEF']); + $id2 = DB::table('users')->insertGetId(['name' => 'Jane Doe', 'note1' => 'ABC', 'note2' => 'DEF']); - DB::collection('users')->where('name', 'John Doe')->unset('note1'); + DB::table('users')->where('name', 'John Doe')->unset('note1'); - $user1 = DB::collection('users')->find($id1); - $user2 = DB::collection('users')->find($id2); + $user1 = DB::table('users')->find($id1); + $user2 = DB::table('users')->find($id2); $this->assertArrayNotHasKey('note1', $user1); $this->assertArrayHasKey('note2', $user1); $this->assertArrayHasKey('note1', $user2); $this->assertArrayHasKey('note2', $user2); - DB::collection('users')->where('name', 'Jane Doe')->unset(['note1', 'note2']); + DB::table('users')->where('name', 'Jane Doe')->unset(['note1', 'note2']); - $user2 = DB::collection('users')->find($id2); + $user2 = DB::table('users')->find($id2); $this->assertArrayNotHasKey('note1', $user2); $this->assertArrayNotHasKey('note2', $user2); } public function testUpdateSubdocument() { - $id = DB::collection('users')->insertGetId(['name' => 'John Doe', 'address' => ['country' => 'Belgium']]); + $id = DB::table('users')->insertGetId(['name' => 'John Doe', 'address' => ['country' => 'Belgium']]); - DB::collection('users')->where('_id', $id)->update(['address.country' => 'England']); + DB::table('users')->where('_id', $id)->update(['address.country' => 'England']); - $check = DB::collection('users')->find($id); + $check = DB::table('users')->find($id); $this->assertEquals('England', $check['address']['country']); } public function testDates() { - DB::collection('users')->insert([ + DB::table('users')->insert([ ['name' => 'John Doe', 'birthday' => new UTCDateTime(Date::parse('1980-01-01 00:00:00'))], ['name' => 'Robert Roe', 'birthday' => new UTCDateTime(Date::parse('1982-01-01 00:00:00'))], ['name' => 'Mark Moe', 'birthday' => new UTCDateTime(Date::parse('1983-01-01 00:00:00.1'))], ['name' => 'Frank White', 'birthday' => new UTCDateTime(Date::parse('1960-01-01 12:12:12.1'))], ]); - $user = DB::collection('users') + $user = DB::table('users') ->where('birthday', new UTCDateTime(Date::parse('1980-01-01 00:00:00'))) ->first(); $this->assertEquals('John Doe', $user['name']); - $user = DB::collection('users') + $user = DB::table('users') ->where('birthday', new UTCDateTime(Date::parse('1960-01-01 12:12:12.1'))) ->first(); $this->assertEquals('Frank White', $user['name']); - $user = DB::collection('users')->where('birthday', '=', new DateTime('1980-01-01 00:00:00'))->first(); + $user = DB::table('users')->where('birthday', '=', new DateTime('1980-01-01 00:00:00'))->first(); $this->assertEquals('John Doe', $user['name']); $start = new UTCDateTime(1000 * strtotime('1950-01-01 00:00:00')); $stop = new UTCDateTime(1000 * strtotime('1981-01-01 00:00:00')); - $users = DB::collection('users')->whereBetween('birthday', [$start, $stop])->get(); + $users = DB::table('users')->whereBetween('birthday', [$start, $stop])->get(); $this->assertCount(2, $users); } public function testImmutableDates() { - DB::collection('users')->insert([ + DB::table('users')->insert([ ['name' => 'John Doe', 'birthday' => new UTCDateTime(Date::parse('1980-01-01 00:00:00'))], ['name' => 'Robert Roe', 'birthday' => new UTCDateTime(Date::parse('1982-01-01 00:00:00'))], ]); - $users = DB::collection('users')->where('birthday', '=', new DateTimeImmutable('1980-01-01 00:00:00'))->get(); + $users = DB::table('users')->where('birthday', '=', new DateTimeImmutable('1980-01-01 00:00:00'))->get(); $this->assertCount(1, $users); - $users = DB::collection('users')->where('birthday', new DateTimeImmutable('1980-01-01 00:00:00'))->get(); + $users = DB::table('users')->where('birthday', new DateTimeImmutable('1980-01-01 00:00:00'))->get(); $this->assertCount(1, $users); - $users = DB::collection('users')->whereIn('birthday', [ + $users = DB::table('users')->whereIn('birthday', [ new DateTimeImmutable('1980-01-01 00:00:00'), new DateTimeImmutable('1982-01-01 00:00:00'), ])->get(); $this->assertCount(2, $users); - $users = DB::collection('users')->whereBetween('birthday', [ + $users = DB::table('users')->whereBetween('birthday', [ new DateTimeImmutable('1979-01-01 00:00:00'), new DateTimeImmutable('1983-01-01 00:00:00'), ])->get(); @@ -731,79 +731,79 @@ public function testImmutableDates() public function testOperators() { - DB::collection('users')->insert([ + DB::table('users')->insert([ ['name' => 'John Doe', 'age' => 30], ['name' => 'Jane Doe'], ['name' => 'Robert Roe', 'age' => 'thirty-one'], ]); - $results = DB::collection('users')->where('age', 'exists', true)->get(); + $results = DB::table('users')->where('age', 'exists', true)->get(); $this->assertCount(2, $results); $resultsNames = [$results[0]['name'], $results[1]['name']]; $this->assertContains('John Doe', $resultsNames); $this->assertContains('Robert Roe', $resultsNames); - $results = DB::collection('users')->where('age', 'exists', false)->get(); + $results = DB::table('users')->where('age', 'exists', false)->get(); $this->assertCount(1, $results); $this->assertEquals('Jane Doe', $results[0]['name']); - $results = DB::collection('users')->where('age', 'type', 2)->get(); + $results = DB::table('users')->where('age', 'type', 2)->get(); $this->assertCount(1, $results); $this->assertEquals('Robert Roe', $results[0]['name']); - $results = DB::collection('users')->where('age', 'mod', [15, 0])->get(); + $results = DB::table('users')->where('age', 'mod', [15, 0])->get(); $this->assertCount(1, $results); $this->assertEquals('John Doe', $results[0]['name']); - $results = DB::collection('users')->where('age', 'mod', [29, 1])->get(); + $results = DB::table('users')->where('age', 'mod', [29, 1])->get(); $this->assertCount(1, $results); $this->assertEquals('John Doe', $results[0]['name']); - $results = DB::collection('users')->where('age', 'mod', [14, 0])->get(); + $results = DB::table('users')->where('age', 'mod', [14, 0])->get(); $this->assertCount(0, $results); - DB::collection('items')->insert([ + DB::table('items')->insert([ ['name' => 'fork', 'tags' => ['sharp', 'pointy']], ['name' => 'spork', 'tags' => ['sharp', 'pointy', 'round', 'bowl']], ['name' => 'spoon', 'tags' => ['round', 'bowl']], ]); - $results = DB::collection('items')->where('tags', 'all', ['sharp', 'pointy'])->get(); + $results = DB::table('items')->where('tags', 'all', ['sharp', 'pointy'])->get(); $this->assertCount(2, $results); - $results = DB::collection('items')->where('tags', 'all', ['sharp', 'round'])->get(); + $results = DB::table('items')->where('tags', 'all', ['sharp', 'round'])->get(); $this->assertCount(1, $results); - $results = DB::collection('items')->where('tags', 'size', 2)->get(); + $results = DB::table('items')->where('tags', 'size', 2)->get(); $this->assertCount(2, $results); - $results = DB::collection('items')->where('tags', '$size', 2)->get(); + $results = DB::table('items')->where('tags', '$size', 2)->get(); $this->assertCount(2, $results); - $results = DB::collection('items')->where('tags', 'size', 3)->get(); + $results = DB::table('items')->where('tags', 'size', 3)->get(); $this->assertCount(0, $results); - $results = DB::collection('items')->where('tags', 'size', 4)->get(); + $results = DB::table('items')->where('tags', 'size', 4)->get(); $this->assertCount(1, $results); $regex = new Regex('.*doe', 'i'); - $results = DB::collection('users')->where('name', 'regex', $regex)->get(); + $results = DB::table('users')->where('name', 'regex', $regex)->get(); $this->assertCount(2, $results); $regex = new Regex('.*doe', 'i'); - $results = DB::collection('users')->where('name', 'regexp', $regex)->get(); + $results = DB::table('users')->where('name', 'regexp', $regex)->get(); $this->assertCount(2, $results); - $results = DB::collection('users')->where('name', 'REGEX', $regex)->get(); + $results = DB::table('users')->where('name', 'REGEX', $regex)->get(); $this->assertCount(2, $results); - $results = DB::collection('users')->where('name', 'regexp', '/.*doe/i')->get(); + $results = DB::table('users')->where('name', 'regexp', '/.*doe/i')->get(); $this->assertCount(2, $results); - $results = DB::collection('users')->where('name', 'not regexp', '/.*doe/i')->get(); + $results = DB::table('users')->where('name', 'not regexp', '/.*doe/i')->get(); $this->assertCount(1, $results); - DB::collection('users')->insert([ + DB::table('users')->insert([ [ 'name' => 'John Doe', 'addresses' => [ @@ -820,69 +820,69 @@ public function testOperators() ], ]); - $users = DB::collection('users')->where('addresses', 'elemMatch', ['city' => 'Brussels'])->get(); + $users = DB::table('users')->where('addresses', 'elemMatch', ['city' => 'Brussels'])->get(); $this->assertCount(1, $users); $this->assertEquals('Jane Doe', $users[0]['name']); } public function testIncrement() { - DB::collection('users')->insert([ + DB::table('users')->insert([ ['name' => 'John Doe', 'age' => 30, 'note' => 'adult'], ['name' => 'Jane Doe', 'age' => 10, 'note' => 'minor'], ['name' => 'Robert Roe', 'age' => null], ['name' => 'Mark Moe'], ]); - $user = DB::collection('users')->where('name', 'John Doe')->first(); + $user = DB::table('users')->where('name', 'John Doe')->first(); $this->assertEquals(30, $user['age']); - DB::collection('users')->where('name', 'John Doe')->increment('age'); - $user = DB::collection('users')->where('name', 'John Doe')->first(); + DB::table('users')->where('name', 'John Doe')->increment('age'); + $user = DB::table('users')->where('name', 'John Doe')->first(); $this->assertEquals(31, $user['age']); - DB::collection('users')->where('name', 'John Doe')->decrement('age'); - $user = DB::collection('users')->where('name', 'John Doe')->first(); + DB::table('users')->where('name', 'John Doe')->decrement('age'); + $user = DB::table('users')->where('name', 'John Doe')->first(); $this->assertEquals(30, $user['age']); - DB::collection('users')->where('name', 'John Doe')->increment('age', 5); - $user = DB::collection('users')->where('name', 'John Doe')->first(); + DB::table('users')->where('name', 'John Doe')->increment('age', 5); + $user = DB::table('users')->where('name', 'John Doe')->first(); $this->assertEquals(35, $user['age']); - DB::collection('users')->where('name', 'John Doe')->decrement('age', 5); - $user = DB::collection('users')->where('name', 'John Doe')->first(); + DB::table('users')->where('name', 'John Doe')->decrement('age', 5); + $user = DB::table('users')->where('name', 'John Doe')->first(); $this->assertEquals(30, $user['age']); - DB::collection('users')->where('name', 'Jane Doe')->increment('age', 10, ['note' => 'adult']); - $user = DB::collection('users')->where('name', 'Jane Doe')->first(); + DB::table('users')->where('name', 'Jane Doe')->increment('age', 10, ['note' => 'adult']); + $user = DB::table('users')->where('name', 'Jane Doe')->first(); $this->assertEquals(20, $user['age']); $this->assertEquals('adult', $user['note']); - DB::collection('users')->where('name', 'John Doe')->decrement('age', 20, ['note' => 'minor']); - $user = DB::collection('users')->where('name', 'John Doe')->first(); + DB::table('users')->where('name', 'John Doe')->decrement('age', 20, ['note' => 'minor']); + $user = DB::table('users')->where('name', 'John Doe')->first(); $this->assertEquals(10, $user['age']); $this->assertEquals('minor', $user['note']); - DB::collection('users')->increment('age'); - $user = DB::collection('users')->where('name', 'John Doe')->first(); + DB::table('users')->increment('age'); + $user = DB::table('users')->where('name', 'John Doe')->first(); $this->assertEquals(11, $user['age']); - $user = DB::collection('users')->where('name', 'Jane Doe')->first(); + $user = DB::table('users')->where('name', 'Jane Doe')->first(); $this->assertEquals(21, $user['age']); - $user = DB::collection('users')->where('name', 'Robert Roe')->first(); + $user = DB::table('users')->where('name', 'Robert Roe')->first(); $this->assertNull($user['age']); - $user = DB::collection('users')->where('name', 'Mark Moe')->first(); + $user = DB::table('users')->where('name', 'Mark Moe')->first(); $this->assertEquals(1, $user['age']); } public function testProjections() { - DB::collection('items')->insert([ + DB::table('items')->insert([ ['name' => 'fork', 'tags' => ['sharp', 'pointy']], ['name' => 'spork', 'tags' => ['sharp', 'pointy', 'round', 'bowl']], ['name' => 'spoon', 'tags' => ['round', 'bowl']], ]); - $results = DB::collection('items')->project(['tags' => ['$slice' => 1]])->get(); + $results = DB::table('items')->project(['tags' => ['$slice' => 1]])->get(); foreach ($results as $result) { $this->assertEquals(1, count($result['tags'])); @@ -891,32 +891,32 @@ public function testProjections() public function testValue() { - DB::collection('books')->insert([ + DB::table('books')->insert([ ['title' => 'Moby-Dick', 'author' => ['first_name' => 'Herman', 'last_name' => 'Melville']], ]); - $this->assertEquals('Moby-Dick', DB::collection('books')->value('title')); - $this->assertEquals(['first_name' => 'Herman', 'last_name' => 'Melville'], DB::collection('books') + $this->assertEquals('Moby-Dick', DB::table('books')->value('title')); + $this->assertEquals(['first_name' => 'Herman', 'last_name' => 'Melville'], DB::table('books') ->value('author')); - $this->assertEquals('Herman', DB::collection('books')->value('author.first_name')); - $this->assertEquals('Melville', DB::collection('books')->value('author.last_name')); + $this->assertEquals('Herman', DB::table('books')->value('author.first_name')); + $this->assertEquals('Melville', DB::table('books')->value('author.last_name')); } public function testHintOptions() { - DB::collection('items')->insert([ + DB::table('items')->insert([ ['name' => 'fork', 'tags' => ['sharp', 'pointy']], ['name' => 'spork', 'tags' => ['sharp', 'pointy', 'round', 'bowl']], ['name' => 'spoon', 'tags' => ['round', 'bowl']], ]); - $results = DB::collection('items')->hint(['$natural' => -1])->get(); + $results = DB::table('items')->hint(['$natural' => -1])->get(); $this->assertEquals('spoon', $results[0]['name']); $this->assertEquals('spork', $results[1]['name']); $this->assertEquals('fork', $results[2]['name']); - $results = DB::collection('items')->hint(['$natural' => 1])->get(); + $results = DB::table('items')->hint(['$natural' => 1])->get(); $this->assertEquals('spoon', $results[2]['name']); $this->assertEquals('spork', $results[1]['name']); @@ -930,9 +930,9 @@ public function testCursor() ['name' => 'spork', 'tags' => ['sharp', 'pointy', 'round', 'bowl']], ['name' => 'spoon', 'tags' => ['round', 'bowl']], ]; - DB::collection('items')->insert($data); + DB::table('items')->insert($data); - $results = DB::collection('items')->orderBy('_id', 'asc')->cursor(); + $results = DB::table('items')->orderBy('_id', 'asc')->cursor(); $this->assertInstanceOf(LazyCollection::class, $results); foreach ($results as $i => $result) { @@ -942,7 +942,7 @@ public function testCursor() public function testStringableColumn() { - DB::collection('users')->insert([ + DB::table('users')->insert([ ['name' => 'Jane Doe', 'age' => 36, 'birthday' => new UTCDateTime(new DateTime('1987-01-01 00:00:00'))], ['name' => 'John Doe', 'age' => 28, 'birthday' => new UTCDateTime(new DateTime('1995-01-01 00:00:00'))], ]); @@ -950,100 +950,100 @@ public function testStringableColumn() $nameColumn = Str::of('name'); $this->assertInstanceOf(Stringable::class, $nameColumn, 'Ensure we are testing the feature with a Stringable instance'); - $user = DB::collection('users')->where($nameColumn, 'John Doe')->first(); + $user = DB::table('users')->where($nameColumn, 'John Doe')->first(); $this->assertEquals('John Doe', $user['name']); // Test this other document to be sure this is not a random success to data order - $user = DB::collection('users')->where($nameColumn, 'Jane Doe')->orderBy('natural')->first(); + $user = DB::table('users')->where($nameColumn, 'Jane Doe')->orderBy('natural')->first(); $this->assertEquals('Jane Doe', $user['name']); // With an operator - $user = DB::collection('users')->where($nameColumn, '!=', 'Jane Doe')->first(); + $user = DB::table('users')->where($nameColumn, '!=', 'Jane Doe')->first(); $this->assertEquals('John Doe', $user['name']); // whereIn and whereNotIn - $user = DB::collection('users')->whereIn($nameColumn, ['John Doe'])->first(); + $user = DB::table('users')->whereIn($nameColumn, ['John Doe'])->first(); $this->assertEquals('John Doe', $user['name']); - $user = DB::collection('users')->whereNotIn($nameColumn, ['John Doe'])->first(); + $user = DB::table('users')->whereNotIn($nameColumn, ['John Doe'])->first(); $this->assertEquals('Jane Doe', $user['name']); $ageColumn = Str::of('age'); // whereBetween and whereNotBetween - $user = DB::collection('users')->whereBetween($ageColumn, [30, 40])->first(); + $user = DB::table('users')->whereBetween($ageColumn, [30, 40])->first(); $this->assertEquals('Jane Doe', $user['name']); // whereBetween and whereNotBetween - $user = DB::collection('users')->whereNotBetween($ageColumn, [30, 40])->first(); + $user = DB::table('users')->whereNotBetween($ageColumn, [30, 40])->first(); $this->assertEquals('John Doe', $user['name']); $birthdayColumn = Str::of('birthday'); // whereDate - $user = DB::collection('users')->whereDate($birthdayColumn, '1995-01-01')->first(); + $user = DB::table('users')->whereDate($birthdayColumn, '1995-01-01')->first(); $this->assertEquals('John Doe', $user['name']); - $user = DB::collection('users')->whereDate($birthdayColumn, '<', '1990-01-01') + $user = DB::table('users')->whereDate($birthdayColumn, '<', '1990-01-01') ->orderBy($birthdayColumn, 'desc')->first(); $this->assertEquals('Jane Doe', $user['name']); - $user = DB::collection('users')->whereDate($birthdayColumn, '>', '1990-01-01') + $user = DB::table('users')->whereDate($birthdayColumn, '>', '1990-01-01') ->orderBy($birthdayColumn, 'asc')->first(); $this->assertEquals('John Doe', $user['name']); - $user = DB::collection('users')->whereDate($birthdayColumn, '!=', '1987-01-01')->first(); + $user = DB::table('users')->whereDate($birthdayColumn, '!=', '1987-01-01')->first(); $this->assertEquals('John Doe', $user['name']); // increment - DB::collection('users')->where($ageColumn, 28)->increment($ageColumn, 1); - $user = DB::collection('users')->where($ageColumn, 29)->first(); + DB::table('users')->where($ageColumn, 28)->increment($ageColumn, 1); + $user = DB::table('users')->where($ageColumn, 29)->first(); $this->assertEquals('John Doe', $user['name']); } public function testIncrementEach() { - DB::collection('users')->insert([ + DB::table('users')->insert([ ['name' => 'John Doe', 'age' => 30, 'note' => 5], ['name' => 'Jane Doe', 'age' => 10, 'note' => 6], ['name' => 'Robert Roe', 'age' => null], ]); - DB::collection('users')->incrementEach([ + DB::table('users')->incrementEach([ 'age' => 1, 'note' => 2, ]); - $user = DB::collection('users')->where('name', 'John Doe')->first(); + $user = DB::table('users')->where('name', 'John Doe')->first(); $this->assertEquals(31, $user['age']); $this->assertEquals(7, $user['note']); - $user = DB::collection('users')->where('name', 'Jane Doe')->first(); + $user = DB::table('users')->where('name', 'Jane Doe')->first(); $this->assertEquals(11, $user['age']); $this->assertEquals(8, $user['note']); - $user = DB::collection('users')->where('name', 'Robert Roe')->first(); + $user = DB::table('users')->where('name', 'Robert Roe')->first(); $this->assertSame(1, $user['age']); $this->assertSame(2, $user['note']); - DB::collection('users')->where('name', 'Jane Doe')->incrementEach([ + DB::table('users')->where('name', 'Jane Doe')->incrementEach([ 'age' => 1, 'note' => 2, ], ['extra' => 'foo']); - $user = DB::collection('users')->where('name', 'Jane Doe')->first(); + $user = DB::table('users')->where('name', 'Jane Doe')->first(); $this->assertEquals(12, $user['age']); $this->assertEquals(10, $user['note']); $this->assertEquals('foo', $user['extra']); - $user = DB::collection('users')->where('name', 'John Doe')->first(); + $user = DB::table('users')->where('name', 'John Doe')->first(); $this->assertEquals(31, $user['age']); $this->assertEquals(7, $user['note']); $this->assertArrayNotHasKey('extra', $user); - DB::collection('users')->decrementEach([ + DB::table('users')->decrementEach([ 'age' => 1, 'note' => 2, ], ['extra' => 'foo']); - $user = DB::collection('users')->where('name', 'John Doe')->first(); + $user = DB::table('users')->where('name', 'John Doe')->first(); $this->assertEquals(30, $user['age']); $this->assertEquals(5, $user['note']); $this->assertEquals('foo', $user['extra']); diff --git a/tests/Queue/Failed/MongoFailedJobProviderTest.php b/tests/Queue/Failed/MongoFailedJobProviderTest.php index f113428ec..d0487ffcf 100644 --- a/tests/Queue/Failed/MongoFailedJobProviderTest.php +++ b/tests/Queue/Failed/MongoFailedJobProviderTest.php @@ -21,7 +21,7 @@ public function setUp(): void parent::setUp(); DB::connection('mongodb') - ->collection('failed_jobs') + ->table('failed_jobs') ->raw() ->insertMany(array_map(static fn ($i) => [ '_id' => new ObjectId(sprintf('%024d', $i)), @@ -34,7 +34,7 @@ public function setUp(): void public function tearDown(): void { DB::connection('mongodb') - ->collection('failed_jobs') + ->table('failed_jobs') ->raw() ->drop(); diff --git a/tests/SchemaTest.php b/tests/SchemaTest.php index e9d039fa7..baf78d1a5 100644 --- a/tests/SchemaTest.php +++ b/tests/SchemaTest.php @@ -344,11 +344,11 @@ public function testSparseUnique(): void public function testRenameColumn(): void { - DB::connection()->collection('newcollection')->insert(['test' => 'value']); - DB::connection()->collection('newcollection')->insert(['test' => 'value 2']); - DB::connection()->collection('newcollection')->insert(['column' => 'column value']); + DB::connection()->table('newcollection')->insert(['test' => 'value']); + DB::connection()->table('newcollection')->insert(['test' => 'value 2']); + DB::connection()->table('newcollection')->insert(['column' => 'column value']); - $check = DB::connection()->collection('newcollection')->get(); + $check = DB::connection()->table('newcollection')->get(); $this->assertCount(3, $check); $this->assertArrayHasKey('test', $check[0]); @@ -365,7 +365,7 @@ public function testRenameColumn(): void $collection->renameColumn('test', 'newtest'); }); - $check2 = DB::connection()->collection('newcollection')->get(); + $check2 = DB::connection()->table('newcollection')->get(); $this->assertCount(3, $check2); $this->assertArrayHasKey('newtest', $check2[0]); @@ -384,7 +384,7 @@ public function testRenameColumn(): void public function testHasColumn(): void { - DB::connection()->collection('newcollection')->insert(['column1' => 'value']); + DB::connection()->table('newcollection')->insert(['column1' => 'value']); $this->assertTrue(Schema::hasColumn('newcollection', 'column1')); $this->assertFalse(Schema::hasColumn('newcollection', 'column2')); @@ -393,7 +393,7 @@ public function testHasColumn(): void public function testHasColumns(): void { // Insert documents with both column1 and column2 - DB::connection()->collection('newcollection')->insert([ + DB::connection()->table('newcollection')->insert([ ['column1' => 'value1', 'column2' => 'value2'], ['column1' => 'value3'], ]); @@ -404,8 +404,8 @@ public function testHasColumns(): void public function testGetTables() { - DB::connection('mongodb')->collection('newcollection')->insert(['test' => 'value']); - DB::connection('mongodb')->collection('newcollection_two')->insert(['test' => 'value']); + DB::connection('mongodb')->table('newcollection')->insert(['test' => 'value']); + DB::connection('mongodb')->table('newcollection_two')->insert(['test' => 'value']); $tables = Schema::getTables(); $this->assertIsArray($tables); @@ -428,8 +428,8 @@ public function testGetTables() public function testGetTableListing() { - DB::connection('mongodb')->collection('newcollection')->insert(['test' => 'value']); - DB::connection('mongodb')->collection('newcollection_two')->insert(['test' => 'value']); + DB::connection('mongodb')->table('newcollection')->insert(['test' => 'value']); + DB::connection('mongodb')->table('newcollection_two')->insert(['test' => 'value']); $tables = Schema::getTableListing(); @@ -441,7 +441,7 @@ public function testGetTableListing() public function testGetColumns() { - $collection = DB::connection('mongodb')->collection('newcollection'); + $collection = DB::connection('mongodb')->table('newcollection'); $collection->insert(['text' => 'value', 'mixed' => ['key' => 'value']]); $collection->insert(['date' => new UTCDateTime(), 'binary' => new Binary('binary'), 'mixed' => true]); diff --git a/tests/SchemaVersionTest.php b/tests/SchemaVersionTest.php index dfe2f5122..0e115a6c2 100644 --- a/tests/SchemaVersionTest.php +++ b/tests/SchemaVersionTest.php @@ -38,7 +38,7 @@ public function testWithBasicDocument() // The migrated version is saved $data = DB::connection('mongodb') - ->collection('documentVersion') + ->table('documentVersion') ->where('name', 'Vador') ->get(); diff --git a/tests/Seeder/UserTableSeeder.php b/tests/Seeder/UserTableSeeder.php index f230c1018..b0708c9a9 100644 --- a/tests/Seeder/UserTableSeeder.php +++ b/tests/Seeder/UserTableSeeder.php @@ -11,8 +11,8 @@ class UserTableSeeder extends Seeder { public function run() { - DB::collection('users')->delete(); + DB::table('users')->delete(); - DB::collection('users')->insert(['name' => 'John Doe', 'seed' => true]); + DB::table('users')->insert(['name' => 'John Doe', 'seed' => true]); } } diff --git a/tests/TransactionTest.php b/tests/TransactionTest.php index 3338c6832..190f7487a 100644 --- a/tests/TransactionTest.php +++ b/tests/TransactionTest.php @@ -66,19 +66,19 @@ public function testCreateRollBack(): void public function testInsertWithCommit(): void { DB::beginTransaction(); - DB::collection('users')->insert(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + DB::table('users')->insert(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); DB::commit(); - $this->assertTrue(DB::collection('users')->where('name', 'klinson')->exists()); + $this->assertTrue(DB::table('users')->where('name', 'klinson')->exists()); } public function testInsertWithRollBack(): void { DB::beginTransaction(); - DB::collection('users')->insert(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + DB::table('users')->insert(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); DB::rollBack(); - $this->assertFalse(DB::collection('users')->where('name', 'klinson')->exists()); + $this->assertFalse(DB::table('users')->where('name', 'klinson')->exists()); } public function testEloquentCreateWithCommit(): void @@ -116,23 +116,23 @@ public function testEloquentCreateWithRollBack(): void public function testInsertGetIdWithCommit(): void { DB::beginTransaction(); - $userId = DB::collection('users')->insertGetId(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + $userId = DB::table('users')->insertGetId(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); DB::commit(); $this->assertInstanceOf(ObjectId::class, $userId); - $user = DB::collection('users')->find((string) $userId); + $user = DB::table('users')->find((string) $userId); $this->assertEquals('klinson', $user['name']); } public function testInsertGetIdWithRollBack(): void { DB::beginTransaction(); - $userId = DB::collection('users')->insertGetId(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + $userId = DB::table('users')->insertGetId(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); DB::rollBack(); $this->assertInstanceOf(ObjectId::class, $userId); - $this->assertFalse(DB::collection('users')->where('_id', (string) $userId)->exists()); + $this->assertFalse(DB::table('users')->where('_id', (string) $userId)->exists()); } public function testUpdateWithCommit(): void @@ -140,11 +140,11 @@ public function testUpdateWithCommit(): void User::create(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); DB::beginTransaction(); - $updated = DB::collection('users')->where('name', 'klinson')->update(['age' => 21]); + $updated = DB::table('users')->where('name', 'klinson')->update(['age' => 21]); DB::commit(); $this->assertEquals(1, $updated); - $this->assertTrue(DB::collection('users')->where('name', 'klinson')->where('age', 21)->exists()); + $this->assertTrue(DB::table('users')->where('name', 'klinson')->where('age', 21)->exists()); } public function testUpdateWithRollback(): void @@ -152,11 +152,11 @@ public function testUpdateWithRollback(): void User::create(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); DB::beginTransaction(); - $updated = DB::collection('users')->where('name', 'klinson')->update(['age' => 21]); + $updated = DB::table('users')->where('name', 'klinson')->update(['age' => 21]); DB::rollBack(); $this->assertEquals(1, $updated); - $this->assertFalse(DB::collection('users')->where('name', 'klinson')->where('age', 21)->exists()); + $this->assertFalse(DB::table('users')->where('name', 'klinson')->where('age', 21)->exists()); } public function testEloquentUpdateWithCommit(): void @@ -254,10 +254,10 @@ public function testIncrementWithCommit(): void User::create(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); DB::beginTransaction(); - DB::collection('users')->where('name', 'klinson')->increment('age'); + DB::table('users')->where('name', 'klinson')->increment('age'); DB::commit(); - $this->assertTrue(DB::collection('users')->where('name', 'klinson')->where('age', 21)->exists()); + $this->assertTrue(DB::table('users')->where('name', 'klinson')->where('age', 21)->exists()); } public function testIncrementWithRollBack(): void @@ -265,10 +265,10 @@ public function testIncrementWithRollBack(): void User::create(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); DB::beginTransaction(); - DB::collection('users')->where('name', 'klinson')->increment('age'); + DB::table('users')->where('name', 'klinson')->increment('age'); DB::rollBack(); - $this->assertTrue(DB::collection('users')->where('name', 'klinson')->where('age', 20)->exists()); + $this->assertTrue(DB::table('users')->where('name', 'klinson')->where('age', 20)->exists()); } public function testDecrementWithCommit(): void @@ -276,10 +276,10 @@ public function testDecrementWithCommit(): void User::create(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); DB::beginTransaction(); - DB::collection('users')->where('name', 'klinson')->decrement('age'); + DB::table('users')->where('name', 'klinson')->decrement('age'); DB::commit(); - $this->assertTrue(DB::collection('users')->where('name', 'klinson')->where('age', 19)->exists()); + $this->assertTrue(DB::table('users')->where('name', 'klinson')->where('age', 19)->exists()); } public function testDecrementWithRollBack(): void @@ -287,36 +287,36 @@ public function testDecrementWithRollBack(): void User::create(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); DB::beginTransaction(); - DB::collection('users')->where('name', 'klinson')->decrement('age'); + DB::table('users')->where('name', 'klinson')->decrement('age'); DB::rollBack(); - $this->assertTrue(DB::collection('users')->where('name', 'klinson')->where('age', 20)->exists()); + $this->assertTrue(DB::table('users')->where('name', 'klinson')->where('age', 20)->exists()); } public function testQuery() { /** rollback test */ DB::beginTransaction(); - $count = DB::collection('users')->count(); + $count = DB::table('users')->count(); $this->assertEquals(0, $count); - DB::collection('users')->insert(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); - $count = DB::collection('users')->count(); + DB::table('users')->insert(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + $count = DB::table('users')->count(); $this->assertEquals(1, $count); DB::rollBack(); - $count = DB::collection('users')->count(); + $count = DB::table('users')->count(); $this->assertEquals(0, $count); /** commit test */ DB::beginTransaction(); - $count = DB::collection('users')->count(); + $count = DB::table('users')->count(); $this->assertEquals(0, $count); - DB::collection('users')->insert(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); - $count = DB::collection('users')->count(); + DB::table('users')->insert(['name' => 'klinson', 'age' => 20, 'title' => 'admin']); + $count = DB::table('users')->count(); $this->assertEquals(1, $count); DB::commit(); - $count = DB::collection('users')->count(); + $count = DB::table('users')->count(); $this->assertEquals(1, $count); } From b0c3a95f2a7ad14e5b8de2ca9b0bee4f16c112a1 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Tue, 23 Jul 2024 10:40:31 -0400 Subject: [PATCH 320/446] Messed up the base branch/merge - fix (#3065) --- docs/eloquent-models/model-class.txt | 46 ++++++++++++++++++- .../eloquent-models/PlanetThirdParty.php | 15 ++++++ docs/user-authentication.txt | 5 ++ 3 files changed, 64 insertions(+), 2 deletions(-) create mode 100644 docs/includes/eloquent-models/PlanetThirdParty.php diff --git a/docs/eloquent-models/model-class.txt b/docs/eloquent-models/model-class.txt index ad5565abe..9d38fe1a7 100644 --- a/docs/eloquent-models/model-class.txt +++ b/docs/eloquent-models/model-class.txt @@ -30,7 +30,10 @@ to {+odm-short+} models: - :ref:`laravel-model-define` demonstrates how to create a model class. - :ref:`laravel-authenticatable-model` shows how to set MongoDB as the authentication user provider. -- :ref:`laravel-model-customize` explains several model class customizations. +- :ref:`laravel-model-customize` explains several model class + customizations. +- :ref:`laravel-third-party-model` explains how to make third-party + model classes compatible with MongoDB. - :ref:`laravel-model-pruning` shows how to periodically remove models that you no longer need. - :ref:`laravel-schema-versioning` shows how to implement model schema @@ -180,7 +183,7 @@ in the Laravel docs. .. _laravel-model-cast-data-types: Cast Data Types ---------------- +~~~~~~~~~~~~~~~ Eloquent lets you convert model attribute data types before storing or retrieving data by using a casting helper. This helper is a convenient @@ -281,6 +284,45 @@ To learn how to change the behavior when attempting to fill a field omitted from the ``$fillable`` array, see `Mass Assignment Exceptions `__ in the Laravel docs. +.. _laravel-third-party-model: + +Extend Third-Party Model Classes +-------------------------------- + +You can use {+odm-short+} to extend a third-party model class by +including the ``DocumentModel`` trait when defining your model class. By +including this trait, you can make the third-party class compatible with +MongoDB. + +When you apply the ``DocumentModel`` trait to a model class, you must +declare the following properties in your class: + +- ``$primaryKey = '_id'``, because the ``_id`` field uniquely + identifies MongoDB documents +- ``$keyType = 'string'``, because {+odm-short+} casts MongoDB + ``ObjectId`` values to type ``string`` + +Extended Class Example +~~~~~~~~~~~~~~~~~~~~~~ + +This example creates a ``Planet`` model class that extends the +``CelestialBody`` class from a package called ``ThirdPartyPackage``. The +``Post`` class includes the ``DocumentModel`` trait and defines +properties including ``$primaryKey`` and ``$keyType``: + +.. literalinclude:: /includes/eloquent-models/PlanetThirdParty.php + :language: php + :emphasize-lines: 10,13-14 + :dedent: + +After defining your class, you can perform MongoDB operations as usual. + +.. tip:: + + To view another example that uses the ``DocumentModel`` trait, see + the :ref:`laravel-user-auth-sanctum` section of the User + Authentication guide. + .. _laravel-model-pruning: Specify Pruning Behavior diff --git a/docs/includes/eloquent-models/PlanetThirdParty.php b/docs/includes/eloquent-models/PlanetThirdParty.php new file mode 100644 index 000000000..0f3bae638 --- /dev/null +++ b/docs/includes/eloquent-models/PlanetThirdParty.php @@ -0,0 +1,15 @@ +`__ in the Laravel Sanctum guide. +.. tip:: + + To learn more about the ``DocumentModel`` trait, see + :ref:`laravel-third-party-model` in the Eloquent Model Class guide. + .. _laravel-user-auth-reminders: Password Reminders From 046b92ab109368a5faad7d0848d11af7d4dd5edc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 23 Jul 2024 17:19:27 +0200 Subject: [PATCH 321/446] PHPORM-220 Deprecate using the `$collection` property to customize the name (#3064) Co-authored-by: rustagir --- CHANGELOG.md | 1 + docs/eloquent-models/model-class.txt | 4 ++-- docs/includes/auth/AuthUser.php | 2 +- docs/includes/auth/PersonalAccessToken.php | 2 +- docs/includes/eloquent-models/PlanetCollection.php | 2 +- docs/includes/fundamentals/read-operations/Movie.php | 2 +- docs/includes/usage-examples/Movie.php | 2 +- src/Eloquent/DocumentModel.php | 11 ++++++++++- tests/Models/Birthday.php | 2 +- tests/Models/Book.php | 2 +- tests/Models/Casting.php | 2 +- tests/Models/Client.php | 2 +- tests/Models/Experience.php | 2 +- tests/Models/Group.php | 2 +- tests/Models/Guarded.php | 2 +- tests/Models/Item.php | 2 +- tests/Models/Label.php | 2 +- tests/Models/Location.php | 2 +- tests/Models/Photo.php | 2 +- tests/Models/Role.php | 2 +- tests/Models/SchemaVersion.php | 2 +- tests/Models/Scoped.php | 2 +- tests/Models/Skill.php | 2 +- tests/Models/Soft.php | 2 +- 24 files changed, 34 insertions(+), 24 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 92a945c26..4cffde726 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,7 @@ All notable changes to this project will be documented in this file. * Add `Query\Builder::incrementEach()` and `decrementEach()` methods by @SmallRuralDog in [#2550](https://github.com/mongodb/laravel-mongodb/pull/2550) * Deprecate `Connection::collection()` and `Schema\Builder::collection()` methods by @GromNaN in [#3062](https://github.com/mongodb/laravel-mongodb/pull/3062) +* Deprecate `Model::$collection` property to customize collection name. Use `$table` instead by @GromNaN in [#3064](https://github.com/mongodb/laravel-mongodb/pull/3064) ## [4.7.0] - 2024-07-19 diff --git a/docs/eloquent-models/model-class.txt b/docs/eloquent-models/model-class.txt index 9d38fe1a7..bde8df072 100644 --- a/docs/eloquent-models/model-class.txt +++ b/docs/eloquent-models/model-class.txt @@ -111,7 +111,7 @@ Change the Model Collection Name By default, the model uses the snake case plural form of your model class name. To change the name of the collection the model uses to retrieve -and save data in MongoDB, override the ``$collection`` property of the model +and save data in MongoDB, override the ``$table`` property of the model class. .. note:: @@ -127,7 +127,7 @@ The following example specifies the custom MongoDB collection name, :emphasize-lines: 9 :dedent: -Without overriding the ``$collection`` property, this model maps to the +Without overriding the ``$table`` property, this model maps to the ``planets`` collection. With the overridden property, the example class stores the model in the ``celestial_body`` collection. diff --git a/docs/includes/auth/AuthUser.php b/docs/includes/auth/AuthUser.php index 8b6a0f173..439f923c4 100644 --- a/docs/includes/auth/AuthUser.php +++ b/docs/includes/auth/AuthUser.php @@ -7,7 +7,7 @@ class User extends Authenticatable { protected $connection = 'mongodb'; - protected $collection = 'users'; + protected $table = 'users'; protected $fillable = [ 'name', diff --git a/docs/includes/auth/PersonalAccessToken.php b/docs/includes/auth/PersonalAccessToken.php index 2a3c5e29c..165758770 100644 --- a/docs/includes/auth/PersonalAccessToken.php +++ b/docs/includes/auth/PersonalAccessToken.php @@ -10,7 +10,7 @@ class PersonalAccessToken extends SanctumToken use DocumentModel; protected $connection = 'mongodb'; - protected $collection = 'personal_access_tokens'; + protected $table = 'personal_access_tokens'; protected $primaryKey = '_id'; protected $keyType = 'string'; } diff --git a/docs/includes/eloquent-models/PlanetCollection.php b/docs/includes/eloquent-models/PlanetCollection.php index b36b24daa..f2c894db6 100644 --- a/docs/includes/eloquent-models/PlanetCollection.php +++ b/docs/includes/eloquent-models/PlanetCollection.php @@ -6,5 +6,5 @@ class Planet extends Model { - protected $collection = 'celestial_body'; + protected $table = 'celestial_body'; } diff --git a/docs/includes/fundamentals/read-operations/Movie.php b/docs/includes/fundamentals/read-operations/Movie.php index 728a066de..9b73e8738 100644 --- a/docs/includes/fundamentals/read-operations/Movie.php +++ b/docs/includes/fundamentals/read-operations/Movie.php @@ -7,6 +7,6 @@ class Movie extends Model { protected $connection = 'mongodb'; - protected $collection = 'movies'; + protected $table = 'movies'; protected $fillable = ['title', 'year', 'runtime', 'imdb', 'plot']; } diff --git a/docs/includes/usage-examples/Movie.php b/docs/includes/usage-examples/Movie.php index 728a066de..9b73e8738 100644 --- a/docs/includes/usage-examples/Movie.php +++ b/docs/includes/usage-examples/Movie.php @@ -7,6 +7,6 @@ class Movie extends Model { protected $connection = 'mongodb'; - protected $collection = 'movies'; + protected $table = 'movies'; protected $fillable = ['title', 'year', 'runtime', 'imdb', 'plot']; } diff --git a/src/Eloquent/DocumentModel.php b/src/Eloquent/DocumentModel.php index 15c33ef16..cbc388b22 100644 --- a/src/Eloquent/DocumentModel.php +++ b/src/Eloquent/DocumentModel.php @@ -46,8 +46,11 @@ use function str_contains; use function str_starts_with; use function strcmp; +use function trigger_error; use function var_export; +use const E_USER_DEPRECATED; + trait DocumentModel { use HybridRelations; @@ -141,7 +144,13 @@ public function freshTimestamp() /** @inheritdoc */ public function getTable() { - return $this->collection ?? parent::getTable(); + if (isset($this->collection)) { + trigger_error('Since mongodb/laravel-mongodb 4.8: Using "$collection" property is deprecated. Use "$table" instead.', E_USER_DEPRECATED); + + return $this->collection; + } + + return parent::getTable(); } /** @inheritdoc */ diff --git a/tests/Models/Birthday.php b/tests/Models/Birthday.php index 65b703af1..ae0e108b1 100644 --- a/tests/Models/Birthday.php +++ b/tests/Models/Birthday.php @@ -19,7 +19,7 @@ class Birthday extends Model protected $primaryKey = '_id'; protected $keyType = 'string'; protected $connection = 'mongodb'; - protected string $collection = 'birthday'; + protected $table = 'birthday'; protected $fillable = ['name', 'birthday']; protected $casts = ['birthday' => 'datetime']; diff --git a/tests/Models/Book.php b/tests/Models/Book.php index 5bee76e5c..3293a0eaa 100644 --- a/tests/Models/Book.php +++ b/tests/Models/Book.php @@ -20,7 +20,7 @@ class Book extends Model protected $primaryKey = 'title'; protected $keyType = 'string'; protected $connection = 'mongodb'; - protected string $collection = 'books'; + protected $table = 'books'; protected static $unguarded = true; public function author(): BelongsTo diff --git a/tests/Models/Casting.php b/tests/Models/Casting.php index d033cf444..dd2fadce1 100644 --- a/tests/Models/Casting.php +++ b/tests/Models/Casting.php @@ -10,7 +10,7 @@ class Casting extends Model { protected $connection = 'mongodb'; - protected string $collection = 'casting'; + protected $table = 'casting'; protected $fillable = [ 'uuid', diff --git a/tests/Models/Client.php b/tests/Models/Client.php index 47fd91d03..b0339a0e5 100644 --- a/tests/Models/Client.php +++ b/tests/Models/Client.php @@ -17,7 +17,7 @@ class Client extends Model protected $primaryKey = '_id'; protected $keyType = 'string'; protected $connection = 'mongodb'; - protected string $collection = 'clients'; + protected $table = 'clients'; protected static $unguarded = true; public function users(): BelongsToMany diff --git a/tests/Models/Experience.php b/tests/Models/Experience.php index 37a44e4d1..6a306afe1 100644 --- a/tests/Models/Experience.php +++ b/tests/Models/Experience.php @@ -15,7 +15,7 @@ class Experience extends Model protected $primaryKey = '_id'; protected $keyType = 'string'; protected $connection = 'mongodb'; - protected string $collection = 'experiences'; + protected $table = 'experiences'; protected static $unguarded = true; protected $casts = ['years' => 'int']; diff --git a/tests/Models/Group.php b/tests/Models/Group.php index 689c6d599..57c3af59c 100644 --- a/tests/Models/Group.php +++ b/tests/Models/Group.php @@ -15,7 +15,7 @@ class Group extends Model protected $primaryKey = '_id'; protected $keyType = 'string'; protected $connection = 'mongodb'; - protected string $collection = 'groups'; + protected $table = 'groups'; protected static $unguarded = true; public function users(): BelongsToMany diff --git a/tests/Models/Guarded.php b/tests/Models/Guarded.php index 9837e9222..40d11bea5 100644 --- a/tests/Models/Guarded.php +++ b/tests/Models/Guarded.php @@ -14,6 +14,6 @@ class Guarded extends Model protected $primaryKey = '_id'; protected $keyType = 'string'; protected $connection = 'mongodb'; - protected string $collection = 'guarded'; + protected $table = 'guarded'; protected $guarded = ['foobar', 'level1->level2']; } diff --git a/tests/Models/Item.php b/tests/Models/Item.php index bc0b29b7b..2beb40d75 100644 --- a/tests/Models/Item.php +++ b/tests/Models/Item.php @@ -18,7 +18,7 @@ class Item extends Model protected $primaryKey = '_id'; protected $keyType = 'string'; protected $connection = 'mongodb'; - protected string $collection = 'items'; + protected $table = 'items'; protected static $unguarded = true; public function user(): BelongsTo diff --git a/tests/Models/Label.php b/tests/Models/Label.php index b392184d7..b95aa0dcf 100644 --- a/tests/Models/Label.php +++ b/tests/Models/Label.php @@ -20,7 +20,7 @@ class Label extends Model protected $primaryKey = '_id'; protected $keyType = 'string'; protected $connection = 'mongodb'; - protected string $collection = 'labels'; + protected $table = 'labels'; protected static $unguarded = true; protected $fillable = [ diff --git a/tests/Models/Location.php b/tests/Models/Location.php index 9621d388f..2c62dbda9 100644 --- a/tests/Models/Location.php +++ b/tests/Models/Location.php @@ -14,6 +14,6 @@ class Location extends Model protected $primaryKey = '_id'; protected $keyType = 'string'; protected $connection = 'mongodb'; - protected string $collection = 'locations'; + protected $table = 'locations'; protected static $unguarded = true; } diff --git a/tests/Models/Photo.php b/tests/Models/Photo.php index ea3321337..be7f3666c 100644 --- a/tests/Models/Photo.php +++ b/tests/Models/Photo.php @@ -15,7 +15,7 @@ class Photo extends Model protected $primaryKey = '_id'; protected $keyType = 'string'; protected $connection = 'mongodb'; - protected string $collection = 'photos'; + protected $table = 'photos'; protected static $unguarded = true; public function hasImage(): MorphTo diff --git a/tests/Models/Role.php b/tests/Models/Role.php index 7d0dce7b1..e9f3fa95d 100644 --- a/tests/Models/Role.php +++ b/tests/Models/Role.php @@ -15,7 +15,7 @@ class Role extends Model protected $primaryKey = '_id'; protected $keyType = 'string'; protected $connection = 'mongodb'; - protected string $collection = 'roles'; + protected $table = 'roles'; protected static $unguarded = true; public function user(): BelongsTo diff --git a/tests/Models/SchemaVersion.php b/tests/Models/SchemaVersion.php index cacfc3f65..8acd73545 100644 --- a/tests/Models/SchemaVersion.php +++ b/tests/Models/SchemaVersion.php @@ -14,7 +14,7 @@ class SchemaVersion extends Eloquent public const SCHEMA_VERSION = 2; protected $connection = 'mongodb'; - protected $collection = 'documentVersion'; + protected $table = 'documentVersion'; protected static $unguarded = true; public function migrateSchema(int $fromVersion): void diff --git a/tests/Models/Scoped.php b/tests/Models/Scoped.php index 84b8b81f7..6850dcb21 100644 --- a/tests/Models/Scoped.php +++ b/tests/Models/Scoped.php @@ -15,7 +15,7 @@ class Scoped extends Model protected $primaryKey = '_id'; protected $keyType = 'string'; protected $connection = 'mongodb'; - protected string $collection = 'scoped'; + protected $table = 'scoped'; protected $fillable = ['name', 'favorite']; protected static function boot() diff --git a/tests/Models/Skill.php b/tests/Models/Skill.php index 90c9455b9..1e2daaf80 100644 --- a/tests/Models/Skill.php +++ b/tests/Models/Skill.php @@ -15,7 +15,7 @@ class Skill extends Model protected $primaryKey = '_id'; protected $keyType = 'string'; protected $connection = 'mongodb'; - protected string $collection = 'skills'; + protected $table = 'skills'; protected static $unguarded = true; public function sqlUsers(): BelongsToMany diff --git a/tests/Models/Soft.php b/tests/Models/Soft.php index 549e63758..cbfa2ef23 100644 --- a/tests/Models/Soft.php +++ b/tests/Models/Soft.php @@ -21,7 +21,7 @@ class Soft extends Model protected $primaryKey = '_id'; protected $keyType = 'string'; protected $connection = 'mongodb'; - protected string $collection = 'soft'; + protected $table = 'soft'; protected static $unguarded = true; protected $casts = ['deleted_at' => 'datetime']; From 895dcc73d08b2b6ae206860dad1da968b9199a19 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Thu, 25 Jul 2024 11:20:57 +0200 Subject: [PATCH 322/446] PHPORM-222 Register the `BusServiceProvider` when `BatchRepository` is built (#3071) --- src/MongoDBBusServiceProvider.php | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/src/MongoDBBusServiceProvider.php b/src/MongoDBBusServiceProvider.php index c77ccd118..d3d6f25fc 100644 --- a/src/MongoDBBusServiceProvider.php +++ b/src/MongoDBBusServiceProvider.php @@ -8,8 +8,11 @@ use Illuminate\Container\Container; use Illuminate\Contracts\Support\DeferrableProvider; use Illuminate\Support\ServiceProvider; +use InvalidArgumentException; use MongoDB\Laravel\Bus\MongoBatchRepository; +use function sprintf; + class MongoDBBusServiceProvider extends ServiceProvider implements DeferrableProvider { /** @@ -18,14 +21,21 @@ class MongoDBBusServiceProvider extends ServiceProvider implements DeferrablePro public function register() { $this->app->singleton(MongoBatchRepository::class, function (Container $app) { + $connection = $app->make('db')->connection($app->config->get('queue.batching.database')); + + if (! $connection instanceof Connection) { + throw new InvalidArgumentException(sprintf('The "mongodb" batch driver requires a MongoDB connection. The "%s" connection uses the "%s" driver.', $connection->getName(), $connection->getDriverName())); + } + return new MongoBatchRepository( $app->make(BatchFactory::class), - $app->make('db')->connection($app->config->get('queue.batching.database')), + $connection, $app->config->get('queue.batching.collection', 'job_batches'), ); }); - /** @see BusServiceProvider::registerBatchServices() */ + /** The {@see BatchRepository} service is registered in {@see BusServiceProvider} */ + $this->app->register(BusServiceProvider::class); $this->app->extend(BatchRepository::class, function (BatchRepository $repository, Container $app) { $driver = $app->config->get('queue.batching.driver'); From fb7bbf6b8d1bcb62dfac80e72261b280365759e3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Thu, 25 Jul 2024 11:52:51 +0200 Subject: [PATCH 323/446] Update changelog (#3076) --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index b4b539e13..8c1c4d9c1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,10 @@ # Changelog All notable changes to this project will be documented in this file. +## [4.7.1] - 2024-07-25 + +* Fix registration of `BusServiceProvider` for compatibility with Horizon by @GromNaN in [#3071](https://github.com/mongodb/laravel-mongodb/pull/3071) + ## [4.7.0] - 2024-07-19 * Add `Query\Builder::upsert()` method by @GromNaN in [#3052](https://github.com/mongodb/laravel-mongodb/pull/3052) From 58682e149686a1e2aeb76bd43289bf158ed1b76d Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Mon, 29 Jul 2024 10:49:16 -0400 Subject: [PATCH 324/446] DOCSP-41680: Remove quick start buttons (#3081) --- docs/quick-start.txt | 3 --- docs/quick-start/configure-mongodb.txt | 3 --- docs/quick-start/create-a-connection-string.txt | 3 --- docs/quick-start/create-a-deployment.txt | 3 --- docs/quick-start/download-and-install.txt | 3 --- docs/quick-start/view-data.txt | 3 --- docs/quick-start/write-data.txt | 3 --- 7 files changed, 21 deletions(-) diff --git a/docs/quick-start.txt b/docs/quick-start.txt index 30587454e..d3a87cbf6 100644 --- a/docs/quick-start.txt +++ b/docs/quick-start.txt @@ -56,9 +56,6 @@ that connects to a MongoDB deployment. `laravel-quickstart `__ GitHub repository. -.. button:: Next: Download and Install - :uri: /quick-start/download-and-install/ - .. toctree:: /quick-start/download-and-install/ diff --git a/docs/quick-start/configure-mongodb.txt b/docs/quick-start/configure-mongodb.txt index 6f72455a6..2e50a7a31 100644 --- a/docs/quick-start/configure-mongodb.txt +++ b/docs/quick-start/configure-mongodb.txt @@ -89,6 +89,3 @@ After completing these steps, your Laravel web application is ready to connect to MongoDB. .. include:: /includes/quick-start/troubleshoot.rst - -.. button:: Next: View Sample MongoDB Data - :uri: /quick-start/view-data/ diff --git a/docs/quick-start/create-a-connection-string.txt b/docs/quick-start/create-a-connection-string.txt index 9851531b6..e28bcdf47 100644 --- a/docs/quick-start/create-a-connection-string.txt +++ b/docs/quick-start/create-a-connection-string.txt @@ -58,6 +58,3 @@ After completing these steps, you have a connection string that contains your database username and password. .. include:: /includes/quick-start/troubleshoot.rst - -.. button:: Next: Configure Your MongoDB Connection - :uri: /quick-start/configure-mongodb/ diff --git a/docs/quick-start/create-a-deployment.txt b/docs/quick-start/create-a-deployment.txt index a4edb7dc1..5c0cc6f17 100644 --- a/docs/quick-start/create-a-deployment.txt +++ b/docs/quick-start/create-a-deployment.txt @@ -26,6 +26,3 @@ After completing these steps, you have a new free tier MongoDB deployment on Atlas, database user credentials, and sample data loaded into your database. .. include:: /includes/quick-start/troubleshoot.rst - -.. button:: Next: Create a Connection String - :uri: /quick-start/create-a-connection-string/ diff --git a/docs/quick-start/download-and-install.txt b/docs/quick-start/download-and-install.txt index f4b4b8aa5..5d9d1d69f 100644 --- a/docs/quick-start/download-and-install.txt +++ b/docs/quick-start/download-and-install.txt @@ -114,6 +114,3 @@ to a Laravel web application. {+odm-short+} dependencies installed. .. include:: /includes/quick-start/troubleshoot.rst - -.. button:: Create a MongoDB Deployment - :uri: /quick-start/create-a-deployment/ diff --git a/docs/quick-start/view-data.txt b/docs/quick-start/view-data.txt index ecd5206a0..9be7334af 100644 --- a/docs/quick-start/view-data.txt +++ b/docs/quick-start/view-data.txt @@ -189,6 +189,3 @@ View MongoDB Data root directory to view a list of available routes. .. include:: /includes/quick-start/troubleshoot.rst - -.. button:: Next: Write Data - :uri: /quick-start/write-data/ diff --git a/docs/quick-start/write-data.txt b/docs/quick-start/write-data.txt index 3ede2f8c5..d8a01666c 100644 --- a/docs/quick-start/write-data.txt +++ b/docs/quick-start/write-data.txt @@ -103,6 +103,3 @@ Write Data to MongoDB the top of the results. .. include:: /includes/quick-start/troubleshoot.rst - -.. button:: Next Steps - :uri: /quick-start/next-steps/ From 432456b267be77cee0d4486aa51fa0b0cf87805a Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Tue, 30 Jul 2024 16:28:55 +0200 Subject: [PATCH 325/446] Fix wrong name for driver options in docs (#3074) --- docs/fundamentals/connection/connect-to-mongodb.txt | 6 +++--- docs/fundamentals/connection/connection-options.txt | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/fundamentals/connection/connect-to-mongodb.txt b/docs/fundamentals/connection/connect-to-mongodb.txt index 9f7e07b26..5d697b3a2 100644 --- a/docs/fundamentals/connection/connect-to-mongodb.txt +++ b/docs/fundamentals/connection/connect-to-mongodb.txt @@ -157,7 +157,7 @@ For a MongoDB database connection, you can specify the following details: connection behavior. To learn more about connection options, see :ref:`laravel-connection-auth-options`. - * - ``driverOptions`` + * - ``driver_options`` - Specifies options specific to pass to the {+php-library+} that determine the driver behavior for that connection. To learn more about driver options, see :ref:`laravel-driver-options`. @@ -170,7 +170,7 @@ For a MongoDB database connection, you can specify the following details: - ``host`` - ``username`` - ``password`` - - ``options`` and ``driverOptions``, which are specified by the option name + - ``options`` and ``driver_options``, which are specified by the option name The following example shows how you can specify your MongoDB connection details in the ``connections`` array item: @@ -187,7 +187,7 @@ in the ``connections`` array item: 'maxPoolSize' => 20, 'w' => 'majority', ], - 'driverOptions' => [ + 'driver_options' => [ 'serverApi' => 1, ], ], diff --git a/docs/fundamentals/connection/connection-options.txt b/docs/fundamentals/connection/connection-options.txt index d73cb33d4..03e98ed06 100644 --- a/docs/fundamentals/connection/connection-options.txt +++ b/docs/fundamentals/connection/connection-options.txt @@ -9,7 +9,7 @@ Connection Options :values: reference .. meta:: - :keywords: code example, data source name, dsn, authentication, configuration, options, driverOptions + :keywords: code example, data source name, dsn, authentication, configuration, options, driver_options .. contents:: On this page :local: @@ -329,7 +329,7 @@ connections and all operations between a Laravel application and MongoDB. You can specify driver options in your Laravel web application's ``config/database.php`` configuration file. To add driver options, -add the setting and value as an array item in the ``driverOptions`` array +add the setting and value as an array item in the ``driver_options`` array item, as shown in the following example: .. code-block:: php @@ -340,7 +340,7 @@ item, as shown in the following example: 'dsn' => 'mongodb+srv://mongodb0.example.com/', 'driver' => 'mongodb', 'database' => 'sample_mflix', - 'driverOptions' => [ + 'driver_options' => [ 'serverApi' => 1, 'allow_invalid_hostname' => false, ], From e5b89c60fa16864bb86230d341fd83418a260512 Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Thu, 1 Aug 2024 10:46:54 +0200 Subject: [PATCH 326/446] Move code ownership for docs to Laravel Docs team (#3090) --- .github/CODEOWNERS | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 3fe0077e4..ffb19cd3d 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,2 +1,2 @@ * @mongodb/dbx-php -/docs @mongodb/docs-drivers-team +/docs @mongodb/laravel-docs From 185d93a24e2e7c0bb684ad6eb1db144b99a1054d Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Mon, 12 Aug 2024 11:01:10 -0400 Subject: [PATCH 327/446] DOCSP-41621: upsert (#3089) * DOCSP-41621: upsert * apply phpcbf formatting * heading fixes * test fix * test fix * add model method * apply phpcbf formatting * formatting fix * NR PR fixes 1 * JT tech review 1 --------- Co-authored-by: rustagir --- docs/feature-compatibility.txt | 4 +- docs/fundamentals/write-operations.txt | 90 +++++++++++++- .../write-operations/WriteOperationsTest.php | 39 +++++- .../query-builder/QueryBuilderTest.php | 25 +++- .../query-builder/sample_mflix.movies.json | 117 +++++++++--------- docs/query-builder.txt | 77 ++++++++++-- 6 files changed, 271 insertions(+), 81 deletions(-) diff --git a/docs/feature-compatibility.txt b/docs/feature-compatibility.txt index bbb5767e1..0c28300ba 100644 --- a/docs/feature-compatibility.txt +++ b/docs/feature-compatibility.txt @@ -151,7 +151,7 @@ The following Eloquent methods are not supported in {+odm-short+}: - *Unsupported as MongoDB uses ObjectIDs* * - Upserts - - *Unsupported* + - ✓ See :ref:`laravel-mongodb-query-builder-upsert`. * - Update Statements - ✓ @@ -216,7 +216,7 @@ Eloquent Features - ✓ * - Upserts - - *Unsupported, but you can use the createOneOrFirst() method* + - ✓ See :ref:`laravel-modify-documents-upsert`. * - Deleting Models - ✓ diff --git a/docs/fundamentals/write-operations.txt b/docs/fundamentals/write-operations.txt index 57bbcd8bc..cc7d81337 100644 --- a/docs/fundamentals/write-operations.txt +++ b/docs/fundamentals/write-operations.txt @@ -258,6 +258,88 @@ An **upsert** operation lets you perform an update or insert in a single operation. This operation streamlines the task of updating a document or inserting one if it does not exist. +Starting in v4.7, you can perform an upsert operation by using either of +the following methods: + +- ``upsert()``: When you use this method, you can perform a **batch + upsert** to change or insert multiple documents in one operation. + +- ``update()``: When you use this method, you must specify the + ``upsert`` option to update all documents that match the query filter + or insert one document if no documents are matched. Only this upsert method + is supported in versions v4.6 and earlier. + +Upsert Method +~~~~~~~~~~~~~ + +The ``upsert(array $values, array|string $uniqueBy, array|null +$update)`` method accepts the following parameters: + +- ``$values``: Array of fields and values that specify documents to update or insert. +- ``$uniqueBy``: List of fields that uniquely identify documents in your + first array parameter. +- ``$update``: Optional list of fields to update if a matching document + exists. If you omit this parameter, {+odm-short+} updates all fields. + +To specify an upsert in the ``upsert()`` method, set parameters +as shown in the following code example: + +.. code-block:: php + :copyable: false + + YourModel::upsert( + [/* documents to update or insert */], + '/* unique field */', + [/* fields to update */], + ); + +Example +^^^^^^^ + +This example shows how to use the ``upsert()`` +method to perform an update or insert in a single operation. Click the +:guilabel:`{+code-output-label+}` button to see the resulting data changes when +there is a document in which the value of ``performer`` is ``'Angel +Olsen'`` in the collection already: + +.. io-code-block:: + + .. input:: /includes/fundamentals/write-operations/WriteOperationsTest.php + :language: php + :dedent: + :start-after: begin model upsert + :end-before: end model upsert + + .. output:: + :language: json + :visible: false + + { + "_id": "...", + "performer": "Angel Olsen", + "venue": "State Theatre", + "genres": [ + "indie", + "rock" + ], + "ticketsSold": 275, + "updated_at": ... + }, + { + "_id": "...", + "performer": "Darondo", + "venue": "Cafe du Nord", + "ticketsSold": 300, + "updated_at": ... + } + +In the document in which the value of ``performer`` is ``'Angel +Olsen'``, the ``venue`` field value is not updated, as the upsert +specifies that the update applies only to the ``ticketsSold`` field. + +Update Method +~~~~~~~~~~~~~ + To specify an upsert in an ``update()`` method, set the ``upsert`` option to ``true`` as shown in the following code example: @@ -278,8 +360,8 @@ following actions: - If the query matches zero documents, the ``update()`` method inserts a document that contains the update data and the equality match criteria data. -Upsert Example -~~~~~~~~~~~~~~ +Example +^^^^^^^ This example shows how to pass the ``upsert`` option to the ``update()`` method to perform an update or insert in a single operation. Click the @@ -291,8 +373,8 @@ matching documents exist: .. input:: /includes/fundamentals/write-operations/WriteOperationsTest.php :language: php :dedent: - :start-after: begin model upsert - :end-before: end model upsert + :start-after: begin model update upsert + :end-before: end model update upsert .. output:: :language: json diff --git a/docs/includes/fundamentals/write-operations/WriteOperationsTest.php b/docs/includes/fundamentals/write-operations/WriteOperationsTest.php index d577ef57b..39143ac09 100644 --- a/docs/includes/fundamentals/write-operations/WriteOperationsTest.php +++ b/docs/includes/fundamentals/write-operations/WriteOperationsTest.php @@ -217,22 +217,55 @@ public function testModelUpdateMultiple(): void } } + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function testModelUpsert(): void + { + require_once __DIR__ . '/Concert.php'; + Concert::truncate(); + + // Pre-existing sample document + Concert::create([ + 'performer' => 'Angel Olsen', + 'venue' => 'State Theatre', + 'genres' => [ 'indie', 'rock' ], + 'ticketsSold' => 150, + ]); + + // begin model upsert + Concert::upsert([ + ['performer' => 'Angel Olsen', 'venue' => 'Academy of Music', 'ticketsSold' => 275], + ['performer' => 'Darondo', 'venue' => 'Cafe du Nord', 'ticketsSold' => 300], + ], 'performer', ['ticketsSold']); + // end model upsert + + $this->assertSame(2, Concert::count()); + + $this->assertSame(275, Concert::where('performer', 'Angel Olsen')->first()->ticketsSold); + $this->assertSame('State Theatre', Concert::where('performer', 'Angel Olsen')->first()->venue); + + $this->assertSame(300, Concert::where('performer', 'Darondo')->first()->ticketsSold); + $this->assertSame('Cafe du Nord', Concert::where('performer', 'Darondo')->first()->venue); + } + /** * @runInSeparateProcess * @preserveGlobalState disabled */ - public function testModelUpsert(): void + public function testModelUpdateUpsert(): void { require_once __DIR__ . '/Concert.php'; Concert::truncate(); - // begin model upsert + // begin model update upsert Concert::where(['performer' => 'Jon Batiste', 'venue' => 'Radio City Music Hall']) ->update( ['genres' => ['R&B', 'soul'], 'ticketsSold' => 4000], ['upsert' => true], ); - // end model upsert + // end model update upsert $result = Concert::first(); diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index a7d7a591e..d277ae241 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -506,6 +506,29 @@ function (Collection $collection) { public function testUpsert(): void { // begin upsert + $result = DB::collection('movies') + ->upsert( + [ + ['title' => 'Inspector Maigret', 'recommended' => false, 'runtime' => 128], + ['title' => 'Petit Maman', 'recommended' => true, 'runtime' => 72], + ], + 'title', + 'recommended', + ); + // end upsert + + $this->assertSame(2, $result); + + $this->assertSame(119, DB::collection('movies')->where('title', 'Inspector Maigret')->first()['runtime']); + $this->assertSame(false, DB::collection('movies')->where('title', 'Inspector Maigret')->first()['recommended']); + + $this->assertSame(true, DB::collection('movies')->where('title', 'Petit Maman')->first()['recommended']); + $this->assertSame(72, DB::collection('movies')->where('title', 'Petit Maman')->first()['runtime']); + } + + public function testUpdateUpsert(): void + { + // begin update upsert $result = DB::collection('movies') ->where('title', 'Will Hunting') ->update( @@ -516,7 +539,7 @@ public function testUpsert(): void ], ['upsert' => true], ); - // end upsert + // end update upsert $this->assertIsInt($result); } diff --git a/docs/includes/query-builder/sample_mflix.movies.json b/docs/includes/query-builder/sample_mflix.movies.json index 57873754e..ef8677520 100644 --- a/docs/includes/query-builder/sample_mflix.movies.json +++ b/docs/includes/query-builder/sample_mflix.movies.json @@ -1,17 +1,10 @@ [ { - "genres": [ - "Short" - ], + "genres": ["Short"], "runtime": 1, - "cast": [ - "Charles Kayser", - "John Ott" - ], + "cast": ["Charles Kayser", "John Ott"], "title": "Blacksmith Scene", - "directors": [ - "William K.L. Dickson" - ], + "directors": ["William K.L. Dickson"], "rated": "UNRATED", "year": 1893, "imdb": { @@ -28,10 +21,7 @@ } }, { - "genres": [ - "Short", - "Western" - ], + "genres": ["Short", "Western"], "runtime": 11, "cast": [ "A.C. Abadie", @@ -40,9 +30,7 @@ "Justus D. Barnes" ], "title": "The Great Train Robbery", - "directors": [ - "Edwin S. Porter" - ], + "directors": ["Edwin S. Porter"], "rated": "TV-G", "year": 1903, "imdb": { @@ -59,11 +47,7 @@ } }, { - "genres": [ - "Short", - "Drama", - "Fantasy" - ], + "genres": ["Short", "Drama", "Fantasy"], "runtime": 14, "rated": "UNRATED", "cast": [ @@ -73,12 +57,8 @@ "Ethel Jewett" ], "title": "The Land Beyond the Sunset", - "directors": [ - "Harold M. Shaw" - ], - "writers": [ - "Dorothy G. Shore" - ], + "directors": ["Harold M. Shaw"], + "writers": ["Dorothy G. Shore"], "year": 1912, "imdb": { "rating": 7.1, @@ -94,10 +74,7 @@ } }, { - "genres": [ - "Short", - "Drama" - ], + "genres": ["Short", "Drama"], "runtime": 14, "cast": [ "Frank Powell", @@ -106,9 +83,7 @@ "Linda Arvidson" ], "title": "A Corner in Wheat", - "directors": [ - "D.W. Griffith" - ], + "directors": ["D.W. Griffith"], "rated": "G", "year": 1909, "imdb": { @@ -125,20 +100,11 @@ } }, { - "genres": [ - "Animation", - "Short", - "Comedy" - ], + "genres": ["Animation", "Short", "Comedy"], "runtime": 7, - "cast": [ - "Winsor McCay" - ], + "cast": ["Winsor McCay"], "title": "Winsor McCay, the Famous Cartoonist of the N.Y. Herald and His Moving Comics", - "directors": [ - "Winsor McCay", - "J. Stuart Blackton" - ], + "directors": ["Winsor McCay", "J. Stuart Blackton"], "writers": [ "Winsor McCay (comic strip \"Little Nemo in Slumberland\")", "Winsor McCay (screenplay)" @@ -158,22 +124,11 @@ } }, { - "genres": [ - "Comedy", - "Fantasy", - "Romance" - ], + "genres": ["Comedy", "Fantasy", "Romance"], "runtime": 118, - "cast": [ - "Meg Ryan", - "Hugh Jackman", - "Liev Schreiber", - "Breckin Meyer" - ], + "cast": ["Meg Ryan", "Hugh Jackman", "Liev Schreiber", "Breckin Meyer"], "title": "Kate & Leopold", - "directors": [ - "James Mangold" - ], + "directors": ["James Mangold"], "writers": [ "Steven Rogers (story)", "James Mangold (screenplay)", @@ -192,5 +147,45 @@ "meter": 62 } } + }, + { + "genres": ["Crime", "Drama"], + "runtime": 119, + "cast": [ + "Jean Gabin", + "Annie Girardot", + "Olivier Hussenot", + "Jeanne Boitel" + ], + "title": "Inspector Maigret", + "directors": ["Jean Delannoy"], + "writers": [ + "Georges Simenon (novel)", + "Jean Delannoy (adaptation)", + "Rodolphe-Maurice Arlaud (adaptation)", + "Michel Audiard (adaptation)", + "Michel Audiard (dialogue)" + ], + "year": 1958, + "imdb": { + "rating": 7.1, + "votes": 690, + "id": 50669 + }, + "countries": ["France", "Italy"], + "type": "movie", + "tomatoes": { + "viewer": { + "rating": 2.7, + "numReviews": 77, + "meter": 14 + }, + "dvd": { + "$date": "2007-01-23T00:00:00.000Z" + }, + "lastUpdated": { + "$date": "2015-09-14T22:31:29.000Z" + } + } } ] diff --git a/docs/query-builder.txt b/docs/query-builder.txt index 8b4be3245..dc3225e37 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -399,7 +399,7 @@ of the ``year`` field for documents in the ``movies`` collections. .. _laravel-query-builder-aggregations: Aggregations -~~~~~~~~~~~~ +------------ The examples in this section show the query builder syntax you can use to perform **aggregations**. Aggregations are operations @@ -417,7 +417,7 @@ aggregations to compute and return the following information: .. _laravel-query-builder-aggregation-groupby: Results Grouped by Common Field Values Example -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following example shows how to use the ``groupBy()`` query builder method to retrieve document data grouped by shared values of the ``runtime`` field. @@ -476,7 +476,7 @@ This example chains the following operations to match documents from the .. _laravel-query-builder-aggregation-count: Number of Results Example -^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~ The following example shows how to use the ``count()`` query builder method to return the number of documents @@ -491,7 +491,7 @@ contained in the ``movies`` collection: .. _laravel-query-builder-aggregation-max: Maximum Value of a Field Example -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following example shows how to use the ``max()`` query builder method to return the highest numerical @@ -507,7 +507,7 @@ value of the ``runtime`` field from the entire .. _laravel-query-builder-aggregation-min: Minimum Value of a Field Example -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following example shows how to use the ``min()`` query builder method to return the lowest numerical @@ -523,7 +523,7 @@ collection: .. _laravel-query-builder-aggregation-avg: Average Value of a Field Example -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following example shows how to use the ``avg()`` query builder method to return the numerical average, or @@ -539,7 +539,7 @@ the entire ``movies`` collection. .. _laravel-query-builder-aggregation-sum: Summed Value of a Field Example -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following example shows how to use the ``sum()`` query builder method to return the numerical total of @@ -556,7 +556,7 @@ collection: .. _laravel-query-builder-aggregate-matched: Aggregate Matched Results Example -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following example shows how to aggregate data from results that match a query. The query matches all @@ -1035,6 +1035,63 @@ following MongoDB-specific write operations: Upsert a Document Example ~~~~~~~~~~~~~~~~~~~~~~~~~ +Starting in v4.7, you can perform an upsert operation by using either of +the following query builder methods: + +- ``upsert()``: When you use this method, you can perform a **batch + upsert** to change or insert multiple documents in one operation. + +- ``update()``: When you use this method, you must specify the + ``upsert`` option to update all documents that match the query filter + or insert one document if no documents are matched. Only this upsert method + is supported in versions v4.6 and earlier. + +Upsert Method +^^^^^^^^^^^^^ + +The ``upsert(array $values, array|string $uniqueBy, array|null +$update)`` query builder method accepts the following parameters: + +- ``$values``: Array of fields and values that specify documents to update or insert. +- ``$uniqueBy``: List of fields that uniquely identify documents in your + first array parameter. +- ``$update``: Optional list of fields to update if a matching document + exists. If you omit this parameter, {+odm-short+} updates all fields. + +The following example shows how to use the ``upsert()`` query builder method +to update or insert documents based on the following instructions: + +- Specify a document in which the value of the ``title`` field is + ``'Inspector Maigret'``, the value of the ``recommended`` field is ``false``, + and the value of the ``runtime`` field is ``128``. + +- Specify a document in which the value of the ``title`` field is + ``'Petit Maman'``, the value of the ``recommended`` field is + ``true``, and the value of the ``runtime`` field is ``72``. + +- Indicate that the ``title`` field uniquely identifies documents in the + scope of your operation. + +- Update only the ``recommended`` field in matched documents. + +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin upsert + :end-before: end upsert + +The ``upsert()`` query builder method returns the number of +documents that the operation updated, inserted, and modified. + +.. note:: + + The ``upsert()`` method does not trigger events. To trigger events + from an upsert operation, you can use the ``createOrFirst()`` method + instead. + +Update Method +^^^^^^^^^^^^^ + The following example shows how to use the ``update()`` query builder method and ``upsert`` option to update the matching document or insert one with the specified data if it does not exist. When you set the ``upsert`` option to @@ -1044,8 +1101,8 @@ and the ``title`` field and value specified in the ``where()`` query operation: .. literalinclude:: /includes/query-builder/QueryBuilderTest.php :language: php :dedent: - :start-after: begin upsert - :end-before: end upsert + :start-after: begin update upsert + :end-before: end update upsert The ``update()`` query builder method returns the number of documents that the operation updated or inserted. From 497a074afa47f114ef36c2d80e8711cf64ed6f64 Mon Sep 17 00:00:00 2001 From: hms5232 <43672033+hms5232@users.noreply.github.com> Date: Mon, 12 Aug 2024 23:01:33 +0800 Subject: [PATCH 328/446] Fix missing bracket in config snippet (#3095) --- docs/quick-start/configure-mongodb.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/quick-start/configure-mongodb.txt b/docs/quick-start/configure-mongodb.txt index 2e50a7a31..b3e4583fe 100644 --- a/docs/quick-start/configure-mongodb.txt +++ b/docs/quick-start/configure-mongodb.txt @@ -68,6 +68,7 @@ Configure Your MongoDB Connection 'dsn' => env('DB_URI'), 'database' => 'sample_mflix', ], + ], // ... From 17bc7e621bee806f57423ab93f775a26a3aa12c5 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Mon, 12 Aug 2024 14:03:44 -0400 Subject: [PATCH 329/446] DOCSP-41741: incrementEach and decrementEach (#3088) * DOCSP-41741: incrementEach and decrementEach * clarify v4.8 * edits --- .../query-builder/QueryBuilderTest.php | 28 +++++++++++++++ docs/query-builder.txt | 34 +++++++++++++++++++ 2 files changed, 62 insertions(+) diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index c6ef70592..74f576e32 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -555,6 +555,20 @@ public function testIncrement(): void $this->assertIsInt($result); } + public function testIncrementEach(): void + { + // begin increment each + $result = DB::table('movies') + ->where('title', 'Lost in Translation') + ->incrementEach([ + 'awards.wins' => 2, + 'imdb.votes' => 1050, + ]); + // end increment each + + $this->assertIsInt($result); + } + public function testDecrement(): void { // begin decrement @@ -566,6 +580,20 @@ public function testDecrement(): void $this->assertIsInt($result); } + public function testDecrementEach(): void + { + // begin decrement each + $result = DB::table('movies') + ->where('title', 'Dunkirk') + ->decrementEach([ + 'metacritic' => 1, + 'imdb.rating' => 0.4, + ]); + // end decrement each + + $this->assertIsInt($result); + } + public function testPush(): void { // begin push diff --git a/docs/query-builder.txt b/docs/query-builder.txt index 6b84f9e78..ebe5fd727 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -1125,6 +1125,23 @@ the ``imdb.votes`` field in the matched document: The ``increment()`` query builder method returns the number of documents that the operation updated. +Starting in {+odm-short+} v4.8, you can also use the ``incrementEach()`` query +builder method to increment multiple values in a single operation. The following +example uses the ``incrementEach()`` method to increase the values of the ``awards.wins`` +and ``imdb.votes`` fields in the matched document: + +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin increment each + :end-before: end increment each + +.. note:: + + If you pass a field to the ``increment()`` or ``incrementEach()`` method that + has no value or doesn't exist in the matched documents, these methods initialize + the specified field to the increment value. + .. _laravel-mongodb-query-builder-decrement: Decrement a Numerical Value Example @@ -1143,6 +1160,23 @@ matched document: The ``decrement()`` query builder method returns the number of documents that the operation updated. +Starting in {+odm-short+} v4.8, you can also use the ``decrementEach()`` query builder +method to decrement multiple values in a single operation. The following example uses +the ``decrementEach()`` method to decrease the values of the ``metacritic`` and ``imdb.rating`` +fields in the matched document: + +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin decrement each + :end-before: end decrement each + +.. note:: + + If you pass a field to the ``decrement()`` or ``decrementEach()`` method that + has no value or doesn't exist in the matched documents, these methods initialize + the specified field to the decrement value. + .. _laravel-mongodb-query-builder-push: Add an Array Element Example From f35d63277c837e09a65d43adbc8c827f6d9289c7 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Fri, 16 Aug 2024 10:56:48 -0400 Subject: [PATCH 330/446] DOCSP-41557: New v4.7 commands and methods (#3084) * DOCSP-41557: v4.7 commands and methods * reword, fixes * RR feedback * JT review * wording * fix --- docs/fundamentals/database-collection.txt | 111 +++++++++++++++++++++- 1 file changed, 106 insertions(+), 5 deletions(-) diff --git a/docs/fundamentals/database-collection.txt b/docs/fundamentals/database-collection.txt index 6b629d79e..7bbae4786 100644 --- a/docs/fundamentals/database-collection.txt +++ b/docs/fundamentals/database-collection.txt @@ -161,17 +161,118 @@ as in the preceding example, but the query is constructed by using the List Collections ---------------- -To see information about each of the collections in a database, call the -``listCollections()`` method. +You can take either of the following actions to see information +about the collections in a database: -The following example accesses a database connection, then -calls the ``listCollections()`` method to retrieve information about the -collections in the database: +- :ref:`laravel-list-coll-command` +- :ref:`laravel-list-coll-methods` + +.. _laravel-list-coll-command: + +Run a Shell Command +~~~~~~~~~~~~~~~~~~~ + +You can list the collections in a database by running the following +command in your shell from your project's root directory: + +.. code-block:: bash + + php artisan db:show + +This command outputs information about the configured database and lists its +collections under the ``Table`` header. For more information about the ``db:show`` +command, see `Laravel: New DB Commands `__ +on the official Laravel blog. + +.. _laravel-list-coll-methods: + +Call Database or Schema Methods +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can list the collections in a database by calling the following +methods in your application: + +- ``DB::listCollections()``: lists information about each collection by + using the query builder +- ``Schema::getTablesListing()``: lists the name of each collection by + using the schema builder +- ``Schema::getTables()``: lists the name and size of each collection by + using the schema builder + +.. note:: + + MongoDB is a schemaless database, so the preceding schema builder methods + query the database data rather than the schema. + +Example +``````` + +The following example accesses a database connection, then calls the +``listCollections()`` query builder method to retrieve information about +the collections in the database: .. code-block:: php $collections = DB::connection('mongodb')->getMongoDB()->listCollections(); +List Collection Fields +---------------------- + +You can take either of the following actions to see information +about each field in a collection: + +- :ref:`laravel-list-fields-command` +- :ref:`laravel-list-fields-methods` + +.. _laravel-list-fields-command: + +Run a Shell Command +~~~~~~~~~~~~~~~~~~~ + +You can see a list of fields in a collection by running the following +command in your shell from your project's root directory: + +.. code-block:: bash + + php artisan db:table + +This command outputs each collection field and its corresponding data type +under the ``Column`` header. For more information about the ``db:table`` +command, see `Laravel: New DB Commands `__ +on the official Laravel blog. + +.. _laravel-list-fields-methods: + +Call Schema Methods +~~~~~~~~~~~~~~~~~~~ + +You can list the fields in a collection by calling the ``Schema::getColumns()`` +schema builder method in your application. + +You can also use the following methods to return more information about the +collection fields: + +- ``Schema::hasColumn(string $, string $)``: checks if the specified field exists + in at least one document +- ``Schema::hasColumns(string $, string[] $)``: checks if each specified field exists + in at least one document + +.. note:: + + MongoDB is a schemaless database, so the preceding methods query the collection + data rather than the database schema. If the specified collection doesn't exist + or is empty, these methods return a value of ``false``. + +Example +``````` + +The following example passes a collection name to the ``Schema::getColumns()`` +method to retrieve each field in the ``flowers`` collection: + +.. code-block:: php + + $fields = Schema::getColumns('flowers'); + Create and Drop Collections --------------------------- From a453f8a210462e481bc23168dfeac21eee19261f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 20 Aug 2024 18:13:52 +0200 Subject: [PATCH 331/446] PHPORM-147 Make `id` an alias for `_id` (#3040) * PHPORM-147 Make id an alias for _id * Use id as primary key for DocumentModel * Recursively replace .id with ._id --- CHANGELOG.md | 4 + docs/includes/auth/PersonalAccessToken.php | 1 - .../eloquent-models/PlanetThirdParty.php | 1 - .../write-operations/WriteOperationsTest.php | 18 +- .../includes/usage-examples/DeleteOneTest.php | 2 +- docs/includes/usage-examples/FindManyTest.php | 2 +- docs/includes/usage-examples/FindOneTest.php | 4 +- .../includes/usage-examples/InsertOneTest.php | 2 +- .../includes/usage-examples/UpdateOneTest.php | 2 +- src/Auth/User.php | 1 - src/Eloquent/DocumentModel.php | 17 +- src/Eloquent/Model.php | 7 - src/Query/Builder.php | 134 ++++-- src/Relations/EmbedsMany.php | 10 +- src/Relations/EmbedsOne.php | 6 +- tests/AuthTest.php | 2 +- tests/EmbeddedRelationsTest.php | 48 +-- tests/HybridRelationsTest.php | 24 +- tests/ModelTest.php | 111 ++--- tests/Models/Address.php | 1 - tests/Models/Birthday.php | 1 - tests/Models/Client.php | 1 - tests/Models/Experience.php | 1 - tests/Models/Group.php | 3 +- tests/Models/Guarded.php | 1 - tests/Models/HiddenAnimal.php | 1 - tests/Models/IdIsBinaryUuid.php | 3 +- tests/Models/IdIsInt.php | 3 +- tests/Models/IdIsString.php | 3 +- tests/Models/Item.php | 1 - tests/Models/Label.php | 1 - tests/Models/Location.php | 1 - tests/Models/Photo.php | 1 - tests/Models/Role.php | 1 - tests/Models/Scoped.php | 1 - tests/Models/Skill.php | 1 - tests/Models/Soft.php | 1 - tests/Models/User.php | 5 +- tests/Query/BuilderTest.php | 117 +++--- tests/QueryBuilderTest.php | 67 +-- tests/QueryTest.php | 2 +- tests/QueueTest.php | 4 +- tests/RelationsTest.php | 386 +++++++++--------- tests/SessionTest.php | 33 ++ tests/Ticket/GH2489Test.php | 49 +++ tests/Ticket/GH2783Test.php | 2 +- tests/TransactionTest.php | 24 +- 47 files changed, 635 insertions(+), 476 deletions(-) create mode 100644 tests/SessionTest.php create mode 100644 tests/Ticket/GH2489Test.php diff --git a/CHANGELOG.md b/CHANGELOG.md index a6e7c9144..f0b8a5e27 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,10 @@ # Changelog All notable changes to this project will be documented in this file. +## [5.0.0] - next + +* **BREAKING CHANGE** Use `id` as an alias for `_id` in commands and queries for compatibility with Eloquent packages by @GromNaN in [#3040](https://github.com/mongodb/laravel-mongodb/pull/3040) + ## [4.8.0] - next * Add `Query\Builder::incrementEach()` and `decrementEach()` methods by @SmallRuralDog in [#2550](https://github.com/mongodb/laravel-mongodb/pull/2550) diff --git a/docs/includes/auth/PersonalAccessToken.php b/docs/includes/auth/PersonalAccessToken.php index 165758770..2b08d685f 100644 --- a/docs/includes/auth/PersonalAccessToken.php +++ b/docs/includes/auth/PersonalAccessToken.php @@ -11,6 +11,5 @@ class PersonalAccessToken extends SanctumToken protected $connection = 'mongodb'; protected $table = 'personal_access_tokens'; - protected $primaryKey = '_id'; protected $keyType = 'string'; } diff --git a/docs/includes/eloquent-models/PlanetThirdParty.php b/docs/includes/eloquent-models/PlanetThirdParty.php index 0f3bae638..79d120bba 100644 --- a/docs/includes/eloquent-models/PlanetThirdParty.php +++ b/docs/includes/eloquent-models/PlanetThirdParty.php @@ -10,6 +10,5 @@ class Planet extends CelestialBody use DocumentModel; protected $fillable = ['name', 'diameter']; - protected $primaryKey = '_id'; protected $keyType = 'string'; } diff --git a/docs/includes/fundamentals/write-operations/WriteOperationsTest.php b/docs/includes/fundamentals/write-operations/WriteOperationsTest.php index 39143ac09..b6d54fec4 100644 --- a/docs/includes/fundamentals/write-operations/WriteOperationsTest.php +++ b/docs/includes/fundamentals/write-operations/WriteOperationsTest.php @@ -162,7 +162,7 @@ public function testModelUpdateFluent(): void // begin model update one fluent $concert = Concert::where(['performer' => 'Brad Mehldau']) - ->orderBy('_id') + ->orderBy('id') ->first() ->update(['venue' => 'Manchester Arena', 'ticketsSold' => 9543]); // end model update one fluent @@ -370,7 +370,7 @@ public function testModelDeleteById(): void $data = [ [ - '_id' => 'CH-0401242000', + 'id' => 'CH-0401242000', 'performer' => 'Mitsuko Uchida', 'venue' => 'Carnegie Hall', 'genres' => ['classical'], @@ -378,7 +378,7 @@ public function testModelDeleteById(): void 'performanceDate' => new UTCDateTime(Carbon::create(2024, 4, 1, 20, 0, 0, 'EST')), ], [ - '_id' => 'MSG-0212252000', + 'id' => 'MSG-0212252000', 'performer' => 'Brad Mehldau', 'venue' => 'Philharmonie de Paris', 'genres' => [ 'jazz', 'post-bop' ], @@ -386,7 +386,7 @@ public function testModelDeleteById(): void 'performanceDate' => new UTCDateTime(Carbon::create(2025, 2, 12, 20, 0, 0, 'CET')), ], [ - '_id' => 'MSG-021222000', + 'id' => 'MSG-021222000', 'performer' => 'Billy Joel', 'venue' => 'Madison Square Garden', 'genres' => [ 'rock', 'soft rock', 'pop rock' ], @@ -394,7 +394,7 @@ public function testModelDeleteById(): void 'performanceDate' => new UTCDateTime(Carbon::create(2025, 2, 12, 20, 0, 0, 'CET')), ], [ - '_id' => 'SF-06302000', + 'id' => 'SF-06302000', 'performer' => 'The Rolling Stones', 'venue' => 'Soldier Field', 'genres' => [ 'rock', 'pop', 'blues' ], @@ -478,22 +478,22 @@ public function testModelDeleteMultipleById(): void Concert::truncate(); $data = [ [ - '_id' => 3, + 'id' => 3, 'performer' => 'Mitsuko Uchida', 'venue' => 'Carnegie Hall', ], [ - '_id' => 5, + 'id' => 5, 'performer' => 'Brad Mehldau', 'venue' => 'Philharmonie de Paris', ], [ - '_id' => 7, + 'id' => 7, 'performer' => 'Billy Joel', 'venue' => 'Madison Square Garden', ], [ - '_id' => 9, + 'id' => 9, 'performer' => 'The Rolling Stones', 'venue' => 'Soldier Field', ], diff --git a/docs/includes/usage-examples/DeleteOneTest.php b/docs/includes/usage-examples/DeleteOneTest.php index 1a2acd4e0..b867dfc1f 100644 --- a/docs/includes/usage-examples/DeleteOneTest.php +++ b/docs/includes/usage-examples/DeleteOneTest.php @@ -27,7 +27,7 @@ public function testDeleteOne(): void // begin-delete-one $deleted = Movie::where('title', 'Quiz Show') - ->orderBy('_id') + ->orderBy('id') ->limit(1) ->delete(); diff --git a/docs/includes/usage-examples/FindManyTest.php b/docs/includes/usage-examples/FindManyTest.php index 18324c62d..191ae9719 100644 --- a/docs/includes/usage-examples/FindManyTest.php +++ b/docs/includes/usage-examples/FindManyTest.php @@ -35,7 +35,7 @@ public function testFindMany(): void // begin-find $movies = Movie::where('runtime', '>', 900) - ->orderBy('_id') + ->orderBy('id') ->get(); // end-find diff --git a/docs/includes/usage-examples/FindOneTest.php b/docs/includes/usage-examples/FindOneTest.php index 98452a6a6..8472727be 100644 --- a/docs/includes/usage-examples/FindOneTest.php +++ b/docs/includes/usage-examples/FindOneTest.php @@ -24,13 +24,13 @@ public function testFindOne(): void // begin-find-one $movie = Movie::where('directors', 'Rob Reiner') - ->orderBy('_id') + ->orderBy('id') ->first(); echo $movie->toJson(); // end-find-one $this->assertInstanceOf(Movie::class, $movie); - $this->expectOutputRegex('/^{"_id":"[a-z0-9]{24}","title":"The Shawshank Redemption","directors":\["Frank Darabont","Rob Reiner"\]}$/'); + $this->expectOutputRegex('/^{"_id":"[a-z0-9]{24}","title":"The Shawshank Redemption","directors":\["Frank Darabont","Rob Reiner"\],"id":"[a-z0-9]{24}"}$/'); } } diff --git a/docs/includes/usage-examples/InsertOneTest.php b/docs/includes/usage-examples/InsertOneTest.php index 15eadf419..7e4de48d6 100644 --- a/docs/includes/usage-examples/InsertOneTest.php +++ b/docs/includes/usage-examples/InsertOneTest.php @@ -30,6 +30,6 @@ public function testInsertOne(): void // end-insert-one $this->assertInstanceOf(Movie::class, $movie); - $this->expectOutputRegex('/^{"title":"Marriage Story","year":2019,"runtime":136,"updated_at":".{27}","created_at":".{27}","_id":"[a-z0-9]{24}"}$/'); + $this->expectOutputRegex('/^{"title":"Marriage Story","year":2019,"runtime":136,"updated_at":".{27}","created_at":".{27}","id":"[a-z0-9]{24}"}$/'); } } diff --git a/docs/includes/usage-examples/UpdateOneTest.php b/docs/includes/usage-examples/UpdateOneTest.php index e1f864170..4bf720a75 100644 --- a/docs/includes/usage-examples/UpdateOneTest.php +++ b/docs/includes/usage-examples/UpdateOneTest.php @@ -30,7 +30,7 @@ public function testUpdateOne(): void // begin-update-one $updates = Movie::where('title', 'Carol') - ->orderBy('_id') + ->orderBy('id') ->first() ->update([ 'imdb' => [ diff --git a/src/Auth/User.php b/src/Auth/User.php index a58a898ad..e37fefd3c 100644 --- a/src/Auth/User.php +++ b/src/Auth/User.php @@ -11,6 +11,5 @@ class User extends BaseUser { use DocumentModel; - protected $primaryKey = '_id'; protected $keyType = 'string'; } diff --git a/src/Eloquent/DocumentModel.php b/src/Eloquent/DocumentModel.php index cbc388b22..af3aec3c2 100644 --- a/src/Eloquent/DocumentModel.php +++ b/src/Eloquent/DocumentModel.php @@ -46,6 +46,7 @@ use function str_contains; use function str_starts_with; use function strcmp; +use function strlen; use function trigger_error; use function var_export; @@ -79,9 +80,7 @@ public function getIdAttribute($value = null) { // If we don't have a value for 'id', we will use the MongoDB '_id' value. // This allows us to work with models in a more sql-like way. - if (! $value && array_key_exists('_id', $this->attributes)) { - $value = $this->attributes['_id']; - } + $value ??= $this->attributes['id'] ?? $this->attributes['_id'] ?? null; // Convert ObjectID to string. if ($value instanceof ObjectID) { @@ -248,10 +247,8 @@ public function setAttribute($key, $value) } // Convert _id to ObjectID. - if ($key === '_id' && is_string($value)) { - $builder = $this->newBaseQueryBuilder(); - - $value = $builder->convertKey($value); + if (($key === '_id' || $key === 'id') && is_string($value) && strlen($value) === 24) { + $value = $this->newBaseQueryBuilder()->convertKey($value); } // Support keys in dot notation. @@ -729,12 +726,16 @@ protected function isBSON(mixed $value): bool */ public function save(array $options = []) { - // SQL databases would use autoincrement the id field if set to null. + // SQL databases would autoincrement the id field if set to null. // Apply the same behavior to MongoDB with _id only, otherwise null would be stored. if (array_key_exists('_id', $this->attributes) && $this->attributes['_id'] === null) { unset($this->attributes['_id']); } + if (array_key_exists('id', $this->attributes) && $this->attributes['id'] === null) { + unset($this->attributes['id']); + } + $saved = parent::save($options); // Clear list of unset fields diff --git a/src/Eloquent/Model.php b/src/Eloquent/Model.php index fcb9c4f04..54eef1dc5 100644 --- a/src/Eloquent/Model.php +++ b/src/Eloquent/Model.php @@ -16,13 +16,6 @@ abstract class Model extends BaseModel { use DocumentModel; - /** - * The primary key for the model. - * - * @var string - */ - protected $primaryKey = '_id'; - /** * The primary key type. * diff --git a/src/Query/Builder.php b/src/Query/Builder.php index ddc2413d8..6168159df 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -298,6 +298,7 @@ public function toMql(): array } $wheres = $this->compileWheres(); + $wheres = $this->aliasIdForQuery($wheres); // Use MongoDB's aggregation framework when using grouping or aggregation functions. if ($this->groups || $this->aggregate) { @@ -375,7 +376,7 @@ public function toMql(): array // Apply order and limit if ($this->orders) { - $pipeline[] = ['$sort' => $this->orders]; + $pipeline[] = ['$sort' => $this->aliasIdForQuery($this->orders)]; } if ($this->offset) { @@ -416,7 +417,7 @@ public function toMql(): array // Normal query // Convert select columns to simple projections. - $projection = array_fill_keys($columns, true); + $projection = $this->aliasIdForQuery(array_fill_keys($columns, true)); // Add custom projections. if ($this->projections) { @@ -431,7 +432,7 @@ public function toMql(): array } if ($this->orders) { - $options['sort'] = $this->orders; + $options['sort'] = $this->aliasIdForQuery($this->orders); } if ($this->offset) { @@ -506,7 +507,7 @@ public function getFresh($columns = [], $returnLazy = false) if ($returnLazy) { return LazyCollection::make(function () use ($result) { foreach ($result as $item) { - yield $item; + yield $this->aliasIdForResult($item); } }); } @@ -515,6 +516,12 @@ public function getFresh($columns = [], $returnLazy = false) $result = $result->toArray(); } + foreach ($result as &$document) { + if (is_array($document)) { + $document = $this->aliasIdForResult($document); + } + } + return new Collection($result); } @@ -593,7 +600,7 @@ public function aggregate($function = null, $columns = ['*']) /** @inheritdoc */ public function exists() { - return $this->first(['_id']) !== null; + return $this->first(['id']) !== null; } /** @inheritdoc */ @@ -682,6 +689,18 @@ public function insert(array $values) $values = [$values]; } + // Compatibility with Eloquent queries that uses "id" instead of MongoDB's _id + foreach ($values as &$document) { + if (isset($document['id'])) { + if (isset($document['_id']) && $document['_id'] !== $document['id']) { + throw new InvalidArgumentException('Cannot insert document with different "id" and "_id" values'); + } + + $document['_id'] = $document['id']; + unset($document['id']); + } + } + $options = $this->inheritConnectionOptions(); $result = $this->collection->insertMany($values, $options); @@ -694,17 +713,18 @@ public function insertGetId(array $values, $sequence = null) { $options = $this->inheritConnectionOptions(); + $values = $this->aliasIdForQuery($values); + $result = $this->collection->insertOne($values, $options); if (! $result->isAcknowledged()) { return null; } - if ($sequence === null || $sequence === '_id') { - return $result->getInsertedId(); - } - - return $values[$sequence]; + return match ($sequence) { + '_id', 'id', null => $result->getInsertedId(), + default => $values[$sequence], + }; } /** @inheritdoc */ @@ -720,7 +740,12 @@ public function update(array $values, array $options = []) unset($values[$key]); } - $options = $this->inheritConnectionOptions($options); + // Since "id" is an alias for "_id", we prevent updating it + foreach ($values as $fields) { + if (array_key_exists('id', $fields)) { + throw new InvalidArgumentException('Cannot update "id" field.'); + } + } return $this->performUpdate($values, $options); } @@ -821,18 +846,6 @@ public function decrementEach(array $columns, array $extra = [], array $options return $this->incrementEach($decrement, $extra, $options); } - /** @inheritdoc */ - public function chunkById($count, callable $callback, $column = '_id', $alias = null) - { - return parent::chunkById($count, $callback, $column, $alias); - } - - /** @inheritdoc */ - public function forPageAfterId($perPage = 15, $lastId = 0, $column = '_id') - { - return parent::forPageAfterId($perPage, $lastId, $column); - } - /** @inheritdoc */ public function pluck($column, $key = null) { @@ -1048,21 +1061,26 @@ public function runPaginationCountQuery($columns = ['*']) /** * Perform an update query. * - * @param array $query - * * @return int */ - protected function performUpdate($query, array $options = []) + protected function performUpdate(array $update, array $options = []) { // Update multiple items by default. if (! array_key_exists('multiple', $options)) { $options['multiple'] = true; } + // Since "id" is an alias for "_id", we prevent updating it + foreach ($update as $operator => $fields) { + if (array_key_exists('id', $fields)) { + throw new InvalidArgumentException('Cannot update "id" field.'); + } + } + $options = $this->inheritConnectionOptions($options); $wheres = $this->compileWheres(); - $result = $this->collection->updateMany($wheres, $query, $options); + $result = $this->collection->updateMany($wheres, $update, $options); if ($result->isAcknowledged()) { return $result->getModifiedCount() ? $result->getModifiedCount() : $result->getUpsertedCount(); } @@ -1155,16 +1173,21 @@ protected function compileWheres(): array // Convert column name to string to use as array key if (isset($where['column'])) { $where['column'] = (string) $where['column']; - } - // Convert id's. - if (isset($where['column']) && ($where['column'] === '_id' || str_ends_with($where['column'], '._id'))) { - if (isset($where['values'])) { - // Multiple values. - $where['values'] = array_map($this->convertKey(...), $where['values']); - } elseif (isset($where['value'])) { - // Single value. - $where['value'] = $this->convertKey($where['value']); + // Compatibility with Eloquent queries that uses "id" instead of MongoDB's _id + if ($where['column'] === 'id') { + $where['column'] = '_id'; + } + + // Convert id's. + if ($where['column'] === '_id' || str_ends_with($where['column'], '._id')) { + if (isset($where['values'])) { + // Multiple values. + $where['values'] = array_map($this->convertKey(...), $where['values']); + } elseif (isset($where['value'])) { + // Single value. + $where['value'] = $this->convertKey($where['value']); + } } } @@ -1604,4 +1627,43 @@ public function orWhereIntegerNotInRaw($column, $values, $boolean = 'and') { throw new BadMethodCallException('This method is not supported by MongoDB'); } + + private function aliasIdForQuery(array $values): array + { + if (array_key_exists('id', $values)) { + $values['_id'] = $values['id']; + unset($values['id']); + } + + foreach ($values as $key => $value) { + if (is_string($key) && str_ends_with($key, '.id')) { + $values[substr($key, 0, -3) . '._id'] = $value; + unset($values[$key]); + } + } + + foreach ($values as &$value) { + if (is_array($value)) { + $value = $this->aliasIdForQuery($value); + } + } + + return $values; + } + + private function aliasIdForResult(array $values): array + { + if (array_key_exists('_id', $values) && ! array_key_exists('id', $values)) { + $values['id'] = $values['_id']; + //unset($values['_id']); + } + + foreach ($values as $key => $value) { + if (is_array($value)) { + $values[$key] = $this->aliasIdForResult($value); + } + } + + return $values; + } } diff --git a/src/Relations/EmbedsMany.php b/src/Relations/EmbedsMany.php index 72c77b598..e4bbf535f 100644 --- a/src/Relations/EmbedsMany.php +++ b/src/Relations/EmbedsMany.php @@ -46,9 +46,9 @@ public function getResults() */ public function performInsert(Model $model) { - // Generate a new key if needed. - if ($model->getKeyName() === '_id' && ! $model->getKey()) { - $model->setAttribute('_id', new ObjectID()); + // Create a new key if needed. + if (($model->getKeyName() === '_id' || $model->getKeyName() === 'id') && ! $model->getKey()) { + $model->setAttribute($model->getKeyName(), new ObjectID()); } // For deeply nested documents, let the parent handle the changes. @@ -249,8 +249,8 @@ public function attach(Model $model) protected function associateNew($model) { // Create a new key if needed. - if ($model->getKeyName() === '_id' && ! $model->getAttribute('_id')) { - $model->setAttribute('_id', new ObjectID()); + if (($model->getKeyName() === '_id' || $model->getKeyName() === 'id') && ! $model->getKey()) { + $model->setAttribute($model->getKeyName(), new ObjectID()); } $records = $this->getEmbedded(); diff --git a/src/Relations/EmbedsOne.php b/src/Relations/EmbedsOne.php index 678141cf1..95d5cc15d 100644 --- a/src/Relations/EmbedsOne.php +++ b/src/Relations/EmbedsOne.php @@ -42,9 +42,9 @@ public function getEager() */ public function performInsert(Model $model) { - // Generate a new key if needed. - if ($model->getKeyName() === '_id' && ! $model->getKey()) { - $model->setAttribute('_id', new ObjectID()); + // Create a new key if needed. + if (($model->getKeyName() === '_id' || $model->getKeyName() === 'id') && ! $model->getKey()) { + $model->setAttribute($model->getKeyName(), new ObjectID()); } // For deeply nested documents, let the parent handle the changes. diff --git a/tests/AuthTest.php b/tests/AuthTest.php index 61710bf74..d2b3a9675 100644 --- a/tests/AuthTest.php +++ b/tests/AuthTest.php @@ -52,7 +52,7 @@ public function testRemindOld() $broker->sendResetLink( ['email' => 'john.doe@example.com'], function ($actualUser, $actualToken) use ($user, &$token) { - $this->assertEquals($user->_id, $actualUser->_id); + $this->assertEquals($user->id, $actualUser->id); // Store token for later use $token = $actualToken; }, diff --git a/tests/EmbeddedRelationsTest.php b/tests/EmbeddedRelationsTest.php index 22e6e8d08..8ee8297f7 100644 --- a/tests/EmbeddedRelationsTest.php +++ b/tests/EmbeddedRelationsTest.php @@ -48,15 +48,15 @@ public function testEmbedsManySave() $this->assertEquals(['London'], $user->addresses->pluck('city')->all()); $this->assertInstanceOf(DateTime::class, $address->created_at); $this->assertInstanceOf(DateTime::class, $address->updated_at); - $this->assertNotNull($address->_id); - $this->assertIsString($address->_id); + $this->assertNotNull($address->id); + $this->assertIsString($address->id); $raw = $address->getAttributes(); - $this->assertInstanceOf(ObjectId::class, $raw['_id']); + $this->assertInstanceOf(ObjectId::class, $raw['id']); $address = $user->addresses()->save(new Address(['city' => 'Paris'])); - $user = User::find($user->_id); + $user = User::find($user->id); $this->assertEquals(['London', 'Paris'], $user->addresses->pluck('city')->all()); $address->setEventDispatcher($events = Mockery::mock(Dispatcher::class)); @@ -82,7 +82,7 @@ public function testEmbedsManySave() $this->assertEquals(2, $user->addresses()->count()); $this->assertEquals(['London', 'New York'], $user->addresses->pluck('city')->all()); - $freshUser = User::find($user->_id); + $freshUser = User::find($user->id); $this->assertEquals(['London', 'New York'], $freshUser->addresses->pluck('city')->all()); $address = $user->addresses->first(); @@ -92,7 +92,7 @@ public function testEmbedsManySave() $this->assertInstanceOf(User::class, $address->user); $this->assertEmpty($address->relationsToArray()); // prevent infinite loop - $user = User::find($user->_id); + $user = User::find($user->id); $user->addresses()->save(new Address(['city' => 'Bruxelles'])); $this->assertEquals(['London', 'New York', 'Bruxelles'], $user->addresses->pluck('city')->all()); @@ -101,7 +101,7 @@ public function testEmbedsManySave() $user->addresses()->save($address); $this->assertEquals(['London', 'Manhattan', 'Bruxelles'], $user->addresses->pluck('city')->all()); - $freshUser = User::find($user->_id); + $freshUser = User::find($user->id); $this->assertEquals(['London', 'Manhattan', 'Bruxelles'], $freshUser->addresses->pluck('city')->all()); } @@ -122,16 +122,16 @@ public function testEmbedsManyAssociate() $user->addresses()->associate($address); $this->assertEquals(['London'], $user->addresses->pluck('city')->all()); - $this->assertNotNull($address->_id); + $this->assertNotNull($address->id); - $freshUser = User::find($user->_id); + $freshUser = User::find($user->id); $this->assertEquals([], $freshUser->addresses->pluck('city')->all()); $address->city = 'Londinium'; $user->addresses()->associate($address); $this->assertEquals(['Londinium'], $user->addresses->pluck('city')->all()); - $freshUser = User::find($user->_id); + $freshUser = User::find($user->id); $this->assertEquals([], $freshUser->addresses->pluck('city')->all()); } @@ -162,7 +162,7 @@ public function testEmbedsManyDuplicate() $this->assertEquals(1, $user->addresses->count()); $this->assertEquals(['Paris'], $user->addresses->pluck('city')->all()); - $user->addresses()->create(['_id' => $address->_id, 'city' => 'Bruxelles']); + $user->addresses()->create(['id' => $address->id, 'city' => 'Bruxelles']); $this->assertEquals(1, $user->addresses->count()); $this->assertEquals(['Bruxelles'], $user->addresses->pluck('city')->all()); } @@ -172,21 +172,21 @@ public function testEmbedsManyCreate() $user = User::create([]); $address = $user->addresses()->create(['city' => 'Bruxelles']); $this->assertInstanceOf(Address::class, $address); - $this->assertIsString($address->_id); + $this->assertIsString($address->id); $this->assertEquals(['Bruxelles'], $user->addresses->pluck('city')->all()); $raw = $address->getAttributes(); - $this->assertInstanceOf(ObjectId::class, $raw['_id']); + $this->assertInstanceOf(ObjectId::class, $raw['id']); $freshUser = User::find($user->id); $this->assertEquals(['Bruxelles'], $freshUser->addresses->pluck('city')->all()); $user = User::create([]); - $address = $user->addresses()->create(['_id' => '', 'city' => 'Bruxelles']); - $this->assertIsString($address->_id); + $address = $user->addresses()->create(['id' => '', 'city' => 'Bruxelles']); + $this->assertIsString($address->id); $raw = $address->getAttributes(); - $this->assertInstanceOf(ObjectId::class, $raw['_id']); + $this->assertInstanceOf(ObjectId::class, $raw['id']); } public function testEmbedsManyCreateMany() @@ -222,7 +222,7 @@ public function testEmbedsManyDestroy() ->once() ->with('eloquent.deleted: ' . $address::class, Mockery::type(Address::class)); - $user->addresses()->destroy($address->_id); + $user->addresses()->destroy($address->id); $this->assertEquals(['Bristol', 'Bruxelles'], $user->addresses->pluck('city')->all()); $address->unsetEventDispatcher(); @@ -237,7 +237,7 @@ public function testEmbedsManyDestroy() $freshUser = User::find($user->id); $this->assertEquals(['Bruxelles', 'Paris', 'San Francisco'], $freshUser->addresses->pluck('city')->all()); - $ids = $user->addresses->pluck('_id'); + $ids = $user->addresses->pluck('id'); $user->addresses()->destroy($ids); $this->assertEquals([], $user->addresses->pluck('city')->all()); @@ -414,13 +414,13 @@ public function testEmbedsManyFindOrContains() $address1 = $user->addresses()->save(new Address(['city' => 'New York'])); $address2 = $user->addresses()->save(new Address(['city' => 'Paris'])); - $address = $user->addresses()->find($address1->_id); + $address = $user->addresses()->find($address1->id); $this->assertEquals($address->city, $address1->city); - $address = $user->addresses()->find($address2->_id); + $address = $user->addresses()->find($address2->id); $this->assertEquals($address->city, $address2->city); - $this->assertTrue($user->addresses()->contains($address2->_id)); + $this->assertTrue($user->addresses()->contains($address2->id)); $this->assertFalse($user->addresses()->contains('123')); } @@ -552,11 +552,11 @@ public function testEmbedsOne() $this->assertEquals('Mark Doe', $user->father->name); $this->assertInstanceOf(DateTime::class, $father->created_at); $this->assertInstanceOf(DateTime::class, $father->updated_at); - $this->assertNotNull($father->_id); - $this->assertIsString($father->_id); + $this->assertNotNull($father->id); + $this->assertIsString($father->id); $raw = $father->getAttributes(); - $this->assertInstanceOf(ObjectId::class, $raw['_id']); + $this->assertInstanceOf(ObjectId::class, $raw['id']); $father->setEventDispatcher($events = Mockery::mock(Dispatcher::class)); $events->shouldReceive('dispatch')->with('eloquent.retrieved: ' . $father::class, Mockery::any()); diff --git a/tests/HybridRelationsTest.php b/tests/HybridRelationsTest.php index 5253784c9..71958d27d 100644 --- a/tests/HybridRelationsTest.php +++ b/tests/HybridRelationsTest.php @@ -83,7 +83,7 @@ public function testSqlRelations() // MongoDB has many $book = new SqlBook(['title' => 'Game of Thrones']); $user->sqlBooks()->save($book); - $user = User::find($user->_id); // refetch + $user = User::find($user->id); // refetch $this->assertCount(1, $user->sqlBooks); // SQL belongs to @@ -93,7 +93,7 @@ public function testSqlRelations() // MongoDB has one $role = new SqlRole(['type' => 'admin']); $user->sqlRole()->save($role); - $user = User::find($user->_id); // refetch + $user = User::find($user->id); // refetch $this->assertEquals('admin', $user->sqlRole->type); // SQL belongs to @@ -239,16 +239,16 @@ public function testHybridBelongsToMany() // sync (pivot is empty) $skill->sqlUsers()->sync([$user->id, $user2->id]); - $check = Skill::query()->find($skill->_id); + $check = Skill::query()->find($skill->id); $this->assertEquals(2, $check->sqlUsers->count()); // sync (pivot is not empty) $skill->sqlUsers()->sync($user); - $check = Skill::query()->find($skill->_id); + $check = Skill::query()->find($skill->id); $this->assertEquals(1, $check->sqlUsers->count()); // Inverse sync (pivot is empty) - $user->skills()->sync([$skill->_id, $skill2->_id]); + $user->skills()->sync([$skill->id, $skill2->id]); $check = SqlUser::find($user->id); $this->assertEquals(2, $check->skills->count()); @@ -288,7 +288,7 @@ public function testHybridMorphToManySqlModelToMongoModel() $label2 = Label::query()->create(['name' => 'MongoDB']); // MorphToMany (pivot is empty) - $user->labels()->sync([$label->_id, $label2->_id]); + $user->labels()->sync([$label->id, $label2->id]); $check = SqlUser::query()->find($user->id); $this->assertEquals(2, $check->labels->count()); @@ -308,12 +308,12 @@ public function testHybridMorphToManySqlModelToMongoModel() // Inverse MorphToMany (pivot is empty) $label->sqlUsers()->sync([$user->id, $user2->id]); - $check = Label::query()->find($label->_id); + $check = Label::query()->find($label->id); $this->assertEquals(2, $check->sqlUsers->count()); // Inverse MorphToMany (pivot is empty) $label->sqlUsers()->sync([$user->id, $user2->id]); - $check = Label::query()->find($label->_id); + $check = Label::query()->find($label->id); $this->assertEquals(2, $check->sqlUsers->count()); } @@ -340,21 +340,21 @@ public function testHybridMorphToManyMongoModelToSqlModel() // MorphToMany (pivot is empty) $experience->sqlUsers()->sync([$user->id, $user2->id]); - $check = Experience::query()->find($experience->_id); + $check = Experience::query()->find($experience->id); $this->assertEquals(2, $check->sqlUsers->count()); // MorphToMany (pivot is not empty) $experience->sqlUsers()->sync([$user->id]); - $check = Experience::query()->find($experience->_id); + $check = Experience::query()->find($experience->id); $this->assertEquals(1, $check->sqlUsers->count()); // Inverse MorphToMany (pivot is empty) - $user->experiences()->sync([$experience->_id, $experience2->_id]); + $user->experiences()->sync([$experience->id, $experience2->id]); $check = SqlUser::query()->find($user->id); $this->assertEquals(2, $check->experiences->count()); // Inverse MorphToMany (pivot is not empty) - $user->experiences()->sync([$experience->_id]); + $user->experiences()->sync([$experience->id]); $check = SqlUser::query()->find($user->id); $this->assertEquals(1, $check->experiences->count()); diff --git a/tests/ModelTest.php b/tests/ModelTest.php index 57e49574f..6903ce64c 100644 --- a/tests/ModelTest.php +++ b/tests/ModelTest.php @@ -63,7 +63,7 @@ public function testNewModel(): void $this->assertInstanceOf(Connection::class, $user->getConnection()); $this->assertFalse($user->exists); $this->assertEquals('users', $user->getTable()); - $this->assertEquals('_id', $user->getKeyName()); + $this->assertEquals('id', $user->getKeyName()); } public function testQualifyColumn(): void @@ -89,14 +89,14 @@ public function testInsert(): void $this->assertTrue($user->exists); $this->assertEquals(1, User::count()); - $this->assertTrue(isset($user->_id)); - $this->assertIsString($user->_id); - $this->assertNotEquals('', (string) $user->_id); - $this->assertNotEquals(0, strlen((string) $user->_id)); + $this->assertTrue(isset($user->id)); + $this->assertIsString($user->id); + $this->assertNotEquals('', (string) $user->id); + $this->assertNotEquals(0, strlen((string) $user->id)); $this->assertInstanceOf(Carbon::class, $user->created_at); $raw = $user->getAttributes(); - $this->assertInstanceOf(ObjectID::class, $raw['_id']); + $this->assertInstanceOf(ObjectID::class, $raw['id']); $this->assertEquals('John Doe', $user->name); $this->assertEquals(35, $user->age); @@ -111,9 +111,9 @@ public function testUpdate(): void $user->save(); $raw = $user->getAttributes(); - $this->assertInstanceOf(ObjectID::class, $raw['_id']); + $this->assertInstanceOf(ObjectID::class, $raw['id']); - $check = User::find($user->_id); + $check = User::find($user->id); $this->assertInstanceOf(User::class, $check); $check->age = 36; $check->save(); @@ -129,16 +129,16 @@ public function testUpdate(): void $user->update(['age' => 20]); $raw = $user->getAttributes(); - $this->assertInstanceOf(ObjectID::class, $raw['_id']); + $this->assertInstanceOf(ObjectID::class, $raw['id']); - $check = User::find($user->_id); + $check = User::find($user->id); $this->assertEquals(20, $check->age); $check->age = 24; $check->fullname = 'Hans Thomas'; // new field $check->save(); - $check = User::find($user->_id); + $check = User::find($user->id); $this->assertEquals(24, $check->age); $this->assertEquals('Hans Thomas', $check->fullname); } @@ -180,46 +180,46 @@ public function testUpsert() public function testManualStringId(): void { $user = new User(); - $user->_id = '4af9f23d8ead0e1d32000000'; + $user->id = '4af9f23d8ead0e1d32000000'; $user->name = 'John Doe'; $user->title = 'admin'; $user->age = 35; $user->save(); $this->assertTrue($user->exists); - $this->assertEquals('4af9f23d8ead0e1d32000000', $user->_id); + $this->assertEquals('4af9f23d8ead0e1d32000000', $user->id); $raw = $user->getAttributes(); - $this->assertInstanceOf(ObjectID::class, $raw['_id']); + $this->assertInstanceOf(ObjectID::class, $raw['id']); $user = new User(); - $user->_id = 'customId'; + $user->id = 'customId'; $user->name = 'John Doe'; $user->title = 'admin'; $user->age = 35; $user->save(); $this->assertTrue($user->exists); - $this->assertEquals('customId', $user->_id); + $this->assertEquals('customId', $user->id); $raw = $user->getAttributes(); - $this->assertIsString($raw['_id']); + $this->assertIsString($raw['id']); } public function testManualIntId(): void { $user = new User(); - $user->_id = 1; + $user->id = 1; $user->name = 'John Doe'; $user->title = 'admin'; $user->age = 35; $user->save(); $this->assertTrue($user->exists); - $this->assertEquals(1, $user->_id); + $this->assertEquals(1, $user->id); $raw = $user->getAttributes(); - $this->assertIsInt($raw['_id']); + $this->assertIsInt($raw['id']); } public function testDelete(): void @@ -267,11 +267,11 @@ public function testFind(): void $user->age = 35; $user->save(); - $check = User::find($user->_id); + $check = User::find($user->id); $this->assertInstanceOf(User::class, $check); $this->assertTrue(Model::isDocumentModel($check)); $this->assertTrue($check->exists); - $this->assertEquals($user->_id, $check->_id); + $this->assertEquals($user->id, $check->id); $this->assertEquals('John Doe', $check->name); $this->assertEquals(35, $check->age); @@ -339,7 +339,7 @@ public function testCreate(): void $check = User::where('name', 'Jane Poe')->first(); $this->assertInstanceOf(User::class, $check); - $this->assertEquals($user->_id, $check->_id); + $this->assertEquals($user->id, $check->id); } public function testDestroy(): void @@ -350,7 +350,7 @@ public function testDestroy(): void $user->age = 35; $user->save(); - User::destroy((string) $user->_id); + User::destroy((string) $user->id); $this->assertEquals(0, User::count()); } @@ -367,7 +367,7 @@ public function testTouch(): void sleep(1); $user->touch(); - $check = User::find($user->_id); + $check = User::find($user->id); $this->assertInstanceOf(User::class, $check); $this->assertNotEquals($old, $check->updated_at); @@ -412,12 +412,12 @@ public function testPrimaryKey(string $model, $id, $expected, bool $expectedFoun $expectedType = get_debug_type($expected); $document = new $model(); - $this->assertEquals('_id', $document->getKeyName()); + $this->assertEquals('id', $document->getKeyName()); - $document->_id = $id; + $document->id = $id; $document->save(); - $this->assertSame($expectedType, get_debug_type($document->_id)); - $this->assertEquals($expected, $document->_id); + $this->assertSame($expectedType, get_debug_type($document->id)); + $this->assertEquals($expected, $document->id); $this->assertSame($expectedType, get_debug_type($document->getKey())); $this->assertEquals($expected, $document->getKey()); @@ -425,8 +425,8 @@ public function testPrimaryKey(string $model, $id, $expected, bool $expectedFoun if ($expectedFound) { $this->assertNotNull($check, 'Not found'); - $this->assertSame($expectedType, get_debug_type($check->_id)); - $this->assertEquals($id, $check->_id); + $this->assertSame($expectedType, get_debug_type($check->id)); + $this->assertEquals($id, $check->id); $this->assertSame($expectedType, get_debug_type($check->getKey())); $this->assertEquals($id, $check->getKey()); } else { @@ -534,10 +534,10 @@ public function testToArray(): void $array = $item->toArray(); $keys = array_keys($array); sort($keys); - $this->assertEquals(['_id', 'created_at', 'name', 'type', 'updated_at'], $keys); + $this->assertEquals(['created_at', 'id', 'name', 'type', 'updated_at'], $keys); $this->assertIsString($array['created_at']); $this->assertIsString($array['updated_at']); - $this->assertIsString($array['_id']); + $this->assertIsString($array['id']); } public function testUnset(): void @@ -559,8 +559,8 @@ public function testUnset(): void $this->assertTrue(isset($user2->note2)); // Re-fetch to be sure - $user1 = User::find($user1->_id); - $user2 = User::find($user2->_id); + $user1 = User::find($user1->id); + $user2 = User::find($user2->id); $this->assertFalse(isset($user1->note1)); $this->assertTrue(isset($user1->note2)); @@ -574,7 +574,7 @@ public function testUnset(): void $this->assertFalse(isset($user2->note2)); // Re-re-fetch to be sure - $user2 = User::find($user2->_id); + $user2 = User::find($user2->id); $this->assertFalse(isset($user2->note1)); $this->assertFalse(isset($user2->note2)); @@ -622,14 +622,14 @@ public function testUnsetAndSet(): void $this->assertSame(['note1' => 'GHI'], $user->getDirty()); // Fetch to be sure the changes are not persisted yet - $userCheck = User::find($user->_id); + $userCheck = User::find($user->id); $this->assertSame('ABC', $userCheck['note1']); // Persist the changes $user->save(); // Re-fetch to be sure - $user = User::find($user->_id); + $user = User::find($user->id); $this->assertTrue(isset($user->note1)); $this->assertSame('GHI', $user->note1); @@ -656,7 +656,7 @@ public function testUnsetDotAttributes(): void $this->assertTrue(isset($user->notes['note2'])); // Re-fetch to be sure - $user = User::find($user->_id); + $user = User::find($user->id); $this->assertFalse(isset($user->notes['note1'])); $this->assertTrue(isset($user->notes['note2'])); @@ -673,7 +673,7 @@ public function testUnsetDotAttributes(): void $this->assertFalse(isset($user->notes)); // Re-fetch to be sure - $user = User::find($user->_id); + $user = User::find($user->id); $this->assertFalse(isset($user->notes)); } @@ -705,7 +705,7 @@ public function testUnsetDotAttributesAndSet(): void $this->assertSame(['note2' => 'DEF', 'note1' => 'ABC'], $user->notes); // Re-fetch to be sure - $user = User::find($user->_id); + $user = User::find($user->id); $this->assertSame(['note2' => 'DEF', 'note1' => 'ABC'], $user->notes); } @@ -722,14 +722,14 @@ public function testDateUseLocalTimeZone(): void $this->assertEquals($tz, $user->birthday->getTimezone()->getName()); $user->save(); - $user = User::find($user->_id); + $user = User::find($user->id); $this->assertEquals($date, $user->birthday); $this->assertEquals($tz, $user->birthday->getTimezone()->getName()); $this->assertSame('1965-03-02T15:30:10+10:00', $user->birthday->format(DATE_ATOM)); $tz = 'America/New_York'; date_default_timezone_set($tz); - $user = User::find($user->_id); + $user = User::find($user->id); $this->assertEquals($date, $user->birthday); $this->assertEquals($tz, $user->birthday->getTimezone()->getName()); $this->assertSame('1965-03-02T00:30:10-05:00', $user->birthday->format(DATE_ATOM)); @@ -748,7 +748,7 @@ public function testDates(): void $user = User::create(['name' => 'John Doe', 'birthday' => new DateTime('1980/1/1')]); $this->assertInstanceOf(Carbon::class, $user->birthday); - $check = User::find($user->_id); + $check = User::find($user->id); $this->assertInstanceOf(Carbon::class, $check->birthday); $this->assertEquals($user->birthday, $check->birthday); @@ -833,7 +833,7 @@ public function testDateNull(): void $user->save(); // Re-fetch to be sure - $user = User::find($user->_id); + $user = User::find($user->id); $this->assertNull($user->birthday); // Nested field with dot notation @@ -845,7 +845,7 @@ public function testDateNull(): void $this->assertNull($user->getAttribute('entry.date')); // Re-fetch to be sure - $user = User::find($user->_id); + $user = User::find($user->id); $this->assertNull($user->getAttribute('entry.date')); } @@ -863,10 +863,10 @@ public function testIdAttribute(): void { $user = User::create(['name' => 'John Doe']); $this->assertInstanceOf(User::class, $user); - $this->assertEquals($user->id, $user->_id); + $this->assertSame($user->id, $user->_id); $user = User::create(['id' => 'custom_id', 'name' => 'John Doe']); - $this->assertNotEquals($user->id, $user->_id); + $this->assertSame($user->id, $user->_id); } public function testPushPull(): void @@ -879,20 +879,20 @@ public function testPushPull(): void $user->push('tags', 'tag2', true); $this->assertEquals(['tag1', 'tag1', 'tag2'], $user->tags); - $user = User::where('_id', $user->_id)->first(); + $user = User::where('id', $user->id)->first(); $this->assertEquals(['tag1', 'tag1', 'tag2'], $user->tags); $user->pull('tags', 'tag1'); $this->assertEquals(['tag2'], $user->tags); - $user = User::where('_id', $user->_id)->first(); + $user = User::where('id', $user->id)->first(); $this->assertEquals(['tag2'], $user->tags); $user->push('tags', 'tag3'); $user->pull('tags', ['tag2', 'tag3']); $this->assertEquals([], $user->tags); - $user = User::where('_id', $user->_id)->first(); + $user = User::where('id', $user->id)->first(); $this->assertEquals([], $user->tags); } @@ -1048,7 +1048,7 @@ public function testFirstOrCreate(): void $check = User::where('name', $name)->first(); $this->assertInstanceOf(User::class, $check); - $this->assertEquals($user->_id, $check->_id); + $this->assertEquals($user->id, $check->id); } public function testEnumCast(): void @@ -1163,6 +1163,7 @@ public function testCreateOrFirst(bool $transaction) } #[TestWith([['_id' => new ObjectID()]])] + #[TestWith([['id' => new ObjectID()]])] #[TestWith([['foo' => 'bar']])] public function testUpdateOrCreate(array $criteria) { @@ -1215,9 +1216,11 @@ public function testUpdateOrCreate(array $criteria) $this->assertEquals($updatedAt, $checkUser->updated_at->getTimestamp()); } - public function testCreateWithNullId() + #[TestWith(['_id'])] + #[TestWith(['id'])] + public function testCreateWithNullId(string $id) { - $user = User::create(['_id' => null, 'email' => 'foo@bar']); + $user = User::create([$id => null, 'email' => 'foo@bar']); $this->assertNotNull(ObjectId::class, $user->id); $this->assertSame(1, User::count()); } diff --git a/tests/Models/Address.php b/tests/Models/Address.php index d94e31d24..60e4d6431 100644 --- a/tests/Models/Address.php +++ b/tests/Models/Address.php @@ -12,7 +12,6 @@ class Address extends Model { use DocumentModel; - protected $primaryKey = '_id'; protected $keyType = 'string'; protected $connection = 'mongodb'; protected static $unguarded = true; diff --git a/tests/Models/Birthday.php b/tests/Models/Birthday.php index ae0e108b1..6c9964da5 100644 --- a/tests/Models/Birthday.php +++ b/tests/Models/Birthday.php @@ -16,7 +16,6 @@ class Birthday extends Model { use DocumentModel; - protected $primaryKey = '_id'; protected $keyType = 'string'; protected $connection = 'mongodb'; protected $table = 'birthday'; diff --git a/tests/Models/Client.php b/tests/Models/Client.php index b0339a0e5..f0118f12f 100644 --- a/tests/Models/Client.php +++ b/tests/Models/Client.php @@ -14,7 +14,6 @@ class Client extends Model { use DocumentModel; - protected $primaryKey = '_id'; protected $keyType = 'string'; protected $connection = 'mongodb'; protected $table = 'clients'; diff --git a/tests/Models/Experience.php b/tests/Models/Experience.php index 6a306afe1..2784cc5dd 100644 --- a/tests/Models/Experience.php +++ b/tests/Models/Experience.php @@ -12,7 +12,6 @@ class Experience extends Model { use DocumentModel; - protected $primaryKey = '_id'; protected $keyType = 'string'; protected $connection = 'mongodb'; protected $table = 'experiences'; diff --git a/tests/Models/Group.php b/tests/Models/Group.php index 57c3af59c..9115b8c3e 100644 --- a/tests/Models/Group.php +++ b/tests/Models/Group.php @@ -12,7 +12,6 @@ class Group extends Model { use DocumentModel; - protected $primaryKey = '_id'; protected $keyType = 'string'; protected $connection = 'mongodb'; protected $table = 'groups'; @@ -20,6 +19,6 @@ class Group extends Model public function users(): BelongsToMany { - return $this->belongsToMany(User::class, 'users', 'groups', 'users', '_id', '_id', 'users'); + return $this->belongsToMany(User::class, 'users', 'groups', 'users', 'id', 'id', 'users'); } } diff --git a/tests/Models/Guarded.php b/tests/Models/Guarded.php index 40d11bea5..57616c4c9 100644 --- a/tests/Models/Guarded.php +++ b/tests/Models/Guarded.php @@ -11,7 +11,6 @@ class Guarded extends Model { use DocumentModel; - protected $primaryKey = '_id'; protected $keyType = 'string'; protected $connection = 'mongodb'; protected $table = 'guarded'; diff --git a/tests/Models/HiddenAnimal.php b/tests/Models/HiddenAnimal.php index a47184fe7..240238da0 100644 --- a/tests/Models/HiddenAnimal.php +++ b/tests/Models/HiddenAnimal.php @@ -22,7 +22,6 @@ final class HiddenAnimal extends Model { use DocumentModel; - protected $primaryKey = '_id'; protected $keyType = 'string'; protected $fillable = [ 'name', diff --git a/tests/Models/IdIsBinaryUuid.php b/tests/Models/IdIsBinaryUuid.php index 2314b4b19..33cc86da3 100644 --- a/tests/Models/IdIsBinaryUuid.php +++ b/tests/Models/IdIsBinaryUuid.php @@ -12,11 +12,10 @@ class IdIsBinaryUuid extends Model { use DocumentModel; - protected $primaryKey = '_id'; protected $keyType = 'string'; protected $connection = 'mongodb'; protected static $unguarded = true; protected $casts = [ - '_id' => BinaryUuid::class, + 'id' => BinaryUuid::class, ]; } diff --git a/tests/Models/IdIsInt.php b/tests/Models/IdIsInt.php index 1f8d1ba88..bf7c9f47f 100644 --- a/tests/Models/IdIsInt.php +++ b/tests/Models/IdIsInt.php @@ -11,9 +11,8 @@ class IdIsInt extends Model { use DocumentModel; - protected $primaryKey = '_id'; protected $keyType = 'int'; protected $connection = 'mongodb'; protected static $unguarded = true; - protected $casts = ['_id' => 'int']; + protected $casts = ['id' => 'int']; } diff --git a/tests/Models/IdIsString.php b/tests/Models/IdIsString.php index 37ba1c424..fef6c36bf 100644 --- a/tests/Models/IdIsString.php +++ b/tests/Models/IdIsString.php @@ -11,9 +11,8 @@ class IdIsString extends Model { use DocumentModel; - protected $primaryKey = '_id'; protected $keyType = 'string'; protected $connection = 'mongodb'; protected static $unguarded = true; - protected $casts = ['_id' => 'string']; + protected $casts = ['id' => 'string']; } diff --git a/tests/Models/Item.php b/tests/Models/Item.php index 2beb40d75..deec7a7cf 100644 --- a/tests/Models/Item.php +++ b/tests/Models/Item.php @@ -15,7 +15,6 @@ class Item extends Model { use DocumentModel; - protected $primaryKey = '_id'; protected $keyType = 'string'; protected $connection = 'mongodb'; protected $table = 'items'; diff --git a/tests/Models/Label.php b/tests/Models/Label.php index b95aa0dcf..5088a1053 100644 --- a/tests/Models/Label.php +++ b/tests/Models/Label.php @@ -17,7 +17,6 @@ class Label extends Model { use DocumentModel; - protected $primaryKey = '_id'; protected $keyType = 'string'; protected $connection = 'mongodb'; protected $table = 'labels'; diff --git a/tests/Models/Location.php b/tests/Models/Location.php index 2c62dbda9..75a40d5f3 100644 --- a/tests/Models/Location.php +++ b/tests/Models/Location.php @@ -11,7 +11,6 @@ class Location extends Model { use DocumentModel; - protected $primaryKey = '_id'; protected $keyType = 'string'; protected $connection = 'mongodb'; protected $table = 'locations'; diff --git a/tests/Models/Photo.php b/tests/Models/Photo.php index be7f3666c..d6786267b 100644 --- a/tests/Models/Photo.php +++ b/tests/Models/Photo.php @@ -12,7 +12,6 @@ class Photo extends Model { use DocumentModel; - protected $primaryKey = '_id'; protected $keyType = 'string'; protected $connection = 'mongodb'; protected $table = 'photos'; diff --git a/tests/Models/Role.php b/tests/Models/Role.php index e9f3fa95d..02551971d 100644 --- a/tests/Models/Role.php +++ b/tests/Models/Role.php @@ -12,7 +12,6 @@ class Role extends Model { use DocumentModel; - protected $primaryKey = '_id'; protected $keyType = 'string'; protected $connection = 'mongodb'; protected $table = 'roles'; diff --git a/tests/Models/Scoped.php b/tests/Models/Scoped.php index 6850dcb21..477c33ded 100644 --- a/tests/Models/Scoped.php +++ b/tests/Models/Scoped.php @@ -12,7 +12,6 @@ class Scoped extends Model { use DocumentModel; - protected $primaryKey = '_id'; protected $keyType = 'string'; protected $connection = 'mongodb'; protected $table = 'scoped'; diff --git a/tests/Models/Skill.php b/tests/Models/Skill.php index 1e2daaf80..c6b3e94bb 100644 --- a/tests/Models/Skill.php +++ b/tests/Models/Skill.php @@ -12,7 +12,6 @@ class Skill extends Model { use DocumentModel; - protected $primaryKey = '_id'; protected $keyType = 'string'; protected $connection = 'mongodb'; protected $table = 'skills'; diff --git a/tests/Models/Soft.php b/tests/Models/Soft.php index cbfa2ef23..f887d05a9 100644 --- a/tests/Models/Soft.php +++ b/tests/Models/Soft.php @@ -18,7 +18,6 @@ class Soft extends Model use SoftDeletes; use MassPrunable; - protected $primaryKey = '_id'; protected $keyType = 'string'; protected $connection = 'mongodb'; protected $table = 'soft'; diff --git a/tests/Models/User.php b/tests/Models/User.php index 22048f282..5b8ac983a 100644 --- a/tests/Models/User.php +++ b/tests/Models/User.php @@ -19,7 +19,7 @@ use MongoDB\Laravel\Eloquent\MassPrunable; /** - * @property string $_id + * @property string $id * @property string $name * @property string $email * @property string $title @@ -38,7 +38,6 @@ class User extends Model implements AuthenticatableContract, CanResetPasswordCon use Notifiable; use MassPrunable; - protected $primaryKey = '_id'; protected $keyType = 'string'; protected $connection = 'mongodb'; protected $casts = [ @@ -100,7 +99,7 @@ public function clients() public function groups() { - return $this->belongsToMany(Group::class, 'groups', 'users', 'groups', '_id', '_id', 'groups'); + return $this->belongsToMany(Group::class, 'groups', 'users', 'groups', 'id', 'id', 'groups'); } public function photos() diff --git a/tests/Query/BuilderTest.php b/tests/Query/BuilderTest.php index 3ec933499..b081a0557 100644 --- a/tests/Query/BuilderTest.php +++ b/tests/Query/BuilderTest.php @@ -124,10 +124,9 @@ public static function provideQueryBuilderToMql(): iterable ]; // Nested array are not flattened like in the Eloquent builder. MongoDB can compare objects. - $array = [['issue' => 45582], ['id' => 2], [3]]; yield 'whereIn nested array' => [ - ['find' => [['id' => ['$in' => $array]], []]], - fn (Builder $builder) => $builder->whereIn('id', $array), + ['find' => [['_id' => ['$in' => [['issue' => 45582], ['_id' => 2], [3]]]], []]], + fn (Builder $builder) => $builder->whereIn('id', [['issue' => 45582], ['id' => 2], [3]]), ]; yield 'orWhereIn' => [ @@ -135,21 +134,21 @@ public static function provideQueryBuilderToMql(): iterable 'find' => [ [ '$or' => [ - ['id' => 1], - ['id' => ['$in' => [1, 2, 3]]], + ['foo' => 1], + ['foo' => ['$in' => [1, 2, 3]]], ], ], [], // options ], ], - fn (Builder $builder) => $builder->where('id', '=', 1) - ->orWhereIn('id', [1, 2, 3]), + fn (Builder $builder) => $builder->where('foo', '=', 1) + ->orWhereIn('foo', [1, 2, 3]), ]; /** @see DatabaseQueryBuilderTest::testBasicWhereNotIns */ yield 'whereNotIn' => [ - ['find' => [['id' => ['$nin' => [1, 2, 3]]], []]], - fn (Builder $builder) => $builder->whereNotIn('id', [1, 2, 3]), + ['find' => [['foo' => ['$nin' => [1, 2, 3]]], []]], + fn (Builder $builder) => $builder->whereNotIn('foo', [1, 2, 3]), ]; yield 'orWhereNotIn' => [ @@ -157,20 +156,20 @@ public static function provideQueryBuilderToMql(): iterable 'find' => [ [ '$or' => [ - ['id' => 1], - ['id' => ['$nin' => [1, 2, 3]]], + ['foo' => 1], + ['foo' => ['$nin' => [1, 2, 3]]], ], ], [], // options ], ], - fn (Builder $builder) => $builder->where('id', '=', 1) - ->orWhereNotIn('id', [1, 2, 3]), + fn (Builder $builder) => $builder->where('foo', '=', 1) + ->orWhereNotIn('foo', [1, 2, 3]), ]; /** @see DatabaseQueryBuilderTest::testEmptyWhereIns */ yield 'whereIn empty array' => [ - ['find' => [['id' => ['$in' => []]], []]], + ['find' => [['_id' => ['$in' => []]], []]], fn (Builder $builder) => $builder->whereIn('id', []), ]; @@ -220,7 +219,7 @@ public static function provideQueryBuilderToMql(): iterable 'find' => [ [ '$or' => [ - ['id' => 1], + ['age' => 1], ['email' => 'foo'], ], ], @@ -228,7 +227,7 @@ public static function provideQueryBuilderToMql(): iterable ], ], fn (Builder $builder) => $builder - ->where('id', '=', 1) + ->where('age', '=', 1) ->orWhere('email', '=', 'foo'), ]; @@ -497,6 +496,11 @@ public static function provideQueryBuilderToMql(): iterable ->orderBy('age', 'desc'), ]; + yield 'orders by id field' => [ + ['find' => [[], ['sort' => ['_id' => 1]]]], + fn (Builder $builder) => $builder->orderBy('id'), + ]; + yield 'orders = null' => [ ['find' => [[], []]], function (Builder $builder) { @@ -553,12 +557,12 @@ function (Builder $builder) { /** @see DatabaseQueryBuilderTest::testWhereBetweens() */ yield 'whereBetween array of numbers' => [ - ['find' => [['id' => ['$gte' => 1, '$lte' => 2]], []]], + ['find' => [['_id' => ['$gte' => 1, '$lte' => 2]], []]], fn (Builder $builder) => $builder->whereBetween('id', [1, 2]), ]; yield 'whereBetween nested array of numbers' => [ - ['find' => [['id' => ['$gte' => [1], '$lte' => [2, 3]]], []]], + ['find' => [['_id' => ['$gte' => [1], '$lte' => [2, 3]]], []]], fn (Builder $builder) => $builder->whereBetween('id', [[1], [2, 3]]), ]; @@ -579,7 +583,7 @@ function (Builder $builder) { ]; yield 'whereBetween collection' => [ - ['find' => [['id' => ['$gte' => 1, '$lte' => 2]], []]], + ['find' => [['_id' => ['$gte' => 1, '$lte' => 2]], []]], fn (Builder $builder) => $builder->whereBetween('id', collect([1, 2])), ]; @@ -589,16 +593,16 @@ function (Builder $builder) { 'find' => [ [ '$or' => [ - ['id' => 1], - ['id' => ['$gte' => 3, '$lte' => 5]], + ['age' => 1], + ['age' => ['$gte' => 3, '$lte' => 5]], ], ], [], // options ], ], fn (Builder $builder) => $builder - ->where('id', '=', 1) - ->orWhereBetween('id', [3, 5]), + ->where('age', '=', 1) + ->orWhereBetween('age', [3, 5]), ]; /** @link https://www.mongodb.com/docs/manual/reference/bson-type-comparison-order/#arrays */ @@ -607,16 +611,16 @@ function (Builder $builder) { 'find' => [ [ '$or' => [ - ['id' => 1], - ['id' => ['$gte' => [4], '$lte' => [6, 8]]], + ['age' => 1], + ['age' => ['$gte' => [4], '$lte' => [6, 8]]], ], ], [], // options ], ], fn (Builder $builder) => $builder - ->where('id', '=', 1) - ->orWhereBetween('id', [[4], [6, 8]]), + ->where('age', '=', 1) + ->orWhereBetween('age', [[4], [6, 8]]), ]; yield 'orWhereBetween collection' => [ @@ -624,16 +628,16 @@ function (Builder $builder) { 'find' => [ [ '$or' => [ - ['id' => 1], - ['id' => ['$gte' => 3, '$lte' => 4]], + ['age' => 1], + ['age' => ['$gte' => 3, '$lte' => 4]], ], ], [], // options ], ], fn (Builder $builder) => $builder - ->where('id', '=', 1) - ->orWhereBetween('id', collect([3, 4])), + ->where('age', '=', 1) + ->orWhereBetween('age', collect([3, 4])), ]; yield 'whereNotBetween array of numbers' => [ @@ -641,14 +645,14 @@ function (Builder $builder) { 'find' => [ [ '$or' => [ - ['id' => ['$lte' => 1]], - ['id' => ['$gte' => 2]], + ['age' => ['$lte' => 1]], + ['age' => ['$gte' => 2]], ], ], [], // options ], ], - fn (Builder $builder) => $builder->whereNotBetween('id', [1, 2]), + fn (Builder $builder) => $builder->whereNotBetween('age', [1, 2]), ]; /** @see DatabaseQueryBuilderTest::testOrWhereNotBetween() */ @@ -657,11 +661,11 @@ function (Builder $builder) { 'find' => [ [ '$or' => [ - ['id' => 1], + ['age' => 1], [ '$or' => [ - ['id' => ['$lte' => 3]], - ['id' => ['$gte' => 5]], + ['age' => ['$lte' => 3]], + ['age' => ['$gte' => 5]], ], ], ], @@ -670,8 +674,8 @@ function (Builder $builder) { ], ], fn (Builder $builder) => $builder - ->where('id', '=', 1) - ->orWhereNotBetween('id', [3, 5]), + ->where('age', '=', 1) + ->orWhereNotBetween('age', [3, 5]), ]; yield 'orWhereNotBetween nested array of numbers' => [ @@ -679,11 +683,11 @@ function (Builder $builder) { 'find' => [ [ '$or' => [ - ['id' => 1], + ['age' => 1], [ '$or' => [ - ['id' => ['$lte' => [2, 3]]], - ['id' => ['$gte' => [5]]], + ['age' => ['$lte' => [2, 3]]], + ['age' => ['$gte' => [5]]], ], ], ], @@ -692,8 +696,8 @@ function (Builder $builder) { ], ], fn (Builder $builder) => $builder - ->where('id', '=', 1) - ->orWhereNotBetween('id', [[2, 3], [5]]), + ->where('age', '=', 1) + ->orWhereNotBetween('age', [[2, 3], [5]]), ]; yield 'orWhereNotBetween collection' => [ @@ -701,11 +705,11 @@ function (Builder $builder) { 'find' => [ [ '$or' => [ - ['id' => 1], + ['age' => 1], [ '$or' => [ - ['id' => ['$lte' => 3]], - ['id' => ['$gte' => 4]], + ['age' => ['$lte' => 3]], + ['age' => ['$gte' => 4]], ], ], ], @@ -714,8 +718,8 @@ function (Builder $builder) { ], ], fn (Builder $builder) => $builder - ->where('id', '=', 1) - ->orWhereNotBetween('id', collect([3, 4])), + ->where('age', '=', 1) + ->orWhereNotBetween('age', collect([3, 4])), ]; yield 'where like' => [ @@ -1160,6 +1164,21 @@ function (Builder $elemMatchQuery): void { ), ]; + yield 'id alias for _id' => [ + ['find' => [['_id' => 1], []]], + fn (Builder $builder) => $builder->where('id', 1), + ]; + + yield 'id alias for _id with $or' => [ + ['find' => [['$or' => [['_id' => 1], ['_id' => 2]]], []]], + fn (Builder $builder) => $builder->where('id', 1)->orWhere('id', 2), + ]; + + yield 'select colums with id alias' => [ + ['find' => [[], ['projection' => ['name' => 1, 'email' => 1, '_id' => 1]]]], + fn (Builder $builder) => $builder->select('name', 'email', 'id'), + ]; + // Method added in Laravel v10.47.0 if (method_exists(Builder::class, 'whereAll')) { /** @see DatabaseQueryBuilderTest::testWhereAll */ diff --git a/tests/QueryBuilderTest.php b/tests/QueryBuilderTest.php index e1d0ec7f2..6b08a15b7 100644 --- a/tests/QueryBuilderTest.php +++ b/tests/QueryBuilderTest.php @@ -25,6 +25,7 @@ use MongoDB\Laravel\Query\Builder; use MongoDB\Laravel\Tests\Models\Item; use MongoDB\Laravel\Tests\Models\User; +use PHPUnit\Framework\Attributes\TestWith; use Stringable; use function count; @@ -59,7 +60,7 @@ public function testDeleteWithId() $product = DB::table('items')->first(); - $pid = (string) ($product['_id']); + $pid = (string) ($product['id']); DB::table('items')->where('user_id', $userId)->delete($pid); @@ -67,7 +68,7 @@ public function testDeleteWithId() $product = DB::table('items')->first(); - $pid = $product['_id']; + $pid = $product['id']; DB::table('items')->where('user_id', $userId)->delete($pid); @@ -100,7 +101,7 @@ public function testNoDocument() $item = DB::table('items')->where('name', 'nothing')->first(); $this->assertNull($item); - $item = DB::table('items')->where('_id', '51c33d8981fec6813e00000a')->first(); + $item = DB::table('items')->where('id', '51c33d8981fec6813e00000a')->first(); $this->assertNull($item); } @@ -339,37 +340,37 @@ public function testPush() 'messages' => [], ]); - DB::table('users')->where('_id', $id)->push('tags', 'tag1'); + DB::table('users')->where('id', $id)->push('tags', 'tag1'); $user = DB::table('users')->find($id); $this->assertIsArray($user['tags']); $this->assertCount(1, $user['tags']); $this->assertEquals('tag1', $user['tags'][0]); - DB::table('users')->where('_id', $id)->push('tags', 'tag2'); + DB::table('users')->where('id', $id)->push('tags', 'tag2'); $user = DB::table('users')->find($id); $this->assertCount(2, $user['tags']); $this->assertEquals('tag2', $user['tags'][1]); // Add duplicate - DB::table('users')->where('_id', $id)->push('tags', 'tag2'); + DB::table('users')->where('id', $id)->push('tags', 'tag2'); $user = DB::table('users')->find($id); $this->assertCount(3, $user['tags']); // Add unique - DB::table('users')->where('_id', $id)->push('tags', 'tag1', true); + DB::table('users')->where('id', $id)->push('tags', 'tag1', true); $user = DB::table('users')->find($id); $this->assertCount(3, $user['tags']); $message = ['from' => 'Jane', 'body' => 'Hi John']; - DB::table('users')->where('_id', $id)->push('messages', $message); + DB::table('users')->where('id', $id)->push('messages', $message); $user = DB::table('users')->find($id); $this->assertIsArray($user['messages']); $this->assertCount(1, $user['messages']); $this->assertEquals($message, $user['messages'][0]); // Raw - DB::table('users')->where('_id', $id)->push([ + DB::table('users')->where('id', $id)->push([ 'tags' => 'tag3', 'messages' => ['from' => 'Mark', 'body' => 'Hi John'], ]); @@ -377,7 +378,7 @@ public function testPush() $this->assertCount(4, $user['tags']); $this->assertCount(2, $user['messages']); - DB::table('users')->where('_id', $id)->push([ + DB::table('users')->where('id', $id)->push([ 'messages' => [ 'date' => new DateTime(), 'body' => 'Hi John', @@ -406,21 +407,21 @@ public function testPull() 'messages' => [$message1, $message2], ]); - DB::table('users')->where('_id', $id)->pull('tags', 'tag3'); + DB::table('users')->where('id', $id)->pull('tags', 'tag3'); $user = DB::table('users')->find($id); $this->assertIsArray($user['tags']); $this->assertCount(3, $user['tags']); $this->assertEquals('tag4', $user['tags'][2]); - DB::table('users')->where('_id', $id)->pull('messages', $message1); + DB::table('users')->where('id', $id)->pull('messages', $message1); $user = DB::table('users')->find($id); $this->assertIsArray($user['messages']); $this->assertCount(1, $user['messages']); // Raw - DB::table('users')->where('_id', $id)->pull(['tags' => 'tag2', 'messages' => $message2]); + DB::table('users')->where('id', $id)->pull(['tags' => 'tag2', 'messages' => $message2]); $user = DB::table('users')->find($id); $this->assertCount(2, $user['tags']); $this->assertCount(0, $user['messages']); @@ -449,24 +450,24 @@ public function testDistinct() public function testCustomId() { DB::table('items')->insert([ - ['_id' => 'knife', 'type' => 'sharp', 'amount' => 34], - ['_id' => 'fork', 'type' => 'sharp', 'amount' => 20], - ['_id' => 'spoon', 'type' => 'round', 'amount' => 3], + ['id' => 'knife', 'type' => 'sharp', 'amount' => 34], + ['id' => 'fork', 'type' => 'sharp', 'amount' => 20], + ['id' => 'spoon', 'type' => 'round', 'amount' => 3], ]); $item = DB::table('items')->find('knife'); - $this->assertEquals('knife', $item['_id']); + $this->assertEquals('knife', $item['id']); - $item = DB::table('items')->where('_id', 'fork')->first(); - $this->assertEquals('fork', $item['_id']); + $item = DB::table('items')->where('id', 'fork')->first(); + $this->assertEquals('fork', $item['id']); DB::table('users')->insert([ - ['_id' => 1, 'name' => 'Jane Doe'], - ['_id' => 2, 'name' => 'John Doe'], + ['id' => 1, 'name' => 'Jane Doe'], + ['id' => 2, 'name' => 'John Doe'], ]); $item = DB::table('users')->find(1); - $this->assertEquals(1, $item['_id']); + $this->assertEquals(1, $item['id']); } public function testTake() @@ -526,7 +527,7 @@ public function testList() $this->assertCount(3, $list); $this->assertEquals(['knife' => 'sharp', 'fork' => 'sharp', 'spoon' => 'round'], $list); - $list = DB::table('items')->pluck('name', '_id')->toArray(); + $list = DB::table('items')->pluck('name', 'id')->toArray(); $this->assertCount(4, $list); $this->assertEquals(24, strlen(key($list))); } @@ -667,7 +668,7 @@ public function testUpdateSubdocument() { $id = DB::table('users')->insertGetId(['name' => 'John Doe', 'address' => ['country' => 'Belgium']]); - DB::table('users')->where('_id', $id)->update(['address.country' => 'England']); + DB::table('users')->where('id', $id)->update(['address.country' => 'England']); $check = DB::table('users')->find($id); $this->assertEquals('England', $check['address']['country']); @@ -932,7 +933,7 @@ public function testCursor() ]; DB::table('items')->insert($data); - $results = DB::table('items')->orderBy('_id', 'asc')->cursor(); + $results = DB::table('items')->orderBy('id', 'asc')->cursor(); $this->assertInstanceOf(LazyCollection::class, $results); foreach ($results as $i => $result) { @@ -1048,4 +1049,20 @@ public function testIncrementEach() $this->assertEquals(5, $user['note']); $this->assertEquals('foo', $user['extra']); } + + #[TestWith(['id', 'id'])] + #[TestWith(['id', '_id'])] + #[TestWith(['_id', 'id'])] + public function testIdAlias($insertId, $queryId): void + { + DB::collection('items')->insert([$insertId => 'abc', 'name' => 'Karting']); + $item = DB::collection('items')->where($queryId, '=', 'abc')->first(); + $this->assertNotNull($item); + $this->assertSame('abc', $item['id']); + $this->assertSame('Karting', $item['name']); + + DB::collection('items')->where($insertId, '=', 'abc')->update(['name' => 'Bike']); + $item = DB::collection('items')->where($queryId, '=', 'abc')->first(); + $this->assertSame('Bike', $item['name']); + } } diff --git a/tests/QueryTest.php b/tests/QueryTest.php index 2fd66bf70..e228a0f70 100644 --- a/tests/QueryTest.php +++ b/tests/QueryTest.php @@ -405,7 +405,7 @@ public function testCount(): void $this->assertEquals(6, $count); // Test for issue #165 - $count = User::select('_id', 'age', 'title')->where('age', '<>', 35)->count(); + $count = User::select('id', 'age', 'title')->where('age', '<>', 35)->count(); $this->assertEquals(6, $count); } diff --git a/tests/QueueTest.php b/tests/QueueTest.php index 2236fba1b..af31c8a5b 100644 --- a/tests/QueueTest.php +++ b/tests/QueueTest.php @@ -71,7 +71,7 @@ public function testQueueJobExpired(): void $expiry = Carbon::now()->subSeconds(Config::get('queue.connections.database.expire'))->getTimestamp(); Queue::getDatabase() ->table(Config::get('queue.connections.database.table')) - ->where('_id', $id) + ->where('id', $id) ->update(['reserved' => 1, 'reserved_at' => $expiry]); // Expect an attempted older job in the queue @@ -158,7 +158,7 @@ public function testQueueRelease(): void $releasedJob = Queue::getDatabase() ->table(Config::get('queue.connections.database.table')) - ->where('_id', $releasedJobId) + ->where('id', $releasedJobId) ->first(); $this->assertEquals($queue, $releasedJob['queue']); diff --git a/tests/RelationsTest.php b/tests/RelationsTest.php index 02efbc77b..902f0499c 100644 --- a/tests/RelationsTest.php +++ b/tests/RelationsTest.php @@ -40,16 +40,16 @@ public function tearDown(): void public function testHasMany(): void { $author = User::create(['name' => 'George R. R. Martin']); - Book::create(['title' => 'A Game of Thrones', 'author_id' => $author->_id]); - Book::create(['title' => 'A Clash of Kings', 'author_id' => $author->_id]); + Book::create(['title' => 'A Game of Thrones', 'author_id' => $author->id]); + Book::create(['title' => 'A Clash of Kings', 'author_id' => $author->id]); $books = $author->books; $this->assertCount(2, $books); $user = User::create(['name' => 'John Doe']); - Item::create(['type' => 'knife', 'user_id' => $user->_id]); - Item::create(['type' => 'shield', 'user_id' => $user->_id]); - Item::create(['type' => 'sword', 'user_id' => $user->_id]); + Item::create(['type' => 'knife', 'user_id' => $user->id]); + Item::create(['type' => 'shield', 'user_id' => $user->id]); + Item::create(['type' => 'sword', 'user_id' => $user->id]); Item::create(['type' => 'bag', 'user_id' => null]); $items = $user->items; @@ -59,32 +59,32 @@ public function testHasMany(): void public function testHasManyWithTrashed(): void { $user = User::create(['name' => 'George R. R. Martin']); - $first = Soft::create(['title' => 'A Game of Thrones', 'user_id' => $user->_id]); - $second = Soft::create(['title' => 'The Witcher', 'user_id' => $user->_id]); + $first = Soft::create(['title' => 'A Game of Thrones', 'user_id' => $user->id]); + $second = Soft::create(['title' => 'The Witcher', 'user_id' => $user->id]); self::assertNull($first->deleted_at); - self::assertEquals($user->_id, $first->user->_id); - self::assertEquals([$first->_id, $second->_id], $user->softs->pluck('_id')->toArray()); + self::assertEquals($user->id, $first->user->id); + self::assertEquals([$first->id, $second->id], $user->softs->pluck('id')->toArray()); $first->delete(); $user->refresh(); self::assertNotNull($first->deleted_at); - self::assertEquals([$second->_id], $user->softs->pluck('_id')->toArray()); - self::assertEquals([$first->_id, $second->_id], $user->softsWithTrashed->pluck('_id')->toArray()); + self::assertEquals([$second->id], $user->softs->pluck('id')->toArray()); + self::assertEquals([$first->id, $second->id], $user->softsWithTrashed->pluck('id')->toArray()); } public function testBelongsTo(): void { $user = User::create(['name' => 'George R. R. Martin']); - Book::create(['title' => 'A Game of Thrones', 'author_id' => $user->_id]); - $book = Book::create(['title' => 'A Clash of Kings', 'author_id' => $user->_id]); + Book::create(['title' => 'A Game of Thrones', 'author_id' => $user->id]); + $book = Book::create(['title' => 'A Clash of Kings', 'author_id' => $user->id]); $author = $book->author; $this->assertEquals('George R. R. Martin', $author->name); $user = User::create(['name' => 'John Doe']); - $item = Item::create(['type' => 'sword', 'user_id' => $user->_id]); + $item = Item::create(['type' => 'sword', 'user_id' => $user->id]); $owner = $item->user; $this->assertEquals('John Doe', $owner->name); @@ -96,11 +96,11 @@ public function testBelongsTo(): void public function testHasOne(): void { $user = User::create(['name' => 'John Doe']); - Role::create(['type' => 'admin', 'user_id' => $user->_id]); + Role::create(['type' => 'admin', 'user_id' => $user->id]); $role = $user->role; $this->assertEquals('admin', $role->type); - $this->assertEquals($user->_id, $role->user_id); + $this->assertEquals($user->id, $role->user_id); $user = User::create(['name' => 'Jane Doe']); $role = new Role(['type' => 'user']); @@ -108,20 +108,20 @@ public function testHasOne(): void $role = $user->role; $this->assertEquals('user', $role->type); - $this->assertEquals($user->_id, $role->user_id); + $this->assertEquals($user->id, $role->user_id); $user = User::where('name', 'Jane Doe')->first(); $role = $user->role; $this->assertEquals('user', $role->type); - $this->assertEquals($user->_id, $role->user_id); + $this->assertEquals($user->id, $role->user_id); } public function testWithBelongsTo(): void { $user = User::create(['name' => 'John Doe']); - Item::create(['type' => 'knife', 'user_id' => $user->_id]); - Item::create(['type' => 'shield', 'user_id' => $user->_id]); - Item::create(['type' => 'sword', 'user_id' => $user->_id]); + Item::create(['type' => 'knife', 'user_id' => $user->id]); + Item::create(['type' => 'shield', 'user_id' => $user->id]); + Item::create(['type' => 'sword', 'user_id' => $user->id]); Item::create(['type' => 'bag', 'user_id' => null]); $items = Item::with('user')->orderBy('user_id', 'desc')->get(); @@ -136,12 +136,12 @@ public function testWithBelongsTo(): void public function testWithHashMany(): void { $user = User::create(['name' => 'John Doe']); - Item::create(['type' => 'knife', 'user_id' => $user->_id]); - Item::create(['type' => 'shield', 'user_id' => $user->_id]); - Item::create(['type' => 'sword', 'user_id' => $user->_id]); + Item::create(['type' => 'knife', 'user_id' => $user->id]); + Item::create(['type' => 'shield', 'user_id' => $user->id]); + Item::create(['type' => 'sword', 'user_id' => $user->id]); Item::create(['type' => 'bag', 'user_id' => null]); - $user = User::with('items')->find($user->_id); + $user = User::with('items')->find($user->id); $items = $user->getRelation('items'); $this->assertCount(3, $items); @@ -151,10 +151,10 @@ public function testWithHashMany(): void public function testWithHasOne(): void { $user = User::create(['name' => 'John Doe']); - Role::create(['type' => 'admin', 'user_id' => $user->_id]); - Role::create(['type' => 'guest', 'user_id' => $user->_id]); + Role::create(['type' => 'admin', 'user_id' => $user->id]); + Role::create(['type' => 'guest', 'user_id' => $user->id]); - $user = User::with('role')->find($user->_id); + $user = User::with('role')->find($user->id); $role = $user->getRelation('role'); $this->assertInstanceOf(Role::class, $role); @@ -168,22 +168,22 @@ public function testEasyRelation(): void $item = Item::create(['type' => 'knife']); $user->items()->save($item); - $user = User::find($user->_id); + $user = User::find($user->id); $items = $user->items; $this->assertCount(1, $items); $this->assertInstanceOf(Item::class, $items[0]); - $this->assertEquals($user->_id, $items[0]->user_id); + $this->assertEquals($user->id, $items[0]->user_id); // Has one $user = User::create(['name' => 'John Doe']); $role = Role::create(['type' => 'admin']); $user->role()->save($role); - $user = User::find($user->_id); + $user = User::find($user->id); $role = $user->role; $this->assertInstanceOf(Role::class, $role); $this->assertEquals('admin', $role->type); - $this->assertEquals($user->_id, $role->user_id); + $this->assertEquals($user->id, $role->user_id); } public function testBelongsToMany(): void @@ -195,7 +195,7 @@ public function testBelongsToMany(): void $user->clients()->create(['name' => 'Buffet Bar Inc.']); // Refetch - $user = User::with('clients')->find($user->_id); + $user = User::with('clients')->find($user->id); $client = Client::with('users')->first(); // Check for relation attributes @@ -228,8 +228,8 @@ public function testBelongsToMany(): void $this->assertInstanceOf(User::class, $user); // Assert they are not attached - $this->assertNotContains($client->_id, $user->client_ids); - $this->assertNotContains($user->_id, $client->user_ids); + $this->assertNotContains($client->id, $user->client_ids); + $this->assertNotContains($user->id, $client->user_ids); $this->assertCount(1, $user->clients); $this->assertCount(1, $client->users); @@ -241,8 +241,8 @@ public function testBelongsToMany(): void $client = Client::Where('name', '=', 'Buffet Bar Inc.')->first(); // Assert they are attached - $this->assertContains($client->_id, $user->client_ids); - $this->assertContains($user->_id, $client->user_ids); + $this->assertContains($client->id, $user->client_ids); + $this->assertContains($user->id, $client->user_ids); $this->assertCount(2, $user->clients); $this->assertCount(2, $client->users); @@ -254,8 +254,8 @@ public function testBelongsToMany(): void $client = Client::Where('name', '=', 'Buffet Bar Inc.')->first(); // Assert they are not attached - $this->assertNotContains($client->_id, $user->client_ids); - $this->assertNotContains($user->_id, $client->user_ids); + $this->assertNotContains($client->id, $user->client_ids); + $this->assertNotContains($user->id, $client->user_ids); $this->assertCount(0, $user->clients); $this->assertCount(1, $client->users); } @@ -265,19 +265,19 @@ public function testBelongsToManyAttachesExistingModels(): void $user = User::create(['name' => 'John Doe', 'client_ids' => ['1234523']]); $clients = [ - Client::create(['name' => 'Pork Pies Ltd.'])->_id, - Client::create(['name' => 'Buffet Bar Inc.'])->_id, + Client::create(['name' => 'Pork Pies Ltd.'])->id, + Client::create(['name' => 'Buffet Bar Inc.'])->id, ]; $moreClients = [ - Client::create(['name' => 'synced Boloni Ltd.'])->_id, - Client::create(['name' => 'synced Meatballs Inc.'])->_id, + Client::create(['name' => 'synced Boloni Ltd.'])->id, + Client::create(['name' => 'synced Meatballs Inc.'])->id, ]; // Sync multiple records $user->clients()->sync($clients); - $user = User::with('clients')->find($user->_id); + $user = User::with('clients')->find($user->id); // Assert non attached ID's are detached successfully $this->assertNotContains('1234523', $user->client_ids); @@ -289,7 +289,7 @@ public function testBelongsToManyAttachesExistingModels(): void $user->clients()->sync($moreClients); // Refetch - $user = User::with('clients')->find($user->_id); + $user = User::with('clients')->find($user->id); // Assert there are now still 2 client objects in the relationship $this->assertCount(2, $user->clients); @@ -307,11 +307,11 @@ public function testBelongsToManySync(): void $client2 = Client::create(['name' => 'Buffet Bar Inc.']); // Sync multiple - $user->clients()->sync([$client1->_id, $client2->_id]); + $user->clients()->sync([$client1->id, $client2->id]); $this->assertCount(2, $user->clients); // Sync single wrapped by an array - $user->clients()->sync([$client1->_id]); + $user->clients()->sync([$client1->id]); $user->load('clients'); $this->assertCount(1, $user->clients); @@ -328,8 +328,8 @@ public function testBelongsToManySync(): void public function testBelongsToManyAttachArray(): void { $user = User::create(['name' => 'John Doe']); - $client1 = Client::create(['name' => 'Test 1'])->_id; - $client2 = Client::create(['name' => 'Test 2'])->_id; + $client1 = Client::create(['name' => 'Test 1'])->id; + $client2 = Client::create(['name' => 'Test 2'])->id; $user->clients()->attach([$client1, $client2]); $this->assertCount(2, $user->clients); @@ -353,27 +353,27 @@ public function testBelongsToManySyncWithCustomKeys(): void $skill1 = Skill::create(['cskill_id' => (string) (new ObjectId()), 'name' => 'PHP']); $skill2 = Skill::create(['cskill_id' => (string) (new ObjectId()), 'name' => 'Laravel']); - $client = Client::query()->find($client->_id); + $client = Client::query()->find($client->id); $client->skillsWithCustomKeys()->sync([$skill1->cskill_id, $skill2->cskill_id]); $this->assertCount(2, $client->skillsWithCustomKeys); self::assertIsString($skill1->cskill_id); self::assertContains($skill1->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); - self::assertNotContains($skill1->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($skill1->id, $client->skillsWithCustomKeys->pluck('cskill_id')); self::assertIsString($skill2->cskill_id); self::assertContains($skill2->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); - self::assertNotContains($skill2->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($skill2->id, $client->skillsWithCustomKeys->pluck('cskill_id')); - $check = Skill::query()->find($skill1->_id); + $check = Skill::query()->find($skill1->id); self::assertIsString($check->cskill_id); self::assertContains($check->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); - self::assertNotContains($check->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($check->id, $client->skillsWithCustomKeys->pluck('cskill_id')); - $check = Skill::query()->find($skill2->_id); + $check = Skill::query()->find($skill2->id); self::assertIsString($check->cskill_id); self::assertContains($check->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); - self::assertNotContains($check->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($check->id, $client->skillsWithCustomKeys->pluck('cskill_id')); } public function testBelongsToManySyncModelWithCustomKeys(): void @@ -381,18 +381,18 @@ public function testBelongsToManySyncModelWithCustomKeys(): void $client = Client::create(['cclient_id' => (string) (new ObjectId()), 'years' => '5']); $skill1 = Skill::create(['cskill_id' => (string) (new ObjectId()), 'name' => 'PHP']); - $client = Client::query()->find($client->_id); + $client = Client::query()->find($client->id); $client->skillsWithCustomKeys()->sync($skill1); $this->assertCount(1, $client->skillsWithCustomKeys); self::assertIsString($skill1->cskill_id); self::assertContains($skill1->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); - self::assertNotContains($skill1->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($skill1->id, $client->skillsWithCustomKeys->pluck('cskill_id')); - $check = Skill::query()->find($skill1->_id); - self::assertIsString($check->_id); + $check = Skill::query()->find($skill1->id); + self::assertIsString($check->id); self::assertContains($check->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); - self::assertNotContains($check->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($check->id, $client->skillsWithCustomKeys->pluck('cskill_id')); } public function testBelongsToManySyncEloquentCollectionWithCustomKeys(): void @@ -402,27 +402,27 @@ public function testBelongsToManySyncEloquentCollectionWithCustomKeys(): void $skill2 = Skill::create(['cskill_id' => (string) (new ObjectId()), 'name' => 'Laravel']); $collection = new Collection([$skill1, $skill2]); - $client = Client::query()->find($client->_id); + $client = Client::query()->find($client->id); $client->skillsWithCustomKeys()->sync($collection); $this->assertCount(2, $client->skillsWithCustomKeys); self::assertIsString($skill1->cskill_id); self::assertContains($skill1->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); - self::assertNotContains($skill1->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($skill1->id, $client->skillsWithCustomKeys->pluck('cskill_id')); self::assertIsString($skill2->cskill_id); self::assertContains($skill2->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); - self::assertNotContains($skill2->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($skill2->id, $client->skillsWithCustomKeys->pluck('cskill_id')); - $check = Skill::query()->find($skill1->_id); + $check = Skill::query()->find($skill1->id); self::assertIsString($check->cskill_id); self::assertContains($check->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); - self::assertNotContains($check->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($check->id, $client->skillsWithCustomKeys->pluck('cskill_id')); - $check = Skill::query()->find($skill2->_id); + $check = Skill::query()->find($skill2->id); self::assertIsString($check->cskill_id); self::assertContains($check->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); - self::assertNotContains($check->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($check->id, $client->skillsWithCustomKeys->pluck('cskill_id')); } public function testBelongsToManyAttachWithCustomKeys(): void @@ -431,27 +431,27 @@ public function testBelongsToManyAttachWithCustomKeys(): void $skill1 = Skill::create(['cskill_id' => (string) (new ObjectId()), 'name' => 'PHP']); $skill2 = Skill::create(['cskill_id' => (string) (new ObjectId()), 'name' => 'Laravel']); - $client = Client::query()->find($client->_id); + $client = Client::query()->find($client->id); $client->skillsWithCustomKeys()->attach([$skill1->cskill_id, $skill2->cskill_id]); $this->assertCount(2, $client->skillsWithCustomKeys); self::assertIsString($skill1->cskill_id); self::assertContains($skill1->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); - self::assertNotContains($skill1->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($skill1->id, $client->skillsWithCustomKeys->pluck('cskill_id')); self::assertIsString($skill2->cskill_id); self::assertContains($skill2->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); - self::assertNotContains($skill2->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($skill2->id, $client->skillsWithCustomKeys->pluck('cskill_id')); - $check = Skill::query()->find($skill1->_id); + $check = Skill::query()->find($skill1->id); self::assertIsString($check->cskill_id); self::assertContains($check->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); - self::assertNotContains($check->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($check->id, $client->skillsWithCustomKeys->pluck('cskill_id')); - $check = Skill::query()->find($skill2->_id); + $check = Skill::query()->find($skill2->id); self::assertIsString($check->cskill_id); self::assertContains($check->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); - self::assertNotContains($check->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($check->id, $client->skillsWithCustomKeys->pluck('cskill_id')); } public function testBelongsToManyAttachModelWithCustomKeys(): void @@ -459,18 +459,18 @@ public function testBelongsToManyAttachModelWithCustomKeys(): void $client = Client::create(['cclient_id' => (string) (new ObjectId()), 'years' => '5']); $skill1 = Skill::create(['cskill_id' => (string) (new ObjectId()), 'name' => 'PHP']); - $client = Client::query()->find($client->_id); + $client = Client::query()->find($client->id); $client->skillsWithCustomKeys()->attach($skill1); $this->assertCount(1, $client->skillsWithCustomKeys); self::assertIsString($skill1->cskill_id); self::assertContains($skill1->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); - self::assertNotContains($skill1->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($skill1->id, $client->skillsWithCustomKeys->pluck('cskill_id')); - $check = Skill::query()->find($skill1->_id); - self::assertIsString($check->_id); + $check = Skill::query()->find($skill1->id); + self::assertIsString($check->id); self::assertContains($check->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); - self::assertNotContains($check->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($check->id, $client->skillsWithCustomKeys->pluck('cskill_id')); } public function testBelongsToManyAttachEloquentCollectionWithCustomKeys(): void @@ -480,27 +480,27 @@ public function testBelongsToManyAttachEloquentCollectionWithCustomKeys(): void $skill2 = Skill::create(['cskill_id' => (string) (new ObjectId()), 'name' => 'Laravel']); $collection = new Collection([$skill1, $skill2]); - $client = Client::query()->find($client->_id); + $client = Client::query()->find($client->id); $client->skillsWithCustomKeys()->attach($collection); $this->assertCount(2, $client->skillsWithCustomKeys); self::assertIsString($skill1->cskill_id); self::assertContains($skill1->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); - self::assertNotContains($skill1->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($skill1->id, $client->skillsWithCustomKeys->pluck('cskill_id')); self::assertIsString($skill2->cskill_id); self::assertContains($skill2->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); - self::assertNotContains($skill2->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($skill2->id, $client->skillsWithCustomKeys->pluck('cskill_id')); - $check = Skill::query()->find($skill1->_id); + $check = Skill::query()->find($skill1->id); self::assertIsString($check->cskill_id); self::assertContains($check->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); - self::assertNotContains($check->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($check->id, $client->skillsWithCustomKeys->pluck('cskill_id')); - $check = Skill::query()->find($skill2->_id); + $check = Skill::query()->find($skill2->id); self::assertIsString($check->cskill_id); self::assertContains($check->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); - self::assertNotContains($check->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($check->id, $client->skillsWithCustomKeys->pluck('cskill_id')); } public function testBelongsToManyDetachWithCustomKeys(): void @@ -509,7 +509,7 @@ public function testBelongsToManyDetachWithCustomKeys(): void $skill1 = Skill::create(['cskill_id' => (string) (new ObjectId()), 'name' => 'PHP']); $skill2 = Skill::create(['cskill_id' => (string) (new ObjectId()), 'name' => 'Laravel']); - $client = Client::query()->find($client->_id); + $client = Client::query()->find($client->id); $client->skillsWithCustomKeys()->sync([$skill1->cskill_id, $skill2->cskill_id]); $this->assertCount(2, $client->skillsWithCustomKeys); @@ -519,21 +519,21 @@ public function testBelongsToManyDetachWithCustomKeys(): void self::assertIsString($skill1->cskill_id); self::assertNotContains($skill1->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); - self::assertNotContains($skill1->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($skill1->id, $client->skillsWithCustomKeys->pluck('cskill_id')); self::assertIsString($skill2->cskill_id); self::assertContains($skill2->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); - self::assertNotContains($skill2->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($skill2->id, $client->skillsWithCustomKeys->pluck('cskill_id')); - $check = Skill::query()->find($skill1->_id); + $check = Skill::query()->find($skill1->id); self::assertIsString($check->cskill_id); self::assertNotContains($check->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); - self::assertNotContains($check->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($check->id, $client->skillsWithCustomKeys->pluck('cskill_id')); - $check = Skill::query()->find($skill2->_id); + $check = Skill::query()->find($skill2->id); self::assertIsString($check->cskill_id); self::assertContains($check->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); - self::assertNotContains($check->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($check->id, $client->skillsWithCustomKeys->pluck('cskill_id')); } public function testBelongsToManyDetachModelWithCustomKeys(): void @@ -542,7 +542,7 @@ public function testBelongsToManyDetachModelWithCustomKeys(): void $skill1 = Skill::create(['cskill_id' => (string) (new ObjectId()), 'name' => 'PHP']); $skill2 = Skill::create(['cskill_id' => (string) (new ObjectId()), 'name' => 'Laravel']); - $client = Client::query()->find($client->_id); + $client = Client::query()->find($client->id); $client->skillsWithCustomKeys()->sync([$skill1->cskill_id, $skill2->cskill_id]); $this->assertCount(2, $client->skillsWithCustomKeys); @@ -552,28 +552,28 @@ public function testBelongsToManyDetachModelWithCustomKeys(): void self::assertIsString($skill1->cskill_id); self::assertNotContains($skill1->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); - self::assertNotContains($skill1->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($skill1->id, $client->skillsWithCustomKeys->pluck('cskill_id')); self::assertIsString($skill2->cskill_id); self::assertContains($skill2->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); - self::assertNotContains($skill2->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($skill2->id, $client->skillsWithCustomKeys->pluck('cskill_id')); - $check = Skill::query()->find($skill1->_id); + $check = Skill::query()->find($skill1->id); self::assertIsString($check->cskill_id); self::assertNotContains($check->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); - self::assertNotContains($check->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($check->id, $client->skillsWithCustomKeys->pluck('cskill_id')); - $check = Skill::query()->find($skill2->_id); + $check = Skill::query()->find($skill2->id); self::assertIsString($check->cskill_id); self::assertContains($check->cskill_id, $client->skillsWithCustomKeys->pluck('cskill_id')); - self::assertNotContains($check->_id, $client->skillsWithCustomKeys->pluck('cskill_id')); + self::assertNotContains($check->id, $client->skillsWithCustomKeys->pluck('cskill_id')); } public function testBelongsToManySyncAlreadyPresent(): void { $user = User::create(['name' => 'John Doe']); - $client1 = Client::create(['name' => 'Test 1'])->_id; - $client2 = Client::create(['name' => 'Test 2'])->_id; + $client1 = Client::create(['name' => 'Test 1'])->id; + $client2 = Client::create(['name' => 'Test 2'])->id; $user->clients()->sync([$client1, $client2]); $this->assertCount(2, $user->clients); @@ -592,18 +592,18 @@ public function testBelongsToManyCustom(): void $group = $user->groups()->create(['name' => 'Admins']); // Refetch - $user = User::find($user->_id); - $group = Group::find($group->_id); + $user = User::find($user->id); + $group = Group::find($group->id); // Check for custom relation attributes $this->assertArrayHasKey('users', $group->getAttributes()); $this->assertArrayHasKey('groups', $user->getAttributes()); // Assert they are attached - $this->assertContains($group->_id, $user->groups->pluck('_id')->toArray()); - $this->assertContains($user->_id, $group->users->pluck('_id')->toArray()); - $this->assertEquals($group->_id, $user->groups()->first()->_id); - $this->assertEquals($user->_id, $group->users()->first()->_id); + $this->assertContains($group->id, $user->groups->pluck('id')->toArray()); + $this->assertContains($user->id, $group->users->pluck('id')->toArray()); + $this->assertEquals($group->id, $user->groups()->first()->id); + $this->assertEquals($user->id, $group->users()->first()->id); } public function testMorph(): void @@ -617,7 +617,7 @@ public function testMorph(): void $this->assertEquals(1, $user->photos->count()); $this->assertEquals($photo->id, $user->photos->first()->id); - $user = User::find($user->_id); + $user = User::find($user->id); $this->assertEquals(1, $user->photos->count()); $this->assertEquals($photo->id, $user->photos->first()->id); @@ -627,14 +627,14 @@ public function testMorph(): void $this->assertNotNull($client->photo); $this->assertEquals($photo->id, $client->photo->id); - $client = Client::find($client->_id); + $client = Client::find($client->id); $this->assertNotNull($client->photo); $this->assertEquals($photo->id, $client->photo->id); $photo = Photo::first(); $this->assertEquals($photo->hasImage->name, $user->name); - $user = User::with('photos')->find($user->_id); + $user = User::with('photos')->find($user->id); $relations = $user->getRelations(); $this->assertArrayHasKey('photos', $relations); $this->assertEquals(1, $relations['photos']->count()); @@ -655,7 +655,7 @@ public function testMorph(): void $this->assertCount(1, $photo->hasImage()->get()); $this->assertInstanceOf(Client::class, $photo->hasImage); - $this->assertEquals($client->_id, $photo->hasImage->_id); + $this->assertEquals($client->id, $photo->hasImage->id); // inverse with custom ownerKey $photo = Photo::query()->create(['url' => 'https://graph.facebook.com/young.gerald/picture']); @@ -665,7 +665,7 @@ public function testMorph(): void $this->assertCount(1, $photo->hasImageWithCustomOwnerKey()->get()); $this->assertInstanceOf(Client::class, $photo->hasImageWithCustomOwnerKey); $this->assertEquals($client->cclient_id, $photo->has_image_with_custom_owner_key_id); - $this->assertEquals($client->_id, $photo->hasImageWithCustomOwnerKey->_id); + $this->assertEquals($client->id, $photo->hasImageWithCustomOwnerKey->id); } public function testMorphToMany(): void @@ -679,10 +679,10 @@ public function testMorphToMany(): void $client->labels()->attach($label); $this->assertEquals(1, $user->labels->count()); - $this->assertContains($label->_id, $user->labels->pluck('_id')); + $this->assertContains($label->id, $user->labels->pluck('id')); $this->assertEquals(1, $client->labels->count()); - $this->assertContains($label->_id, $user->labels->pluck('_id')); + $this->assertContains($label->id, $user->labels->pluck('id')); } public function testMorphToManyAttachEloquentCollection(): void @@ -695,8 +695,8 @@ public function testMorphToManyAttachEloquentCollection(): void $client->labels()->attach(new Collection([$label1, $label2])); $this->assertEquals(2, $client->labels->count()); - $this->assertContains($label1->_id, $client->labels->pluck('_id')); - $this->assertContains($label2->_id, $client->labels->pluck('_id')); + $this->assertContains($label1->id, $client->labels->pluck('id')); + $this->assertContains($label2->id, $client->labels->pluck('id')); } public function testMorphToManyAttachMultipleIds(): void @@ -706,11 +706,11 @@ public function testMorphToManyAttachMultipleIds(): void $label1 = Label::query()->create(['name' => 'stayed solid i never fled']); $label2 = Label::query()->create(['name' => "I've got a lane and I'm in gear"]); - $client->labels()->attach([$label1->_id, $label2->_id]); + $client->labels()->attach([$label1->id, $label2->id]); $this->assertEquals(2, $client->labels->count()); - $this->assertContains($label1->_id, $client->labels->pluck('_id')); - $this->assertContains($label2->_id, $client->labels->pluck('_id')); + $this->assertContains($label1->id, $client->labels->pluck('id')); + $this->assertContains($label2->id, $client->labels->pluck('id')); } public function testMorphToManyDetaching(): void @@ -720,7 +720,7 @@ public function testMorphToManyDetaching(): void $label1 = Label::query()->create(['name' => "I'll never love again"]); $label2 = Label::query()->create(['name' => 'The way I loved you']); - $client->labels()->attach([$label1->_id, $label2->_id]); + $client->labels()->attach([$label1->id, $label2->id]); $this->assertEquals(2, $client->labels->count()); @@ -728,7 +728,7 @@ public function testMorphToManyDetaching(): void $check = $client->withoutRelations(); $this->assertEquals(1, $check->labels->count()); - $this->assertContains($label2->_id, $client->labels->pluck('_id')); + $this->assertContains($label2->id, $client->labels->pluck('id')); } public function testMorphToManyDetachingMultipleIds(): void @@ -739,15 +739,15 @@ public function testMorphToManyDetachingMultipleIds(): void $label2 = Label::query()->create(['name' => "My skin's thick, but I'm not bulletproof"]); $label3 = Label::query()->create(['name' => 'All I can be is myself, go, and tell the truth']); - $client->labels()->attach([$label1->_id, $label2->_id, $label3->_id]); + $client->labels()->attach([$label1->id, $label2->id, $label3->id]); $this->assertEquals(3, $client->labels->count()); - $client->labels()->detach([$label1->_id, $label2->_id]); + $client->labels()->detach([$label1->id, $label2->id]); $client->refresh(); $this->assertEquals(1, $client->labels->count()); - $this->assertContains($label3->_id, $client->labels->pluck('_id')); + $this->assertContains($label3->id, $client->labels->pluck('id')); } public function testMorphToManySyncing(): void @@ -763,12 +763,12 @@ public function testMorphToManySyncing(): void $client->labels()->sync($label2, false); $this->assertEquals(1, $user->labels->count()); - $this->assertContains($label->_id, $user->labels->pluck('_id')); - $this->assertNotContains($label2->_id, $user->labels->pluck('_id')); + $this->assertContains($label->id, $user->labels->pluck('id')); + $this->assertNotContains($label2->id, $user->labels->pluck('id')); $this->assertEquals(2, $client->labels->count()); - $this->assertContains($label->_id, $client->labels->pluck('_id')); - $this->assertContains($label2->_id, $client->labels->pluck('_id')); + $this->assertContains($label->id, $client->labels->pluck('id')); + $this->assertContains($label2->id, $client->labels->pluck('id')); } public function testMorphToManySyncingEloquentCollection(): void @@ -781,8 +781,8 @@ public function testMorphToManySyncingEloquentCollection(): void $client->labels()->sync(new Collection([$label, $label2])); $this->assertEquals(2, $client->labels->count()); - $this->assertContains($label->_id, $client->labels->pluck('_id')); - $this->assertContains($label2->_id, $client->labels->pluck('_id')); + $this->assertContains($label->id, $client->labels->pluck('id')); + $this->assertContains($label2->id, $client->labels->pluck('id')); } public function testMorphToManySyncingMultipleIds(): void @@ -792,11 +792,11 @@ public function testMorphToManySyncingMultipleIds(): void $label = Label::query()->create(['name' => 'They all talk about karma, how it slowly comes']); $label2 = Label::query()->create(['name' => "But life is short, enjoy it while you're young"]); - $client->labels()->sync([$label->_id, $label2->_id]); + $client->labels()->sync([$label->id, $label2->id]); $this->assertEquals(2, $client->labels->count()); - $this->assertContains($label->_id, $client->labels->pluck('_id')); - $this->assertContains($label2->_id, $client->labels->pluck('_id')); + $this->assertContains($label->id, $client->labels->pluck('id')); + $this->assertContains($label2->id, $client->labels->pluck('id')); } public function testMorphToManySyncingWithCustomKeys(): void @@ -809,15 +809,15 @@ public function testMorphToManySyncingWithCustomKeys(): void $client->labelsWithCustomKeys()->sync([$label->clabel_id, $label2->clabel_id]); $this->assertEquals(2, $client->labelsWithCustomKeys->count()); - $this->assertContains($label->_id, $client->labelsWithCustomKeys->pluck('_id')); - $this->assertContains($label2->_id, $client->labelsWithCustomKeys->pluck('_id')); + $this->assertContains($label->id, $client->labelsWithCustomKeys->pluck('id')); + $this->assertContains($label2->id, $client->labelsWithCustomKeys->pluck('id')); $client->labelsWithCustomKeys()->sync($label); $client->load('labelsWithCustomKeys'); $this->assertEquals(1, $client->labelsWithCustomKeys->count()); - $this->assertContains($label->_id, $client->labelsWithCustomKeys->pluck('_id')); - $this->assertNotContains($label2->_id, $client->labelsWithCustomKeys->pluck('_id')); + $this->assertContains($label->id, $client->labelsWithCustomKeys->pluck('id')); + $this->assertNotContains($label2->id, $client->labelsWithCustomKeys->pluck('id')); } public function testMorphToManyLoadAndRefreshing(): void @@ -829,7 +829,7 @@ public function testMorphToManyLoadAndRefreshing(): void $label = Label::query()->create(['name' => 'The greatest gift is knowledge itself']); $label2 = Label::query()->create(['name' => "I made it here all by my lonely, no askin' for help"]); - $client->labels()->sync([$label->_id, $label2->_id]); + $client->labels()->sync([$label->id, $label2->id]); $client->users()->sync($user); $this->assertEquals(2, $client->labels->count()); @@ -842,11 +842,11 @@ public function testMorphToManyLoadAndRefreshing(): void $this->assertEquals(2, $client->labels->count()); - $check = Client::query()->find($client->_id); + $check = Client::query()->find($client->id); $this->assertEquals(2, $check->labels->count()); - $check = Client::query()->with('labels')->find($client->_id); + $check = Client::query()->with('labels')->find($client->id); $this->assertEquals(2, $check->labels->count()); } @@ -860,7 +860,7 @@ public function testMorphToManyHasQuery(): void $label = Label::query()->create(['name' => "I've been digging myself down deeper"]); $label2 = Label::query()->create(['name' => "I won't stop 'til I get where you are"]); - $client->labels()->sync([$label->_id, $label2->_id]); + $client->labels()->sync([$label->id, $label2->id]); $client2->labels()->sync($label); $this->assertEquals(2, $client->labels->count()); @@ -871,12 +871,12 @@ public function testMorphToManyHasQuery(): void $check = Client::query()->has('labels', '>', 1)->get(); $this->assertCount(1, $check); - $this->assertContains($client->_id, $check->pluck('_id')); + $this->assertContains($client->id, $check->pluck('id')); $check = Client::query()->has('labels', '<', 2)->get(); $this->assertCount(2, $check); - $this->assertContains($client2->_id, $check->pluck('_id')); - $this->assertContains($client3->_id, $check->pluck('_id')); + $this->assertContains($client2->id, $check->pluck('id')); + $this->assertContains($client3->id, $check->pluck('id')); } public function testMorphedByMany(): void @@ -891,10 +891,10 @@ public function testMorphedByMany(): void $label->clients()->attach($client); $this->assertEquals(1, $label->users->count()); - $this->assertContains($user->_id, $label->users->pluck('_id')); + $this->assertContains($user->id, $label->users->pluck('id')); $this->assertEquals(1, $label->clients->count()); - $this->assertContains($client->_id, $label->clients->pluck('_id')); + $this->assertContains($client->id, $label->clients->pluck('id')); } public function testMorphedByManyAttachEloquentCollection(): void @@ -908,8 +908,8 @@ public function testMorphedByManyAttachEloquentCollection(): void $label->clients()->attach(new Collection([$client1, $client2])); $this->assertEquals(2, $label->clients->count()); - $this->assertContains($client1->_id, $label->clients->pluck('_id')); - $this->assertContains($client2->_id, $label->clients->pluck('_id')); + $this->assertContains($client1->id, $label->clients->pluck('id')); + $this->assertContains($client2->id, $label->clients->pluck('id')); $client1->refresh(); $this->assertEquals(1, $client1->labels->count()); @@ -923,11 +923,11 @@ public function testMorphedByManyAttachMultipleIds(): void $label = Label::query()->create(['name' => 'Always in the game and never played by the rules']); - $label->clients()->attach([$client1->_id, $client2->_id]); + $label->clients()->attach([$client1->id, $client2->id]); $this->assertEquals(2, $label->clients->count()); - $this->assertContains($client1->_id, $label->clients->pluck('_id')); - $this->assertContains($client2->_id, $label->clients->pluck('_id')); + $this->assertContains($client1->id, $label->clients->pluck('id')); + $this->assertContains($client2->id, $label->clients->pluck('id')); $client1->refresh(); $this->assertEquals(1, $client1->labels->count()); @@ -941,15 +941,15 @@ public function testMorphedByManyDetaching(): void $label = Label::query()->create(['name' => 'Seasons change and our love went cold']); - $label->clients()->attach([$client1->_id, $client2->_id]); + $label->clients()->attach([$client1->id, $client2->id]); $this->assertEquals(2, $label->clients->count()); - $label->clients()->detach($client1->_id); + $label->clients()->detach($client1->id); $check = $label->withoutRelations(); $this->assertEquals(1, $check->clients->count()); - $this->assertContains($client2->_id, $check->clients->pluck('_id')); + $this->assertContains($client2->id, $check->clients->pluck('id')); } public function testMorphedByManyDetachingMultipleIds(): void @@ -960,15 +960,15 @@ public function testMorphedByManyDetachingMultipleIds(): void $label = Label::query()->create(['name' => "Run away, but we're running in circles"]); - $label->clients()->attach([$client1->_id, $client2->_id, $client3->_id]); + $label->clients()->attach([$client1->id, $client2->id, $client3->id]); $this->assertEquals(3, $label->clients->count()); - $label->clients()->detach([$client1->_id, $client2->_id]); + $label->clients()->detach([$client1->id, $client2->id]); $label->load('clients'); $this->assertEquals(1, $label->clients->count()); - $this->assertContains($client3->_id, $label->clients->pluck('_id')); + $this->assertContains($client3->id, $label->clients->pluck('id')); } public function testMorphedByManySyncing(): void @@ -984,9 +984,9 @@ public function testMorphedByManySyncing(): void $label->clients()->sync($client3, false); $this->assertEquals(3, $label->clients->count()); - $this->assertContains($client1->_id, $label->clients->pluck('_id')); - $this->assertContains($client2->_id, $label->clients->pluck('_id')); - $this->assertContains($client3->_id, $label->clients->pluck('_id')); + $this->assertContains($client1->id, $label->clients->pluck('id')); + $this->assertContains($client2->id, $label->clients->pluck('id')); + $this->assertContains($client3->id, $label->clients->pluck('id')); } public function testMorphedByManySyncingEloquentCollection(): void @@ -1000,10 +1000,10 @@ public function testMorphedByManySyncingEloquentCollection(): void $label->clients()->sync(new Collection([$client1, $client2])); $this->assertEquals(2, $label->clients->count()); - $this->assertContains($client1->_id, $label->clients->pluck('_id')); - $this->assertContains($client2->_id, $label->clients->pluck('_id')); + $this->assertContains($client1->id, $label->clients->pluck('id')); + $this->assertContains($client2->id, $label->clients->pluck('id')); - $this->assertNotContains($extra->_id, $label->clients->pluck('_id')); + $this->assertNotContains($extra->id, $label->clients->pluck('id')); } public function testMorphedByManySyncingMultipleIds(): void @@ -1014,13 +1014,13 @@ public function testMorphedByManySyncingMultipleIds(): void $label = Label::query()->create(['name' => "Love ain't patient, it's not kind. true love waits to rob you blind"]); - $label->clients()->sync([$client1->_id, $client2->_id]); + $label->clients()->sync([$client1->id, $client2->id]); $this->assertEquals(2, $label->clients->count()); - $this->assertContains($client1->_id, $label->clients->pluck('_id')); - $this->assertContains($client2->_id, $label->clients->pluck('_id')); + $this->assertContains($client1->id, $label->clients->pluck('id')); + $this->assertContains($client2->id, $label->clients->pluck('id')); - $this->assertNotContains($extra->_id, $label->clients->pluck('_id')); + $this->assertNotContains($extra->id, $label->clients->pluck('id')); } public function testMorphedByManySyncingWithCustomKeys(): void @@ -1034,19 +1034,19 @@ public function testMorphedByManySyncingWithCustomKeys(): void $label->clientsWithCustomKeys()->sync([$client1->cclient_id, $client2->cclient_id]); $this->assertEquals(2, $label->clientsWithCustomKeys->count()); - $this->assertContains($client1->_id, $label->clientsWithCustomKeys->pluck('_id')); - $this->assertContains($client2->_id, $label->clientsWithCustomKeys->pluck('_id')); + $this->assertContains($client1->id, $label->clientsWithCustomKeys->pluck('id')); + $this->assertContains($client2->id, $label->clientsWithCustomKeys->pluck('id')); - $this->assertNotContains($client3->_id, $label->clientsWithCustomKeys->pluck('_id')); + $this->assertNotContains($client3->id, $label->clientsWithCustomKeys->pluck('id')); $label->clientsWithCustomKeys()->sync($client3); $label->load('clientsWithCustomKeys'); $this->assertEquals(1, $label->clientsWithCustomKeys->count()); - $this->assertNotContains($client1->_id, $label->clientsWithCustomKeys->pluck('_id')); - $this->assertNotContains($client2->_id, $label->clientsWithCustomKeys->pluck('_id')); + $this->assertNotContains($client1->id, $label->clientsWithCustomKeys->pluck('id')); + $this->assertNotContains($client2->id, $label->clientsWithCustomKeys->pluck('id')); - $this->assertContains($client3->_id, $label->clientsWithCustomKeys->pluck('_id')); + $this->assertContains($client3->id, $label->clientsWithCustomKeys->pluck('id')); } public function testMorphedByManyLoadAndRefreshing(): void @@ -1072,11 +1072,11 @@ public function testMorphedByManyLoadAndRefreshing(): void $this->assertEquals(3, $label->clients->count()); - $check = Label::query()->find($label->_id); + $check = Label::query()->find($label->id); $this->assertEquals(3, $check->clients->count()); - $check = Label::query()->with('clients')->find($label->_id); + $check = Label::query()->with('clients')->find($label->id); $this->assertEquals(3, $check->clients->count()); } @@ -1100,16 +1100,16 @@ public function testMorphedByManyHasQuery(): void $check = Label::query()->has('clients')->get(); $this->assertCount(2, $check); - $this->assertContains($label->_id, $check->pluck('_id')); - $this->assertContains($label2->_id, $check->pluck('_id')); + $this->assertContains($label->id, $check->pluck('id')); + $this->assertContains($label2->id, $check->pluck('id')); $check = Label::query()->has('users')->get(); $this->assertCount(1, $check); - $this->assertContains($label3->_id, $check->pluck('_id')); + $this->assertContains($label3->id, $check->pluck('id')); $check = Label::query()->has('clients', '>', 1)->get(); $this->assertCount(1, $check); - $this->assertContains($label->_id, $check->pluck('_id')); + $this->assertContains($label->id, $check->pluck('id')); } public function testHasManyHas(): void @@ -1219,18 +1219,18 @@ public function testDoubleSaveOneToMany(): void $author->books()->save($book); $author->save(); $this->assertEquals(1, $author->books()->count()); - $this->assertEquals($author->_id, $book->author_id); + $this->assertEquals($author->id, $book->author_id); $author = User::where('name', 'George R. R. Martin')->first(); $book = Book::where('title', 'A Game of Thrones')->first(); $this->assertEquals(1, $author->books()->count()); - $this->assertEquals($author->_id, $book->author_id); + $this->assertEquals($author->id, $book->author_id); $author->books()->save($book); $author->books()->save($book); $author->save(); $this->assertEquals(1, $author->books()->count()); - $this->assertEquals($author->_id, $book->author_id); + $this->assertEquals($author->id, $book->author_id); } public function testDoubleSaveManyToMany(): void @@ -1243,29 +1243,29 @@ public function testDoubleSaveManyToMany(): void $user->save(); $this->assertEquals(1, $user->clients()->count()); - $this->assertEquals([$user->_id], $client->user_ids); - $this->assertEquals([$client->_id], $user->client_ids); + $this->assertEquals([$user->id], $client->user_ids); + $this->assertEquals([$client->id], $user->client_ids); $user = User::where('name', 'John Doe')->first(); $client = Client::where('name', 'Admins')->first(); $this->assertEquals(1, $user->clients()->count()); - $this->assertEquals([$user->_id], $client->user_ids); - $this->assertEquals([$client->_id], $user->client_ids); + $this->assertEquals([$user->id], $client->user_ids); + $this->assertEquals([$client->id], $user->client_ids); $user->clients()->save($client); $user->clients()->save($client); $user->save(); $this->assertEquals(1, $user->clients()->count()); - $this->assertEquals([$user->_id], $client->user_ids); - $this->assertEquals([$client->_id], $user->client_ids); + $this->assertEquals([$user->id], $client->user_ids); + $this->assertEquals([$client->id], $user->client_ids); } public function testWhereBelongsTo() { $user = User::create(['name' => 'John Doe']); - Item::create(['user_id' => $user->_id]); - Item::create(['user_id' => $user->_id]); - Item::create(['user_id' => $user->_id]); + Item::create(['user_id' => $user->id]); + Item::create(['user_id' => $user->id]); + Item::create(['user_id' => $user->id]); Item::create(['user_id' => null]); $items = Item::whereBelongsTo($user)->get(); diff --git a/tests/SessionTest.php b/tests/SessionTest.php new file mode 100644 index 000000000..7ffbb51f0 --- /dev/null +++ b/tests/SessionTest.php @@ -0,0 +1,33 @@ +getCollection('sessions')->drop(); + + parent::tearDown(); + } + + public function testDatabaseSessionHandler() + { + $sessionId = '123'; + + $handler = new DatabaseSessionHandler( + $this->app['db']->connection('mongodb'), + 'sessions', + 10, + ); + + $handler->write($sessionId, 'foo'); + $this->assertEquals('foo', $handler->read($sessionId)); + + $handler->write($sessionId, 'bar'); + $this->assertEquals('bar', $handler->read($sessionId)); + } +} diff --git a/tests/Ticket/GH2489Test.php b/tests/Ticket/GH2489Test.php new file mode 100644 index 000000000..62ce11d0e --- /dev/null +++ b/tests/Ticket/GH2489Test.php @@ -0,0 +1,49 @@ + 'Location 1', + 'images' => [ + ['_id' => 1, 'uri' => 'image1.jpg'], + ['_id' => 2, 'uri' => 'image2.jpg'], + ], + ], + [ + 'name' => 'Location 2', + 'images' => [ + ['_id' => 3, 'uri' => 'image3.jpg'], + ['_id' => 4, 'uri' => 'image4.jpg'], + ], + ], + ]); + + // With _id + $results = Location::whereIn('images._id', [1])->get(); + + $this->assertCount(1, $results); + $this->assertSame('Location 1', $results->first()->name); + + // With id + $results = Location::whereIn('images.id', [1])->get(); + + $this->assertCount(1, $results); + $this->assertSame('Location 1', $results->first()->name); + } +} diff --git a/tests/Ticket/GH2783Test.php b/tests/Ticket/GH2783Test.php index 73324ddc0..f1580c1e6 100644 --- a/tests/Ticket/GH2783Test.php +++ b/tests/Ticket/GH2783Test.php @@ -32,7 +32,7 @@ public function testMorphToInfersCustomOwnerKey() $queriedImageWithPost = GH2783Image::with('imageable')->find($imageWithPost->getKey()); $this->assertInstanceOf(GH2783Post::class, $queriedImageWithPost->imageable); - $this->assertEquals($post->_id, $queriedImageWithPost->imageable->getKey()); + $this->assertEquals($post->id, $queriedImageWithPost->imageable->getKey()); $queriedImageWithUser = GH2783Image::with('imageable')->find($imageWithUser->getKey()); $this->assertInstanceOf(GH2783User::class, $queriedImageWithUser->imageable); diff --git a/tests/TransactionTest.php b/tests/TransactionTest.php index 190f7487a..bbb45ac05 100644 --- a/tests/TransactionTest.php +++ b/tests/TransactionTest.php @@ -44,7 +44,7 @@ public function testCreateWithCommit(): void $this->assertTrue($klinson->exists); $this->assertEquals('klinson', $klinson->name); - $check = User::find($klinson->_id); + $check = User::find($klinson->id); $this->assertInstanceOf(User::class, $check); $this->assertEquals($klinson->name, $check->name); } @@ -60,7 +60,7 @@ public function testCreateRollBack(): void $this->assertTrue($klinson->exists); $this->assertEquals('klinson', $klinson->name); - $this->assertFalse(User::where('_id', $klinson->_id)->exists()); + $this->assertFalse(User::where('id', $klinson->id)->exists()); } public function testInsertWithCommit(): void @@ -93,7 +93,7 @@ public function testEloquentCreateWithCommit(): void $this->assertTrue($klinson->exists); $this->assertNotNull($klinson->getIdAttribute()); - $check = User::find($klinson->_id); + $check = User::find($klinson->id); $this->assertInstanceOf(User::class, $check); $this->assertEquals($check->name, $klinson->name); } @@ -110,7 +110,7 @@ public function testEloquentCreateWithRollBack(): void $this->assertTrue($klinson->exists); $this->assertNotNull($klinson->getIdAttribute()); - $this->assertFalse(User::where('_id', $klinson->_id)->exists()); + $this->assertFalse(User::where('id', $klinson->id)->exists()); } public function testInsertGetIdWithCommit(): void @@ -132,7 +132,7 @@ public function testInsertGetIdWithRollBack(): void DB::rollBack(); $this->assertInstanceOf(ObjectId::class, $userId); - $this->assertFalse(DB::table('users')->where('_id', (string) $userId)->exists()); + $this->assertFalse(DB::table('users')->where('id', (string) $userId)->exists()); } public function testUpdateWithCommit(): void @@ -176,8 +176,8 @@ public function testEloquentUpdateWithCommit(): void $this->assertEquals(21, $klinson->age); $this->assertEquals(39, $alcaeus->age); - $this->assertTrue(User::where('_id', $klinson->_id)->where('age', 21)->exists()); - $this->assertTrue(User::where('_id', $alcaeus->_id)->where('age', 39)->exists()); + $this->assertTrue(User::where('id', $klinson->id)->where('age', 21)->exists()); + $this->assertTrue(User::where('id', $alcaeus->id)->where('age', 39)->exists()); } public function testEloquentUpdateWithRollBack(): void @@ -197,8 +197,8 @@ public function testEloquentUpdateWithRollBack(): void $this->assertEquals(21, $klinson->age); $this->assertEquals(39, $alcaeus->age); - $this->assertFalse(User::where('_id', $klinson->_id)->where('age', 21)->exists()); - $this->assertFalse(User::where('_id', $alcaeus->_id)->where('age', 39)->exists()); + $this->assertFalse(User::where('id', $klinson->id)->where('age', 21)->exists()); + $this->assertFalse(User::where('id', $alcaeus->id)->where('age', 39)->exists()); } public function testDeleteWithCommit(): void @@ -234,7 +234,7 @@ public function testEloquentDeleteWithCommit(): void $klinson->delete(); DB::commit(); - $this->assertFalse(User::where('_id', $klinson->_id)->exists()); + $this->assertFalse(User::where('id', $klinson->id)->exists()); } public function testEloquentDeleteWithRollBack(): void @@ -246,7 +246,7 @@ public function testEloquentDeleteWithRollBack(): void $klinson->delete(); DB::rollBack(); - $this->assertTrue(User::where('_id', $klinson->_id)->exists()); + $this->assertTrue(User::where('id', $klinson->id)->exists()); } public function testIncrementWithCommit(): void @@ -390,7 +390,7 @@ public function testTransactionRespectsRepetitionLimit(): void $this->assertSame(2, $timesRun); - $check = User::find($klinson->_id); + $check = User::find($klinson->id); $this->assertInstanceOf(User::class, $check); // Age is expected to be 24: the callback is executed twice, incrementing age by 2 every time From 80694e4974715d7eb7932f1dc13e97bc195d272d Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Fri, 23 Aug 2024 10:57:52 -0400 Subject: [PATCH 332/446] DOCSP-42155: adjust for updated source constants (#3110) * DOCSP-42155: adjust for updated source constants * MW PR fixes 1 --- docs/cache.txt | 2 +- docs/compatibility.txt | 4 ++-- docs/eloquent-models.txt | 4 ++-- docs/eloquent-models/model-class.txt | 24 +++++++++---------- docs/eloquent-models/relationships.txt | 20 ++++++++-------- docs/eloquent-models/schema-builder.txt | 10 ++++---- docs/feature-compatibility.txt | 18 +++++++------- docs/fundamentals.txt | 2 +- docs/fundamentals/aggregation-builder.txt | 6 ++--- docs/fundamentals/connection.txt | 2 +- .../connection/connect-to-mongodb.txt | 8 +++---- docs/fundamentals/database-collection.txt | 10 ++++---- docs/fundamentals/read-operations.txt | 2 +- docs/fundamentals/write-operations.txt | 20 ++++++++-------- .../framework-compatibility-laravel.rst | 2 +- docs/index.txt | 19 ++++++++------- docs/issues-and-help.txt | 6 ++--- docs/query-builder.txt | 6 ++--- docs/quick-start.txt | 4 ++-- docs/quick-start/download-and-install.txt | 12 +++++----- docs/quick-start/next-steps.txt | 4 ++-- docs/quick-start/view-data.txt | 2 +- docs/quick-start/write-data.txt | 5 ++-- docs/transactions.txt | 10 ++++---- docs/upgrade.txt | 6 ++--- docs/usage-examples/deleteMany.txt | 2 +- docs/usage-examples/deleteOne.txt | 2 +- docs/usage-examples/find.txt | 2 +- docs/usage-examples/findOne.txt | 2 +- docs/usage-examples/updateMany.txt | 2 +- docs/usage-examples/updateOne.txt | 2 +- docs/user-authentication.txt | 2 +- 32 files changed, 111 insertions(+), 111 deletions(-) diff --git a/docs/cache.txt b/docs/cache.txt index 19609b94b..d3fd0f6e6 100644 --- a/docs/cache.txt +++ b/docs/cache.txt @@ -150,7 +150,7 @@ adds 5, and removes 2. .. note:: - {+odm-short+} supports incrementing and decrementing with integer and float values. + The {+odm-short+} supports incrementing and decrementing with integer and float values. For more information about using the cache, see the `Laravel Cache documentation `__. diff --git a/docs/compatibility.txt b/docs/compatibility.txt index dc0b33148..e02bda581 100644 --- a/docs/compatibility.txt +++ b/docs/compatibility.txt @@ -21,10 +21,10 @@ Laravel Compatibility --------------------- The following compatibility table specifies the versions of Laravel and -{+odm-short+} that you can use together. +the {+odm-short+} that you can use together. .. include:: /includes/framework-compatibility-laravel.rst -To find compatibility information for unmaintained versions of {+odm-short+}, +To find compatibility information for unmaintained versions of the {+odm-short+}, see `Laravel Version Compatibility <{+mongodb-laravel-gh+}/blob/3.9/README.md#installation>`__ on GitHub. diff --git a/docs/eloquent-models.txt b/docs/eloquent-models.txt index 95fe24d15..8aee6baf7 100644 --- a/docs/eloquent-models.txt +++ b/docs/eloquent-models.txt @@ -13,12 +13,12 @@ Eloquent Models Eloquent models are part of the Laravel Eloquent object-relational mapping (ORM) framework, which lets you to work with data in a relational -database by using model classes and Eloquent syntax. {+odm-short+} extends +database by using model classes and Eloquent syntax. The {+odm-short+} extends this framework so that you can use Eloquent syntax to work with data in a MongoDB database. This section contains guidance on how to use Eloquent models in -{+odm-short+} to work with MongoDB in the following ways: +the {+odm-short+} to work with MongoDB in the following ways: - :ref:`laravel-eloquent-model-class` shows how to define models and customize their behavior diff --git a/docs/eloquent-models/model-class.txt b/docs/eloquent-models/model-class.txt index 9d38fe1a7..f9d3e8bcc 100644 --- a/docs/eloquent-models/model-class.txt +++ b/docs/eloquent-models/model-class.txt @@ -20,12 +20,12 @@ Eloquent Model Class Overview -------- -This guide shows you how to use the {+odm-long+} to define and +This guide shows you how to use {+odm-long+} to define and customize Laravel Eloquent models. You can use these models to work with MongoDB data by using the Laravel Eloquent object-relational mapper (ORM). The following sections explain how to add Laravel Eloquent ORM behaviors -to {+odm-short+} models: +to {+odm-long+} models: - :ref:`laravel-model-define` demonstrates how to create a model class. - :ref:`laravel-authenticatable-model` shows how to set MongoDB as the @@ -47,7 +47,7 @@ Define an Eloquent Model Class Eloquent models are classes that represent your data. They include methods that perform database operations such as inserts, updates, and deletes. -To declare a {+odm-short+} model, create a class in the ``app/Models`` +To declare a {+odm-long+} model, create a class in the ``app/Models`` directory of your Laravel application that extends ``MongoDB\Laravel\Eloquent\Model`` as shown in the following code example: @@ -78,8 +78,8 @@ Extend the Authenticatable Model -------------------------------- To configure MongoDB as the Laravel user provider, you can extend the -{+odm-short+} ``MongoDB\Laravel\Auth\User`` class. The following code example -shows how to extend this class: +{+odm-short+} ``MongoDB\Laravel\Auth\User`` class. The following code +example shows how to extend this class: .. literalinclude:: /includes/eloquent-models/AuthenticatableUser.php :language: php @@ -155,7 +155,7 @@ To learn more about primary key behavior and customization options, see in the Laravel docs. To learn more about the ``_id`` field, ObjectIDs, and the MongoDB document -structure, see :manual:`Documents ` in the MongoDB server docs. +structure, see :manual:`Documents ` in the Server manual. .. _laravel-model-soft-delete: @@ -227,7 +227,7 @@ less than three years ago: Planet::where( 'discovery_dt', '>', new DateTime('-3 years'))->get(); To learn more about MongoDB's data types, see :manual:`BSON Types ` -in the MongoDB server docs. +in the Server manual. To learn more about the Laravel casting helper and supported types, see `Attribute Casting `__ in the Laravel docs. @@ -289,7 +289,7 @@ in the Laravel docs. Extend Third-Party Model Classes -------------------------------- -You can use {+odm-short+} to extend a third-party model class by +You can use the {+odm-short+} to extend a third-party model class by including the ``DocumentModel`` trait when defining your model class. By including this trait, you can make the third-party class compatible with MongoDB. @@ -299,7 +299,7 @@ declare the following properties in your class: - ``$primaryKey = '_id'``, because the ``_id`` field uniquely identifies MongoDB documents -- ``$keyType = 'string'``, because {+odm-short+} casts MongoDB +- ``$keyType = 'string'``, because the {+odm-short+} casts MongoDB ``ObjectId`` values to type ``string`` Extended Class Example @@ -344,7 +344,7 @@ appropriate import to your model: .. note:: When enabling soft deletes on a mass prunable model, you must import the - following {+odm-short+} packages: + following {+odm-long+} packages: - ``MongoDB\Laravel\Eloquent\SoftDeletes`` - ``MongoDB\Laravel\Eloquent\MassPrunable`` @@ -437,11 +437,11 @@ You can define the new model class with the following behavior: In the ``"WASP-39 b"`` document in the following code, the ``schema_version`` field value is less than ``2``. When you retrieve the -document, {+odm-short+} adds the ``galaxy`` field and updates the schema +document, the {+odm-short+} adds the ``galaxy`` field and updates the schema version to the current version, ``2``. The ``"Saturn"`` document does not contain the ``schema_version`` field, -so {+odm-short+} assigns it the current schema version upon saving. +so the {+odm-short+} assigns it the current schema version upon saving. Finally, the code retrieves the models from the collection to demonstrate the changes: diff --git a/docs/eloquent-models/relationships.txt b/docs/eloquent-models/relationships.txt index b71b8b8c2..a4a2c87a3 100644 --- a/docs/eloquent-models/relationships.txt +++ b/docs/eloquent-models/relationships.txt @@ -32,7 +32,7 @@ related model by using the same syntax as you use to access a property on the model. The following sections describe the Laravel Eloquent and MongoDB-specific -relationships available in {+odm-short+} and show examples of how to define +relationships available in the {+odm-short+} and show examples of how to define and use them: - :ref:`One to one relationship `, @@ -59,7 +59,7 @@ When you add a one to one relationship, Eloquent lets you access the model by using a dynamic property and stores the model's document ID on the related model. -In {+odm-short+}, you can define a one to one relationship by using the +In {+odm-long+}, you can define a one to one relationship by using the ``hasOne()`` method or ``belongsTo()`` method. When you add the inverse of the relationship by using the ``belongsTo()`` @@ -143,7 +143,7 @@ When you add a one to many relationship method, Eloquent lets you access the model by using a dynamic property and stores the parent model's document ID on each child model document. -In {+odm-short+}, you can define a one to many relationship by adding the +In {+odm-long+}, you can define a one to many relationship by adding the ``hasMany()`` method on the parent class and, optionally, the ``belongsTo()`` method on the child class. @@ -234,17 +234,17 @@ A many to many relationship consists of a relationship between two different model types in which, for each type of model, an instance of the model can be related to multiple instances of the other type. -In {+odm-short+}, you can define a many to many relationship by adding the +In {+odm-long+}, you can define a many to many relationship by adding the ``belongsToMany()`` method to both related classes. When you define a many to many relationship in a relational database, Laravel -creates a pivot table to track the relationships. When you use {+odm-short+}, +creates a pivot table to track the relationships. When you use the {+odm-short+}, it omits the pivot table creation and adds the related document IDs to a document field derived from the related model class name. .. tip:: - Since {+odm-short+} uses a document field instead of a pivot table, omit + Since the {+odm-short+} uses a document field instead of a pivot table, omit the pivot table parameter from the ``belongsToMany()`` constructor or set it to ``null``. @@ -365,7 +365,7 @@ to meet one or more of the following requirements: data - Reducing the number of reads required to fetch the data -In {+odm-short+}, you can define embedded documents by adding one of the +In {+odm-long+}, you can define embedded documents by adding one of the following methods: - ``embedsOne()`` to embed a single document @@ -377,7 +377,7 @@ following methods: objects. To learn more about the MongoDB embedded document pattern, see the following -MongoDB server tutorials: +MongoDB Server tutorials: - :manual:`Model One-to-One Relationships with Embedded Documents ` - :manual:`Model One-to-Many Relationships with Embedded Documents ` @@ -446,13 +446,13 @@ running the code: Cross-Database Relationships ---------------------------- -A cross-database relationship in {+odm-short+} is a relationship between models +A cross-database relationship in {+odm-long+} is a relationship between models stored in a relational database and models stored in a MongoDB database. When you add a cross-database relationship, Eloquent lets you access the related models by using a dynamic property. -{+odm-short+} supports the following cross-database relationship methods: +The {+odm-short+} supports the following cross-database relationship methods: - ``hasOne()`` - ``hasMany()`` diff --git a/docs/eloquent-models/schema-builder.txt b/docs/eloquent-models/schema-builder.txt index 0003d3e7b..510365d06 100644 --- a/docs/eloquent-models/schema-builder.txt +++ b/docs/eloquent-models/schema-builder.txt @@ -24,14 +24,14 @@ Laravel provides a **facade** to access the schema builder class ``Schema``, which lets you create and modify tables. Facades are static interfaces to classes that make the syntax more concise and improve testability. -{+odm-short+} supports a subset of the index and collection management methods +The {+odm-short+} supports a subset of the index and collection management methods in the Laravel ``Schema`` facade. To learn more about facades, see `Facades `__ in the Laravel documentation. The following sections describe the Laravel schema builder features available -in {+odm-short+} and show examples of how to use them: +in the {+odm-short+} and show examples of how to use them: - :ref:`` - :ref:`` @@ -39,7 +39,7 @@ in {+odm-short+} and show examples of how to use them: .. note:: - {+odm-short+} supports managing indexes and collections, but + The {+odm-short+} supports managing indexes and collections, but excludes support for MongoDB JSON schemas for data validation. To learn more about JSON schema validation, see :manual:`Schema Validation ` in the {+server-docs-name+}. @@ -67,7 +67,7 @@ following changes to perform the schema changes on your MongoDB database: - Replace the ``Illuminate\Database\Schema\Blueprint`` import with ``MongoDB\Laravel\Schema\Blueprint`` if it is referenced in your migration -- Use only commands and syntax supported by {+odm-short+} +- Use only commands and syntax supported by the {+odm-short+} .. tip:: @@ -251,7 +251,7 @@ in the {+server-docs-name+}. Create Sparse, TTL, and Unique Indexes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can use {+odm-short+} helper methods to create the following types of +You can use {+odm-long+} helper methods to create the following types of indexes: - Sparse indexes, which allow index entries only for documents that contain the diff --git a/docs/feature-compatibility.txt b/docs/feature-compatibility.txt index 0c28300ba..57c8c7486 100644 --- a/docs/feature-compatibility.txt +++ b/docs/feature-compatibility.txt @@ -21,11 +21,11 @@ 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+}. +{+odm-long+}. This page discusses Laravel version 11.x feature +availability in the {+odm-short+}. The following sections contain tables that describe whether individual -features are available in {+odm-short+}. +features are available in the {+odm-short+}. Database Features ----------------- @@ -66,7 +66,7 @@ Database Features Query Features -------------- -The following Eloquent methods are not supported in {+odm-short+}: +The following Eloquent methods are not supported in the {+odm-short+}: - ``toSql()`` - ``toRawSql()`` @@ -168,19 +168,19 @@ The following Eloquent methods are not supported in {+odm-short+}: Pagination Features ------------------- -{+odm-short+} supports all Laravel pagination features. +The {+odm-short+} supports all Laravel pagination features. Migration Features ------------------ -{+odm-short+} supports all Laravel migration features, but the +The {+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. +The {+odm-short+} supports all Laravel seeding features. Eloquent Features ----------------- @@ -268,7 +268,7 @@ Eloquent Relationship Features Eloquent Collection Features ---------------------------- -{+odm-short+} supports all Eloquent collection features. +The {+odm-short+} supports all Eloquent collection features. Eloquent Mutator Features ------------------------- @@ -304,4 +304,4 @@ Eloquent Mutator Features Eloquent Model Factory Features ------------------------------- -{+odm-short+} supports all Eloquent factory features. +The {+odm-short+} supports all Eloquent factory features. diff --git a/docs/fundamentals.txt b/docs/fundamentals.txt index d5ee9e796..f0945ad63 100644 --- a/docs/fundamentals.txt +++ b/docs/fundamentals.txt @@ -21,7 +21,7 @@ Fundamentals /fundamentals/write-operations /fundamentals/aggregation-builder -Learn more about the following concepts related to the {+odm-long+}: +Learn more about the following concepts related to {+odm-long+}: - :ref:`laravel-fundamentals-connection` - :ref:`laravel-db-coll` diff --git a/docs/fundamentals/aggregation-builder.txt b/docs/fundamentals/aggregation-builder.txt index 79d650499..0dbcd3823 100644 --- a/docs/fundamentals/aggregation-builder.txt +++ b/docs/fundamentals/aggregation-builder.txt @@ -33,7 +33,7 @@ An aggregation pipeline is composed of **aggregation stages**. Aggregation stages use operators to process input data and produce data that the next stage uses as its input. -The {+odm-short+} aggregation builder lets you build aggregation stages and +The {+odm-long+} aggregation builder lets you build aggregation stages and aggregation pipelines. The following sections show examples of how to use the aggregation builder to create the stages of an aggregation pipeline: @@ -43,7 +43,7 @@ aggregation builder to create the stages of an aggregation pipeline: .. tip:: - The aggregation builder feature is available only in {+odm-short+} versions + The aggregation builder feature is available only in {+odm-long+} versions 4.3 and later. To learn more about running aggregations without using the aggregation builder, see :ref:`laravel-query-builder-aggregations` in the Query Builder guide. @@ -136,7 +136,7 @@ available indexes and reduce the amount of data the subsequent stages process. aggregation stages. This example constructs a query filter for a **match** aggregation stage by -using the ``MongoDB\Builder\Query`` builder. The match stage includes the the +using the ``MongoDB\Builder\Query`` builder. The match stage includes the following criteria: - Returns results that match either of the query filters by using the diff --git a/docs/fundamentals/connection.txt b/docs/fundamentals/connection.txt index 3141cfeaf..26a937323 100644 --- a/docs/fundamentals/connection.txt +++ b/docs/fundamentals/connection.txt @@ -26,7 +26,7 @@ Connections Overview -------- -Learn how to use {+odm-short+} to set up a connection to a MongoDB deployment +Learn how to use {+odm-long+} to set up a connection to a MongoDB deployment and specify connection behavior in the following sections: - :ref:`laravel-connect-to-mongodb` diff --git a/docs/fundamentals/connection/connect-to-mongodb.txt b/docs/fundamentals/connection/connect-to-mongodb.txt index 5d697b3a2..d17bcf2be 100644 --- a/docs/fundamentals/connection/connect-to-mongodb.txt +++ b/docs/fundamentals/connection/connect-to-mongodb.txt @@ -21,7 +21,7 @@ Overview -------- In this guide, you can learn how to connect your Laravel application to a -MongoDB instance or replica set deployment by using {+odm-short+}. +MongoDB instance or replica set deployment by using {+odm-long+}. This guide includes the following sections: @@ -41,7 +41,7 @@ Connection URI -------------- A **connection URI**, also known as a connection string, specifies how -{+odm-short+} connects to MongoDB and how to behave while connected. +the {+odm-short+} connects to MongoDB and how to behave while connected. Parts of a Connection URI ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -86,7 +86,7 @@ To learn more about connection options, see Laravel Database Connection Configuration ------------------------------------------ -{+odm-short+} lets you configure your MongoDB database connection in the +The {+odm-short+} lets you configure your MongoDB database connection in the ``config/database.php`` Laravel application file. You can specify the following connection details in this file: @@ -308,7 +308,7 @@ following sample values: DB_URI="mongodb://myUser:myPass123@host1:27017,host2:27017,host3:27017/?replicaSet=myRS" -When connecting to a replica set, the library that {+odm-short+} uses to manage +When connecting to a replica set, the library that the {+odm-short+} uses to manage connections with MongoDB performs the following actions unless otherwise specified: diff --git a/docs/fundamentals/database-collection.txt b/docs/fundamentals/database-collection.txt index 7bbae4786..dbb6d7b0c 100644 --- a/docs/fundamentals/database-collection.txt +++ b/docs/fundamentals/database-collection.txt @@ -20,14 +20,14 @@ Databases and Collections Overview -------- -In this guide, you can learn how to use {+odm-short+} to access +In this guide, you can learn how to use {+odm-long+} to access and manage MongoDB databases and collections. MongoDB organizes data in a hierarchical structure. A MongoDB deployment contains one or more **databases**, and each database contains one or more **collections**. In each collection, MongoDB stores data as **documents** that contain field-and-value pairs. In -{+odm-short+}, you can access documents through Eloquent models. +the {+odm-short+}, you can access documents through Eloquent models. To learn more about the document data format, see :manual:`Documents ` in the {+server-docs-name+}. @@ -68,7 +68,7 @@ create a database connection to the ``animals`` database in the ], ... ] -When you set a default database connection, {+odm-short+} uses that +When you set a default database connection, the {+odm-short+} uses that connection for operations, but you can specify multiple database connections in your ``config/database.php`` file. @@ -107,7 +107,7 @@ to store your model in a database other than the default, override the The following example shows how to override the ``$connection`` property on the ``Flower`` model class to use the ``mongodb_alt`` connection. -This directs {+odm-short+} to store the model in the ``flowers`` +This directs the {+odm-short+} to store the model in the ``flowers`` collection of the ``plants`` database, instead of in the default database: .. code-block:: php @@ -123,7 +123,7 @@ Access a Collection ------------------- When you create model class that extends -``MongoDB\Laravel\Eloquent\Model``, {+odm-short+} stores the model data +``MongoDB\Laravel\Eloquent\Model``, the {+odm-short+} stores the model data in a collection with a name formatted as the snake case plural form of your model class name. diff --git a/docs/fundamentals/read-operations.txt b/docs/fundamentals/read-operations.txt index 023494613..d5605033b 100644 --- a/docs/fundamentals/read-operations.txt +++ b/docs/fundamentals/read-operations.txt @@ -21,7 +21,7 @@ Read Operations Overview -------- -In this guide, you can learn how to use {+odm-short+} to perform **find operations** +In this guide, you can learn how to use {+odm-long+} to perform **find operations** on your MongoDB collections. Find operations allow you to retrieve documents based on criteria that you specify. diff --git a/docs/fundamentals/write-operations.txt b/docs/fundamentals/write-operations.txt index cc7d81337..6554d2dd0 100644 --- a/docs/fundamentals/write-operations.txt +++ b/docs/fundamentals/write-operations.txt @@ -20,7 +20,7 @@ Write Operations Overview -------- -In this guide, you can learn how to use {+odm-short+} to perform +In this guide, you can learn how to use {+odm-long+} to perform **write operations** on your MongoDB collections. Write operations include inserting, updating, and deleting data based on specified criteria. @@ -58,7 +58,7 @@ Insert Documents ---------------- In this section, you can learn how to insert documents into MongoDB collections -from your Laravel application by using the {+odm-long+}. +from your Laravel application by using {+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 @@ -69,7 +69,7 @@ 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. -To learn more about Eloquent models in {+odm-short+}, see the :ref:`laravel-eloquent-models` +To learn more about Eloquent models in the {+odm-short+}, see the :ref:`laravel-eloquent-models` section. Insert a Document Examples @@ -195,7 +195,7 @@ of the model and calling its ``save()`` method: When the ``save()`` method succeeds, the model instance on which you called the method contains the updated values. -If the operation fails, {+odm-short+} assigns the model instance a ``null`` value. +If the operation fails, the {+odm-short+} assigns the model instance a ``null`` value. The following example shows how to update a document by chaining methods to retrieve and update the first matching document: @@ -212,7 +212,7 @@ retrieve and update the first matching document: When the ``update()`` method succeeds, the operation returns the number of documents updated. -If the retrieve part of the call does not match any documents, {+odm-short+} +If the retrieve part of the call does not match any documents, the {+odm-short+} returns the following error: .. code-block:: none @@ -242,7 +242,7 @@ When the ``update()`` method succeeds, the operation returns the number of documents updated. If the retrieve part of the call does not match any documents in the -collection, {+odm-short+} returns the following error: +collection, the {+odm-short+} returns the following error: .. code-block:: none :copyable: false @@ -279,7 +279,7 @@ $update)`` method accepts the following parameters: - ``$uniqueBy``: List of fields that uniquely identify documents in your first array parameter. - ``$update``: Optional list of fields to update if a matching document - exists. If you omit this parameter, {+odm-short+} updates all fields. + exists. If you omit this parameter, the {+odm-short+} updates all fields. To specify an upsert in the ``upsert()`` method, set parameters as shown in the following code example: @@ -518,7 +518,7 @@ structure of a positional operator update call on a single matching document: .. note:: - Currently, {+odm-short+} offers this operation only on the ``DB`` facade + Currently, the {+odm-short+} offers this operation only on the ``DB`` facade and not on the Eloquent ORM. .. code-block:: none @@ -567,7 +567,7 @@ 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 +by using the {+odm-short+}. Use delete operations to remove data from your MongoDB database. This section provides examples of the following delete operations: @@ -575,7 +575,7 @@ This section provides examples of the following delete operations: - :ref:`Delete one document ` - :ref:`Delete multiple documents ` -To learn about the Laravel features available in {+odm-short+} that modify +To learn about the Laravel features available in the {+odm-short+} that modify delete behavior, see the following sections: - :ref:`Soft delete `, which lets you mark diff --git a/docs/includes/framework-compatibility-laravel.rst b/docs/includes/framework-compatibility-laravel.rst index 608560dd1..723f0e776 100644 --- a/docs/includes/framework-compatibility-laravel.rst +++ b/docs/includes/framework-compatibility-laravel.rst @@ -2,7 +2,7 @@ :header-rows: 1 :stub-columns: 1 - * - {+odm-short+} Version + * - {+odm-long+} Version - Laravel 11.x - Laravel 10.x - Laravel 9.x diff --git a/docs/index.txt b/docs/index.txt index 6cc7ea429..12269e0c4 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -1,5 +1,5 @@ =============== -{+odm-short+} +{+odm-long+} =============== .. facet:: @@ -32,10 +32,11 @@ Introduction ------------ -Welcome to the documentation site for the official {+odm-long+}. -This package extends methods in the PHP Laravel API to work with MongoDB as -a datastore in your Laravel application. {+odm-short+} allows you to use -Laravel Eloquent and Query Builder syntax to work with your MongoDB data. +Welcome to the documentation site for {+odm-long+}, the official +Laravel integration for MongoDB. This package extends methods in the PHP +Laravel API to work with MongoDB as a datastore in your Laravel +application. The {+odm-short+} allows you to use Laravel Eloquent and +Query Builder syntax to work with your MongoDB data. .. note:: @@ -47,7 +48,7 @@ Laravel Eloquent and Query Builder syntax to work with your MongoDB data. Quick Start ----------- -Learn how to add {+odm-short+} to a Laravel web application, connect to +Learn how to add the {+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. @@ -60,7 +61,7 @@ MongoDB operations in the :ref:`laravel-usage-examples` section. Fundamentals ------------ -To learn how to perform the following tasks by using {+odm-short+}, +To learn how to perform the following tasks by using the {+odm-short+}, see the following content: - :ref:`laravel-fundamentals-connection` @@ -85,13 +86,13 @@ more resources in the :ref:`laravel-issues-and-help` section. Feature Compatibility --------------------- -Learn about Laravel features that {+odm-short+} supports in the +Learn about Laravel features that the {+odm-short+} supports in the :ref:`laravel-feature-compat` section. Compatibility ------------- -To learn more about which versions of the {+odm-long+} and Laravel are +To learn more about which versions of {+odm-long+} and Laravel are compatible, see the :ref:`laravel-compatibility` section. Upgrade Versions diff --git a/docs/issues-and-help.txt b/docs/issues-and-help.txt index 197f0a5b1..cedbc3c22 100644 --- a/docs/issues-and-help.txt +++ b/docs/issues-and-help.txt @@ -12,7 +12,7 @@ Issues & Help :keywords: debug, report bug, request, contribute, github, support We are lucky to have a vibrant PHP community that includes users of varying -experience with {+php-library+} and {+odm-short+}. To get support for +experience with {+php-library+} and the {+odm-short+}. To get support for general questions, search or post in the :community-forum:`MongoDB PHP Community Forums `. @@ -22,7 +22,7 @@ To learn more about MongoDB support options, see the Bugs / Feature Requests ----------------------- -If you find a bug or want to see a new feature in {+odm-short+}, +If you find a bug or want to see a new feature in the {+odm-short+}, please report it as a GitHub issue in the `mongodb/laravel-mongodb <{+mongodb-laravel-gh+}>`__ repository. @@ -53,7 +53,7 @@ For general questions and support requests, please use one of MongoDB's Pull Requests ------------- -We are happy to accept contributions to help improve {+odm-short+}. +We are happy to accept contributions to help improve {+odm-long+}. We track current development in `PHPORM `__ MongoDB JIRA project. diff --git a/docs/query-builder.txt b/docs/query-builder.txt index dc3225e37..822a4f42e 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -27,7 +27,7 @@ supported database. .. note:: - {+odm-short+} extends Laravel's query builder and Eloquent ORM, which can + The {+odm-short+} extends Laravel's query builder and Eloquent ORM, which can run similar database operations. To learn more about retrieving documents by using Eloquent models, see :ref:`laravel-fundamentals-retrieve`. @@ -36,7 +36,7 @@ lets you perform database operations. Facades, which are static interfaces to classes, make the syntax more concise, avoid runtime errors, and improve testability. -{+odm-short+} aliases the ``DB`` method ``table()`` as the ``collection()`` +The {+odm-short+} aliases the ``DB`` method ``table()`` as the ``collection()`` method. Chain methods to specify commands and any constraints. Then, chain the ``get()`` method at the end to run the methods and retrieve the results. The following example shows the syntax of a query builder call: @@ -1056,7 +1056,7 @@ $update)`` query builder method accepts the following parameters: - ``$uniqueBy``: List of fields that uniquely identify documents in your first array parameter. - ``$update``: Optional list of fields to update if a matching document - exists. If you omit this parameter, {+odm-short+} updates all fields. + exists. If you omit this parameter, the {+odm-short+} updates all fields. The following example shows how to use the ``upsert()`` query builder method to update or insert documents based on the following instructions: diff --git a/docs/quick-start.txt b/docs/quick-start.txt index d3a87cbf6..39d8ba0b4 100644 --- a/docs/quick-start.txt +++ b/docs/quick-start.txt @@ -20,7 +20,7 @@ Quick Start Overview -------- -This guide shows you how to add the {+odm-long+} to a new Laravel web +This guide shows you how to add {+odm-long+} to a new Laravel web application, connect to a MongoDB cluster hosted on MongoDB Atlas, and perform read and write operations on the data. @@ -40,7 +40,7 @@ read and write operations on the data. Laravel, see `Connecting to MongoDB `__ in the {+php-library+} documentation. -{+odm-short+} extends the Laravel Eloquent and Query Builder syntax to +The {+odm-short+} extends the Laravel Eloquent and Query Builder syntax to store and retrieve data from MongoDB. MongoDB Atlas is a fully managed cloud database service that hosts your diff --git a/docs/quick-start/download-and-install.txt b/docs/quick-start/download-and-install.txt index 5d9d1d69f..5e9139ec8 100644 --- a/docs/quick-start/download-and-install.txt +++ b/docs/quick-start/download-and-install.txt @@ -33,7 +33,7 @@ to a Laravel web application. .. step:: Install the {+php-extension+} - {+odm-short+} requires the {+php-extension+} to manage MongoDB + {+odm-long+} requires the {+php-extension+} to manage MongoDB connections and commands. Follow the `Installing the MongoDB PHP Driver with PECL `__ guide to install the {+php-extension+}. @@ -41,7 +41,7 @@ to a Laravel web application. .. step:: Install Laravel Ensure that the version of Laravel you install is compatible with the - version of {+odm-short+}. To learn which versions are compatible, + version of the {+odm-short+}. To learn which versions are compatible, see the :ref:`laravel-compatibility` page. Run the following command to install Laravel: @@ -93,9 +93,9 @@ to a Laravel web application. php artisan key:generate - .. step:: Add {+odm-short+} to the dependencies + .. step:: Add {+odm-long+} to the dependencies - Run the following command to add the {+odm-short+} dependency to + Run the following command to add the {+odm-long+} dependency to your application: .. code-block:: bash @@ -110,7 +110,7 @@ to a Laravel web application. "mongodb/laravel-mongodb": "^{+package-version+}" - After completing these steps, you have a new Laravel project with the - {+odm-short+} dependencies installed. + After completing these steps, you have a new Laravel project with + the {+odm-short+} dependencies installed. .. include:: /includes/quick-start/troubleshoot.rst diff --git a/docs/quick-start/next-steps.txt b/docs/quick-start/next-steps.txt index 1afcc2f7e..1a7f45c6e 100644 --- a/docs/quick-start/next-steps.txt +++ b/docs/quick-start/next-steps.txt @@ -14,14 +14,14 @@ Next Steps Congratulations on completing the Quick Start tutorial! After you complete these steps, you have a Laravel web application that -uses the {+odm-long+} to connect to your MongoDB deployment, run a query on +uses {+odm-long+} to connect to your MongoDB deployment, run a query on the sample data, and render a retrieved result. You can download the web application project by cloning the `laravel-quickstart `__ GitHub repository. -Learn more about {+odm-short+} features from the following resources: +Learn more about {+odm-long+} features from the following resources: - :ref:`laravel-fundamentals-connection`: learn how to configure your MongoDB connection. diff --git a/docs/quick-start/view-data.txt b/docs/quick-start/view-data.txt index 9be7334af..f29b2bd12 100644 --- a/docs/quick-start/view-data.txt +++ b/docs/quick-start/view-data.txt @@ -33,7 +33,7 @@ View MongoDB Data INFO Controller [app/Http/Controllers/MovieController.php] created successfully. - .. step:: Edit the model to use {+odm-short+} + .. step:: Edit the model to use the {+odm-short+} Open the ``Movie.php`` model in your ``app/Models`` directory and make the following edits: diff --git a/docs/quick-start/write-data.txt b/docs/quick-start/write-data.txt index d8a01666c..14a971ebd 100644 --- a/docs/quick-start/write-data.txt +++ b/docs/quick-start/write-data.txt @@ -56,7 +56,6 @@ Write Data to MongoDB 'store' ]); - .. step:: Update the model fields Update the ``Movie`` model in the ``app/Models`` directory to @@ -79,14 +78,14 @@ Write Data to MongoDB .. code-block:: json { - "title": "The {+odm-short+} Quick Start", + "title": "The {+odm-long+} Quick Start", "year": 2024, "runtime": 15, "imdb": { "rating": 9.5, "votes": 1 }, - "plot": "This movie entry was created by running through the {+odm-short+} Quick Start tutorial." + "plot": "This movie entry was created by running through the {+odm-long+} Quick Start tutorial." } Send the JSON payload to the endpoint as a ``POST`` request by running diff --git a/docs/transactions.txt b/docs/transactions.txt index e85f06361..377423d67 100644 --- a/docs/transactions.txt +++ b/docs/transactions.txt @@ -21,11 +21,11 @@ Overview -------- In this guide, you can learn how to perform a **transaction** in MongoDB by -using the {+odm-long+}. Transactions let you run a sequence of write operations +using {+odm-long+}. Transactions let you run a sequence of write operations that update the data only after the transaction is committed. If the transaction fails, the {+php-library+} that manages MongoDB operations -for {+odm-short+} ensures that MongoDB discards all the changes made within +for the {+odm-short+} ensures that MongoDB discards all the changes made within the transaction before they become visible. This property of transactions that ensures that all changes within a transaction are either applied or discarded is called **atomicity**. @@ -51,7 +51,7 @@ This guide contains the following sections: .. tip:: Transactions Learning Byte - Practice using {+odm-short+} to perform transactions + Practice using the {+odm-short+} to perform transactions in the `Laravel Transactions Learning Byte `__. @@ -66,7 +66,7 @@ version and topology: - MongoDB version 4.0 or later - A replica set deployment or sharded cluster -MongoDB server and {+odm-short+} have the following limitations: +MongoDB Server and the {+odm-short+} have the following limitations: - In MongoDB versions 4.2 and earlier, write operations performed within a transaction must be on existing collections. In MongoDB versions 4.4 and @@ -78,7 +78,7 @@ MongoDB server and {+odm-short+} have the following limitations: transaction within another one, the extension raises a ``RuntimeException``. To learn more about this limitation, see :manual:`Transactions and Sessions ` in the {+server-docs-name+}. -- The {+odm-long+} does not support the database testing traits +- {+odm-long+} does not support the database testing traits ``Illuminate\Foundation\Testing\DatabaseTransactions`` and ``Illuminate\Foundation\Testing\RefreshDatabase``. As a workaround, you can create migrations with the ``Illuminate\Foundation\Testing\DatabaseMigrations`` trait to reset the database after each test. diff --git a/docs/upgrade.txt b/docs/upgrade.txt index 46308d6de..5d8ca09a3 100644 --- a/docs/upgrade.txt +++ b/docs/upgrade.txt @@ -20,7 +20,7 @@ Upgrade Library Version Overview -------- -On this page, you can learn how to upgrade {+odm-short+} to a new major version. +On this page, you can learn how to upgrade {+odm-long+} to a new major version. This page also includes the changes you must make to your application to upgrade your object-document mapper (ODM) version without losing functionality, if applicable. @@ -33,7 +33,7 @@ Before you upgrade, perform the following actions: your application connects to and the version of Laravel that your application runs on. See the :ref:`` page for this information. -- Address any breaking changes between the version of {+odm-short+} that +- Address any breaking changes between the version of the {+odm-short+} that your application now uses and your planned upgrade version in the :ref:`` section of this guide. @@ -53,7 +53,7 @@ Breaking Changes ---------------- A breaking change is a modification in a convention or behavior in -a specific version of {+odm-short+} that might prevent your application +a specific version of the {+odm-short+} that might prevent your application from working as expected. The breaking changes in this section are categorized by the major diff --git a/docs/usage-examples/deleteMany.txt b/docs/usage-examples/deleteMany.txt index 14a1091f8..cf8680184 100644 --- a/docs/usage-examples/deleteMany.txt +++ b/docs/usage-examples/deleteMany.txt @@ -59,6 +59,6 @@ The example calls the following methods on the ``Movie`` model: .. tip:: - To learn more about deleting documents with {+odm-short+}, see the :ref:`laravel-fundamentals-delete-documents` + To learn more about deleting documents with the {+odm-short+}, see the :ref:`laravel-fundamentals-delete-documents` section of the Write Operations guide. diff --git a/docs/usage-examples/deleteOne.txt b/docs/usage-examples/deleteOne.txt index 9c8d6b127..1298255da 100644 --- a/docs/usage-examples/deleteOne.txt +++ b/docs/usage-examples/deleteOne.txt @@ -60,7 +60,7 @@ The example calls the following methods on the ``Movie`` model: .. tip:: - To learn more about deleting documents with {+odm-short+}, see the `Deleting Models + To learn more about deleting documents with the {+odm-short+}, see the `Deleting Models `__ section of the Laravel documentation. diff --git a/docs/usage-examples/find.txt b/docs/usage-examples/find.txt index b12c97f41..957ece537 100644 --- a/docs/usage-examples/find.txt +++ b/docs/usage-examples/find.txt @@ -86,5 +86,5 @@ The example calls the following methods on the ``Movie`` model: .. tip:: - To learn about other ways to retrieve documents with {+odm-short+}, see the + To learn about other ways to retrieve documents with the {+odm-short+}, see the :ref:`laravel-fundamentals-retrieve` guide. diff --git a/docs/usage-examples/findOne.txt b/docs/usage-examples/findOne.txt index 815d7923e..aa0e035f1 100644 --- a/docs/usage-examples/findOne.txt +++ b/docs/usage-examples/findOne.txt @@ -66,5 +66,5 @@ The example calls the following methods on the ``Movie`` model: .. tip:: - To learn more about retrieving documents with {+odm-short+}, see the + To learn more about retrieving documents with the {+odm-short+}, see the :ref:`laravel-fundamentals-retrieve` guide. diff --git a/docs/usage-examples/updateMany.txt b/docs/usage-examples/updateMany.txt index 7fd5bfd1b..89c262da7 100644 --- a/docs/usage-examples/updateMany.txt +++ b/docs/usage-examples/updateMany.txt @@ -61,6 +61,6 @@ The example calls the following methods on the ``Movie`` model: .. tip:: - To learn more about updating data with {+odm-short+}, see the :ref:`laravel-fundamentals-modify-documents` + To learn more about updating data with the {+odm-short+}, see the :ref:`laravel-fundamentals-modify-documents` section of the Write Operations guide. diff --git a/docs/usage-examples/updateOne.txt b/docs/usage-examples/updateOne.txt index 42fcda477..ecdc8982d 100644 --- a/docs/usage-examples/updateOne.txt +++ b/docs/usage-examples/updateOne.txt @@ -61,6 +61,6 @@ The example calls the following methods on the ``Movie`` model: .. tip:: - To learn more about updating data with {+odm-short+}, see the :ref:`laravel-fundamentals-modify-documents` + To learn more about updating data with the {+odm-short+}, see the :ref:`laravel-fundamentals-modify-documents` section of the Write Operations guide. diff --git a/docs/user-authentication.txt b/docs/user-authentication.txt index d02b8b089..65d983ed5 100644 --- a/docs/user-authentication.txt +++ b/docs/user-authentication.txt @@ -129,7 +129,7 @@ Sanctum and publish its migration file: composer require laravel/sanctum php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider" -To use Laravel Sanctum with {+odm-short+}, modify the ``PersonalAccessToken`` model provided +To use Laravel Sanctum with the {+odm-short+}, modify the ``PersonalAccessToken`` model provided by Sanctum to use the ``DocumentModel`` trait from the ``MongoDB\Laravel\Eloquent`` namespace. The following code modifies the ``PersonalAccessToken`` model to enable MongoDB: From 59e16b9df325068b992233bbc3785ee98c924926 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 26 Aug 2024 12:14:00 +0200 Subject: [PATCH 333/446] PHPORM-232 Support whereLike and whereNotLike (#3108) * PHPORM-232 Support whereLike and whereNotLike * Check required methods from Laravel in tests --- CHANGELOG.md | 1 + src/Query/Builder.php | 10 +- tests/Query/BuilderTest.php | 281 ++++++++++++++++++++++-------------- 3 files changed, 180 insertions(+), 112 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a6e7c9144..ac591881f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,7 @@ All notable changes to this project will be documented in this file. ## [4.8.0] - next * Add `Query\Builder::incrementEach()` and `decrementEach()` methods by @SmallRuralDog in [#2550](https://github.com/mongodb/laravel-mongodb/pull/2550) +* Add `Query\Builder::whereLike()` and `whereNotLike()` methods by @GromNaN in [#3108](https://github.com/mongodb/laravel-mongodb/pull/3108) * Deprecate `Connection::collection()` and `Schema\Builder::collection()` methods by @GromNaN in [#3062](https://github.com/mongodb/laravel-mongodb/pull/3062) * Deprecate `Model::$collection` property to customize collection name. Use `$table` instead by @GromNaN in [#3064](https://github.com/mongodb/laravel-mongodb/pull/3064) diff --git a/src/Query/Builder.php b/src/Query/Builder.php index ddc2413d8..8c7a37854 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -1266,7 +1266,8 @@ protected function compileWhereBasic(array $where): array // All backslashes are converted to \\, which are needed in matching regexes. preg_quote($value), ); - $value = new Regex('^' . $regex . '$', 'i'); + $flags = $where['caseSensitive'] ?? false ? '' : 'i'; + $value = new Regex('^' . $regex . '$', $flags); // For inverse like operations, we can just use the $not operator with the Regex $operator = $operator === 'like' ? '=' : 'not'; @@ -1324,6 +1325,13 @@ protected function compileWhereNotIn(array $where): array return [$where['column'] => ['$nin' => array_values($where['values'])]]; } + protected function compileWhereLike(array $where): array + { + $where['operator'] = $where['not'] ? 'not like' : 'like'; + + return $this->compileWhereBasic($where); + } + protected function compileWhereNull(array $where): array { $where['operator'] = '='; diff --git a/tests/Query/BuilderTest.php b/tests/Query/BuilderTest.php index 3ec933499..c5c13260b 100644 --- a/tests/Query/BuilderTest.php +++ b/tests/Query/BuilderTest.php @@ -26,13 +26,18 @@ use function collect; use function method_exists; use function now; +use function sprintf; use function var_export; class BuilderTest extends TestCase { #[DataProvider('provideQueryBuilderToMql')] - public function testMql(array $expected, Closure $build): void + public function testMql(array $expected, Closure $build, ?string $requiredMethod = null): void { + if ($requiredMethod && ! method_exists(Builder::class, $requiredMethod)) { + $this->markTestSkipped(sprintf('Method "%s::%s()" does not exist.', Builder::class, $requiredMethod)); + } + $builder = $build(self::getBuilder()); $this->assertInstanceOf(Builder::class, $builder); $mql = $builder->toMql(); @@ -748,6 +753,48 @@ function (Builder $builder) { fn (Builder $builder) => $builder->where('name', 'like', '_ac__me_'), ]; + yield 'whereLike' => [ + ['find' => [['name' => new Regex('^1$', 'i')], []]], + fn + (Builder $builder) => $builder->whereLike('name', '1'), + 'whereLike', + ]; + + yield 'whereLike case not sensitive' => [ + ['find' => [['name' => new Regex('^1$', 'i')], []]], + fn + (Builder $builder) => $builder->whereLike('name', '1', false), + 'whereLike', + ]; + + yield 'whereLike case sensitive' => [ + ['find' => [['name' => new Regex('^1$', '')], []]], + fn + (Builder $builder) => $builder->whereLike('name', '1', true), + 'whereLike', + ]; + + yield 'whereNotLike' => [ + ['find' => [['name' => ['$not' => new Regex('^1$', 'i')]], []]], + fn + (Builder $builder) => $builder->whereNotLike('name', '1'), + 'whereNotLike', + ]; + + yield 'whereNotLike case not sensitive' => [ + ['find' => [['name' => ['$not' => new Regex('^1$', 'i')]], []]], + fn + (Builder $builder) => $builder->whereNotLike('name', '1', false), + 'whereNotLike', + ]; + + yield 'whereNotLike case sensitive' => [ + ['find' => [['name' => ['$not' => new Regex('^1$', '')]], []]], + fn + (Builder $builder) => $builder->whereNotLike('name', '1', true), + 'whereNotLike', + ]; + $regex = new Regex('^acme$', 'si'); yield 'where BSON\Regex' => [ ['find' => [['name' => $regex], []]], @@ -1161,142 +1208,154 @@ function (Builder $elemMatchQuery): void { ]; // Method added in Laravel v10.47.0 - if (method_exists(Builder::class, 'whereAll')) { - /** @see DatabaseQueryBuilderTest::testWhereAll */ - yield 'whereAll' => [ - [ - 'find' => [ - ['$and' => [['last_name' => 'Doe'], ['email' => 'Doe']]], - [], // options - ], + /** @see DatabaseQueryBuilderTest::testWhereAll */ + yield 'whereAll' => [ + [ + 'find' => [ + ['$and' => [['last_name' => 'Doe'], ['email' => 'Doe']]], + [], // options ], - fn(Builder $builder) => $builder->whereAll(['last_name', 'email'], 'Doe'), - ]; - - yield 'whereAll operator' => [ - [ - 'find' => [ - [ - '$and' => [ - ['last_name' => ['$not' => new Regex('^.*Doe.*$', 'i')]], - ['email' => ['$not' => new Regex('^.*Doe.*$', 'i')]], - ], + ], + fn + (Builder $builder) => $builder->whereAll(['last_name', 'email'], 'Doe'), + 'whereAll', + ]; + + yield 'whereAll operator' => [ + [ + 'find' => [ + [ + '$and' => [ + ['last_name' => ['$not' => new Regex('^.*Doe.*$', 'i')]], + ['email' => ['$not' => new Regex('^.*Doe.*$', 'i')]], ], - [], // options ], + [], // options ], - fn(Builder $builder) => $builder->whereAll(['last_name', 'email'], 'not like', '%Doe%'), - ]; - - /** @see DatabaseQueryBuilderTest::testOrWhereAll */ - yield 'orWhereAll' => [ - [ - 'find' => [ - [ - '$or' => [ - ['first_name' => 'John'], - ['$and' => [['last_name' => 'Doe'], ['email' => 'Doe']]], - ], + ], + fn + (Builder $builder) => $builder->whereAll(['last_name', 'email'], 'not like', '%Doe%'), + 'whereAll', + ]; + + /** @see DatabaseQueryBuilderTest::testOrWhereAll */ + yield 'orWhereAll' => [ + [ + 'find' => [ + [ + '$or' => [ + ['first_name' => 'John'], + ['$and' => [['last_name' => 'Doe'], ['email' => 'Doe']]], ], - [], // options ], + [], // options ], - fn(Builder $builder) => $builder - ->where('first_name', 'John') - ->orWhereAll(['last_name', 'email'], 'Doe'), - ]; - - yield 'orWhereAll operator' => [ - [ - 'find' => [ - [ - '$or' => [ - ['first_name' => new Regex('^.*John.*$', 'i')], - [ - '$and' => [ - ['last_name' => ['$not' => new Regex('^.*Doe.*$', 'i')]], - ['email' => ['$not' => new Regex('^.*Doe.*$', 'i')]], - ], + ], + fn + (Builder $builder) => $builder + ->where('first_name', 'John') + ->orWhereAll(['last_name', 'email'], 'Doe'), + 'orWhereAll', + ]; + + yield 'orWhereAll operator' => [ + [ + 'find' => [ + [ + '$or' => [ + ['first_name' => new Regex('^.*John.*$', 'i')], + [ + '$and' => [ + ['last_name' => ['$not' => new Regex('^.*Doe.*$', 'i')]], + ['email' => ['$not' => new Regex('^.*Doe.*$', 'i')]], ], ], ], - [], // options ], + [], // options ], - fn(Builder $builder) => $builder - ->where('first_name', 'like', '%John%') - ->orWhereAll(['last_name', 'email'], 'not like', '%Doe%'), - ]; - } + ], + fn + (Builder $builder) => $builder + ->where('first_name', 'like', '%John%') + ->orWhereAll(['last_name', 'email'], 'not like', '%Doe%'), + 'orWhereAll', + ]; // Method added in Laravel v10.47.0 - if (method_exists(Builder::class, 'whereAny')) { - /** @see DatabaseQueryBuilderTest::testWhereAny */ - yield 'whereAny' => [ - [ - 'find' => [ - ['$or' => [['last_name' => 'Doe'], ['email' => 'Doe']]], - [], // options - ], + /** @see DatabaseQueryBuilderTest::testWhereAny */ + yield 'whereAny' => [ + [ + 'find' => [ + ['$or' => [['last_name' => 'Doe'], ['email' => 'Doe']]], + [], // options ], - fn(Builder $builder) => $builder->whereAny(['last_name', 'email'], 'Doe'), - ]; - - yield 'whereAny operator' => [ - [ - 'find' => [ - [ - '$or' => [ - ['last_name' => ['$not' => new Regex('^.*Doe.*$', 'i')]], - ['email' => ['$not' => new Regex('^.*Doe.*$', 'i')]], - ], + ], + fn + (Builder $builder) => $builder->whereAny(['last_name', 'email'], 'Doe'), + 'whereAny', + ]; + + yield 'whereAny operator' => [ + [ + 'find' => [ + [ + '$or' => [ + ['last_name' => ['$not' => new Regex('^.*Doe.*$', 'i')]], + ['email' => ['$not' => new Regex('^.*Doe.*$', 'i')]], ], - [], // options ], + [], // options ], - fn(Builder $builder) => $builder->whereAny(['last_name', 'email'], 'not like', '%Doe%'), - ]; - - /** @see DatabaseQueryBuilderTest::testOrWhereAny */ - yield 'orWhereAny' => [ - [ - 'find' => [ - [ - '$or' => [ - ['first_name' => 'John'], - ['$or' => [['last_name' => 'Doe'], ['email' => 'Doe']]], - ], + ], + fn + (Builder $builder) => $builder->whereAny(['last_name', 'email'], 'not like', '%Doe%'), + 'whereAny', + ]; + + /** @see DatabaseQueryBuilderTest::testOrWhereAny */ + yield 'orWhereAny' => [ + [ + 'find' => [ + [ + '$or' => [ + ['first_name' => 'John'], + ['$or' => [['last_name' => 'Doe'], ['email' => 'Doe']]], ], - [], // options ], + [], // options ], - fn(Builder $builder) => $builder - ->where('first_name', 'John') - ->orWhereAny(['last_name', 'email'], 'Doe'), - ]; - - yield 'orWhereAny operator' => [ - [ - 'find' => [ - [ - '$or' => [ - ['first_name' => new Regex('^.*John.*$', 'i')], - [ - '$or' => [ - ['last_name' => ['$not' => new Regex('^.*Doe.*$', 'i')]], - ['email' => ['$not' => new Regex('^.*Doe.*$', 'i')]], - ], + ], + fn + (Builder $builder) => $builder + ->where('first_name', 'John') + ->orWhereAny(['last_name', 'email'], 'Doe'), + 'whereAny', + ]; + + yield 'orWhereAny operator' => [ + [ + 'find' => [ + [ + '$or' => [ + ['first_name' => new Regex('^.*John.*$', 'i')], + [ + '$or' => [ + ['last_name' => ['$not' => new Regex('^.*Doe.*$', 'i')]], + ['email' => ['$not' => new Regex('^.*Doe.*$', 'i')]], ], ], ], - [], // options ], + [], // options ], - fn(Builder $builder) => $builder - ->where('first_name', 'like', '%John%') - ->orWhereAny(['last_name', 'email'], 'not like', '%Doe%'), - ]; - } + ], + fn + (Builder $builder) => $builder + ->where('first_name', 'like', '%John%') + ->orWhereAny(['last_name', 'email'], 'not like', '%Doe%'), + 'orWhereAny', + ]; } #[DataProvider('provideExceptions')] From bd9ef30f98c92b915e9f657504e9cf15e4a2b046 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 26 Aug 2024 12:23:20 +0200 Subject: [PATCH 334/446] PHPORM-230 Convert DateTimeInterface to UTCDateTime in queries (#3105) * PHPORM-230 Convert DateTimeInterface to UTCDateTime in queries * Alias id to _id in subdocuments --- src/Query/Builder.php | 65 +++++++++----------------- tests/Query/AggregationBuilderTest.php | 5 +- tests/Query/BuilderTest.php | 6 +++ tests/QueryBuilderTest.php | 12 +++-- 4 files changed, 37 insertions(+), 51 deletions(-) diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 6168159df..fef4eb45c 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -32,7 +32,6 @@ use function array_map; use function array_merge; use function array_values; -use function array_walk_recursive; use function assert; use function blank; use function call_user_func; @@ -689,17 +688,7 @@ public function insert(array $values) $values = [$values]; } - // Compatibility with Eloquent queries that uses "id" instead of MongoDB's _id - foreach ($values as &$document) { - if (isset($document['id'])) { - if (isset($document['_id']) && $document['_id'] !== $document['id']) { - throw new InvalidArgumentException('Cannot insert document with different "id" and "_id" values'); - } - - $document['_id'] = $document['id']; - unset($document['id']); - } - } + $values = $this->aliasIdForQuery($values); $options = $this->inheritConnectionOptions(); @@ -876,6 +865,7 @@ public function delete($id = null) } $wheres = $this->compileWheres(); + $wheres = $this->aliasIdForQuery($wheres); $options = $this->inheritConnectionOptions(); if (is_int($this->limit)) { @@ -1070,16 +1060,12 @@ protected function performUpdate(array $update, array $options = []) $options['multiple'] = true; } - // Since "id" is an alias for "_id", we prevent updating it - foreach ($update as $operator => $fields) { - if (array_key_exists('id', $fields)) { - throw new InvalidArgumentException('Cannot update "id" field.'); - } - } + $update = $this->aliasIdForQuery($update); $options = $this->inheritConnectionOptions($options); $wheres = $this->compileWheres(); + $wheres = $this->aliasIdForQuery($wheres); $result = $this->collection->updateMany($wheres, $update, $options); if ($result->isAcknowledged()) { return $result->getModifiedCount() ? $result->getModifiedCount() : $result->getUpsertedCount(); @@ -1191,32 +1177,12 @@ protected function compileWheres(): array } } - // Convert DateTime values to UTCDateTime. - if (isset($where['value'])) { - if (is_array($where['value'])) { - array_walk_recursive($where['value'], function (&$item, $key) { - if ($item instanceof DateTimeInterface) { - $item = new UTCDateTime($item); - } - }); - } else { - if ($where['value'] instanceof DateTimeInterface) { - $where['value'] = new UTCDateTime($where['value']); - } - } - } elseif (isset($where['values'])) { - if (is_array($where['values'])) { - array_walk_recursive($where['values'], function (&$item, $key) { - if ($item instanceof DateTimeInterface) { - $item = new UTCDateTime($item); - } - }); - } elseif ($where['values'] instanceof CarbonPeriod) { - $where['values'] = [ - new UTCDateTime($where['values']->getStartDate()), - new UTCDateTime($where['values']->getEndDate()), - ]; - } + // Convert CarbonPeriod to DateTime interval. + if (isset($where['values']) && $where['values'] instanceof CarbonPeriod) { + $where['values'] = [ + $where['values']->getStartDate(), + $where['values']->getEndDate(), + ]; } // In a sequence of "where" clauses, the logical operator of the @@ -1631,12 +1597,21 @@ public function orWhereIntegerNotInRaw($column, $values, $boolean = 'and') private function aliasIdForQuery(array $values): array { if (array_key_exists('id', $values)) { + if (array_key_exists('_id', $values)) { + throw new InvalidArgumentException('Cannot have both "id" and "_id" fields.'); + } + $values['_id'] = $values['id']; unset($values['id']); } foreach ($values as $key => $value) { if (is_string($key) && str_ends_with($key, '.id')) { + $newkey = substr($key, 0, -3) . '._id'; + if (array_key_exists($newkey, $values)) { + throw new InvalidArgumentException(sprintf('Cannot have both "%s" and "%s" fields.', $key, $newkey)); + } + $values[substr($key, 0, -3) . '._id'] = $value; unset($values[$key]); } @@ -1645,6 +1620,8 @@ private function aliasIdForQuery(array $values): array foreach ($values as &$value) { if (is_array($value)) { $value = $this->aliasIdForQuery($value); + } elseif ($value instanceof DateTimeInterface) { + $value = new UTCDateTime($value); } } diff --git a/tests/Query/AggregationBuilderTest.php b/tests/Query/AggregationBuilderTest.php index b3828597d..a355db439 100644 --- a/tests/Query/AggregationBuilderTest.php +++ b/tests/Query/AggregationBuilderTest.php @@ -11,7 +11,6 @@ use InvalidArgumentException; use MongoDB\BSON\Document; use MongoDB\BSON\ObjectId; -use MongoDB\BSON\UTCDateTime; use MongoDB\Builder\BuilderEncoder; use MongoDB\Builder\Expression; use MongoDB\Builder\Pipeline; @@ -33,8 +32,8 @@ public function tearDown(): void public function testCreateAggregationBuilder(): void { User::insert([ - ['name' => 'John Doe', 'birthday' => new UTCDateTime(new DateTimeImmutable('1989-01-01'))], - ['name' => 'Jane Doe', 'birthday' => new UTCDateTime(new DateTimeImmutable('1990-01-01'))], + ['name' => 'John Doe', 'birthday' => new DateTimeImmutable('1989-01-01')], + ['name' => 'Jane Doe', 'birthday' => new DateTimeImmutable('1990-01-01')], ]); // Create the aggregation pipeline from the query builder diff --git a/tests/Query/BuilderTest.php b/tests/Query/BuilderTest.php index b081a0557..666747a46 100644 --- a/tests/Query/BuilderTest.php +++ b/tests/Query/BuilderTest.php @@ -566,6 +566,12 @@ function (Builder $builder) { fn (Builder $builder) => $builder->whereBetween('id', [[1], [2, 3]]), ]; + $date = new DateTimeImmutable('2018-09-30 15:00:00 +02:00'); + yield 'where $lt DateTimeInterface' => [ + ['find' => [['created_at' => ['$lt' => new UTCDateTime($date)]], []]], + fn (Builder $builder) => $builder->where('created_at', '<', $date), + ]; + $period = now()->toPeriod(now()->addMonth()); yield 'whereBetween CarbonPeriod' => [ [ diff --git a/tests/QueryBuilderTest.php b/tests/QueryBuilderTest.php index 6b08a15b7..0495f38aa 100644 --- a/tests/QueryBuilderTest.php +++ b/tests/QueryBuilderTest.php @@ -1053,16 +1053,20 @@ public function testIncrementEach() #[TestWith(['id', 'id'])] #[TestWith(['id', '_id'])] #[TestWith(['_id', 'id'])] + #[TestWith(['_id', '_id'])] public function testIdAlias($insertId, $queryId): void { - DB::collection('items')->insert([$insertId => 'abc', 'name' => 'Karting']); - $item = DB::collection('items')->where($queryId, '=', 'abc')->first(); + DB::table('items')->insert([$insertId => 'abc', 'name' => 'Karting']); + $item = DB::table('items')->where($queryId, '=', 'abc')->first(); $this->assertNotNull($item); $this->assertSame('abc', $item['id']); $this->assertSame('Karting', $item['name']); - DB::collection('items')->where($insertId, '=', 'abc')->update(['name' => 'Bike']); - $item = DB::collection('items')->where($queryId, '=', 'abc')->first(); + DB::table('items')->where($insertId, '=', 'abc')->update(['name' => 'Bike']); + $item = DB::table('items')->where($queryId, '=', 'abc')->first(); $this->assertSame('Bike', $item['name']); + + $result = DB::table('items')->where($queryId, '=', 'abc')->delete(); + $this->assertSame(1, $result); } } From f24b464ef96dbcded872bf700907f6c94ec8d409 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 26 Aug 2024 15:37:52 +0200 Subject: [PATCH 335/446] Add ConnectionCount and DriverTitle for monitoring commands (#3072) --- src/Connection.php | 14 ++++++++++++++ tests/ConnectionTest.php | 11 +++++++++++ 2 files changed, 25 insertions(+) diff --git a/src/Connection.php b/src/Connection.php index 9b4cc26ed..a0affa56a 100644 --- a/src/Connection.php +++ b/src/Connection.php @@ -294,6 +294,12 @@ public function getDriverName() return 'mongodb'; } + /** @inheritdoc */ + public function getDriverTitle() + { + return 'MongoDB'; + } + /** @inheritdoc */ protected function getDefaultPostProcessor() { @@ -320,6 +326,14 @@ public function setDatabase(Database $db) $this->db = $db; } + /** @inheritdoc */ + public function threadCount() + { + $status = $this->db->command(['serverStatus' => 1])->toArray(); + + return $status[0]['connections']['current']; + } + /** * Dynamically pass methods to the connection. * diff --git a/tests/ConnectionTest.php b/tests/ConnectionTest.php index 214050840..ac4cc78fc 100644 --- a/tests/ConnectionTest.php +++ b/tests/ConnectionTest.php @@ -25,6 +25,9 @@ public function testConnection() { $connection = DB::connection('mongodb'); $this->assertInstanceOf(Connection::class, $connection); + + $this->assertSame('mongodb', $connection->getDriverName()); + $this->assertSame('MongoDB', $connection->getDriverTitle()); } public function testReconnect() @@ -305,4 +308,12 @@ public function testServerVersion() $version = DB::connection('mongodb')->getServerVersion(); $this->assertIsString($version); } + + public function testThreadsCount() + { + $threads = DB::connection('mongodb')->threadCount(); + + $this->assertIsInt($threads); + $this->assertGreaterThanOrEqual(1, $threads); + } } From 9c1146c12767d35a75fb7876427ebafd8b7516c9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 26 Aug 2024 17:38:03 +0200 Subject: [PATCH 336/446] PHPORM-216 Remove $collection setting from DocumentModel and Connection::collection(). Use $table and Connection::table() instead (#3104) --- src/Connection.php | 18 ---------- src/Eloquent/DocumentModel.php | 15 -------- src/Schema/Builder.php | 19 ---------- tests/SchemaTest.php | 66 +++++++++++++++++----------------- 4 files changed, 33 insertions(+), 85 deletions(-) diff --git a/src/Connection.php b/src/Connection.php index a0affa56a..cb2bc78de 100644 --- a/src/Connection.php +++ b/src/Connection.php @@ -22,9 +22,7 @@ use function is_array; use function preg_match; use function str_contains; -use function trigger_error; -use const E_USER_DEPRECATED; use const FILTER_FLAG_IPV6; use const FILTER_VALIDATE_IP; @@ -77,22 +75,6 @@ public function __construct(array $config) $this->useDefaultQueryGrammar(); } - /** - * Begin a fluent query against a database collection. - * - * @deprecated since mongodb/laravel-mongodb 4.8, use the function table() instead - * - * @param string $collection - * - * @return Query\Builder - */ - public function collection($collection) - { - @trigger_error('Since mongodb/laravel-mongodb 4.8, the method Connection::collection() is deprecated and will be removed in version 5.0. Use the table() method instead.', E_USER_DEPRECATED); - - return $this->table($collection); - } - /** * Begin a fluent query against a database collection. * diff --git a/src/Eloquent/DocumentModel.php b/src/Eloquent/DocumentModel.php index af3aec3c2..fbbc69e49 100644 --- a/src/Eloquent/DocumentModel.php +++ b/src/Eloquent/DocumentModel.php @@ -47,11 +47,8 @@ use function str_starts_with; use function strcmp; use function strlen; -use function trigger_error; use function var_export; -use const E_USER_DEPRECATED; - trait DocumentModel { use HybridRelations; @@ -140,18 +137,6 @@ public function freshTimestamp() return new UTCDateTime(Date::now()); } - /** @inheritdoc */ - public function getTable() - { - if (isset($this->collection)) { - trigger_error('Since mongodb/laravel-mongodb 4.8: Using "$collection" property is deprecated. Use "$table" instead.', E_USER_DEPRECATED); - - return $this->collection; - } - - return parent::getTable(); - } - /** @inheritdoc */ public function getAttribute($key) { diff --git a/src/Schema/Builder.php b/src/Schema/Builder.php index e31a1efe1..630ff4c75 100644 --- a/src/Schema/Builder.php +++ b/src/Schema/Builder.php @@ -17,11 +17,8 @@ use function iterator_to_array; use function sort; use function sprintf; -use function trigger_error; use function usort; -use const E_USER_DEPRECATED; - class Builder extends \Illuminate\Database\Schema\Builder { /** @@ -75,22 +72,6 @@ public function hasTable($table) return $this->hasCollection($table); } - /** - * Modify a collection on the schema. - * - * @deprecated since mongodb/laravel-mongodb 4.8, use the function table() instead - * - * @param string $collection - * - * @return void - */ - public function collection($collection, Closure $callback) - { - @trigger_error('Since mongodb/laravel-mongodb 4.8, the method Schema\Builder::collection() is deprecated and will be removed in version 5.0. Use the function table() instead.', E_USER_DEPRECATED); - - $this->table($collection, $callback); - } - /** @inheritdoc */ public function table($table, Closure $callback) { diff --git a/tests/SchemaTest.php b/tests/SchemaTest.php index baf78d1a5..914b79389 100644 --- a/tests/SchemaTest.php +++ b/tests/SchemaTest.php @@ -61,7 +61,7 @@ public function testBluePrint(): void { $instance = $this; - Schema::collection('newcollection', function ($collection) use ($instance) { + Schema::table('newcollection', function ($collection) use ($instance) { $instance->assertInstanceOf(Blueprint::class, $collection); }); @@ -72,21 +72,21 @@ public function testBluePrint(): void public function testIndex(): void { - Schema::collection('newcollection', function ($collection) { + Schema::table('newcollection', function ($collection) { $collection->index('mykey1'); }); $index = $this->getIndex('newcollection', 'mykey1'); $this->assertEquals(1, $index['key']['mykey1']); - Schema::collection('newcollection', function ($collection) { + Schema::table('newcollection', function ($collection) { $collection->index(['mykey2']); }); $index = $this->getIndex('newcollection', 'mykey2'); $this->assertEquals(1, $index['key']['mykey2']); - Schema::collection('newcollection', function ($collection) { + Schema::table('newcollection', function ($collection) { $collection->string('mykey3')->index(); }); @@ -96,7 +96,7 @@ public function testIndex(): void public function testPrimary(): void { - Schema::collection('newcollection', function ($collection) { + Schema::table('newcollection', function ($collection) { $collection->string('mykey', 100)->primary(); }); @@ -106,7 +106,7 @@ public function testPrimary(): void public function testUnique(): void { - Schema::collection('newcollection', function ($collection) { + Schema::table('newcollection', function ($collection) { $collection->unique('uniquekey'); }); @@ -116,7 +116,7 @@ public function testUnique(): void public function testDropIndex(): void { - Schema::collection('newcollection', function ($collection) { + Schema::table('newcollection', function ($collection) { $collection->unique('uniquekey'); $collection->dropIndex('uniquekey_1'); }); @@ -124,7 +124,7 @@ public function testDropIndex(): void $index = $this->getIndex('newcollection', 'uniquekey'); $this->assertEquals(null, $index); - Schema::collection('newcollection', function ($collection) { + Schema::table('newcollection', function ($collection) { $collection->unique('uniquekey'); $collection->dropIndex(['uniquekey']); }); @@ -132,42 +132,42 @@ public function testDropIndex(): void $index = $this->getIndex('newcollection', 'uniquekey'); $this->assertEquals(null, $index); - Schema::collection('newcollection', function ($collection) { + Schema::table('newcollection', function ($collection) { $collection->index(['field_a', 'field_b']); }); $index = $this->getIndex('newcollection', 'field_a_1_field_b_1'); $this->assertNotNull($index); - Schema::collection('newcollection', function ($collection) { + Schema::table('newcollection', function ($collection) { $collection->dropIndex(['field_a', 'field_b']); }); $index = $this->getIndex('newcollection', 'field_a_1_field_b_1'); $this->assertFalse($index); - Schema::collection('newcollection', function ($collection) { + Schema::table('newcollection', function ($collection) { $collection->index(['field_a' => -1, 'field_b' => 1]); }); $index = $this->getIndex('newcollection', 'field_a_-1_field_b_1'); $this->assertNotNull($index); - Schema::collection('newcollection', function ($collection) { + Schema::table('newcollection', function ($collection) { $collection->dropIndex(['field_a' => -1, 'field_b' => 1]); }); $index = $this->getIndex('newcollection', 'field_a_-1_field_b_1'); $this->assertFalse($index); - Schema::collection('newcollection', function ($collection) { + Schema::table('newcollection', function ($collection) { $collection->index(['field_a', 'field_b'], 'custom_index_name'); }); $index = $this->getIndex('newcollection', 'custom_index_name'); $this->assertNotNull($index); - Schema::collection('newcollection', function ($collection) { + Schema::table('newcollection', function ($collection) { $collection->dropIndex('custom_index_name'); }); @@ -177,7 +177,7 @@ public function testDropIndex(): void public function testDropIndexIfExists(): void { - Schema::collection('newcollection', function (Blueprint $collection) { + Schema::table('newcollection', function (Blueprint $collection) { $collection->unique('uniquekey'); $collection->dropIndexIfExists('uniquekey_1'); }); @@ -185,7 +185,7 @@ public function testDropIndexIfExists(): void $index = $this->getIndex('newcollection', 'uniquekey'); $this->assertEquals(null, $index); - Schema::collection('newcollection', function (Blueprint $collection) { + Schema::table('newcollection', function (Blueprint $collection) { $collection->unique('uniquekey'); $collection->dropIndexIfExists(['uniquekey']); }); @@ -193,28 +193,28 @@ public function testDropIndexIfExists(): void $index = $this->getIndex('newcollection', 'uniquekey'); $this->assertEquals(null, $index); - Schema::collection('newcollection', function (Blueprint $collection) { + Schema::table('newcollection', function (Blueprint $collection) { $collection->index(['field_a', 'field_b']); }); $index = $this->getIndex('newcollection', 'field_a_1_field_b_1'); $this->assertNotNull($index); - Schema::collection('newcollection', function (Blueprint $collection) { + Schema::table('newcollection', function (Blueprint $collection) { $collection->dropIndexIfExists(['field_a', 'field_b']); }); $index = $this->getIndex('newcollection', 'field_a_1_field_b_1'); $this->assertFalse($index); - Schema::collection('newcollection', function (Blueprint $collection) { + Schema::table('newcollection', function (Blueprint $collection) { $collection->index(['field_a', 'field_b'], 'custom_index_name'); }); $index = $this->getIndex('newcollection', 'custom_index_name'); $this->assertNotNull($index); - Schema::collection('newcollection', function (Blueprint $collection) { + Schema::table('newcollection', function (Blueprint $collection) { $collection->dropIndexIfExists('custom_index_name'); }); @@ -226,19 +226,19 @@ public function testHasIndex(): void { $instance = $this; - Schema::collection('newcollection', function (Blueprint $collection) use ($instance) { + Schema::table('newcollection', function (Blueprint $collection) use ($instance) { $collection->index('myhaskey1'); $instance->assertTrue($collection->hasIndex('myhaskey1_1')); $instance->assertFalse($collection->hasIndex('myhaskey1')); }); - Schema::collection('newcollection', function (Blueprint $collection) use ($instance) { + Schema::table('newcollection', function (Blueprint $collection) use ($instance) { $collection->index('myhaskey2'); $instance->assertTrue($collection->hasIndex(['myhaskey2'])); $instance->assertFalse($collection->hasIndex(['myhaskey2_1'])); }); - Schema::collection('newcollection', function (Blueprint $collection) use ($instance) { + Schema::table('newcollection', function (Blueprint $collection) use ($instance) { $collection->index(['field_a', 'field_b']); $instance->assertTrue($collection->hasIndex(['field_a_1_field_b'])); $instance->assertFalse($collection->hasIndex(['field_a_1_field_b_1'])); @@ -247,7 +247,7 @@ public function testHasIndex(): void public function testBackground(): void { - Schema::collection('newcollection', function ($collection) { + Schema::table('newcollection', function ($collection) { $collection->background('backgroundkey'); }); @@ -257,7 +257,7 @@ public function testBackground(): void public function testSparse(): void { - Schema::collection('newcollection', function ($collection) { + Schema::table('newcollection', function ($collection) { $collection->sparse('sparsekey'); }); @@ -267,7 +267,7 @@ public function testSparse(): void public function testExpire(): void { - Schema::collection('newcollection', function ($collection) { + Schema::table('newcollection', function ($collection) { $collection->expire('expirekey', 60); }); @@ -277,11 +277,11 @@ public function testExpire(): void public function testSoftDeletes(): void { - Schema::collection('newcollection', function ($collection) { + Schema::table('newcollection', function ($collection) { $collection->softDeletes(); }); - Schema::collection('newcollection', function ($collection) { + Schema::table('newcollection', function ($collection) { $collection->string('email')->nullable()->index(); }); @@ -291,7 +291,7 @@ public function testSoftDeletes(): void public function testFluent(): void { - Schema::collection('newcollection', function ($collection) { + Schema::table('newcollection', function ($collection) { $collection->string('email')->index(); $collection->string('token')->index(); $collection->timestamp('created_at'); @@ -306,7 +306,7 @@ public function testFluent(): void public function testGeospatial(): void { - Schema::collection('newcollection', function ($collection) { + Schema::table('newcollection', function ($collection) { $collection->geospatial('point'); $collection->geospatial('area', '2d'); $collection->geospatial('continent', '2dsphere'); @@ -324,7 +324,7 @@ public function testGeospatial(): void public function testDummies(): void { - Schema::collection('newcollection', function ($collection) { + Schema::table('newcollection', function ($collection) { $collection->boolean('activated')->default(0); $collection->integer('user_id')->unsigned(); }); @@ -333,7 +333,7 @@ public function testDummies(): void public function testSparseUnique(): void { - Schema::collection('newcollection', function ($collection) { + Schema::table('newcollection', function ($collection) { $collection->sparse_and_unique('sparseuniquekey'); }); @@ -361,7 +361,7 @@ public function testRenameColumn(): void $this->assertArrayNotHasKey('test', $check[2]); $this->assertArrayNotHasKey('newtest', $check[2]); - Schema::collection('newcollection', function (Blueprint $collection) { + Schema::table('newcollection', function (Blueprint $collection) { $collection->renameColumn('test', 'newtest'); }); From efab63bf6da5b6df23f57ac4dc0f519e096d0a4e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 26 Aug 2024 17:49:44 +0200 Subject: [PATCH 337/446] PHPORM-227 Fix single document upsert (#3100) --- CHANGELOG.md | 4 ++++ src/Query/Builder.php | 5 +++++ tests/ModelTest.php | 5 ++--- tests/QueryBuilderTest.php | 5 ++--- 4 files changed, 13 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8c1c4d9c1..fa510e9aa 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,10 @@ # Changelog All notable changes to this project will be documented in this file. +## [4.7.2] - coming soon + +* Add `Query\Builder::upsert()` method with a single document by @GromNaN in [#3100](https://github.com/mongodb/laravel-mongodb/pull/3100) + ## [4.7.1] - 2024-07-25 * Fix registration of `BusServiceProvider` for compatibility with Horizon by @GromNaN in [#3071](https://github.com/mongodb/laravel-mongodb/pull/3071) diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 1d4dcf153..23f2ec02c 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -732,6 +732,11 @@ public function upsert(array $values, $uniqueBy, $update = null): int return 0; } + // Single document provided + if (! array_is_list($values)) { + $values = [$values]; + } + $this->applyBeforeQueryCallbacks(); $options = $this->inheritConnectionOptions(); diff --git a/tests/ModelTest.php b/tests/ModelTest.php index 57e49574f..24dc9a5ae 100644 --- a/tests/ModelTest.php +++ b/tests/ModelTest.php @@ -168,9 +168,8 @@ public function testUpsert() $this->assertSame('bar2', User::where('email', 'foo')->first()->name); // If no update fields are specified, all fields are updated - $result = User::upsert([ - ['email' => 'foo', 'name' => 'bar3'], - ], 'email'); + // Test single document update + $result = User::upsert(['email' => 'foo', 'name' => 'bar3'], 'email'); $this->assertSame(1, $result); $this->assertSame(2, User::count()); diff --git a/tests/QueryBuilderTest.php b/tests/QueryBuilderTest.php index 7924e02f3..ac35e8978 100644 --- a/tests/QueryBuilderTest.php +++ b/tests/QueryBuilderTest.php @@ -632,9 +632,8 @@ public function testUpsert() $this->assertSame('bar2', DB::collection('users')->where('email', 'foo')->first()['name']); // If no update fields are specified, all fields are updated - $result = DB::collection('users')->upsert([ - ['email' => 'foo', 'name' => 'bar3'], - ], 'email'); + // Test single document update + $result = DB::collection('users')->upsert(['email' => 'foo', 'name' => 'bar3'], 'email'); $this->assertSame(1, $result); $this->assertSame(2, DB::collection('users')->count()); From 500ae9bbcea974cc09f28a048b573d8f0da060bf Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Mon, 26 Aug 2024 16:16:22 -0400 Subject: [PATCH 338/446] DOCSP-42818: wherelike and wherenotlike docs (#3114) * DOCSP-42818: wherelike and wherenotlike docs * heading fix * move section * wip * add cross link --- .../query-builder/QueryBuilderTest.php | 12 +++++++ .../query-builder/sample_mflix.movies.json | 5 +++ docs/query-builder.txt | 36 +++++++++++++++++++ 3 files changed, 53 insertions(+) diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index 74f576e32..46822f257 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -374,6 +374,18 @@ public function testWhereRegex(): void $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); } + public function testWhereLike(): void + { + // begin query whereLike + $result = DB::connection('mongodb') + ->table('movies') + ->whereLike('title', 'Start%', true) + ->get(); + // end query whereLike + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + public function testWhereRaw(): void { // begin query raw diff --git a/docs/includes/query-builder/sample_mflix.movies.json b/docs/includes/query-builder/sample_mflix.movies.json index ef8677520..2d5f45e6d 100644 --- a/docs/includes/query-builder/sample_mflix.movies.json +++ b/docs/includes/query-builder/sample_mflix.movies.json @@ -148,6 +148,11 @@ } } }, + { + "runtime": 120, + "directors": ["Alan Pakula"], + "title": "Starting Over" + }, { "genres": ["Crime", "Drama"], "runtime": 119, diff --git a/docs/query-builder.txt b/docs/query-builder.txt index 45e3c5993..7d33c016d 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -381,6 +381,42 @@ wildcard characters: ... ] +whereLike() and whereNotLike() Methods +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following methods provide the same functionality as using the +:ref:`like ` query operator to match +patterns: + +- ``whereLike()``: Matches a specified pattern. By default, this method + performs a case-insensitive match. You can enable case-sensitivity by + passing ``true`` as the last parameter to the method. +- ``whereNotLike()``: Matches documents in which the field + value does not contain the specified string pattern. + +The following example shows how to use the ``whereLike()`` method to +match documents in which the ``title`` field has a value that matches the +pattern ``'Start%'`` with case-sensitivity enabled: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query whereLike + :end-before: end query whereLike + + .. output:: + :language: json + :visible: false + + [ + { "title": "Start-Up", ... }, + { "title": "Start the Revolution Without Me", ... }, + ... + ] + .. _laravel-query-builder-distinct: Retrieve Distinct Values From ebda1fa0e4a5059cf253c2a0e329b0bd86efcf70 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 27 Aug 2024 23:58:04 +0200 Subject: [PATCH 339/446] PHPORM-229 Make Query\Builder return objects instead of array to match Laravel's behavior (#3107) --- CHANGELOG.md | 1 + .../query-builder/QueryBuilderTest.php | 8 +- src/Query/Builder.php | 47 +++- src/Queue/Failed/MongoFailedJobProvider.php | 10 +- src/Queue/MongoQueue.php | 2 +- tests/AuthTest.php | 6 +- tests/Query/BuilderTest.php | 4 +- tests/QueryBuilderTest.php | 220 +++++++++--------- tests/QueueTest.php | 26 +-- tests/SchemaTest.php | 34 +-- tests/SchemaVersionTest.php | 2 +- tests/TransactionTest.php | 2 +- 12 files changed, 194 insertions(+), 168 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c2b4dddca..2b9b491eb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,7 @@ All notable changes to this project will be documented in this file. ## [5.0.0] - next * **BREAKING CHANGE** Use `id` as an alias for `_id` in commands and queries for compatibility with Eloquent packages by @GromNaN in [#3040](https://github.com/mongodb/laravel-mongodb/pull/3040) +* **BREAKING CHANGE** Make Query\Builder return objects instead of array to match Laravel behavior by @GromNaN in [#3107](https://github.com/mongodb/laravel-mongodb/pull/3107) ## [4.8.0] - 2024-08-27 diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index 46822f257..bf92b9a6b 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -531,11 +531,11 @@ public function testUpsert(): void $this->assertSame(2, $result); - $this->assertSame(119, DB::table('movies')->where('title', 'Inspector Maigret')->first()['runtime']); - $this->assertSame(false, DB::table('movies')->where('title', 'Inspector Maigret')->first()['recommended']); + $this->assertSame(119, DB::table('movies')->where('title', 'Inspector Maigret')->first()->runtime); + $this->assertSame(false, DB::table('movies')->where('title', 'Inspector Maigret')->first()->recommended); - $this->assertSame(true, DB::table('movies')->where('title', 'Petit Maman')->first()['recommended']); - $this->assertSame(72, DB::table('movies')->where('title', 'Petit Maman')->first()['runtime']); + $this->assertSame(true, DB::table('movies')->where('title', 'Petit Maman')->first()->recommended); + $this->assertSame(72, DB::table('movies')->where('title', 'Petit Maman')->first()->runtime); } public function testUpdateUpsert(): void diff --git a/src/Query/Builder.php b/src/Query/Builder.php index b41168b80..9a2cc6cd8 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -25,6 +25,7 @@ use MongoDB\Driver\Cursor; use Override; use RuntimeException; +use stdClass; use function array_fill_keys; use function array_is_list; @@ -45,6 +46,7 @@ use function func_get_args; use function func_num_args; use function get_debug_type; +use function get_object_vars; use function implode; use function in_array; use function is_array; @@ -52,11 +54,13 @@ use function is_callable; use function is_float; use function is_int; +use function is_object; use function is_string; use function md5; use function preg_match; use function preg_quote; use function preg_replace; +use function property_exists; use function serialize; use function sprintf; use function str_ends_with; @@ -391,7 +395,7 @@ public function toMql(): array } $options = [ - 'typeMap' => ['root' => 'array', 'document' => 'array'], + 'typeMap' => ['root' => 'object', 'document' => 'array'], ]; // Add custom query options @@ -450,8 +454,7 @@ public function toMql(): array $options['projection'] = $projection; } - // Fix for legacy support, converts the results to arrays instead of objects. - $options['typeMap'] = ['root' => 'array', 'document' => 'array']; + $options['typeMap'] = ['root' => 'object', 'document' => 'array']; // Add custom query options if (count($this->options)) { @@ -516,7 +519,7 @@ public function getFresh($columns = [], $returnLazy = false) } foreach ($result as &$document) { - if (is_array($document)) { + if (is_array($document) || is_object($document)) { $document = $this->aliasIdForResult($document); } } @@ -1641,16 +1644,38 @@ private function aliasIdForQuery(array $values): array return $values; } - private function aliasIdForResult(array $values): array + /** + * @psalm-param T $values + * + * @psalm-return T + * + * @template T of array|object + */ + private function aliasIdForResult(array|object $values): array|object { - if (array_key_exists('_id', $values) && ! array_key_exists('id', $values)) { - $values['id'] = $values['_id']; - //unset($values['_id']); + if (is_array($values)) { + if (array_key_exists('_id', $values) && ! array_key_exists('id', $values)) { + $values['id'] = $values['_id']; + //unset($values['_id']); + } + + foreach ($values as $key => $value) { + if (is_array($value) || is_object($value)) { + $values[$key] = $this->aliasIdForResult($value); + } + } } - foreach ($values as $key => $value) { - if (is_array($value)) { - $values[$key] = $this->aliasIdForResult($value); + if ($values instanceof stdClass) { + if (property_exists($values, '_id') && ! property_exists($values, 'id')) { + $values->id = $values->_id; + //unset($values->_id); + } + + foreach (get_object_vars($values) as $key => $value) { + if (is_array($value) || is_object($value)) { + $values->{$key} = $this->aliasIdForResult($value); + } } } diff --git a/src/Queue/Failed/MongoFailedJobProvider.php b/src/Queue/Failed/MongoFailedJobProvider.php index 357f27ddc..102fc98d7 100644 --- a/src/Queue/Failed/MongoFailedJobProvider.php +++ b/src/Queue/Failed/MongoFailedJobProvider.php @@ -43,12 +43,12 @@ public function log($connection, $queue, $payload, $exception) */ public function all() { - $all = $this->getTable()->orderBy('_id', 'desc')->get()->all(); + $all = $this->getTable()->orderBy('id', 'desc')->get()->all(); $all = array_map(function ($job) { - $job['id'] = (string) $job['_id']; + $job->id = (string) $job->id; - return (object) $job; + return $job; }, $all); return $all; @@ -69,9 +69,9 @@ public function find($id) return null; } - $job['id'] = (string) $job['_id']; + $job->id = (string) $job->id; - return (object) $job; + return $job; } /** diff --git a/src/Queue/MongoQueue.php b/src/Queue/MongoQueue.php index 5b91afb6b..7810aab92 100644 --- a/src/Queue/MongoQueue.php +++ b/src/Queue/MongoQueue.php @@ -116,7 +116,7 @@ protected function releaseJobsThatHaveBeenReservedTooLong($queue) ->get(); foreach ($reserved as $job) { - $this->releaseJob($job['_id'], $job['attempts']); + $this->releaseJob($job->id, $job->attempts); } } diff --git a/tests/AuthTest.php b/tests/AuthTest.php index d2b3a9675..ffe3d46e9 100644 --- a/tests/AuthTest.php +++ b/tests/AuthTest.php @@ -61,9 +61,9 @@ function ($actualUser, $actualToken) use ($user, &$token) { $this->assertEquals(1, DB::table('password_reset_tokens')->count()); $reminder = DB::table('password_reset_tokens')->first(); - $this->assertEquals('john.doe@example.com', $reminder['email']); - $this->assertNotNull($reminder['token']); - $this->assertInstanceOf(UTCDateTime::class, $reminder['created_at']); + $this->assertEquals('john.doe@example.com', $reminder->email); + $this->assertNotNull($reminder->token); + $this->assertInstanceOf(UTCDateTime::class, $reminder->created_at); $credentials = [ 'email' => 'john.doe@example.com', diff --git a/tests/Query/BuilderTest.php b/tests/Query/BuilderTest.php index 199935743..49da6fada 100644 --- a/tests/Query/BuilderTest.php +++ b/tests/Query/BuilderTest.php @@ -44,11 +44,11 @@ public function testMql(array $expected, Closure $build, ?string $requiredMethod // Operations that return a Cursor expect a "typeMap" option. if (isset($expected['find'][1])) { - $expected['find'][1]['typeMap'] = ['root' => 'array', 'document' => 'array']; + $expected['find'][1]['typeMap'] = ['root' => 'object', 'document' => 'array']; } if (isset($expected['aggregate'][1])) { - $expected['aggregate'][1]['typeMap'] = ['root' => 'array', 'document' => 'array']; + $expected['aggregate'][1]['typeMap'] = ['root' => 'object', 'document' => 'array']; } // Compare with assertEquals because the query can contain BSON objects. diff --git a/tests/QueryBuilderTest.php b/tests/QueryBuilderTest.php index 436c86996..d34bb5241 100644 --- a/tests/QueryBuilderTest.php +++ b/tests/QueryBuilderTest.php @@ -60,7 +60,7 @@ public function testDeleteWithId() $product = DB::table('items')->first(); - $pid = (string) ($product['id']); + $pid = (string) ($product->id); DB::table('items')->where('user_id', $userId)->delete($pid); @@ -68,7 +68,7 @@ public function testDeleteWithId() $product = DB::table('items')->first(); - $pid = $product['id']; + $pid = $product->id; DB::table('items')->where('user_id', $userId)->delete($pid); @@ -116,8 +116,8 @@ public function testInsert() $this->assertCount(1, $users); $user = $users[0]; - $this->assertEquals('John Doe', $user['name']); - $this->assertIsArray($user['tags']); + $this->assertEquals('John Doe', $user->name); + $this->assertIsArray($user->tags); } public function testInsertGetId() @@ -141,7 +141,7 @@ public function testBatchInsert() $users = DB::table('users')->get(); $this->assertCount(2, $users); - $this->assertIsArray($users[0]['tags']); + $this->assertIsArray($users[0]->tags); } public function testFind() @@ -149,7 +149,7 @@ public function testFind() $id = DB::table('users')->insertGetId(['name' => 'John Doe']); $user = DB::table('users')->find($id); - $this->assertEquals('John Doe', $user['name']); + $this->assertEquals('John Doe', $user->name); } public function testFindWithTimeout() @@ -211,8 +211,8 @@ public function testUpdate() $john = DB::table('users')->where('name', 'John Doe')->first(); $jane = DB::table('users')->where('name', 'Jane Doe')->first(); - $this->assertEquals(100, $john['age']); - $this->assertEquals(20, $jane['age']); + $this->assertEquals(100, $john->age); + $this->assertEquals(20, $jane->age); } public function testUpdateOperators() @@ -239,12 +239,12 @@ public function testUpdateOperators() $john = DB::table('users')->where('name', 'John Doe')->first(); $jane = DB::table('users')->where('name', 'Jane Doe')->first(); - $this->assertArrayNotHasKey('age', $john); - $this->assertTrue($john['ageless']); + $this->assertObjectNotHasProperty('age', $john); + $this->assertTrue($john->ageless); - $this->assertEquals(21, $jane['age']); - $this->assertEquals('she', $jane['pronoun']); - $this->assertFalse($jane['ageless']); + $this->assertEquals(21, $jane->age); + $this->assertEquals('she', $jane->pronoun); + $this->assertFalse($jane->ageless); } public function testDelete() @@ -286,7 +286,7 @@ public function testSubKey() $users = DB::table('users')->where('address.country', 'Belgium')->get(); $this->assertCount(1, $users); - $this->assertEquals('John Doe', $users[0]['name']); + $this->assertEquals('John Doe', $users[0]->name); } public function testInArray() @@ -329,7 +329,7 @@ public function testRaw() $results = DB::table('users')->whereRaw(['age' => 20])->get(); $this->assertCount(1, $results); - $this->assertEquals('Jane Doe', $results[0]['name']); + $this->assertEquals('Jane Doe', $results[0]->name); } public function testPush() @@ -343,31 +343,31 @@ public function testPush() DB::table('users')->where('id', $id)->push('tags', 'tag1'); $user = DB::table('users')->find($id); - $this->assertIsArray($user['tags']); - $this->assertCount(1, $user['tags']); - $this->assertEquals('tag1', $user['tags'][0]); + $this->assertIsArray($user->tags); + $this->assertCount(1, $user->tags); + $this->assertEquals('tag1', $user->tags[0]); DB::table('users')->where('id', $id)->push('tags', 'tag2'); $user = DB::table('users')->find($id); - $this->assertCount(2, $user['tags']); - $this->assertEquals('tag2', $user['tags'][1]); + $this->assertCount(2, $user->tags); + $this->assertEquals('tag2', $user->tags[1]); // Add duplicate DB::table('users')->where('id', $id)->push('tags', 'tag2'); $user = DB::table('users')->find($id); - $this->assertCount(3, $user['tags']); + $this->assertCount(3, $user->tags); // Add unique DB::table('users')->where('id', $id)->push('tags', 'tag1', true); $user = DB::table('users')->find($id); - $this->assertCount(3, $user['tags']); + $this->assertCount(3, $user->tags); $message = ['from' => 'Jane', 'body' => 'Hi John']; DB::table('users')->where('id', $id)->push('messages', $message); $user = DB::table('users')->find($id); - $this->assertIsArray($user['messages']); - $this->assertCount(1, $user['messages']); - $this->assertEquals($message, $user['messages'][0]); + $this->assertIsArray($user->messages); + $this->assertCount(1, $user->messages); + $this->assertEquals($message, $user->messages[0]); // Raw DB::table('users')->where('id', $id)->push([ @@ -375,8 +375,8 @@ public function testPush() 'messages' => ['from' => 'Mark', 'body' => 'Hi John'], ]); $user = DB::table('users')->find($id); - $this->assertCount(4, $user['tags']); - $this->assertCount(2, $user['messages']); + $this->assertCount(4, $user->tags); + $this->assertCount(2, $user->messages); DB::table('users')->where('id', $id)->push([ 'messages' => [ @@ -385,7 +385,7 @@ public function testPush() ], ]); $user = DB::table('users')->find($id); - $this->assertCount(3, $user['messages']); + $this->assertCount(3, $user->messages); } public function testPushRefuses2ndArgumentWhen1stIsAnArray() @@ -410,21 +410,21 @@ public function testPull() DB::table('users')->where('id', $id)->pull('tags', 'tag3'); $user = DB::table('users')->find($id); - $this->assertIsArray($user['tags']); - $this->assertCount(3, $user['tags']); - $this->assertEquals('tag4', $user['tags'][2]); + $this->assertIsArray($user->tags); + $this->assertCount(3, $user->tags); + $this->assertEquals('tag4', $user->tags[2]); DB::table('users')->where('id', $id)->pull('messages', $message1); $user = DB::table('users')->find($id); - $this->assertIsArray($user['messages']); - $this->assertCount(1, $user['messages']); + $this->assertIsArray($user->messages); + $this->assertCount(1, $user->messages); // Raw DB::table('users')->where('id', $id)->pull(['tags' => 'tag2', 'messages' => $message2]); $user = DB::table('users')->find($id); - $this->assertCount(2, $user['tags']); - $this->assertCount(0, $user['messages']); + $this->assertCount(2, $user->tags); + $this->assertCount(0, $user->messages); } public function testDistinct() @@ -456,10 +456,10 @@ public function testCustomId() ]); $item = DB::table('items')->find('knife'); - $this->assertEquals('knife', $item['id']); + $this->assertEquals('knife', $item->id); $item = DB::table('items')->where('id', 'fork')->first(); - $this->assertEquals('fork', $item['id']); + $this->assertEquals('fork', $item->id); DB::table('users')->insert([ ['id' => 1, 'name' => 'Jane Doe'], @@ -467,7 +467,7 @@ public function testCustomId() ]); $item = DB::table('users')->find(1); - $this->assertEquals(1, $item['id']); + $this->assertEquals(1, $item->id); } public function testTake() @@ -481,7 +481,7 @@ public function testTake() $items = DB::table('items')->orderBy('name')->take(2)->get(); $this->assertCount(2, $items); - $this->assertEquals('fork', $items[0]['name']); + $this->assertEquals('fork', $items[0]->name); } public function testSkip() @@ -495,7 +495,7 @@ public function testSkip() $items = DB::table('items')->orderBy('name')->skip(2)->get(); $this->assertCount(2, $items); - $this->assertEquals('spoon', $items[0]['name']); + $this->assertEquals('spoon', $items[0]->name); } public function testPluck() @@ -620,7 +620,7 @@ public function testUpsert() $this->assertSame(2, $result); $this->assertSame(2, DB::table('users')->count()); - $this->assertSame('bar', DB::table('users')->where('email', 'foo')->first()['name']); + $this->assertSame('bar', DB::table('users')->where('email', 'foo')->first()->name); // Update 1 document $result = DB::table('users')->upsert([ @@ -630,7 +630,7 @@ public function testUpsert() $this->assertSame(1, $result); $this->assertSame(2, DB::table('users')->count()); - $this->assertSame('bar2', DB::table('users')->where('email', 'foo')->first()['name']); + $this->assertSame('bar2', DB::table('users')->where('email', 'foo')->first()->name); // If no update fields are specified, all fields are updated // Test single document update @@ -638,7 +638,7 @@ public function testUpsert() $this->assertSame(1, $result); $this->assertSame(2, DB::table('users')->count()); - $this->assertSame('bar3', DB::table('users')->where('email', 'foo')->first()['name']); + $this->assertSame('bar3', DB::table('users')->where('email', 'foo')->first()->name); } public function testUnset() @@ -651,16 +651,16 @@ public function testUnset() $user1 = DB::table('users')->find($id1); $user2 = DB::table('users')->find($id2); - $this->assertArrayNotHasKey('note1', $user1); - $this->assertArrayHasKey('note2', $user1); - $this->assertArrayHasKey('note1', $user2); - $this->assertArrayHasKey('note2', $user2); + $this->assertObjectNotHasProperty('note1', $user1); + $this->assertObjectHasProperty('note2', $user1); + $this->assertObjectHasProperty('note1', $user2); + $this->assertObjectHasProperty('note2', $user2); DB::table('users')->where('name', 'Jane Doe')->unset(['note1', 'note2']); $user2 = DB::table('users')->find($id2); - $this->assertArrayNotHasKey('note1', $user2); - $this->assertArrayNotHasKey('note2', $user2); + $this->assertObjectNotHasProperty('note1', $user2); + $this->assertObjectNotHasProperty('note2', $user2); } public function testUpdateSubdocument() @@ -670,7 +670,7 @@ public function testUpdateSubdocument() DB::table('users')->where('id', $id)->update(['address.country' => 'England']); $check = DB::table('users')->find($id); - $this->assertEquals('England', $check['address']['country']); + $this->assertEquals('England', $check->address['country']); } public function testDates() @@ -685,15 +685,15 @@ public function testDates() $user = DB::table('users') ->where('birthday', new UTCDateTime(Date::parse('1980-01-01 00:00:00'))) ->first(); - $this->assertEquals('John Doe', $user['name']); + $this->assertEquals('John Doe', $user->name); $user = DB::table('users') ->where('birthday', new UTCDateTime(Date::parse('1960-01-01 12:12:12.1'))) ->first(); - $this->assertEquals('Frank White', $user['name']); + $this->assertEquals('Frank White', $user->name); $user = DB::table('users')->where('birthday', '=', new DateTime('1980-01-01 00:00:00'))->first(); - $this->assertEquals('John Doe', $user['name']); + $this->assertEquals('John Doe', $user->name); $start = new UTCDateTime(1000 * strtotime('1950-01-01 00:00:00')); $stop = new UTCDateTime(1000 * strtotime('1981-01-01 00:00:00')); @@ -739,25 +739,25 @@ public function testOperators() $results = DB::table('users')->where('age', 'exists', true)->get(); $this->assertCount(2, $results); - $resultsNames = [$results[0]['name'], $results[1]['name']]; + $resultsNames = [$results[0]->name, $results[1]->name]; $this->assertContains('John Doe', $resultsNames); $this->assertContains('Robert Roe', $resultsNames); $results = DB::table('users')->where('age', 'exists', false)->get(); $this->assertCount(1, $results); - $this->assertEquals('Jane Doe', $results[0]['name']); + $this->assertEquals('Jane Doe', $results[0]->name); $results = DB::table('users')->where('age', 'type', 2)->get(); $this->assertCount(1, $results); - $this->assertEquals('Robert Roe', $results[0]['name']); + $this->assertEquals('Robert Roe', $results[0]->name); $results = DB::table('users')->where('age', 'mod', [15, 0])->get(); $this->assertCount(1, $results); - $this->assertEquals('John Doe', $results[0]['name']); + $this->assertEquals('John Doe', $results[0]->name); $results = DB::table('users')->where('age', 'mod', [29, 1])->get(); $this->assertCount(1, $results); - $this->assertEquals('John Doe', $results[0]['name']); + $this->assertEquals('John Doe', $results[0]->name); $results = DB::table('users')->where('age', 'mod', [14, 0])->get(); $this->assertCount(0, $results); @@ -822,7 +822,7 @@ public function testOperators() $users = DB::table('users')->where('addresses', 'elemMatch', ['city' => 'Brussels'])->get(); $this->assertCount(1, $users); - $this->assertEquals('Jane Doe', $users[0]['name']); + $this->assertEquals('Jane Doe', $users[0]->name); } public function testIncrement() @@ -835,43 +835,43 @@ public function testIncrement() ]); $user = DB::table('users')->where('name', 'John Doe')->first(); - $this->assertEquals(30, $user['age']); + $this->assertEquals(30, $user->age); DB::table('users')->where('name', 'John Doe')->increment('age'); $user = DB::table('users')->where('name', 'John Doe')->first(); - $this->assertEquals(31, $user['age']); + $this->assertEquals(31, $user->age); DB::table('users')->where('name', 'John Doe')->decrement('age'); $user = DB::table('users')->where('name', 'John Doe')->first(); - $this->assertEquals(30, $user['age']); + $this->assertEquals(30, $user->age); DB::table('users')->where('name', 'John Doe')->increment('age', 5); $user = DB::table('users')->where('name', 'John Doe')->first(); - $this->assertEquals(35, $user['age']); + $this->assertEquals(35, $user->age); DB::table('users')->where('name', 'John Doe')->decrement('age', 5); $user = DB::table('users')->where('name', 'John Doe')->first(); - $this->assertEquals(30, $user['age']); + $this->assertEquals(30, $user->age); DB::table('users')->where('name', 'Jane Doe')->increment('age', 10, ['note' => 'adult']); $user = DB::table('users')->where('name', 'Jane Doe')->first(); - $this->assertEquals(20, $user['age']); - $this->assertEquals('adult', $user['note']); + $this->assertEquals(20, $user->age); + $this->assertEquals('adult', $user->note); DB::table('users')->where('name', 'John Doe')->decrement('age', 20, ['note' => 'minor']); $user = DB::table('users')->where('name', 'John Doe')->first(); - $this->assertEquals(10, $user['age']); - $this->assertEquals('minor', $user['note']); + $this->assertEquals(10, $user->age); + $this->assertEquals('minor', $user->note); DB::table('users')->increment('age'); $user = DB::table('users')->where('name', 'John Doe')->first(); - $this->assertEquals(11, $user['age']); + $this->assertEquals(11, $user->age); $user = DB::table('users')->where('name', 'Jane Doe')->first(); - $this->assertEquals(21, $user['age']); + $this->assertEquals(21, $user->age); $user = DB::table('users')->where('name', 'Robert Roe')->first(); - $this->assertNull($user['age']); + $this->assertNull($user->age); $user = DB::table('users')->where('name', 'Mark Moe')->first(); - $this->assertEquals(1, $user['age']); + $this->assertEquals(1, $user->age); } public function testProjections() @@ -885,7 +885,7 @@ public function testProjections() $results = DB::table('items')->project(['tags' => ['$slice' => 1]])->get(); foreach ($results as $result) { - $this->assertEquals(1, count($result['tags'])); + $this->assertEquals(1, count($result->tags)); } } @@ -912,15 +912,15 @@ public function testHintOptions() $results = DB::table('items')->hint(['$natural' => -1])->get(); - $this->assertEquals('spoon', $results[0]['name']); - $this->assertEquals('spork', $results[1]['name']); - $this->assertEquals('fork', $results[2]['name']); + $this->assertEquals('spoon', $results[0]->name); + $this->assertEquals('spork', $results[1]->name); + $this->assertEquals('fork', $results[2]->name); $results = DB::table('items')->hint(['$natural' => 1])->get(); - $this->assertEquals('spoon', $results[2]['name']); - $this->assertEquals('spork', $results[1]['name']); - $this->assertEquals('fork', $results[0]['name']); + $this->assertEquals('spoon', $results[2]->name); + $this->assertEquals('spork', $results[1]->name); + $this->assertEquals('fork', $results[0]->name); } public function testCursor() @@ -936,7 +936,7 @@ public function testCursor() $this->assertInstanceOf(LazyCollection::class, $results); foreach ($results as $i => $result) { - $this->assertEquals($data[$i]['name'], $result['name']); + $this->assertEquals($data[$i]['name'], $result->name); } } @@ -951,52 +951,52 @@ public function testStringableColumn() $this->assertInstanceOf(Stringable::class, $nameColumn, 'Ensure we are testing the feature with a Stringable instance'); $user = DB::table('users')->where($nameColumn, 'John Doe')->first(); - $this->assertEquals('John Doe', $user['name']); + $this->assertEquals('John Doe', $user->name); // Test this other document to be sure this is not a random success to data order $user = DB::table('users')->where($nameColumn, 'Jane Doe')->orderBy('natural')->first(); - $this->assertEquals('Jane Doe', $user['name']); + $this->assertEquals('Jane Doe', $user->name); // With an operator $user = DB::table('users')->where($nameColumn, '!=', 'Jane Doe')->first(); - $this->assertEquals('John Doe', $user['name']); + $this->assertEquals('John Doe', $user->name); // whereIn and whereNotIn $user = DB::table('users')->whereIn($nameColumn, ['John Doe'])->first(); - $this->assertEquals('John Doe', $user['name']); + $this->assertEquals('John Doe', $user->name); $user = DB::table('users')->whereNotIn($nameColumn, ['John Doe'])->first(); - $this->assertEquals('Jane Doe', $user['name']); + $this->assertEquals('Jane Doe', $user->name); $ageColumn = Str::of('age'); // whereBetween and whereNotBetween $user = DB::table('users')->whereBetween($ageColumn, [30, 40])->first(); - $this->assertEquals('Jane Doe', $user['name']); + $this->assertEquals('Jane Doe', $user->name); // whereBetween and whereNotBetween $user = DB::table('users')->whereNotBetween($ageColumn, [30, 40])->first(); - $this->assertEquals('John Doe', $user['name']); + $this->assertEquals('John Doe', $user->name); $birthdayColumn = Str::of('birthday'); // whereDate $user = DB::table('users')->whereDate($birthdayColumn, '1995-01-01')->first(); - $this->assertEquals('John Doe', $user['name']); + $this->assertEquals('John Doe', $user->name); $user = DB::table('users')->whereDate($birthdayColumn, '<', '1990-01-01') ->orderBy($birthdayColumn, 'desc')->first(); - $this->assertEquals('Jane Doe', $user['name']); + $this->assertEquals('Jane Doe', $user->name); $user = DB::table('users')->whereDate($birthdayColumn, '>', '1990-01-01') ->orderBy($birthdayColumn, 'asc')->first(); - $this->assertEquals('John Doe', $user['name']); + $this->assertEquals('John Doe', $user->name); $user = DB::table('users')->whereDate($birthdayColumn, '!=', '1987-01-01')->first(); - $this->assertEquals('John Doe', $user['name']); + $this->assertEquals('John Doe', $user->name); // increment DB::table('users')->where($ageColumn, 28)->increment($ageColumn, 1); $user = DB::table('users')->where($ageColumn, 29)->first(); - $this->assertEquals('John Doe', $user['name']); + $this->assertEquals('John Doe', $user->name); } public function testIncrementEach() @@ -1012,16 +1012,16 @@ public function testIncrementEach() 'note' => 2, ]); $user = DB::table('users')->where('name', 'John Doe')->first(); - $this->assertEquals(31, $user['age']); - $this->assertEquals(7, $user['note']); + $this->assertEquals(31, $user->age); + $this->assertEquals(7, $user->note); $user = DB::table('users')->where('name', 'Jane Doe')->first(); - $this->assertEquals(11, $user['age']); - $this->assertEquals(8, $user['note']); + $this->assertEquals(11, $user->age); + $this->assertEquals(8, $user->note); $user = DB::table('users')->where('name', 'Robert Roe')->first(); - $this->assertSame(1, $user['age']); - $this->assertSame(2, $user['note']); + $this->assertSame(1, $user->age); + $this->assertSame(2, $user->note); DB::table('users')->where('name', 'Jane Doe')->incrementEach([ 'age' => 1, @@ -1029,14 +1029,14 @@ public function testIncrementEach() ], ['extra' => 'foo']); $user = DB::table('users')->where('name', 'Jane Doe')->first(); - $this->assertEquals(12, $user['age']); - $this->assertEquals(10, $user['note']); - $this->assertEquals('foo', $user['extra']); + $this->assertEquals(12, $user->age); + $this->assertEquals(10, $user->note); + $this->assertEquals('foo', $user->extra); $user = DB::table('users')->where('name', 'John Doe')->first(); - $this->assertEquals(31, $user['age']); - $this->assertEquals(7, $user['note']); - $this->assertArrayNotHasKey('extra', $user); + $this->assertEquals(31, $user->age); + $this->assertEquals(7, $user->note); + $this->assertObjectNotHasProperty('extra', $user); DB::table('users')->decrementEach([ 'age' => 1, @@ -1044,9 +1044,9 @@ public function testIncrementEach() ], ['extra' => 'foo']); $user = DB::table('users')->where('name', 'John Doe')->first(); - $this->assertEquals(30, $user['age']); - $this->assertEquals(5, $user['note']); - $this->assertEquals('foo', $user['extra']); + $this->assertEquals(30, $user->age); + $this->assertEquals(5, $user->note); + $this->assertEquals('foo', $user->extra); } #[TestWith(['id', 'id'])] @@ -1058,12 +1058,12 @@ public function testIdAlias($insertId, $queryId): void DB::table('items')->insert([$insertId => 'abc', 'name' => 'Karting']); $item = DB::table('items')->where($queryId, '=', 'abc')->first(); $this->assertNotNull($item); - $this->assertSame('abc', $item['id']); - $this->assertSame('Karting', $item['name']); + $this->assertSame('abc', $item->id); + $this->assertSame('Karting', $item->name); DB::table('items')->where($insertId, '=', 'abc')->update(['name' => 'Bike']); $item = DB::table('items')->where($queryId, '=', 'abc')->first(); - $this->assertSame('Bike', $item['name']); + $this->assertSame('Bike', $item->name); $result = DB::table('items')->where($queryId, '=', 'abc')->delete(); $this->assertSame(1, $result); diff --git a/tests/QueueTest.php b/tests/QueueTest.php index af31c8a5b..04a279640 100644 --- a/tests/QueueTest.php +++ b/tests/QueueTest.php @@ -114,7 +114,7 @@ public function testIncrementAttempts(): void ->get(); $this->assertCount(1, $othersJobs); - $this->assertEquals(0, $othersJobs[0]['attempts']); + $this->assertEquals(0, $othersJobs[0]->attempts); } public function testJobRelease(): void @@ -131,7 +131,7 @@ public function testJobRelease(): void ->get(); $this->assertCount(1, $jobs); - $this->assertEquals(1, $jobs[0]['attempts']); + $this->assertEquals(1, $jobs[0]->attempts); } public function testQueueDeleteReserved(): void @@ -161,15 +161,15 @@ public function testQueueRelease(): void ->where('id', $releasedJobId) ->first(); - $this->assertEquals($queue, $releasedJob['queue']); - $this->assertEquals(1, $releasedJob['attempts']); - $this->assertNull($releasedJob['reserved_at']); + $this->assertEquals($queue, $releasedJob->queue); + $this->assertEquals(1, $releasedJob->attempts); + $this->assertNull($releasedJob->reserved_at); $this->assertEquals( Carbon::now()->addRealSeconds($delay)->getTimestamp(), - $releasedJob['available_at'], + $releasedJob->available_at, ); - $this->assertEquals(Carbon::now()->getTimestamp(), $releasedJob['created_at']); - $this->assertEquals($job->getRawBody(), $releasedJob['payload']); + $this->assertEquals(Carbon::now()->getTimestamp(), $releasedJob->created_at); + $this->assertEquals($job->getRawBody(), $releasedJob->payload); } public function testQueueDeleteAndRelease(): void @@ -194,10 +194,10 @@ public function testFailedJobLogging() $failedJob = Queue::getDatabase()->table(Config::get('queue.failed.table'))->first(); - $this->assertSame('test_connection', $failedJob['connection']); - $this->assertSame('test_queue', $failedJob['queue']); - $this->assertSame('test_payload', $failedJob['payload']); - $this->assertEquals(new UTCDateTime(Carbon::now()), $failedJob['failed_at']); - $this->assertStringStartsWith('Exception: test_exception in ', $failedJob['exception']); + $this->assertSame('test_connection', $failedJob->connection); + $this->assertSame('test_queue', $failedJob->queue); + $this->assertSame('test_payload', $failedJob->payload); + $this->assertEquals(new UTCDateTime(Carbon::now()), $failedJob->failed_at); + $this->assertStringStartsWith('Exception: test_exception in ', $failedJob->exception); } } diff --git a/tests/SchemaTest.php b/tests/SchemaTest.php index 914b79389..82d4a68c6 100644 --- a/tests/SchemaTest.php +++ b/tests/SchemaTest.php @@ -351,15 +351,15 @@ public function testRenameColumn(): void $check = DB::connection()->table('newcollection')->get(); $this->assertCount(3, $check); - $this->assertArrayHasKey('test', $check[0]); - $this->assertArrayNotHasKey('newtest', $check[0]); + $this->assertObjectHasProperty('test', $check[0]); + $this->assertObjectNotHasProperty('newtest', $check[0]); - $this->assertArrayHasKey('test', $check[1]); - $this->assertArrayNotHasKey('newtest', $check[1]); + $this->assertObjectHasProperty('test', $check[1]); + $this->assertObjectNotHasProperty('newtest', $check[1]); - $this->assertArrayHasKey('column', $check[2]); - $this->assertArrayNotHasKey('test', $check[2]); - $this->assertArrayNotHasKey('newtest', $check[2]); + $this->assertObjectHasProperty('column', $check[2]); + $this->assertObjectNotHasProperty('test', $check[2]); + $this->assertObjectNotHasProperty('newtest', $check[2]); Schema::table('newcollection', function (Blueprint $collection) { $collection->renameColumn('test', 'newtest'); @@ -368,18 +368,18 @@ public function testRenameColumn(): void $check2 = DB::connection()->table('newcollection')->get(); $this->assertCount(3, $check2); - $this->assertArrayHasKey('newtest', $check2[0]); - $this->assertArrayNotHasKey('test', $check2[0]); - $this->assertSame($check[0]['test'], $check2[0]['newtest']); + $this->assertObjectHasProperty('newtest', $check2[0]); + $this->assertObjectNotHasProperty('test', $check2[0]); + $this->assertSame($check[0]->test, $check2[0]->newtest); - $this->assertArrayHasKey('newtest', $check2[1]); - $this->assertArrayNotHasKey('test', $check2[1]); - $this->assertSame($check[1]['test'], $check2[1]['newtest']); + $this->assertObjectHasProperty('newtest', $check2[1]); + $this->assertObjectNotHasProperty('test', $check2[1]); + $this->assertSame($check[1]->test, $check2[1]->newtest); - $this->assertArrayHasKey('column', $check2[2]); - $this->assertArrayNotHasKey('test', $check2[2]); - $this->assertArrayNotHasKey('newtest', $check2[2]); - $this->assertSame($check[2]['column'], $check2[2]['column']); + $this->assertObjectHasProperty('column', $check2[2]); + $this->assertObjectNotHasProperty('test', $check2[2]); + $this->assertObjectNotHasProperty('newtest', $check2[2]); + $this->assertSame($check[2]->column, $check2[2]->column); } public function testHasColumn(): void diff --git a/tests/SchemaVersionTest.php b/tests/SchemaVersionTest.php index 0e115a6c2..4a205c77b 100644 --- a/tests/SchemaVersionTest.php +++ b/tests/SchemaVersionTest.php @@ -42,7 +42,7 @@ public function testWithBasicDocument() ->where('name', 'Vador') ->get(); - $this->assertEquals(2, $data[0]['schema_version']); + $this->assertEquals(2, $data[0]->schema_version); } public function testIncompleteImplementation(): void diff --git a/tests/TransactionTest.php b/tests/TransactionTest.php index bbb45ac05..f6a3cd509 100644 --- a/tests/TransactionTest.php +++ b/tests/TransactionTest.php @@ -122,7 +122,7 @@ public function testInsertGetIdWithCommit(): void $this->assertInstanceOf(ObjectId::class, $userId); $user = DB::table('users')->find((string) $userId); - $this->assertEquals('klinson', $user['name']); + $this->assertEquals('klinson', $user->name); } public function testInsertGetIdWithRollBack(): void From 18a49b41630d880a2218439d6aeb46b9f7fdf4db Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Thu, 29 Aug 2024 11:45:57 -0500 Subject: [PATCH 340/446] version bump --- docs/includes/framework-compatibility-laravel.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/includes/framework-compatibility-laravel.rst b/docs/includes/framework-compatibility-laravel.rst index 723f0e776..19bcafc1a 100644 --- a/docs/includes/framework-compatibility-laravel.rst +++ b/docs/includes/framework-compatibility-laravel.rst @@ -7,7 +7,7 @@ - Laravel 10.x - Laravel 9.x - * - 4.2 to 4.7 + * - 4.2 to 4.8 - ✓ - ✓ - From b84d583588028050f6afc2d56c61011777b37593 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Thu, 29 Aug 2024 16:14:43 -0400 Subject: [PATCH 341/446] DOCSP-42794: Laravel Passport (#3113) Adds a section to the User Authentication page that describes Laravel Passport. --- docs/includes/auth/AppServiceProvider.php | 32 +++++++ docs/user-authentication.txt | 110 ++++++++++++++++++++++ 2 files changed, 142 insertions(+) create mode 100644 docs/includes/auth/AppServiceProvider.php diff --git a/docs/includes/auth/AppServiceProvider.php b/docs/includes/auth/AppServiceProvider.php new file mode 100644 index 000000000..24ee1802c --- /dev/null +++ b/docs/includes/auth/AppServiceProvider.php @@ -0,0 +1,32 @@ +`__ in the + Laravel documentation. + + - `OAuth 2.0 `__ on the OAuth website. + +Install Laravel Passport +```````````````````````` + +To install Laravel Passport and run the database migrations required +to store OAuth2 clients, run the following command from your project root: + +.. code-block:: bash + + php artisan install:api --passport + +Next, navigate to your ``User`` model and add the ``Laravel\Passport\HasApiTokens`` +trait. This trait provides helper methods that allow you to inspect a user's +authentication token and scopes. The following code shows how to add ``Laravel\Passport\HasApiTokens`` +to your ``app\Models\User.php`` file: + +.. code-block:: php + + [ + 'web' => [ + 'driver' => 'session', + 'provider' => 'users', + ], + 'api' => [ + 'driver' => 'passport', + 'provider' => 'users', + ], + ], + +Use Laravel Passport with Laravel MongoDB +````````````````````````````````````````` + +After installing Laravel Passport, you must enable Passport compatibility with MongoDB by +defining custom {+odm-short+} models that extend the corresponding Passport models. +To extend each Passport model class, include the ``DocumentModel`` trait in the custom models. +You can define the following {+odm-short+} model classes: + +- ``MongoDB\Laravel\Passport\AuthCode``, which extends ``Laravel\Passport\AuthCode`` +- ``MongoDB\Laravel\Passport\Client``, which extends ``Laravel\Passport\Client`` +- ``MongoDB\Laravel\Passport\PersonalAccessClient``, which extends ``Laravel\Passport\PersonalAccessClient`` +- ``MongoDB\Laravel\Passport\RefreshToken``, which extends ``Laravel\Passport\RefreshToken`` +- ``MongoDB\Laravel\Passport\Token``, which extends ``Laravel\Passport\Token`` + +The following example code extends the default ``Laravel\Passport\AuthCode`` +model class when defining a ``MongoDB\Laravel\Passport\AuthCode`` class and includes +the ``DocumentModel`` trait: + +.. code-block:: php + + class MongoDB\Laravel\Passport\AuthCode extends Laravel\Passport\AuthCode + { + use MongoDB\Laravel\Eloquent\DocumentModel; + + protected $primaryKey = '_id'; + protected $keyType = 'string'; + } + +After defining custom models that extend each ``Laravel\Passport`` class, instruct +Passport to use the models in the ``boot()`` method of your application's +``App\Providers\AppServiceProvider`` class. The following example adds each custom +model to the ``boot()`` method: + +.. literalinclude:: /includes/auth/AppServiceProvider.php + :language: php + :emphasize-lines: 26-30 + :dedent: + +Then, you can use Laravel Passport and MongoDB in your application. + .. _laravel-user-auth-reminders: Password Reminders From d7da552c92225fff0f0c9f386700561beb95fe65 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 2 Sep 2024 14:44:30 +0200 Subject: [PATCH 342/446] Update PR template (#3121) --- .github/PULL_REQUEST_TEMPLATE.md | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index c3aad8477..321d843c0 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -7,4 +7,3 @@ This will help reviewers and should be a good start for the documentation. - [ ] Add tests and ensure they pass - [ ] Add an entry to the CHANGELOG.md file -- [ ] Update documentation for new features From a0b613498b3d7148821566d7774c0655e8629bbe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 2 Sep 2024 14:45:36 +0200 Subject: [PATCH 343/446] PHPORM-231 Remove MongoFailedJobProvider (#3122) --- CHANGELOG.md | 1 + src/MongoDBQueueServiceProvider.php | 68 ---------- src/Query/Builder.php | 10 +- src/Queue/Failed/MongoFailedJobProvider.php | 119 ------------------ tests/QueryTest.php | 11 -- ....php => DatabaseFailedJobProviderTest.php} | 14 ++- tests/QueueTest.php | 4 +- tests/TestCase.php | 2 - 8 files changed, 16 insertions(+), 213 deletions(-) delete mode 100644 src/MongoDBQueueServiceProvider.php delete mode 100644 src/Queue/Failed/MongoFailedJobProvider.php rename tests/Queue/Failed/{MongoFailedJobProviderTest.php => DatabaseFailedJobProviderTest.php} (90%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2b9b491eb..c34e9640f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,7 @@ All notable changes to this project will be documented in this file. * **BREAKING CHANGE** Use `id` as an alias for `_id` in commands and queries for compatibility with Eloquent packages by @GromNaN in [#3040](https://github.com/mongodb/laravel-mongodb/pull/3040) * **BREAKING CHANGE** Make Query\Builder return objects instead of array to match Laravel behavior by @GromNaN in [#3107](https://github.com/mongodb/laravel-mongodb/pull/3107) +* Remove `MongoFailedJobProvider`, replaced by Laravel `DatabaseFailedJobProvider` by @GromNaN in [#3122](https://github.com/mongodb/laravel-mongodb/pull/3122) ## [4.8.0] - 2024-08-27 diff --git a/src/MongoDBQueueServiceProvider.php b/src/MongoDBQueueServiceProvider.php deleted file mode 100644 index ea7a06176..000000000 --- a/src/MongoDBQueueServiceProvider.php +++ /dev/null @@ -1,68 +0,0 @@ -app->singleton('queue.failer', function ($app) { - $config = $app['config']['queue.failed']; - - if (array_key_exists('driver', $config) && ($config['driver'] === null || $config['driver'] === 'null')) { - return new NullFailedJobProvider(); - } - - if (isset($config['driver']) && $config['driver'] === 'mongodb') { - return $this->mongoFailedJobProvider($config); - } - - if (isset($config['driver']) && $config['driver'] === 'dynamodb') { - return $this->dynamoFailedJobProvider($config); - } - - if (isset($config['driver']) && $config['driver'] === 'database-uuids') { - return $this->databaseUuidFailedJobProvider($config); - } - - if (isset($config['table'])) { - return $this->databaseFailedJobProvider($config); - } - - return new NullFailedJobProvider(); - }); - } - - /** - * Create a new MongoDB failed job provider. - */ - protected function mongoFailedJobProvider(array $config): MongoFailedJobProvider - { - if (! isset($config['collection']) && isset($config['table'])) { - trigger_error('Since mongodb/laravel-mongodb 4.4: Using "table" option for the queue is deprecated. Use "collection" instead.', E_USER_DEPRECATED); - $config['collection'] = $config['table']; - } - - return new MongoFailedJobProvider( - $this->app['db'], - $config['database'] ?? null, - $config['collection'] ?? 'failed_jobs', - ); - } -} diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 9a2cc6cd8..486325029 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -876,11 +876,11 @@ public function delete($id = null) $wheres = $this->aliasIdForQuery($wheres); $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)); - } - + /** + * Ignore the limit if it is set to more than 1, as it is not supported by the deleteMany method. + * Required for {@see DatabaseFailedJobProvider::prune()} + */ + if ($this->limit === 1) { $result = $this->collection->deleteOne($wheres, $options); } else { $result = $this->collection->deleteMany($wheres, $options); diff --git a/src/Queue/Failed/MongoFailedJobProvider.php b/src/Queue/Failed/MongoFailedJobProvider.php deleted file mode 100644 index 102fc98d7..000000000 --- a/src/Queue/Failed/MongoFailedJobProvider.php +++ /dev/null @@ -1,119 +0,0 @@ -getTable()->insert([ - 'connection' => $connection, - 'queue' => $queue, - 'payload' => $payload, - 'failed_at' => new UTCDateTime(Carbon::now()), - 'exception' => (string) $exception, - ]); - } - - /** - * Get a list of all of the failed jobs. - * - * @return object[] - */ - public function all() - { - $all = $this->getTable()->orderBy('id', 'desc')->get()->all(); - - $all = array_map(function ($job) { - $job->id = (string) $job->id; - - return $job; - }, $all); - - return $all; - } - - /** - * Get a single failed job. - * - * @param string $id - * - * @return object|null - */ - public function find($id) - { - $job = $this->getTable()->find($id); - - if (! $job) { - return null; - } - - $job->id = (string) $job->id; - - return $job; - } - - /** - * Delete a single failed job from storage. - * - * @param string $id - * - * @return bool - */ - public function forget($id) - { - return $this->getTable()->where('_id', $id)->delete() > 0; - } - - /** - * Get the IDs of all the failed jobs. - * - * @param string|null $queue - * - * @return list - */ - public function ids($queue = null) - { - return $this->getTable() - ->when($queue !== null, static fn ($query) => $query->where('queue', $queue)) - ->orderBy('_id', 'desc') - ->pluck('_id') - ->all(); - } - - /** - * Prune all failed jobs older than the given date. - * - * @param DateTimeInterface $before - * - * @return int - */ - public function prune(DateTimeInterface $before) - { - return $this - ->getTable() - ->where('failed_at', '<', $before) - ->delete(); - } -} diff --git a/tests/QueryTest.php b/tests/QueryTest.php index e228a0f70..1b5746842 100644 --- a/tests/QueryTest.php +++ b/tests/QueryTest.php @@ -6,13 +6,11 @@ use BadMethodCallException; use DateTimeImmutable; -use LogicException; use MongoDB\BSON\Regex; use MongoDB\Laravel\Eloquent\Builder; use MongoDB\Laravel\Tests\Models\Birthday; use MongoDB\Laravel\Tests\Models\Scoped; use MongoDB\Laravel\Tests\Models\User; -use PHPUnit\Framework\Attributes\TestWith; use function str; @@ -662,13 +660,4 @@ public function testDelete(): void User::limit(null)->delete(); $this->assertEquals(0, User::count()); } - - #[TestWith([0])] - #[TestWith([2])] - public function testDeleteException(int $limit): void - { - $this->expectException(LogicException::class); - $this->expectExceptionMessage('Delete limit can be 1 or null (unlimited).'); - User::limit($limit)->delete(); - } } diff --git a/tests/Queue/Failed/MongoFailedJobProviderTest.php b/tests/Queue/Failed/DatabaseFailedJobProviderTest.php similarity index 90% rename from tests/Queue/Failed/MongoFailedJobProviderTest.php rename to tests/Queue/Failed/DatabaseFailedJobProviderTest.php index d0487ffcf..88a7f0e7b 100644 --- a/tests/Queue/Failed/MongoFailedJobProviderTest.php +++ b/tests/Queue/Failed/DatabaseFailedJobProviderTest.php @@ -2,11 +2,11 @@ namespace MongoDB\Laravel\Tests\Queue\Failed; +use Illuminate\Queue\Failed\DatabaseFailedJobProvider; use Illuminate\Support\Facades\Date; use Illuminate\Support\Facades\DB; use MongoDB\BSON\ObjectId; use MongoDB\BSON\UTCDateTime; -use MongoDB\Laravel\Queue\Failed\MongoFailedJobProvider; use MongoDB\Laravel\Tests\TestCase; use OutOfBoundsException; @@ -14,7 +14,10 @@ use function range; use function sprintf; -class MongoFailedJobProviderTest extends TestCase +/** + * Ensure the Laravel class {@see DatabaseFailedJobProvider} works with a MongoDB connection. + */ +class DatabaseFailedJobProviderTest extends TestCase { public function setUp(): void { @@ -57,8 +60,7 @@ public function testLog(): void $this->assertSame('default', $inserted->queue); $this->assertSame('{"foo":"bar"}', $inserted->payload); $this->assertStringContainsString('OutOfBoundsException: This is the error', $inserted->exception); - $this->assertInstanceOf(ObjectId::class, $inserted->_id); - $this->assertSame((string) $inserted->_id, $inserted->id); + $this->assertInstanceOf(ObjectId::class, $inserted->id); } public function testCount(): void @@ -143,8 +145,8 @@ public function testPrune(): void $this->assertEquals(3, $provider->count()); } - private function getProvider(): MongoFailedJobProvider + private function getProvider(): DatabaseFailedJobProvider { - return new MongoFailedJobProvider(DB::getFacadeRoot(), '', 'failed_jobs'); + return new DatabaseFailedJobProvider(DB::getFacadeRoot(), '', 'failed_jobs'); } } diff --git a/tests/QueueTest.php b/tests/QueueTest.php index 04a279640..e149b9ef4 100644 --- a/tests/QueueTest.php +++ b/tests/QueueTest.php @@ -6,12 +6,12 @@ use Carbon\Carbon; use Exception; +use Illuminate\Queue\Failed\DatabaseFailedJobProvider; use Illuminate\Support\Facades\Config; use Illuminate\Support\Facades\Queue; use Illuminate\Support\Str; use Mockery; use MongoDB\BSON\UTCDateTime; -use MongoDB\Laravel\Queue\Failed\MongoFailedJobProvider; use MongoDB\Laravel\Queue\MongoJob; use MongoDB\Laravel\Queue\MongoQueue; @@ -87,7 +87,7 @@ public function testFailQueueJob(): void { $provider = app('queue.failer'); - $this->assertInstanceOf(MongoFailedJobProvider::class, $provider); + $this->assertInstanceOf(DatabaseFailedJobProvider::class, $provider); } public function testFindFailJobNull(): void diff --git a/tests/TestCase.php b/tests/TestCase.php index 5f37ea170..2353915ed 100644 --- a/tests/TestCase.php +++ b/tests/TestCase.php @@ -7,7 +7,6 @@ use Illuminate\Auth\Passwords\PasswordResetServiceProvider as BasePasswordResetServiceProviderAlias; use Illuminate\Foundation\Application; use MongoDB\Laravel\Auth\PasswordResetServiceProvider; -use MongoDB\Laravel\MongoDBQueueServiceProvider; use MongoDB\Laravel\MongoDBServiceProvider; use MongoDB\Laravel\Tests\Models\User; use MongoDB\Laravel\Validation\ValidationServiceProvider; @@ -40,7 +39,6 @@ protected function getPackageProviders($app): array { return [ MongoDBServiceProvider::class, - MongoDBQueueServiceProvider::class, PasswordResetServiceProvider::class, ValidationServiceProvider::class, ]; From af4e73d9d22c19f8e3f8bf649613dff0217c1198 Mon Sep 17 00:00:00 2001 From: Jason Date: Tue, 3 Sep 2024 14:45:23 +0800 Subject: [PATCH 344/446] Remove MongoDBQueueServiceProvider in composer.json (#3131) Class "MongoDB\Laravel\MongoDBQueueServiceProvider" not found due to being removed in this commit https://github.com/mongodb/laravel-mongodb/commit/a0b613498b3d7148821566d7774c0655e8629bbe --- composer.json | 1 - 1 file changed, 1 deletion(-) diff --git a/composer.json b/composer.json index af060bb3c..251f3ad3c 100644 --- a/composer.json +++ b/composer.json @@ -68,7 +68,6 @@ "laravel": { "providers": [ "MongoDB\\Laravel\\MongoDBServiceProvider", - "MongoDB\\Laravel\\MongoDBQueueServiceProvider", "MongoDB\\Laravel\\MongoDBBusServiceProvider" ] } From 5b7ca02fb8fefb94390c782efb02d50f34a286b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 3 Sep 2024 14:19:02 +0200 Subject: [PATCH 345/446] Remove support for Laravel 10 (#3123) --- .github/workflows/build-ci.yml | 11 ++++------- .github/workflows/static-analysis.yml | 2 +- CHANGELOG.md | 1 + composer.json | 19 ++++++++----------- 4 files changed, 14 insertions(+), 19 deletions(-) diff --git a/.github/workflows/build-ci.yml b/.github/workflows/build-ci.yml index 45833d579..60d96f34f 100644 --- a/.github/workflows/build-ci.yml +++ b/.github/workflows/build-ci.yml @@ -20,15 +20,15 @@ jobs: - "6.0" - "7.0" php: - - "8.1" - "8.2" - "8.3" laravel: - - "10.*" - "11.*" + mode: + - "" include: - - php: "8.1" - laravel: "10.*" + - php: "8.2" + laravel: "11.*" mongodb: "5.0" mode: "low-deps" os: "ubuntu-latest" @@ -37,9 +37,6 @@ jobs: mongodb: "7.0" mode: "ignore-php-req" os: "ubuntu-latest" - exclude: - - php: "8.1" - laravel: "11.*" steps: - uses: "actions/checkout@v4" diff --git a/.github/workflows/static-analysis.yml b/.github/workflows/static-analysis.yml index 18ea2014e..331fe22d8 100644 --- a/.github/workflows/static-analysis.yml +++ b/.github/workflows/static-analysis.yml @@ -21,8 +21,8 @@ jobs: strategy: matrix: php: - - '8.1' - '8.2' + - '8.3' steps: - name: Checkout uses: actions/checkout@v4 diff --git a/CHANGELOG.md b/CHANGELOG.md index c34e9640f..297959410 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,7 @@ All notable changes to this project will be documented in this file. ## [5.0.0] - next +* Remove support for Laravel 10 by @GromNaN in [#3123](https://github.com/mongodb/laravel-mongodb/pull/3123) * **BREAKING CHANGE** Use `id` as an alias for `_id` in commands and queries for compatibility with Eloquent packages by @GromNaN in [#3040](https://github.com/mongodb/laravel-mongodb/pull/3040) * **BREAKING CHANGE** Make Query\Builder return objects instead of array to match Laravel behavior by @GromNaN in [#3107](https://github.com/mongodb/laravel-mongodb/pull/3107) * Remove `MongoFailedJobProvider`, replaced by Laravel `DatabaseFailedJobProvider` by @GromNaN in [#3122](https://github.com/mongodb/laravel-mongodb/pull/3122) diff --git a/composer.json b/composer.json index 251f3ad3c..e7d2f09cd 100644 --- a/composer.json +++ b/composer.json @@ -22,30 +22,27 @@ ], "license": "MIT", "require": { - "php": "^8.1", + "php": "^8.2", "ext-mongodb": "^1.15", "composer-runtime-api": "^2.0.0", - "illuminate/cache": "^10.36|^11", - "illuminate/container": "^10.0|^11", - "illuminate/database": "^10.30|^11", - "illuminate/events": "^10.0|^11", - "illuminate/support": "^10.0|^11", + "illuminate/cache": "^11", + "illuminate/container": "^11", + "illuminate/database": "^11", + "illuminate/events": "^11", + "illuminate/support": "^11", "mongodb/mongodb": "^1.15" }, "require-dev": { "mongodb/builder": "^0.2", "league/flysystem-gridfs": "^3.28", "league/flysystem-read-only": "^3.0", - "phpunit/phpunit": "^10.3", - "orchestra/testbench": "^8.0|^9.0", + "phpunit/phpunit": "^10.5", + "orchestra/testbench": "^9.0", "mockery/mockery": "^1.4.4", "doctrine/coding-standard": "12.0.x-dev", "spatie/laravel-query-builder": "^5.6", "phpstan/phpstan": "^1.10" }, - "conflict": { - "illuminate/bus": "< 10.37.2" - }, "suggest": { "league/flysystem-gridfs": "Filesystem storage in MongoDB with GridFS", "mongodb/builder": "Provides a fluent aggregation builder for MongoDB pipelines" From c710097f0d9e627e868dd32de0b7c04433633349 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 3 Sep 2024 23:35:13 +0200 Subject: [PATCH 346/446] PHPORM-234 Convert dates in DB Query results (#3119) Use the current timezone when reading an UTCDateTime --- CHANGELOG.md | 1 + src/Eloquent/DocumentModel.php | 22 ++++++++++++++++++---- src/Query/Builder.php | 13 +++++++++++-- tests/AuthTest.php | 4 ++-- tests/QueryBuilderTest.php | 23 ++++++++++++++--------- tests/QueueTest.php | 3 +-- 6 files changed, 47 insertions(+), 19 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 297959410..162bdd010 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ All notable changes to this project will be documented in this file. * Remove support for Laravel 10 by @GromNaN in [#3123](https://github.com/mongodb/laravel-mongodb/pull/3123) * **BREAKING CHANGE** Use `id` as an alias for `_id` in commands and queries for compatibility with Eloquent packages by @GromNaN in [#3040](https://github.com/mongodb/laravel-mongodb/pull/3040) * **BREAKING CHANGE** Make Query\Builder return objects instead of array to match Laravel behavior by @GromNaN in [#3107](https://github.com/mongodb/laravel-mongodb/pull/3107) +* **BREAKING CHANGE** In DB query results, convert BSON `UTCDateTime` objects into `Carbon` date with the default timezone by @GromNaN in [#3119](https://github.com/mongodb/laravel-mongodb/pull/3119) * Remove `MongoFailedJobProvider`, replaced by Laravel `DatabaseFailedJobProvider` by @GromNaN in [#3122](https://github.com/mongodb/laravel-mongodb/pull/3122) ## [4.8.0] - 2024-08-27 diff --git a/src/Eloquent/DocumentModel.php b/src/Eloquent/DocumentModel.php index fbbc69e49..930ed6286 100644 --- a/src/Eloquent/DocumentModel.php +++ b/src/Eloquent/DocumentModel.php @@ -5,12 +5,14 @@ namespace MongoDB\Laravel\Eloquent; use BackedEnum; +use Carbon\Carbon; use Carbon\CarbonInterface; use DateTimeInterface; use DateTimeZone; use Illuminate\Contracts\Queue\QueueableCollection; use Illuminate\Contracts\Queue\QueueableEntity; use Illuminate\Contracts\Support\Arrayable; +use Illuminate\Database\Eloquent\Concerns\HasAttributes; use Illuminate\Database\Eloquent\Model; use Illuminate\Database\Eloquent\Relations\Relation; use Illuminate\Support\Arr; @@ -97,8 +99,14 @@ public function getQualifiedKeyName() return $this->getKeyName(); } - /** @inheritdoc */ - public function fromDateTime($value) + /** + * Convert a DateTimeInterface (including Carbon) to a storable UTCDateTime. + * + * @see HasAttributes::fromDateTime() + * + * @param mixed $value + */ + public function fromDateTime($value): UTCDateTime { // If the value is already a UTCDateTime instance, we don't need to parse it. if ($value instanceof UTCDateTime) { @@ -113,8 +121,14 @@ public function fromDateTime($value) return new UTCDateTime($value); } - /** @inheritdoc */ - protected function asDateTime($value) + /** + * Return a timestamp as Carbon object. + * + * @see HasAttributes::asDateTime() + * + * @param mixed $value + */ + protected function asDateTime($value): Carbon { // Convert UTCDateTime instances to Carbon. if ($value instanceof UTCDateTime) { diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 486325029..f4f31b58f 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -9,11 +9,13 @@ use Carbon\CarbonPeriod; use Closure; use DateTimeInterface; +use DateTimeZone; use Illuminate\Database\Query\Builder as BaseBuilder; use Illuminate\Database\Query\Expression; use Illuminate\Support\Arr; use Illuminate\Support\Carbon; use Illuminate\Support\Collection; +use Illuminate\Support\Facades\Date; use Illuminate\Support\LazyCollection; use InvalidArgumentException; use LogicException; @@ -39,6 +41,7 @@ use function call_user_func_array; use function count; use function ctype_xdigit; +use function date_default_timezone_get; use function dd; use function dump; use function end; @@ -1660,7 +1663,10 @@ private function aliasIdForResult(array|object $values): array|object } foreach ($values as $key => $value) { - if (is_array($value) || is_object($value)) { + if ($value instanceof UTCDateTime) { + $values[$key] = Date::instance($value->toDateTime()) + ->setTimezone(new DateTimeZone(date_default_timezone_get())); + } elseif (is_array($value) || is_object($value)) { $values[$key] = $this->aliasIdForResult($value); } } @@ -1673,7 +1679,10 @@ private function aliasIdForResult(array|object $values): array|object } foreach (get_object_vars($values) as $key => $value) { - if (is_array($value) || is_object($value)) { + if ($value instanceof UTCDateTime) { + $values->{$key} = Date::instance($value->toDateTime()) + ->setTimezone(new DateTimeZone(date_default_timezone_get())); + } elseif (is_array($value) || is_object($value)) { $values->{$key} = $this->aliasIdForResult($value); } } diff --git a/tests/AuthTest.php b/tests/AuthTest.php index ffe3d46e9..98d42832e 100644 --- a/tests/AuthTest.php +++ b/tests/AuthTest.php @@ -4,11 +4,11 @@ namespace MongoDB\Laravel\Tests; +use Carbon\Carbon; use Illuminate\Auth\Passwords\PasswordBroker; use Illuminate\Support\Facades\Auth; use Illuminate\Support\Facades\DB; use Illuminate\Support\Facades\Hash; -use MongoDB\BSON\UTCDateTime; use MongoDB\Laravel\Tests\Models\User; use function bcrypt; @@ -63,7 +63,7 @@ function ($actualUser, $actualToken) use ($user, &$token) { $reminder = DB::table('password_reset_tokens')->first(); $this->assertEquals('john.doe@example.com', $reminder->email); $this->assertNotNull($reminder->token); - $this->assertInstanceOf(UTCDateTime::class, $reminder->created_at); + $this->assertInstanceOf(Carbon::class, $reminder->created_at); $credentials = [ 'email' => 'john.doe@example.com', diff --git a/tests/QueryBuilderTest.php b/tests/QueryBuilderTest.php index d34bb5241..846f48514 100644 --- a/tests/QueryBuilderTest.php +++ b/tests/QueryBuilderTest.php @@ -4,6 +4,7 @@ namespace MongoDB\Laravel\Tests; +use Carbon\Carbon; use DateTime; use DateTimeImmutable; use Illuminate\Support\Facades\Date; @@ -33,7 +34,6 @@ use function md5; use function sort; use function strlen; -use function strtotime; class QueryBuilderTest extends TestCase { @@ -676,27 +676,32 @@ public function testUpdateSubdocument() public function testDates() { DB::table('users')->insert([ - ['name' => 'John Doe', 'birthday' => new UTCDateTime(Date::parse('1980-01-01 00:00:00'))], - ['name' => 'Robert Roe', 'birthday' => new UTCDateTime(Date::parse('1982-01-01 00:00:00'))], - ['name' => 'Mark Moe', 'birthday' => new UTCDateTime(Date::parse('1983-01-01 00:00:00.1'))], - ['name' => 'Frank White', 'birthday' => new UTCDateTime(Date::parse('1960-01-01 12:12:12.1'))], + ['name' => 'John Doe', 'birthday' => Date::parse('1980-01-01 00:00:00')], + ['name' => 'Robert Roe', 'birthday' => Date::parse('1982-01-01 00:00:00')], + ['name' => 'Mark Moe', 'birthday' => Date::parse('1983-01-01 00:00:00.1')], + ['name' => 'Frank White', 'birthday' => Date::parse('1975-01-01 12:12:12.1')], ]); $user = DB::table('users') - ->where('birthday', new UTCDateTime(Date::parse('1980-01-01 00:00:00'))) + ->where('birthday', Date::parse('1980-01-01 00:00:00')) ->first(); $this->assertEquals('John Doe', $user->name); $user = DB::table('users') - ->where('birthday', new UTCDateTime(Date::parse('1960-01-01 12:12:12.1'))) + ->where('birthday', Date::parse('1975-01-01 12:12:12.1')) ->first(); + $this->assertEquals('Frank White', $user->name); + $this->assertInstanceOf(Carbon::class, $user->birthday); + $this->assertSame('1975-01-01 12:12:12.100000', $user->birthday->format('Y-m-d H:i:s.u')); $user = DB::table('users')->where('birthday', '=', new DateTime('1980-01-01 00:00:00'))->first(); $this->assertEquals('John Doe', $user->name); + $this->assertInstanceOf(Carbon::class, $user->birthday); + $this->assertSame('1980-01-01 00:00:00.000000', $user->birthday->format('Y-m-d H:i:s.u')); - $start = new UTCDateTime(1000 * strtotime('1950-01-01 00:00:00')); - $stop = new UTCDateTime(1000 * strtotime('1981-01-01 00:00:00')); + $start = new UTCDateTime(new DateTime('1950-01-01 00:00:00')); + $stop = new UTCDateTime(new DateTime('1981-01-01 00:00:00')); $users = DB::table('users')->whereBetween('birthday', [$start, $stop])->get(); $this->assertCount(2, $users); diff --git a/tests/QueueTest.php b/tests/QueueTest.php index e149b9ef4..efc8f07ff 100644 --- a/tests/QueueTest.php +++ b/tests/QueueTest.php @@ -11,7 +11,6 @@ use Illuminate\Support\Facades\Queue; use Illuminate\Support\Str; use Mockery; -use MongoDB\BSON\UTCDateTime; use MongoDB\Laravel\Queue\MongoJob; use MongoDB\Laravel\Queue\MongoQueue; @@ -197,7 +196,7 @@ public function testFailedJobLogging() $this->assertSame('test_connection', $failedJob->connection); $this->assertSame('test_queue', $failedJob->queue); $this->assertSame('test_payload', $failedJob->payload); - $this->assertEquals(new UTCDateTime(Carbon::now()), $failedJob->failed_at); + $this->assertEquals(Carbon::now(), $failedJob->failed_at); $this->assertStringStartsWith('Exception: test_exception in ', $failedJob->exception); } } From 5f0682fe1180af71f2ad57d97e35d37330267f96 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 4 Sep 2024 10:08:36 +0200 Subject: [PATCH 347/446] PHPORM-157 Remove Blueprint::background() (#3132) --- CHANGELOG.md | 1 + src/Schema/Blueprint.php | 16 ---------------- tests/SchemaTest.php | 10 ---------- 3 files changed, 1 insertion(+), 26 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 162bdd010..534250191 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ All notable changes to this project will be documented in this file. * **BREAKING CHANGE** Make Query\Builder return objects instead of array to match Laravel behavior by @GromNaN in [#3107](https://github.com/mongodb/laravel-mongodb/pull/3107) * **BREAKING CHANGE** In DB query results, convert BSON `UTCDateTime` objects into `Carbon` date with the default timezone by @GromNaN in [#3119](https://github.com/mongodb/laravel-mongodb/pull/3119) * Remove `MongoFailedJobProvider`, replaced by Laravel `DatabaseFailedJobProvider` by @GromNaN in [#3122](https://github.com/mongodb/laravel-mongodb/pull/3122) +* Remove `Blueprint::background()` method by @GromNaN in [#3132](https://github.com/mongodb/laravel-mongodb/pull/3132) ## [4.8.0] - 2024-08-27 diff --git a/src/Schema/Blueprint.php b/src/Schema/Blueprint.php index 52a5762f5..0ad4535cf 100644 --- a/src/Schema/Blueprint.php +++ b/src/Schema/Blueprint.php @@ -177,22 +177,6 @@ public function unique($columns = null, $name = null, $algorithm = null, $option return $this; } - /** - * Specify a non blocking index for the collection. - * - * @param string|array $columns - * - * @return Blueprint - */ - public function background($columns = null) - { - $columns = $this->fluent($columns); - - $this->index($columns, null, null, ['background' => true]); - - return $this; - } - /** * Specify a sparse index for the collection. * diff --git a/tests/SchemaTest.php b/tests/SchemaTest.php index 82d4a68c6..0f04ab6d4 100644 --- a/tests/SchemaTest.php +++ b/tests/SchemaTest.php @@ -245,16 +245,6 @@ public function testHasIndex(): void }); } - public function testBackground(): void - { - Schema::table('newcollection', function ($collection) { - $collection->background('backgroundkey'); - }); - - $index = $this->getIndex('newcollection', 'backgroundkey'); - $this->assertEquals(1, $index['background']); - } - public function testSparse(): void { Schema::table('newcollection', function ($collection) { From 7551f76b41e70e4883c3005cb557288a1f2a2ff4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 4 Sep 2024 10:11:34 +0200 Subject: [PATCH 348/446] PHPORM-235 Remove custom DatabaseTokenRepository (#3124) --- CHANGELOG.md | 1 + src/Auth/DatabaseTokenRepository.php | 59 ----------------------- src/Auth/PasswordBrokerManager.php | 23 --------- src/Auth/PasswordResetServiceProvider.php | 22 --------- tests/TestCase.php | 19 -------- 5 files changed, 1 insertion(+), 123 deletions(-) delete mode 100644 src/Auth/DatabaseTokenRepository.php delete mode 100644 src/Auth/PasswordBrokerManager.php delete mode 100644 src/Auth/PasswordResetServiceProvider.php diff --git a/CHANGELOG.md b/CHANGELOG.md index 534250191..0f53f4c22 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ All notable changes to this project will be documented in this file. * **BREAKING CHANGE** Make Query\Builder return objects instead of array to match Laravel behavior by @GromNaN in [#3107](https://github.com/mongodb/laravel-mongodb/pull/3107) * **BREAKING CHANGE** In DB query results, convert BSON `UTCDateTime` objects into `Carbon` date with the default timezone by @GromNaN in [#3119](https://github.com/mongodb/laravel-mongodb/pull/3119) * Remove `MongoFailedJobProvider`, replaced by Laravel `DatabaseFailedJobProvider` by @GromNaN in [#3122](https://github.com/mongodb/laravel-mongodb/pull/3122) +* Remove custom `PasswordResetServiceProvider`, use the default `DatabaseTokenRepository` by @GromNaN in [#3124](https://github.com/mongodb/laravel-mongodb/pull/3124) * Remove `Blueprint::background()` method by @GromNaN in [#3132](https://github.com/mongodb/laravel-mongodb/pull/3132) ## [4.8.0] - 2024-08-27 diff --git a/src/Auth/DatabaseTokenRepository.php b/src/Auth/DatabaseTokenRepository.php deleted file mode 100644 index 83ce9bf6d..000000000 --- a/src/Auth/DatabaseTokenRepository.php +++ /dev/null @@ -1,59 +0,0 @@ - $email, - 'token' => $this->hasher->make($token), - 'created_at' => new UTCDateTime(Date::now()), - ]; - } - - /** @inheritdoc */ - protected function tokenExpired($createdAt) - { - $createdAt = $this->convertDateTime($createdAt); - - return parent::tokenExpired($createdAt); - } - - /** @inheritdoc */ - protected function tokenRecentlyCreated($createdAt) - { - $createdAt = $this->convertDateTime($createdAt); - - return parent::tokenRecentlyCreated($createdAt); - } - - private function convertDateTime($createdAt) - { - // Convert UTCDateTime to a date string. - if ($createdAt instanceof UTCDateTime) { - $date = $createdAt->toDateTime(); - $date->setTimezone(new DateTimeZone(date_default_timezone_get())); - $createdAt = $date->format('Y-m-d H:i:s'); - } elseif (is_array($createdAt) && isset($createdAt['date'])) { - $date = new DateTime($createdAt['date'], new DateTimeZone($createdAt['timezone'] ?? 'UTC')); - $date->setTimezone(new DateTimeZone(date_default_timezone_get())); - $createdAt = $date->format('Y-m-d H:i:s'); - } - - return $createdAt; - } -} diff --git a/src/Auth/PasswordBrokerManager.php b/src/Auth/PasswordBrokerManager.php deleted file mode 100644 index 157df3d97..000000000 --- a/src/Auth/PasswordBrokerManager.php +++ /dev/null @@ -1,23 +0,0 @@ -app['db']->connection(), - $this->app['hash'], - $config['table'], - $this->app['config']['app.key'], - $config['expire'], - $config['throttle'] ?? 0, - ); - } -} diff --git a/src/Auth/PasswordResetServiceProvider.php b/src/Auth/PasswordResetServiceProvider.php deleted file mode 100644 index a8aa61da4..000000000 --- a/src/Auth/PasswordResetServiceProvider.php +++ /dev/null @@ -1,22 +0,0 @@ -app->singleton('auth.password', function ($app) { - return new PasswordBrokerManager($app); - }); - - $this->app->bind('auth.password.broker', function ($app) { - return $app->make('auth.password')->broker(); - }); - } -} diff --git a/tests/TestCase.php b/tests/TestCase.php index 2353915ed..5f5bbecdc 100644 --- a/tests/TestCase.php +++ b/tests/TestCase.php @@ -4,32 +4,14 @@ namespace MongoDB\Laravel\Tests; -use Illuminate\Auth\Passwords\PasswordResetServiceProvider as BasePasswordResetServiceProviderAlias; use Illuminate\Foundation\Application; -use MongoDB\Laravel\Auth\PasswordResetServiceProvider; use MongoDB\Laravel\MongoDBServiceProvider; use MongoDB\Laravel\Tests\Models\User; use MongoDB\Laravel\Validation\ValidationServiceProvider; use Orchestra\Testbench\TestCase as OrchestraTestCase; -use function array_search; - class TestCase extends OrchestraTestCase { - /** - * Get application providers. - * - * @param Application $app - */ - protected function getApplicationProviders($app): array - { - $providers = parent::getApplicationProviders($app); - - unset($providers[array_search(BasePasswordResetServiceProviderAlias::class, $providers)]); - - return $providers; - } - /** * Get package providers. * @@ -39,7 +21,6 @@ protected function getPackageProviders($app): array { return [ MongoDBServiceProvider::class, - PasswordResetServiceProvider::class, ValidationServiceProvider::class, ]; } From 807f5fa587ea68ce38e2bc29fd32b0c807f46625 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Thu, 5 Sep 2024 12:55:54 -0400 Subject: [PATCH 349/446] DOCSP-43158: carbon date values db query results (#3133) * DOCSP-43158: carbon date values db query results * add to upgrade guide * wip --- docs/eloquent-models/model-class.txt | 11 +++++++++-- docs/query-builder.txt | 7 +++++++ docs/upgrade.txt | 15 ++++++++++++++- 3 files changed, 30 insertions(+), 3 deletions(-) diff --git a/docs/eloquent-models/model-class.txt b/docs/eloquent-models/model-class.txt index 8cedb4ece..4e699309a 100644 --- a/docs/eloquent-models/model-class.txt +++ b/docs/eloquent-models/model-class.txt @@ -216,8 +216,8 @@ type, to the Laravel ``datetime`` type. To learn more, see `Attribute Casting `__ in the Laravel documentation. -This conversion lets you use the PHP `DateTime `__ -or the `Carbon class `__ to work with dates +This conversion lets you use the PHP `DateTime +`__ class to work with dates in this field. The following example shows a Laravel query that uses the casting helper on the model to query for planets with a ``discovery_dt`` of less than three years ago: @@ -226,6 +226,13 @@ less than three years ago: Planet::where( 'discovery_dt', '>', new DateTime('-3 years'))->get(); +.. note:: Carbon Date Class + + Starting in {+odm-long+} v5.0, ``UTCDateTime`` BSON values in MongoDB + are returned as `Carbon `__ date + classes in query results. The {+odm-short+} applies the default + timezone when performing this conversion. + To learn more about MongoDB's data types, see :manual:`BSON Types ` in the Server manual. diff --git a/docs/query-builder.txt b/docs/query-builder.txt index 7d33c016d..c3a219aa8 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -346,6 +346,13 @@ query builder method to retrieve documents from the :start-after: begin query whereDate :end-before: end query whereDate +.. note:: Date Query Result Type + + Starting in {+odm-long+} v5.0, ``UTCDateTime`` BSON values in MongoDB + are returned as `Carbon `__ date + classes in query results. The {+odm-short+} applies the default + timezone when performing this conversion. + .. _laravel-query-builder-pattern: Text Pattern Match Example diff --git a/docs/upgrade.txt b/docs/upgrade.txt index 5d8ca09a3..301a2100e 100644 --- a/docs/upgrade.txt +++ b/docs/upgrade.txt @@ -22,7 +22,7 @@ Overview On this page, you can learn how to upgrade {+odm-long+} to a new major version. This page also includes the changes you must make to your application to upgrade -your object-document mapper (ODM) version without losing functionality, if applicable. +your version of the {+odm-short+} without losing functionality, if applicable. How to Upgrade -------------- @@ -61,6 +61,19 @@ version releases that introduced them. When upgrading library versions, address all the breaking changes between your current version and the planned upgrade version. +- :ref:`laravel-breaking-changes-v5.x` +- :ref:`laravel-breaking-changes-v4.x` + +.. _laravel-breaking-changes-v5.x: + +Version 5.x Breaking Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This library version introduces the following breaking changes: + +- In query results, the library converts BSON ``UTCDateTime`` objects to ``Carbon`` + date classes, applying the default timezone. + .. _laravel-breaking-changes-v4.x: Version 4.x Breaking Changes From 837078f8660c4d2846e94f43b26c431741703b89 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Thu, 5 Sep 2024 19:54:40 +0200 Subject: [PATCH 350/446] PHPORM-236 Remove _id from query results (#3136) --- CHANGELOG.md | 2 +- docs/includes/usage-examples/FindOneTest.php | 2 +- src/Query/Builder.php | 8 ++++---- tests/QueryBuilderTest.php | 20 +++++++++++++++++-- .../Failed/DatabaseFailedJobProviderTest.php | 8 +++++--- 5 files changed, 29 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0f53f4c22..7a175e414 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,7 @@ All notable changes to this project will be documented in this file. ## [5.0.0] - next * Remove support for Laravel 10 by @GromNaN in [#3123](https://github.com/mongodb/laravel-mongodb/pull/3123) -* **BREAKING CHANGE** Use `id` as an alias for `_id` in commands and queries for compatibility with Eloquent packages by @GromNaN in [#3040](https://github.com/mongodb/laravel-mongodb/pull/3040) +* **BREAKING CHANGE** Use `id` as an alias for `_id` in commands and queries for compatibility with Eloquent packages by @GromNaN in [#3040](https://github.com/mongodb/laravel-mongodb/pull/3040) and [#3136](https://github.com/mongodb/laravel-mongodb/pull/3136) * **BREAKING CHANGE** Make Query\Builder return objects instead of array to match Laravel behavior by @GromNaN in [#3107](https://github.com/mongodb/laravel-mongodb/pull/3107) * **BREAKING CHANGE** In DB query results, convert BSON `UTCDateTime` objects into `Carbon` date with the default timezone by @GromNaN in [#3119](https://github.com/mongodb/laravel-mongodb/pull/3119) * Remove `MongoFailedJobProvider`, replaced by Laravel `DatabaseFailedJobProvider` by @GromNaN in [#3122](https://github.com/mongodb/laravel-mongodb/pull/3122) diff --git a/docs/includes/usage-examples/FindOneTest.php b/docs/includes/usage-examples/FindOneTest.php index 8472727be..e46ba1be4 100644 --- a/docs/includes/usage-examples/FindOneTest.php +++ b/docs/includes/usage-examples/FindOneTest.php @@ -31,6 +31,6 @@ public function testFindOne(): void // end-find-one $this->assertInstanceOf(Movie::class, $movie); - $this->expectOutputRegex('/^{"_id":"[a-z0-9]{24}","title":"The Shawshank Redemption","directors":\["Frank Darabont","Rob Reiner"\],"id":"[a-z0-9]{24}"}$/'); + $this->expectOutputRegex('/^{"title":"The Shawshank Redemption","directors":\["Frank Darabont","Rob Reiner"\],"id":"[a-z0-9]{24}"}$/'); } } diff --git a/src/Query/Builder.php b/src/Query/Builder.php index f4f31b58f..e2f8867b3 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -1616,7 +1616,7 @@ public function orWhereIntegerNotInRaw($column, $values, $boolean = 'and') private function aliasIdForQuery(array $values): array { if (array_key_exists('id', $values)) { - if (array_key_exists('_id', $values)) { + if (array_key_exists('_id', $values) && $values['id'] !== $values['_id']) { throw new InvalidArgumentException('Cannot have both "id" and "_id" fields.'); } @@ -1627,7 +1627,7 @@ private function aliasIdForQuery(array $values): array foreach ($values as $key => $value) { if (is_string($key) && str_ends_with($key, '.id')) { $newkey = substr($key, 0, -3) . '._id'; - if (array_key_exists($newkey, $values)) { + if (array_key_exists($newkey, $values) && $value !== $values[$newkey]) { throw new InvalidArgumentException(sprintf('Cannot have both "%s" and "%s" fields.', $key, $newkey)); } @@ -1659,7 +1659,7 @@ private function aliasIdForResult(array|object $values): array|object if (is_array($values)) { if (array_key_exists('_id', $values) && ! array_key_exists('id', $values)) { $values['id'] = $values['_id']; - //unset($values['_id']); + unset($values['_id']); } foreach ($values as $key => $value) { @@ -1675,7 +1675,7 @@ private function aliasIdForResult(array|object $values): array|object if ($values instanceof stdClass) { if (property_exists($values, '_id') && ! property_exists($values, 'id')) { $values->id = $values->_id; - //unset($values->_id); + unset($values->_id); } foreach (get_object_vars($values) as $key => $value) { diff --git a/tests/QueryBuilderTest.php b/tests/QueryBuilderTest.php index 846f48514..910adecfc 100644 --- a/tests/QueryBuilderTest.php +++ b/tests/QueryBuilderTest.php @@ -449,18 +449,33 @@ public function testDistinct() public function testCustomId() { + $tags = [['id' => 'sharp', 'name' => 'Sharp']]; DB::table('items')->insert([ - ['id' => 'knife', 'type' => 'sharp', 'amount' => 34], - ['id' => 'fork', 'type' => 'sharp', 'amount' => 20], + ['id' => 'knife', 'type' => 'sharp', 'amount' => 34, 'tags' => $tags], + ['id' => 'fork', 'type' => 'sharp', 'amount' => 20, 'tags' => $tags], ['id' => 'spoon', 'type' => 'round', 'amount' => 3], ]); $item = DB::table('items')->find('knife'); $this->assertEquals('knife', $item->id); + $this->assertObjectNotHasProperty('_id', $item); + $this->assertEquals('sharp', $item->tags[0]['id']); + $this->assertArrayNotHasKey('_id', $item->tags[0]); $item = DB::table('items')->where('id', 'fork')->first(); $this->assertEquals('fork', $item->id); + $item = DB::table('items')->where('_id', 'fork')->first(); + $this->assertEquals('fork', $item->id); + + // tags.id is translated into tags._id in query + $items = DB::table('items')->whereIn('tags.id', ['sharp'])->get(); + $this->assertCount(2, $items); + + // Ensure the field _id is stored in the database + $items = DB::table('items')->whereIn('tags._id', ['sharp'])->get(); + $this->assertCount(2, $items); + DB::table('users')->insert([ ['id' => 1, 'name' => 'Jane Doe'], ['id' => 2, 'name' => 'John Doe'], @@ -468,6 +483,7 @@ public function testCustomId() $item = DB::table('users')->find(1); $this->assertEquals(1, $item->id); + $this->assertObjectNotHasProperty('_id', $item); } public function testTake() diff --git a/tests/Queue/Failed/DatabaseFailedJobProviderTest.php b/tests/Queue/Failed/DatabaseFailedJobProviderTest.php index 88a7f0e7b..01f38b9df 100644 --- a/tests/Queue/Failed/DatabaseFailedJobProviderTest.php +++ b/tests/Queue/Failed/DatabaseFailedJobProviderTest.php @@ -77,8 +77,9 @@ public function testAll(): void $all = $this->getProvider()->all(); $this->assertCount(5, $all); - $this->assertEquals(new ObjectId(sprintf('%024d', 5)), $all[0]->_id); - $this->assertEquals(sprintf('%024d', 5), $all[0]->id, 'id field is added for compatibility with DatabaseFailedJobProvider'); + $this->assertInstanceOf(ObjectId::class, $all[0]->id); + $this->assertEquals(new ObjectId(sprintf('%024d', 5)), $all[0]->id); + $this->assertEquals(sprintf('%024d', 5), (string) $all[0]->id, 'id field is added for compatibility with DatabaseFailedJobProvider'); } public function testFindAndForget(): void @@ -89,7 +90,8 @@ public function testFindAndForget(): void $found = $provider->find($id); $this->assertIsObject($found, 'The job is found'); - $this->assertEquals(new ObjectId($id), $found->_id); + $this->assertInstanceOf(ObjectId::class, $found->id); + $this->assertEquals(new ObjectId($id), $found->id); $this->assertObjectHasProperty('failed_at', $found); // Delete the job From e4248611f148d6ff706e331042edf5a33d313acb Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Thu, 5 Sep 2024 15:13:31 -0400 Subject: [PATCH 351/446] DOCSP-41335: Id field alias (#3042) Adds information and an example of the ID field alias. --------- Co-authored-by: norareidy Co-authored-by: rustagir --- docs/eloquent-models/model-class.txt | 8 ++------ .../includes/query-builder/QueryBuilderTest.php | 3 ++- docs/query-builder.txt | 17 +++++++++++++++-- docs/upgrade.txt | 5 +++++ 4 files changed, 24 insertions(+), 9 deletions(-) diff --git a/docs/eloquent-models/model-class.txt b/docs/eloquent-models/model-class.txt index 4e699309a..4f81f4663 100644 --- a/docs/eloquent-models/model-class.txt +++ b/docs/eloquent-models/model-class.txt @@ -302,12 +302,8 @@ including this trait, you can make the third-party class compatible with MongoDB. When you apply the ``DocumentModel`` trait to a model class, you must -declare the following properties in your class: - -- ``$primaryKey = '_id'``, because the ``_id`` field uniquely - identifies MongoDB documents -- ``$keyType = 'string'``, because the {+odm-short+} casts MongoDB - ``ObjectId`` values to type ``string`` +set the ``$keyType`` property to ``'string'`` as the {+odm-short+} +casts MongoDB ``ObjectId`` values to type ``string``. Extended Class Example ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index bf92b9a6b..5105e59b5 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -7,6 +7,7 @@ use Illuminate\Database\Query\Builder; use Illuminate\Pagination\AbstractPaginator; use Illuminate\Support\Facades\DB; +use MongoDB\BSON\ObjectId; use MongoDB\BSON\Regex; use MongoDB\Laravel\Collection; use MongoDB\Laravel\Tests\TestCase; @@ -63,7 +64,7 @@ public function testOrWhere(): void // begin query orWhere $result = DB::connection('mongodb') ->table('movies') - ->where('year', 1955) + ->where('id', new ObjectId('573a1398f29313caabce9682')) ->orWhere('title', 'Back to the Future') ->get(); // end query orWhere diff --git a/docs/query-builder.txt b/docs/query-builder.txt index c3a219aa8..9b1fe65f9 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -176,8 +176,9 @@ Logical OR Example The following example shows how to chain the ``orWhere()`` query builder method to retrieve documents from the -``movies`` collection that either match the ``year`` -value of ``1955`` or match the ``title`` value ``"Back to the Future"``: +``movies`` collection in which the value of the ``_id`` +field is ``ObjectId('573a1398f29313caabce9682')`` or +the value of the ``title`` field is ``"Back to the Future"``: .. literalinclude:: /includes/query-builder/QueryBuilderTest.php :language: php @@ -185,6 +186,18 @@ value of ``1955`` or match the ``title`` value ``"Back to the Future"``: :start-after: begin query orWhere :end-before: end query orWhere +.. note:: + + You can use the ``id`` alias in your queries to represent the + ``_id`` field in MongoDB documents, as shown in the preceding + code. When you run a find operation using the query builder, {+odm-short+} + automatically converts between ``id`` and ``_id``. This provides better + compatibility with Laravel, as the framework assumes that each record has a + primary key named ``id`` by default. + + Because of this behavior, you cannot have two separate ``id`` and ``_id`` + fields in your documents. + .. _laravel-query-builder-logical-and: Logical AND Example diff --git a/docs/upgrade.txt b/docs/upgrade.txt index 301a2100e..fed27d862 100644 --- a/docs/upgrade.txt +++ b/docs/upgrade.txt @@ -74,6 +74,11 @@ This library version introduces the following breaking changes: - In query results, the library converts BSON ``UTCDateTime`` objects to ``Carbon`` date classes, applying the default timezone. +- ``id`` is an alias for the ``_id`` field in MongoDB documents, and the library + automatically converts between ``id`` and ``_id`` when querying data. Because + of this behavior, you cannot have two separate ``id`` and ``_id`` fields in your + documents. + .. _laravel-breaking-changes-v4.x: Version 4.x Breaking Changes From 74f219c60382ea85eac6cdae54c313a386763c38 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Fri, 6 Sep 2024 14:35:22 +0200 Subject: [PATCH 352/446] PHPORM-56 Replace Collection proxy class with Driver monitoring (#3137) --- CHANGELOG.md | 1 + composer.json | 2 +- .../query-builder/QueryBuilderTest.php | 2 +- src/Bus/MongoBatchRepository.php | 2 +- src/Cache/MongoLock.php | 2 +- src/Cache/MongoStore.php | 2 +- src/Collection.php | 80 ------------------- src/CommandSubscriber.php | 53 ++++++++++++ src/Connection.php | 17 ++-- src/Query/AggregationBuilder.php | 5 +- src/Query/Builder.php | 2 +- src/Schema/Blueprint.php | 8 +- tests/Cache/MongoLockTest.php | 2 +- tests/Casts/DecimalTest.php | 2 +- tests/CollectionTest.php | 36 --------- tests/ConnectionTest.php | 25 ++++-- tests/ModelTest.php | 2 +- tests/QueryBuilderTest.php | 2 +- 18 files changed, 97 insertions(+), 148 deletions(-) delete mode 100644 src/Collection.php create mode 100644 src/CommandSubscriber.php delete mode 100644 tests/CollectionTest.php diff --git a/CHANGELOG.md b/CHANGELOG.md index 7a175e414..fdedba537 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ All notable changes to this project will be documented in this file. * Remove `MongoFailedJobProvider`, replaced by Laravel `DatabaseFailedJobProvider` by @GromNaN in [#3122](https://github.com/mongodb/laravel-mongodb/pull/3122) * Remove custom `PasswordResetServiceProvider`, use the default `DatabaseTokenRepository` by @GromNaN in [#3124](https://github.com/mongodb/laravel-mongodb/pull/3124) * Remove `Blueprint::background()` method by @GromNaN in [#3132](https://github.com/mongodb/laravel-mongodb/pull/3132) +* Replace `Collection` proxy class with Driver monitoring by @GromNaN in [#3137]((https://github.com/mongodb/laravel-mongodb/pull/3137) ## [4.8.0] - 2024-08-27 diff --git a/composer.json b/composer.json index e7d2f09cd..f03fdc89d 100644 --- a/composer.json +++ b/composer.json @@ -30,7 +30,7 @@ "illuminate/database": "^11", "illuminate/events": "^11", "illuminate/support": "^11", - "mongodb/mongodb": "^1.15" + "mongodb/mongodb": "^1.18" }, "require-dev": { "mongodb/builder": "^0.2", diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index 5105e59b5..02d15cc48 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -9,7 +9,7 @@ use Illuminate\Support\Facades\DB; use MongoDB\BSON\ObjectId; use MongoDB\BSON\Regex; -use MongoDB\Laravel\Collection; +use MongoDB\Collection; use MongoDB\Laravel\Tests\TestCase; use function file_get_contents; diff --git a/src/Bus/MongoBatchRepository.php b/src/Bus/MongoBatchRepository.php index dd0713f97..c6314ba69 100644 --- a/src/Bus/MongoBatchRepository.php +++ b/src/Bus/MongoBatchRepository.php @@ -14,8 +14,8 @@ use Illuminate\Support\Carbon; use MongoDB\BSON\ObjectId; use MongoDB\BSON\UTCDateTime; +use MongoDB\Collection; use MongoDB\Driver\ReadPreference; -use MongoDB\Laravel\Collection; use MongoDB\Laravel\Connection; use MongoDB\Operation\FindOneAndUpdate; use Override; diff --git a/src/Cache/MongoLock.php b/src/Cache/MongoLock.php index e9bd3d607..d273b4d99 100644 --- a/src/Cache/MongoLock.php +++ b/src/Cache/MongoLock.php @@ -6,7 +6,7 @@ use Illuminate\Support\Carbon; use InvalidArgumentException; use MongoDB\BSON\UTCDateTime; -use MongoDB\Laravel\Collection; +use MongoDB\Collection; use MongoDB\Operation\FindOneAndUpdate; use Override; diff --git a/src/Cache/MongoStore.php b/src/Cache/MongoStore.php index e35d0f70d..e37884a93 100644 --- a/src/Cache/MongoStore.php +++ b/src/Cache/MongoStore.php @@ -7,7 +7,7 @@ use Illuminate\Contracts\Cache\Store; use Illuminate\Support\Carbon; use MongoDB\BSON\UTCDateTime; -use MongoDB\Laravel\Collection; +use MongoDB\Collection; use MongoDB\Laravel\Connection; use MongoDB\Operation\FindOneAndUpdate; use Override; diff --git a/src/Collection.php b/src/Collection.php deleted file mode 100644 index 22c0dfa05..000000000 --- a/src/Collection.php +++ /dev/null @@ -1,80 +0,0 @@ -connection = $connection; - $this->collection = $collection; - } - - /** - * Handle dynamic method calls. - * - * @return mixed - */ - public function __call(string $method, array $parameters) - { - $start = microtime(true); - $result = $this->collection->$method(...$parameters); - - // Once we have run the query we will calculate the time that it took to run and - // then log the query, bindings, and execution time so we will report them on - // the event that the developer needs them. We'll log time in milliseconds. - $time = $this->connection->getElapsedTime($start); - - $query = []; - - // Convert the query parameters to a json string. - array_walk_recursive($parameters, function (&$item, $key) { - if ($item instanceof ObjectID) { - $item = (string) $item; - } - }); - - // Convert the query parameters to a json string. - foreach ($parameters as $parameter) { - try { - $query[] = json_encode($parameter, JSON_THROW_ON_ERROR); - } catch (Exception) { - $query[] = '{...}'; - } - } - - $queryString = $this->collection->getCollectionName() . '.' . $method . '(' . implode(',', $query) . ')'; - - $this->connection->logQuery($queryString, [], $time); - - return $result; - } -} diff --git a/src/CommandSubscriber.php b/src/CommandSubscriber.php new file mode 100644 index 000000000..ef282bcac --- /dev/null +++ b/src/CommandSubscriber.php @@ -0,0 +1,53 @@ + */ + private array $commands = []; + + public function __construct(private Connection $connection) + { + } + + public function commandStarted(CommandStartedEvent $event) + { + $this->commands[$event->getOperationId()] = $event; + } + + public function commandFailed(CommandFailedEvent $event) + { + $this->logQuery($event); + } + + public function commandSucceeded(CommandSucceededEvent $event) + { + $this->logQuery($event); + } + + private function logQuery(CommandSucceededEvent|CommandFailedEvent $event): void + { + $startedEvent = $this->commands[$event->getOperationId()]; + unset($this->commands[$event->getOperationId()]); + + $command = []; + foreach (get_object_vars($startedEvent->getCommand()) as $key => $value) { + if ($key[0] !== '$' && ! in_array($key, ['lsid', 'txnNumber'])) { + $command[$key] = $value; + } + } + + $this->connection->logQuery(Document::fromPHP($command)->toCanonicalExtendedJSON(), [], $event->getDurationMicros()); + } +} diff --git a/src/Connection.php b/src/Connection.php index cb2bc78de..a76ddc010 100644 --- a/src/Connection.php +++ b/src/Connection.php @@ -8,6 +8,7 @@ use Illuminate\Database\Connection as BaseConnection; use InvalidArgumentException; use MongoDB\Client; +use MongoDB\Collection; use MongoDB\Database; use MongoDB\Driver\Exception\AuthenticationException; use MongoDB\Driver\Exception\ConnectionException; @@ -47,6 +48,8 @@ class Connection extends BaseConnection */ protected $connection; + private ?CommandSubscriber $commandSubscriber; + /** * Create a new database connection instance. */ @@ -62,6 +65,8 @@ public function __construct(array $config) // Create the connection $this->connection = $this->createConnection($dsn, $config, $options); + $this->commandSubscriber = new CommandSubscriber($this); + $this->connection->addSubscriber($this->commandSubscriber); // Select database $this->db = $this->connection->selectDatabase($this->getDefaultDatabaseName($dsn, $config)); @@ -97,9 +102,9 @@ public function table($table, $as = null) * * @return Collection */ - public function getCollection($name) + public function getCollection($name): Collection { - return new Collection($this, $this->db->selectCollection($this->tablePrefix . $name)); + return $this->db->selectCollection($this->tablePrefix . $name); } /** @inheritdoc */ @@ -198,6 +203,8 @@ public function ping(): void /** @inheritdoc */ public function disconnect() { + $this->connection?->removeSubscriber($this->commandSubscriber); + $this->commandSubscriber = null; $this->connection = null; } @@ -264,12 +271,6 @@ protected function getDsn(array $config): string throw new InvalidArgumentException('MongoDB connection configuration requires "dsn" or "host" key.'); } - /** @inheritdoc */ - public function getElapsedTime($start) - { - return parent::getElapsedTime($start); - } - /** @inheritdoc */ public function getDriverName() { diff --git a/src/Query/AggregationBuilder.php b/src/Query/AggregationBuilder.php index ad0c195d4..0d4638731 100644 --- a/src/Query/AggregationBuilder.php +++ b/src/Query/AggregationBuilder.php @@ -10,9 +10,8 @@ use Iterator; use MongoDB\Builder\BuilderEncoder; use MongoDB\Builder\Stage\FluentFactoryTrait; -use MongoDB\Collection as MongoDBCollection; +use MongoDB\Collection; use MongoDB\Driver\CursorInterface; -use MongoDB\Laravel\Collection as LaravelMongoDBCollection; use function array_replace; use function collect; @@ -24,7 +23,7 @@ class AggregationBuilder use FluentFactoryTrait; public function __construct( - private MongoDBCollection|LaravelMongoDBCollection $collection, + private Collection $collection, private readonly array $options = [], ) { } diff --git a/src/Query/Builder.php b/src/Query/Builder.php index e2f8867b3..9b446f8e8 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -82,7 +82,7 @@ class Builder extends BaseBuilder /** * The database collection. * - * @var \MongoDB\Laravel\Collection + * @var \MongoDB\Collection */ protected $collection; diff --git a/src/Schema/Blueprint.php b/src/Schema/Blueprint.php index 0ad4535cf..f107bd7e5 100644 --- a/src/Schema/Blueprint.php +++ b/src/Schema/Blueprint.php @@ -6,7 +6,7 @@ use Illuminate\Database\Connection; use Illuminate\Database\Schema\Blueprint as SchemaBlueprint; -use MongoDB\Laravel\Collection; +use MongoDB\Collection; use function array_flip; use function implode; @@ -21,14 +21,14 @@ class Blueprint extends SchemaBlueprint /** * The MongoConnection object for this blueprint. * - * @var \MongoDB\Laravel\Connection + * @var Connection */ protected $connection; /** - * The MongoCollection object for this blueprint. + * The Collection object for this blueprint. * - * @var Collection|\MongoDB\Collection + * @var Collection */ protected $collection; diff --git a/tests/Cache/MongoLockTest.php b/tests/Cache/MongoLockTest.php index e3d2568d5..f305061cf 100644 --- a/tests/Cache/MongoLockTest.php +++ b/tests/Cache/MongoLockTest.php @@ -8,8 +8,8 @@ use Illuminate\Support\Facades\DB; use InvalidArgumentException; use MongoDB\BSON\UTCDateTime; +use MongoDB\Collection; use MongoDB\Laravel\Cache\MongoLock; -use MongoDB\Laravel\Collection; use MongoDB\Laravel\Tests\TestCase; use PHPUnit\Framework\Attributes\TestWith; diff --git a/tests/Casts/DecimalTest.php b/tests/Casts/DecimalTest.php index f69d24d62..184abd026 100644 --- a/tests/Casts/DecimalTest.php +++ b/tests/Casts/DecimalTest.php @@ -10,7 +10,7 @@ use MongoDB\BSON\Int64; use MongoDB\BSON\Javascript; use MongoDB\BSON\UTCDateTime; -use MongoDB\Laravel\Collection; +use MongoDB\Collection; use MongoDB\Laravel\Tests\Models\Casting; use MongoDB\Laravel\Tests\TestCase; diff --git a/tests/CollectionTest.php b/tests/CollectionTest.php deleted file mode 100644 index fbdbf3daf..000000000 --- a/tests/CollectionTest.php +++ /dev/null @@ -1,36 +0,0 @@ - 'bar']; - $where = ['id' => new ObjectID('56f94800911dcc276b5723dd')]; - $time = 1.1; - $queryString = 'name-collection.findOne({"id":"56f94800911dcc276b5723dd"})'; - - $mongoCollection = $this->getMockBuilder(MongoCollection::class) - ->disableOriginalConstructor() - ->getMock(); - - $mongoCollection->expects($this->once())->method('findOne')->with($where)->willReturn($return); - $mongoCollection->expects($this->once())->method('getCollectionName')->willReturn('name-collection'); - - $connection = $this->getMockBuilder(Connection::class)->disableOriginalConstructor()->getMock(); - $connection->expects($this->once())->method('getElapsedTime')->willReturn($time); - $connection->expects($this->once())->method('logQuery')->with($queryString, [], $time); - - $collection = new Collection($connection, $mongoCollection); - - $this->assertEquals($return, $collection->findOne($where)); - } -} diff --git a/tests/ConnectionTest.php b/tests/ConnectionTest.php index ac4cc78fc..4f9dfa10c 100644 --- a/tests/ConnectionTest.php +++ b/tests/ConnectionTest.php @@ -7,10 +7,12 @@ use Generator; use Illuminate\Support\Facades\DB; use InvalidArgumentException; +use MongoDB\BSON\ObjectId; use MongoDB\Client; +use MongoDB\Collection; use MongoDB\Database; +use MongoDB\Driver\Exception\BulkWriteException; use MongoDB\Driver\Exception\ConnectionTimeoutException; -use MongoDB\Laravel\Collection; use MongoDB\Laravel\Connection; use MongoDB\Laravel\Query\Builder; use MongoDB\Laravel\Schema\Builder as SchemaBuilder; @@ -225,9 +227,6 @@ public function testCollection() $collection = DB::connection('mongodb')->table('unittests'); $this->assertInstanceOf(Builder::class, $collection); - - $collection = DB::connection('mongodb')->table('unittests'); - $this->assertInstanceOf(Builder::class, $collection); } public function testPrefix() @@ -251,10 +250,12 @@ public function testQueryLog() $this->assertCount(0, DB::getQueryLog()); DB::table('items')->get(); - $this->assertCount(1, DB::getQueryLog()); + $this->assertCount(1, $logs = DB::getQueryLog()); + $this->assertJsonStringEqualsJsonString('{"find":"items","filter":{}}', $logs[0]['query']); - DB::table('items')->insert(['name' => 'test']); - $this->assertCount(2, DB::getQueryLog()); + DB::table('items')->insert(['id' => $id = new ObjectId(), 'name' => 'test']); + $this->assertCount(2, $logs = DB::getQueryLog()); + $this->assertJsonStringEqualsJsonString('{"insert":"items","ordered":true,"documents":[{"name":"test","_id":{"$oid":"' . $id . '"}}]}', $logs[1]['query']); DB::table('items')->count(); $this->assertCount(3, DB::getQueryLog()); @@ -264,6 +265,16 @@ public function testQueryLog() DB::table('items')->where('name', 'test')->delete(); $this->assertCount(5, DB::getQueryLog()); + + // Error + try { + DB::table('items')->where('name', 'test')->update( + ['$set' => ['embed' => ['foo' => 'bar']], '$unset' => ['embed' => ['foo']]], + ); + self::fail('Expected BulkWriteException'); + } catch (BulkWriteException) { + $this->assertCount(6, DB::getQueryLog()); + } } public function testSchemaBuilder() diff --git a/tests/ModelTest.php b/tests/ModelTest.php index 36465ce53..075c0d3ad 100644 --- a/tests/ModelTest.php +++ b/tests/ModelTest.php @@ -15,7 +15,7 @@ use MongoDB\BSON\Binary; use MongoDB\BSON\ObjectID; use MongoDB\BSON\UTCDateTime; -use MongoDB\Laravel\Collection; +use MongoDB\Collection; use MongoDB\Laravel\Connection; use MongoDB\Laravel\Eloquent\Model; use MongoDB\Laravel\Tests\Models\Book; diff --git a/tests/QueryBuilderTest.php b/tests/QueryBuilderTest.php index 910adecfc..523ad3411 100644 --- a/tests/QueryBuilderTest.php +++ b/tests/QueryBuilderTest.php @@ -17,12 +17,12 @@ use MongoDB\BSON\ObjectId; use MongoDB\BSON\Regex; use MongoDB\BSON\UTCDateTime; +use MongoDB\Collection; use MongoDB\Driver\Cursor; use MongoDB\Driver\Monitoring\CommandFailedEvent; use MongoDB\Driver\Monitoring\CommandStartedEvent; use MongoDB\Driver\Monitoring\CommandSubscriber; use MongoDB\Driver\Monitoring\CommandSucceededEvent; -use MongoDB\Laravel\Collection; use MongoDB\Laravel\Query\Builder; use MongoDB\Laravel\Tests\Models\Item; use MongoDB\Laravel\Tests\Models\User; From 2ee0dd99617da56d893cfe1d3cafe7687f51aa91 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Fri, 6 Sep 2024 20:40:54 +0200 Subject: [PATCH 353/446] Modernize code with rector (#3139) --- composer.json | 6 ++++-- rector.php | 25 +++++++++++++++++++++++++ src/Bus/MongoBatchRepository.php | 2 +- src/Helpers/QueriesRelationships.php | 7 +++---- src/Query/Builder.php | 2 +- tests/PHPStan/SarifErrorFormatter.php | 6 +++--- 6 files changed, 37 insertions(+), 11 deletions(-) create mode 100644 rector.php diff --git a/composer.json b/composer.json index f03fdc89d..4d679a95c 100644 --- a/composer.json +++ b/composer.json @@ -41,7 +41,8 @@ "mockery/mockery": "^1.4.4", "doctrine/coding-standard": "12.0.x-dev", "spatie/laravel-query-builder": "^5.6", - "phpstan/phpstan": "^1.10" + "phpstan/phpstan": "^1.10", + "rector/rector": "^1.2" }, "suggest": { "league/flysystem-gridfs": "Filesystem storage in MongoDB with GridFS", @@ -73,7 +74,8 @@ "test": "phpunit", "test:coverage": "phpunit --coverage-clover ./coverage.xml", "cs": "phpcs", - "cs:fix": "phpcbf" + "cs:fix": "phpcbf", + "rector": "rector" }, "config": { "allow-plugins": { diff --git a/rector.php b/rector.php new file mode 100644 index 000000000..23afcb2ea --- /dev/null +++ b/rector.php @@ -0,0 +1,25 @@ +withPaths([ + __FILE__, + __DIR__ . '/docs', + __DIR__ . '/src', + __DIR__ . '/tests', + ]) + ->withPhpSets() + ->withTypeCoverageLevel(0) + ->withSkip([ + RemoveExtraParametersRector::class, + ClosureToArrowFunctionRector::class, + NullToStrictStringFuncCallArgRector::class, + MixedTypeRector::class, + AddClosureVoidReturnTypeWhereNoReturnRector::class, + ]); diff --git a/src/Bus/MongoBatchRepository.php b/src/Bus/MongoBatchRepository.php index c6314ba69..2656bbc30 100644 --- a/src/Bus/MongoBatchRepository.php +++ b/src/Bus/MongoBatchRepository.php @@ -28,7 +28,7 @@ // are called by PruneBatchesCommand class MongoBatchRepository extends DatabaseBatchRepository implements PrunableBatchRepository { - private Collection $collection; + private readonly Collection $collection; public function __construct( BatchFactory $factory, diff --git a/src/Helpers/QueriesRelationships.php b/src/Helpers/QueriesRelationships.php index 933b6ec32..1f1ffa34b 100644 --- a/src/Helpers/QueriesRelationships.php +++ b/src/Helpers/QueriesRelationships.php @@ -21,12 +21,11 @@ use function array_map; use function class_basename; use function collect; -use function get_class; use function in_array; use function is_array; use function is_string; use function method_exists; -use function strpos; +use function str_contains; trait QueriesRelationships { @@ -45,7 +44,7 @@ trait QueriesRelationships public function has($relation, $operator = '>=', $count = 1, $boolean = 'and', ?Closure $callback = null) { if (is_string($relation)) { - if (strpos($relation, '.') !== false) { + if (str_contains($relation, '.')) { return $this->hasNested($relation, $operator, $count, $boolean, $callback); } @@ -139,7 +138,7 @@ private function handleMorphToMany($hasQuery, $relation) { // First we select the parent models that have a relation to our related model, // Then extracts related model's ids from the pivot column - $hasQuery->where($relation->getTable() . '.' . $relation->getMorphType(), get_class($relation->getParent())); + $hasQuery->where($relation->getTable() . '.' . $relation->getMorphType(), $relation->getParent()::class); $relations = $hasQuery->pluck($relation->getTable()); $relations = $relation->extractIds($relations->flatten(1)->toArray(), $relation->getForeignPivotKeyName()); diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 9b446f8e8..2bbd5a01a 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -1079,7 +1079,7 @@ protected function performUpdate(array $update, array $options = []) $wheres = $this->aliasIdForQuery($wheres); $result = $this->collection->updateMany($wheres, $update, $options); if ($result->isAcknowledged()) { - return $result->getModifiedCount() ? $result->getModifiedCount() : $result->getUpsertedCount(); + return $result->getModifiedCount() ?: $result->getUpsertedCount(); } return 0; diff --git a/tests/PHPStan/SarifErrorFormatter.php b/tests/PHPStan/SarifErrorFormatter.php index 1fb814cde..92c0255cc 100644 --- a/tests/PHPStan/SarifErrorFormatter.php +++ b/tests/PHPStan/SarifErrorFormatter.php @@ -26,9 +26,9 @@ class SarifErrorFormatter implements ErrorFormatter private const URI_BASE_ID = 'WORKINGDIR'; public function __construct( - private RelativePathHelper $relativePathHelper, - private string $currentWorkingDirectory, - private bool $pretty, + private readonly RelativePathHelper $relativePathHelper, + private readonly string $currentWorkingDirectory, + private readonly bool $pretty, ) { } From 65072798194fdeabba20ded39be75366bafa0f29 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Fri, 6 Sep 2024 16:19:12 -0400 Subject: [PATCH 354/446] DOCSP-43172: Remove DatabaseTokenRepository class (#3130) * DOCSP-43172: Remove DatabaseTokenRepository class * JT feedback * edit * JT feedback 2 --- docs/upgrade.txt | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/upgrade.txt b/docs/upgrade.txt index fed27d862..4d7dca0d8 100644 --- a/docs/upgrade.txt +++ b/docs/upgrade.txt @@ -71,6 +71,16 @@ Version 5.x Breaking Changes This library version introduces the following breaking changes: +- Removes support for the following classes: + + - ``MongoDB\Laravel\Auth\DatabaseTokenRepository``. Instead, use the default + ``Illuminate\Queue\Failed\DatabaseFailedJobProvider`` class and + specify a connection to MongoDB. + + - ``MongoDB\Laravel\Queue\Failed\MongoFailedJobProvider``. Instead, + use the default ``Illuminate\Queue\Failed\DatabaseFailedJobProvider`` + class and specify a connection to MongoDB. + - In query results, the library converts BSON ``UTCDateTime`` objects to ``Carbon`` date classes, applying the default timezone. From 47662745dee06148397d08cc06559be5a71d26a1 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Mon, 9 Sep 2024 11:59:40 -0400 Subject: [PATCH 355/446] DOCSP-43159: QB returns objects (#3135) * DOCSP-43159: QB returns objects * add to upgrade guide * add depth layer * JT tech review 2 * wip --- docs/query-builder.txt | 9 +++++++-- docs/upgrade.txt | 22 +++++++++++++++++++++- 2 files changed, 28 insertions(+), 3 deletions(-) diff --git a/docs/query-builder.txt b/docs/query-builder.txt index 9b1fe65f9..ecd9e7d61 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -38,7 +38,11 @@ testability. The {+odm-short+} provides the ``DB`` method ``table()`` to access a collection. Chain methods to specify commands and any constraints. Then, chain -the ``get()`` method at the end to run the methods and retrieve the results. +the ``get()`` method at the end to run the methods and retrieve the +results. To retrieve only the first matching result, chain the +``first()`` method instead of the ``get()`` method. Starting in +{+odm-long+} v5.0, the query builder returns results as ``stdClass`` objects. + The following example shows the syntax of a query builder call: .. code-block:: php @@ -46,7 +50,8 @@ The following example shows the syntax of a query builder call: DB::table('') // chain methods by using the "->" object operator ->get(); -.. tip:: + +.. tip:: Set Database Connection Before using the ``DB::table()`` method, ensure that you specify MongoDB as your application's default database connection. For instructions on setting the database connection, diff --git a/docs/upgrade.txt b/docs/upgrade.txt index 4d7dca0d8..a188a9322 100644 --- a/docs/upgrade.txt +++ b/docs/upgrade.txt @@ -14,7 +14,7 @@ Upgrade Library Version .. contents:: On this page :local: :backlinks: none - :depth: 1 + :depth: 2 :class: singlecol Overview @@ -71,6 +71,26 @@ Version 5.x Breaking Changes This library version introduces the following breaking changes: +- The query builder returns results as as ``stdClass`` objects instead + of as arrays. This change requires that you change array access to + property access when interacting with query results. + + The following code shows how to retrieve a query result and access a + property from the result object in older versions compared to v5.0: + + .. code-block:: php + :emphasize-lines: 8-9 + + $document = DB::table('accounts') + ->where('name', 'Anita Charles') + ->first(); + + // older versions + $document['balance']; + + // v5.0 + $document->balance; + - Removes support for the following classes: - ``MongoDB\Laravel\Auth\DatabaseTokenRepository``. Instead, use the default From f65b9e0b0529ceba8985345373a879a06c6e9f40 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Tue, 10 Sep 2024 11:18:09 -0400 Subject: [PATCH 356/446] DOCSP-42956: Remove $collection support (#3138) Adds a note about removed $collection and collection() support to the upgrade guide. --- docs/upgrade.txt | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/docs/upgrade.txt b/docs/upgrade.txt index a188a9322..5747cf300 100644 --- a/docs/upgrade.txt +++ b/docs/upgrade.txt @@ -109,6 +109,47 @@ This library version introduces the following breaking changes: of this behavior, you cannot have two separate ``id`` and ``_id`` fields in your documents. +- Removes support for the ``$collection`` property. The following code shows + how to assign a MongoDB collection to a variable in your ``User`` class in + older versions compared to v5.0: + + .. code-block:: php + :emphasize-lines: 10-11 + + use MongoDB\Laravel\Eloquent\Model; + + class User extends Model + { + protected $keyType = 'string'; + + // older versions + protected $collection = 'app_user'; + + // v5.0 + protected $table = 'app_user'; + + ... + } + + This release also modifies the associated ``DB`` and ``Schema`` methods for + accessing a MongoDB collection. The following code shows how to access the + ``app_user`` collection in older versions compared to v5.0: + + .. code-block:: php + :emphasize-lines: 9-11 + + use Illuminate\Support\Facades\Schema; + use Illuminate\Support\Facades\DB; + use MongoDB\Laravel\Schema\Blueprint; + + // older versions + Schema::collection('app_user', function (Blueprint $collection) { ... }); + DB::collection('app_user')->find($id); + + // v5.0 + Schema::table('app_user', function (Blueprint $table) { ... }); + DB::table('app_user')->find($id); + .. _laravel-breaking-changes-v4.x: Version 4.x Breaking Changes From aebf049162a06e0bfa01379de72242193e8a3e15 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Tue, 10 Sep 2024 16:50:07 -0400 Subject: [PATCH 357/446] DOCSP-42957: DateTimeInterface in queries (#3140) Adds information & a code example about automatic conversion from DateTimeInterface to UTCDateTime in queries. --- .../query-builder/QueryBuilderTest.php | 17 +++++++-- docs/query-builder.txt | 35 +++++++++++++------ docs/upgrade.txt | 10 ++++++ 3 files changed, 50 insertions(+), 12 deletions(-) diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index 02d15cc48..38f001a33 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -4,6 +4,7 @@ namespace App\Http\Controllers; +use Carbon\Carbon; use Illuminate\Database\Query\Builder; use Illuminate\Pagination\AbstractPaginator; use Illuminate\Support\Facades\DB; @@ -148,14 +149,26 @@ public function testWhereIn(): void $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); } + public function testWhereCarbon(): void + { + // begin query where date + $result = DB::connection('mongodb') + ->table('movies') + ->where('released', Carbon::create(2010, 1, 15)) + ->get(); + // end query where date + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + public function testWhereDate(): void { - // begin query whereDate + // begin query whereDate string $result = DB::connection('mongodb') ->table('movies') ->whereDate('released', '2010-1-15') ->get(); - // end query whereDate + // end query whereDate string $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); } diff --git a/docs/query-builder.txt b/docs/query-builder.txt index ecd9e7d61..0a4c878df 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -353,23 +353,38 @@ query builder method to retrieve documents from the Match Dates Example ^^^^^^^^^^^^^^^^^^^ -The following example shows how to use the ``whereDate()`` +The following example shows how to use the ``where()`` query builder method to retrieve documents from the -``movies`` collection that match the specified date of -``2010-1-15`` in the ``released`` field: +``movies`` collection in which the ``released`` value +is January 15, 2010, specified in a ``Carbon`` object: .. literalinclude:: /includes/query-builder/QueryBuilderTest.php :language: php :dedent: - :start-after: begin query whereDate - :end-before: end query whereDate + :start-after: begin query where date + :end-before: end query where date -.. note:: Date Query Result Type +.. note:: Date Query Filter and Result Type - Starting in {+odm-long+} v5.0, ``UTCDateTime`` BSON values in MongoDB - are returned as `Carbon `__ date - classes in query results. The {+odm-short+} applies the default - timezone when performing this conversion. + Starting in {+odm-long+} v5.0, `Carbon `__ + objects passed as query filters, as shown in the preceding code, are + converted to ``UTCDateTime`` BSON values. + + In query results, ``UTCDateTime`` BSON values in MongoDB are returned as ``Carbon`` + objects. The {+odm-short+} applies the default timezone when performing + this conversion. + +If you want to represent a date as a string in your query filter +rather than as a ``Carbon`` object, use the ``whereDate()`` query +builder method. The following example retrieves documents from +the ``movies`` collection in which the ``released`` value +is January 15, 2010 and specifies the date as a string: + +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query whereDate string + :end-before: end query whereDate string .. _laravel-query-builder-pattern: diff --git a/docs/upgrade.txt b/docs/upgrade.txt index 5747cf300..a992197f3 100644 --- a/docs/upgrade.txt +++ b/docs/upgrade.txt @@ -101,6 +101,16 @@ This library version introduces the following breaking changes: use the default ``Illuminate\Queue\Failed\DatabaseFailedJobProvider`` class and specify a connection to MongoDB. +- When using a ``DateTimeInterface`` object, including ``Carbon``, in a query, + the library converts the ``DateTimeInterface`` to a ``MongoDB\BSON\UTCDateTime`` + object. This conversion applies to ``DateTimeInterface`` objects passed as query + filters to the ``where()`` method or as data passed to the ``insert()`` and + ``update()`` methods. + + To view an example that passes a ``Carbon`` object to the + ``DB::where()`` method, see the :ref:`laravel-query-builder-wheredate` + section of the Query Builder guide. + - In query results, the library converts BSON ``UTCDateTime`` objects to ``Carbon`` date classes, applying the default timezone. From 25a6e9e1538d6a01a0f998c7a0b7103b1203d692 Mon Sep 17 00:00:00 2001 From: JaeYeong Choi <80824142+verduck@users.noreply.github.com> Date: Wed, 11 Sep 2024 16:55:58 +0900 Subject: [PATCH 358/446] Add options to countDocuments method (#3142) --- CHANGELOG.md | 1 + src/Query/Builder.php | 2 +- tests/QueryTest.php | 9 +++++++++ 3 files changed, 11 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fdedba537..d813edb5a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ All notable changes to this project will be documented in this file. * Remove custom `PasswordResetServiceProvider`, use the default `DatabaseTokenRepository` by @GromNaN in [#3124](https://github.com/mongodb/laravel-mongodb/pull/3124) * Remove `Blueprint::background()` method by @GromNaN in [#3132](https://github.com/mongodb/laravel-mongodb/pull/3132) * Replace `Collection` proxy class with Driver monitoring by @GromNaN in [#3137]((https://github.com/mongodb/laravel-mongodb/pull/3137) +* Support options in `count()` queries by @verduck in [#3142](https://github.com/mongodb/laravel-mongodb/pull/3142) ## [4.8.0] - 2024-08-27 diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 2bbd5a01a..43acbcc24 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -346,7 +346,7 @@ public function toMql(): array $aggregations = blank($this->aggregate['columns']) ? [] : $this->aggregate['columns']; if (in_array('*', $aggregations) && $function === 'count') { - $options = $this->inheritConnectionOptions(); + $options = $this->inheritConnectionOptions($this->options); return ['countDocuments' => [$wheres, $options]]; } diff --git a/tests/QueryTest.php b/tests/QueryTest.php index 1b5746842..78a7b1bee 100644 --- a/tests/QueryTest.php +++ b/tests/QueryTest.php @@ -660,4 +660,13 @@ public function testDelete(): void User::limit(null)->delete(); $this->assertEquals(0, User::count()); } + + public function testLimitCount(): void + { + $count = User::where('age', '>=', 20)->count(); + $this->assertEquals(7, $count); + + $count = User::where('age', '>=', 20)->options(['limit' => 3])->count(); + $this->assertEquals(3, $count); + } } From de037dd35322a75877eba8404115ed7cdf1c10d3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Thu, 12 Sep 2024 10:50:20 +0200 Subject: [PATCH 359/446] Update merge-up config for new branch pattern (#3143) --- .github/workflows/merge-up.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/merge-up.yml b/.github/workflows/merge-up.yml index bdd4cfefa..1ddbb7228 100644 --- a/.github/workflows/merge-up.yml +++ b/.github/workflows/merge-up.yml @@ -3,7 +3,7 @@ name: Merge up on: push: branches: - - "[0-9]+.[0-9]+" + - "[0-9]+.[0-9x]+" env: GH_TOKEN: ${{ secrets.MERGE_UP_TOKEN }} @@ -28,4 +28,5 @@ jobs: with: ref: ${{ github.ref_name }} branchNamePattern: '.' + devBranchNamePattern: '.x' enableAutoMerge: true From 3c1aab747ef67e818bb2b4f8191247112f588863 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Thu, 12 Sep 2024 11:44:12 +0200 Subject: [PATCH 360/446] Update changelog (#3144) --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d813edb5a..90c22dfd1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,7 +1,7 @@ # Changelog All notable changes to this project will be documented in this file. -## [5.0.0] - next +## [5.0.0] - 2024-09-12 * Remove support for Laravel 10 by @GromNaN in [#3123](https://github.com/mongodb/laravel-mongodb/pull/3123) * **BREAKING CHANGE** Use `id` as an alias for `_id` in commands and queries for compatibility with Eloquent packages by @GromNaN in [#3040](https://github.com/mongodb/laravel-mongodb/pull/3040) and [#3136](https://github.com/mongodb/laravel-mongodb/pull/3136) From 11fe1ef26e0a41889fc10b215e38694bbaa084b5 Mon Sep 17 00:00:00 2001 From: MongoDB PHP Bot <162451593+mongodb-php-bot@users.noreply.github.com> Date: Thu, 12 Sep 2024 12:50:20 +0200 Subject: [PATCH 361/446] Update changelog (#3144) (#3147) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jérôme Tamarelle --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d813edb5a..90c22dfd1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,7 +1,7 @@ # Changelog All notable changes to this project will be documented in this file. -## [5.0.0] - next +## [5.0.0] - 2024-09-12 * Remove support for Laravel 10 by @GromNaN in [#3123](https://github.com/mongodb/laravel-mongodb/pull/3123) * **BREAKING CHANGE** Use `id` as an alias for `_id` in commands and queries for compatibility with Eloquent packages by @GromNaN in [#3040](https://github.com/mongodb/laravel-mongodb/pull/3040) and [#3136](https://github.com/mongodb/laravel-mongodb/pull/3136) From 3ac795581aadb9152efb0a3923984e2e5d19435c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Fri, 13 Sep 2024 08:47:54 +0200 Subject: [PATCH 362/446] Re-enable support for Laravel 10 (#3148) --- .github/workflows/build-ci.yml | 11 +++++++---- .github/workflows/static-analysis.yml | 1 + CHANGELOG.md | 5 ++++- composer.json | 19 +++++++++++-------- 4 files changed, 23 insertions(+), 13 deletions(-) diff --git a/.github/workflows/build-ci.yml b/.github/workflows/build-ci.yml index 60d96f34f..45833d579 100644 --- a/.github/workflows/build-ci.yml +++ b/.github/workflows/build-ci.yml @@ -20,15 +20,15 @@ jobs: - "6.0" - "7.0" php: + - "8.1" - "8.2" - "8.3" laravel: + - "10.*" - "11.*" - mode: - - "" include: - - php: "8.2" - laravel: "11.*" + - php: "8.1" + laravel: "10.*" mongodb: "5.0" mode: "low-deps" os: "ubuntu-latest" @@ -37,6 +37,9 @@ jobs: mongodb: "7.0" mode: "ignore-php-req" os: "ubuntu-latest" + exclude: + - php: "8.1" + laravel: "11.*" steps: - uses: "actions/checkout@v4" diff --git a/.github/workflows/static-analysis.yml b/.github/workflows/static-analysis.yml index 331fe22d8..a66100d93 100644 --- a/.github/workflows/static-analysis.yml +++ b/.github/workflows/static-analysis.yml @@ -21,6 +21,7 @@ jobs: strategy: matrix: php: + - '8.1' - '8.2' - '8.3' steps: diff --git a/CHANGELOG.md b/CHANGELOG.md index 90c22dfd1..32f7b856b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,9 +1,12 @@ # Changelog All notable changes to this project will be documented in this file. +## [5.0.1] - 2024-09-13 + +* Restore support for Laravel 10 by @GromNaN in [#3148](https://github.com/mongodb/laravel-mongodb/pull/3148) + ## [5.0.0] - 2024-09-12 -* Remove support for Laravel 10 by @GromNaN in [#3123](https://github.com/mongodb/laravel-mongodb/pull/3123) * **BREAKING CHANGE** Use `id` as an alias for `_id` in commands and queries for compatibility with Eloquent packages by @GromNaN in [#3040](https://github.com/mongodb/laravel-mongodb/pull/3040) and [#3136](https://github.com/mongodb/laravel-mongodb/pull/3136) * **BREAKING CHANGE** Make Query\Builder return objects instead of array to match Laravel behavior by @GromNaN in [#3107](https://github.com/mongodb/laravel-mongodb/pull/3107) * **BREAKING CHANGE** In DB query results, convert BSON `UTCDateTime` objects into `Carbon` date with the default timezone by @GromNaN in [#3119](https://github.com/mongodb/laravel-mongodb/pull/3119) diff --git a/composer.json b/composer.json index 4d679a95c..9c958f1c4 100644 --- a/composer.json +++ b/composer.json @@ -22,28 +22,31 @@ ], "license": "MIT", "require": { - "php": "^8.2", + "php": "^8.1", "ext-mongodb": "^1.15", "composer-runtime-api": "^2.0.0", - "illuminate/cache": "^11", - "illuminate/container": "^11", - "illuminate/database": "^11", - "illuminate/events": "^11", - "illuminate/support": "^11", + "illuminate/cache": "^10.36|^11", + "illuminate/container": "^10.0|^11", + "illuminate/database": "^10.30|^11", + "illuminate/events": "^10.0|^11", + "illuminate/support": "^10.0|^11", "mongodb/mongodb": "^1.18" }, "require-dev": { "mongodb/builder": "^0.2", "league/flysystem-gridfs": "^3.28", "league/flysystem-read-only": "^3.0", - "phpunit/phpunit": "^10.5", - "orchestra/testbench": "^9.0", + "phpunit/phpunit": "^10.3", + "orchestra/testbench": "^8.0|^9.0", "mockery/mockery": "^1.4.4", "doctrine/coding-standard": "12.0.x-dev", "spatie/laravel-query-builder": "^5.6", "phpstan/phpstan": "^1.10", "rector/rector": "^1.2" }, + "conflict": { + "illuminate/bus": "< 10.37.2" + }, "suggest": { "league/flysystem-gridfs": "Filesystem storage in MongoDB with GridFS", "mongodb/builder": "Provides a fluent aggregation builder for MongoDB pipelines" From cf9c9b10900e3c487f021802a7446431ea7405f7 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Fri, 13 Sep 2024 10:55:22 -0400 Subject: [PATCH 363/446] DOCSP-43539: v5 release (#3154) * DOCSP-43539: v5 release * toc reshuffle --- docs/compatibility.txt | 2 +- .../framework-compatibility-laravel.rst | 2 +- docs/index.txt | 22 ++++--- docs/upgrade.txt | 58 +++++++++---------- 4 files changed, 44 insertions(+), 40 deletions(-) diff --git a/docs/compatibility.txt b/docs/compatibility.txt index e02bda581..fb253f888 100644 --- a/docs/compatibility.txt +++ b/docs/compatibility.txt @@ -15,7 +15,7 @@ Compatibility :class: singlecol .. meta:: - :keywords: laravel 9, laravel 10, laravel 11, 4.0, 4.1, 4.2 + :keywords: laravel 9, laravel 10, laravel 11, 4.0, 4.1, 4.2, 5.0 Laravel Compatibility --------------------- diff --git a/docs/includes/framework-compatibility-laravel.rst b/docs/includes/framework-compatibility-laravel.rst index 19bcafc1a..bdfbd4d4c 100644 --- a/docs/includes/framework-compatibility-laravel.rst +++ b/docs/includes/framework-compatibility-laravel.rst @@ -7,7 +7,7 @@ - Laravel 10.x - Laravel 9.x - * - 4.2 to 4.8 + * - 4.2 to 5.0 - ✓ - ✓ - diff --git a/docs/index.txt b/docs/index.txt index 12269e0c4..b767d4247 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -14,8 +14,9 @@ :maxdepth: 1 /quick-start - /usage-examples Release Notes + /upgrade + /usage-examples /fundamentals /eloquent-models /query-builder @@ -27,7 +28,6 @@ /issues-and-help /feature-compatibility /compatibility - /upgrade Introduction ------------ @@ -52,6 +52,17 @@ Learn how to add the {+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. +Upgrade Versions +---------------- + +.. important:: + + {+odm-long+} v5.0 introduces breaking changes that might affect how you + upgrade your application from a v4.x version. + +Learn what changes you must make to your application to upgrade between +major versions in the :ref:`laravel-upgrading` section. + Usage Examples -------------- @@ -94,10 +105,3 @@ Compatibility To learn more about which versions of {+odm-long+} and Laravel are compatible, see the :ref:`laravel-compatibility` section. - -Upgrade Versions ----------------- - -Learn what changes you must make to your application to upgrade versions in -the :ref:`laravel-upgrading` section. - diff --git a/docs/upgrade.txt b/docs/upgrade.txt index a992197f3..17d44cbb3 100644 --- a/docs/upgrade.txt +++ b/docs/upgrade.txt @@ -124,41 +124,41 @@ This library version introduces the following breaking changes: older versions compared to v5.0: .. code-block:: php - :emphasize-lines: 10-11 - - use MongoDB\Laravel\Eloquent\Model; - - class User extends Model - { - protected $keyType = 'string'; - - // older versions - protected $collection = 'app_user'; - - // v5.0 - protected $table = 'app_user'; - - ... - } + :emphasize-lines: 10-11 + + use MongoDB\Laravel\Eloquent\Model; + + class User extends Model + { + protected $keyType = 'string'; + + // older versions + protected $collection = 'app_user'; + + // v5.0 + protected $table = 'app_user'; + + ... + } This release also modifies the associated ``DB`` and ``Schema`` methods for accessing a MongoDB collection. The following code shows how to access the ``app_user`` collection in older versions compared to v5.0: .. code-block:: php - :emphasize-lines: 9-11 - - use Illuminate\Support\Facades\Schema; - use Illuminate\Support\Facades\DB; - use MongoDB\Laravel\Schema\Blueprint; - - // older versions - Schema::collection('app_user', function (Blueprint $collection) { ... }); - DB::collection('app_user')->find($id); - - // v5.0 - Schema::table('app_user', function (Blueprint $table) { ... }); - DB::table('app_user')->find($id); + :emphasize-lines: 9-11 + + use Illuminate\Support\Facades\Schema; + use Illuminate\Support\Facades\DB; + use MongoDB\Laravel\Schema\Blueprint; + + // older versions + Schema::collection('app_user', function (Blueprint $collection) { ... }); + DB::collection('app_user')->find($id); + + // v5.0 + Schema::table('app_user', function (Blueprint $table) { ... }); + DB::table('app_user')->find($id); .. _laravel-breaking-changes-v4.x: From 98474c34d90b6f08ff2107eaeb4b7488ae763681 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Fri, 13 Sep 2024 11:33:33 -0400 Subject: [PATCH 364/446] DOCSP-43530: Id field in query results (#3149) Adds information about ID field representation in query builder results --- docs/query-builder.txt | 7 ++++--- docs/upgrade.txt | 7 ++++--- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/query-builder.txt b/docs/query-builder.txt index 0a4c878df..2bb6f75f2 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -195,9 +195,10 @@ the value of the ``title`` field is ``"Back to the Future"``: You can use the ``id`` alias in your queries to represent the ``_id`` field in MongoDB documents, as shown in the preceding - code. When you run a find operation using the query builder, {+odm-short+} - automatically converts between ``id`` and ``_id``. This provides better - compatibility with Laravel, as the framework assumes that each record has a + code. When you use the query builder to run a find operation, the {+odm-short+} + automatically converts between ``_id`` and ``id`` field names. In query results, + the ``_id`` field is presented as ``id``. This provides better + consistency with Laravel, as the framework assumes that each record has a primary key named ``id`` by default. Because of this behavior, you cannot have two separate ``id`` and ``_id`` diff --git a/docs/upgrade.txt b/docs/upgrade.txt index 17d44cbb3..3032b8e1e 100644 --- a/docs/upgrade.txt +++ b/docs/upgrade.txt @@ -115,9 +115,10 @@ This library version introduces the following breaking changes: date classes, applying the default timezone. - ``id`` is an alias for the ``_id`` field in MongoDB documents, and the library - automatically converts between ``id`` and ``_id`` when querying data. Because - of this behavior, you cannot have two separate ``id`` and ``_id`` fields in your - documents. + automatically converts between ``id`` and ``_id`` when querying data. The query + result object includes an ``id`` field to represent the document's ``_id`` field. + Because of this behavior, you cannot have two separate ``id`` and ``_id`` fields + in your documents. - Removes support for the ``$collection`` property. The following code shows how to assign a MongoDB collection to a variable in your ``User`` class in From a51642705b66e6147dbbcf66c0d0d8183f1cfb93 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 16 Sep 2024 08:56:49 +0200 Subject: [PATCH 365/446] PHPORM-241 Add return type to CommandSubscriber (#3157) --- CHANGELOG.md | 4 ++++ src/CommandSubscriber.php | 6 +++--- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 32f7b856b..d21a52fb8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,10 @@ # Changelog All notable changes to this project will be documented in this file. +## [5.0.2] - next + +* Fix missing return types in CommandSubscriber by @GromNaN in [#3157](https://github.com/mongodb/laravel-mongodb/pull/3157) + ## [5.0.1] - 2024-09-13 * Restore support for Laravel 10 by @GromNaN in [#3148](https://github.com/mongodb/laravel-mongodb/pull/3148) diff --git a/src/CommandSubscriber.php b/src/CommandSubscriber.php index ef282bcac..569c7c909 100644 --- a/src/CommandSubscriber.php +++ b/src/CommandSubscriber.php @@ -21,17 +21,17 @@ public function __construct(private Connection $connection) { } - public function commandStarted(CommandStartedEvent $event) + public function commandStarted(CommandStartedEvent $event): void { $this->commands[$event->getOperationId()] = $event; } - public function commandFailed(CommandFailedEvent $event) + public function commandFailed(CommandFailedEvent $event): void { $this->logQuery($event); } - public function commandSucceeded(CommandSucceededEvent $event) + public function commandSucceeded(CommandSucceededEvent $event): void { $this->logQuery($event); } From f7e5758d3b942dbb04f87ac4c02ca7968a193ae4 Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Mon, 16 Sep 2024 15:05:27 +0200 Subject: [PATCH 366/446] PHPORM-205: Automate branch creation when releasing (#3145) * Automate branch creation when releasing * Apply feedback from code review --- .github/workflows/release.yml | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index e957b7faf..4afbe78f1 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -32,6 +32,7 @@ jobs: run: | echo RELEASE_VERSION=${{ inputs.version }} >> $GITHUB_ENV echo RELEASE_BRANCH=$(echo ${{ inputs.version }} | cut -d '.' -f-2) >> $GITHUB_ENV + echo DEV_BRANCH=$(echo ${{ inputs.version }} | cut -d '.' - f-1).x >> $GITHUB_ENV - name: "Ensure release tag does not already exist" run: | @@ -40,12 +41,31 @@ jobs: exit 1 fi - - name: "Fail if branch names don't match" - if: ${{ github.ref_name != env.RELEASE_BRANCH }} + # For patch releases (A.B.C where C != 0), we expect the release to be + # triggered from the A.B maintenance branch + - name: "Fail if patch release is created from wrong release branch" + if: ${{ !endsWith(inputs.version, '.0') && env.RELEASE_BRANCH != github.ref_name }} run: | echo '❌ Release failed due to branch mismatch: expected ${{ inputs.version }} to be released from ${{ env.RELEASE_BRANCH }}, got ${{ github.ref_name }}' >> $GITHUB_STEP_SUMMARY exit 1 + # For non-patch releases (A.B.C where C == 0), we expect the release to + # be triggered from the A.x maintenance branch or A.x development branch + - name: "Fail if non-patch release is created from wrong release branch" + if: ${{ endsWith(inputs.version, '.0') && env.RELEASE_BRANCH != github.ref_name && env.DEV_BRANCH != github.ref_name }} + run: | + echo '❌ Release failed due to branch mismatch: expected ${{ inputs.version }} to be released from ${{ env.RELEASE_BRANCH }} or ${{ env.DEV_BRANCH }}, got ${{ github.ref_name }}' >> $GITHUB_STEP_SUMMARY + exit 1 + + # If a non-patch release is created from its A.x development branch, + # create the A.B maintenance branch from the current one and push it + - name: "Create and push new release branch for non-patch release" + if: ${{ endsWith(inputs.version, '.0') && env.DEV_BRANCH == github.ref_name }} + run: | + echo '🆕 Creating new release branch ${RELEASE_BRANCH} from ${{ github.ref_name }}' >> $GITHUB_STEP_SUMMARY + git checkout -b ${RELEASE_BRANCH} + git push origin ${RELEASE_BRANCH} + # # Preliminary checks done - commence the release process # From b51aeff76c065839da25c56652428421d1b54cad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 17 Sep 2024 13:05:10 +0200 Subject: [PATCH 367/446] PHPORM-241 Add return type to CommandSubscriber (#3158) --- CHANGELOG.md | 4 ++++ src/CommandSubscriber.php | 6 +++--- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 32f7b856b..bd353702e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,10 @@ # Changelog All notable changes to this project will be documented in this file. +## [5.0.2] - 2024-09-17 + +* Fix missing return types in CommandSubscriber by @GromNaN in [#3158](https://github.com/mongodb/laravel-mongodb/pull/3158) + ## [5.0.1] - 2024-09-13 * Restore support for Laravel 10 by @GromNaN in [#3148](https://github.com/mongodb/laravel-mongodb/pull/3148) diff --git a/src/CommandSubscriber.php b/src/CommandSubscriber.php index ef282bcac..569c7c909 100644 --- a/src/CommandSubscriber.php +++ b/src/CommandSubscriber.php @@ -21,17 +21,17 @@ public function __construct(private Connection $connection) { } - public function commandStarted(CommandStartedEvent $event) + public function commandStarted(CommandStartedEvent $event): void { $this->commands[$event->getOperationId()] = $event; } - public function commandFailed(CommandFailedEvent $event) + public function commandFailed(CommandFailedEvent $event): void { $this->logQuery($event); } - public function commandSucceeded(CommandSucceededEvent $event) + public function commandSucceeded(CommandSucceededEvent $event): void { $this->logQuery($event); } From 38dc1e37f88cf663690e07d3806ba50ee519bd65 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 17 Sep 2024 13:59:04 +0200 Subject: [PATCH 368/446] PHPORM-239 Convert `_id` and `UTCDateTime` in results of `Model::raw()` before hydratation (#3152) --- CHANGELOG.md | 4 +++ src/Eloquent/Builder.php | 28 +++++++++++------ src/Query/Builder.php | 4 ++- tests/ModelTest.php | 63 ++++++++++++++++++++++++++++++++----- tests/Query/BuilderTest.php | 25 +++++++++++++++ 5 files changed, 106 insertions(+), 18 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bd353702e..c0e383338 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,10 @@ # Changelog All notable changes to this project will be documented in this file. +## [5.1.0] - next + +* Convert `_id` and `UTCDateTime` in results of `Model::raw()` before hydratation by @GromNaN in [#3152](https://github.com/mongodb/laravel-mongodb/pull/3152) + ## [5.0.2] - 2024-09-17 * Fix missing return types in CommandSubscriber by @GromNaN in [#3158](https://github.com/mongodb/laravel-mongodb/pull/3158) diff --git a/src/Eloquent/Builder.php b/src/Eloquent/Builder.php index da96b64f1..4fd4880df 100644 --- a/src/Eloquent/Builder.php +++ b/src/Eloquent/Builder.php @@ -5,7 +5,8 @@ namespace MongoDB\Laravel\Eloquent; use Illuminate\Database\Eloquent\Builder as EloquentBuilder; -use MongoDB\Driver\Cursor; +use MongoDB\BSON\Document; +use MongoDB\Driver\CursorInterface; use MongoDB\Driver\Exception\WriteException; use MongoDB\Laravel\Connection; use MongoDB\Laravel\Helpers\QueriesRelationships; @@ -16,7 +17,9 @@ use function array_merge; use function collect; use function is_array; +use function is_object; use function iterator_to_array; +use function property_exists; /** @method \MongoDB\Laravel\Query\Builder toBase() */ class Builder extends EloquentBuilder @@ -177,22 +180,27 @@ public function raw($value = null) $results = $this->query->raw($value); // Convert MongoCursor results to a collection of models. - if ($results instanceof Cursor) { - $results = iterator_to_array($results, false); + if ($results instanceof CursorInterface) { + $results->setTypeMap(['root' => 'array', 'document' => 'array', 'array' => 'array']); + $results = $this->query->aliasIdForResult(iterator_to_array($results)); return $this->model->hydrate($results); } - // Convert MongoDB BSONDocument to a single object. - if ($results instanceof BSONDocument) { - $results = $results->getArrayCopy(); - - return $this->model->newFromBuilder((array) $results); + // Convert MongoDB Document to a single object. + if (is_object($results) && (property_exists($results, '_id') || property_exists($results, 'id'))) { + $results = (array) match (true) { + $results instanceof BSONDocument => $results->getArrayCopy(), + $results instanceof Document => $results->toPHP(['root' => 'array', 'document' => 'array', 'array' => 'array']), + default => $results, + }; } // The result is a single object. - if (is_array($results) && array_key_exists('_id', $results)) { - return $this->model->newFromBuilder((array) $results); + if (is_array($results) && (array_key_exists('_id', $results) || array_key_exists('id', $results))) { + $results = $this->query->aliasIdForResult($results); + + return $this->model->newFromBuilder($results); } return $results; diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 43acbcc24..372dcf633 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -1648,13 +1648,15 @@ private function aliasIdForQuery(array $values): array } /** + * @internal + * * @psalm-param T $values * * @psalm-return T * * @template T of array|object */ - private function aliasIdForResult(array|object $values): array|object + public function aliasIdForResult(array|object $values): array|object { if (is_array($values)) { if (array_key_exists('_id', $values) && ! array_key_exists('id', $values)) { diff --git a/tests/ModelTest.php b/tests/ModelTest.php index 075c0d3ad..c532eea55 100644 --- a/tests/ModelTest.php +++ b/tests/ModelTest.php @@ -28,6 +28,8 @@ use MongoDB\Laravel\Tests\Models\Soft; use MongoDB\Laravel\Tests\Models\SqlUser; use MongoDB\Laravel\Tests\Models\User; +use MongoDB\Model\BSONArray; +use MongoDB\Model\BSONDocument; use PHPUnit\Framework\Attributes\DataProvider; use PHPUnit\Framework\Attributes\TestWith; @@ -907,14 +909,8 @@ public function testRaw(): void $this->assertInstanceOf(EloquentCollection::class, $users); $this->assertInstanceOf(User::class, $users[0]); - $user = User::raw(function (Collection $collection) { - return $collection->findOne(['age' => 35]); - }); - - $this->assertTrue(Model::isDocumentModel($user)); - $count = User::raw(function (Collection $collection) { - return $collection->count(); + return $collection->estimatedDocumentCount(); }); $this->assertEquals(3, $count); @@ -924,6 +920,59 @@ public function testRaw(): void $this->assertNotNull($result); } + #[DataProvider('provideTypeMap')] + public function testRawHyradeModel(array $typeMap): void + { + User::insert([ + ['name' => 'John Doe', 'age' => 35, 'embed' => ['foo' => 'bar'], 'list' => [1, 2, 3]], + ['name' => 'Jane Doe', 'age' => 35, 'embed' => ['foo' => 'bar'], 'list' => [1, 2, 3]], + ['name' => 'Harry Hoe', 'age' => 15, 'embed' => ['foo' => 'bar'], 'list' => [1, 2, 3]], + ]); + + // Single document result + $user = User::raw(fn (Collection $collection) => $collection->findOne( + ['age' => 35], + [ + 'projection' => ['_id' => 1, 'name' => 1, 'age' => 1, 'now' => '$$NOW', 'embed' => 1, 'list' => 1], + 'typeMap' => $typeMap, + ], + )); + + $this->assertInstanceOf(User::class, $user); + $this->assertArrayNotHasKey('_id', $user->getAttributes()); + $this->assertArrayHasKey('id', $user->getAttributes()); + $this->assertNotEmpty($user->id); + $this->assertInstanceOf(Carbon::class, $user->now); + $this->assertEquals(['foo' => 'bar'], (array) $user->embed); + $this->assertEquals([1, 2, 3], (array) $user->list); + + // Cursor result + $result = User::raw(fn (Collection $collection) => $collection->aggregate([ + ['$set' => ['now' => '$$NOW']], + ['$limit' => 2], + ], ['typeMap' => $typeMap])); + + $this->assertInstanceOf(EloquentCollection::class, $result); + $this->assertCount(2, $result); + $user = $result->first(); + $this->assertInstanceOf(User::class, $user); + $this->assertArrayNotHasKey('_id', $user->getAttributes()); + $this->assertArrayHasKey('id', $user->getAttributes()); + $this->assertNotEmpty($user->id); + $this->assertInstanceOf(Carbon::class, $user->now); + $this->assertEquals(['foo' => 'bar'], $user->embed); + $this->assertEquals([1, 2, 3], $user->list); + } + + public static function provideTypeMap(): Generator + { + yield 'default' => [[]]; + yield 'array' => [['root' => 'array', 'document' => 'array', 'array' => 'array']]; + yield 'object' => [['root' => 'object', 'document' => 'object', 'array' => 'array']]; + yield 'Library BSON' => [['root' => BSONDocument::class, 'document' => BSONDocument::class, 'array' => BSONArray::class]]; + yield 'Driver BSON' => [['root' => 'bson', 'document' => 'bson', 'array' => 'bson']]; + } + public function testDotNotation(): void { $user = User::create([ diff --git a/tests/Query/BuilderTest.php b/tests/Query/BuilderTest.php index 49da6fada..c1587dc73 100644 --- a/tests/Query/BuilderTest.php +++ b/tests/Query/BuilderTest.php @@ -1381,6 +1381,31 @@ function (Builder $elemMatchQuery): void { ->orWhereAny(['last_name', 'email'], 'not like', '%Doe%'), 'orWhereAny', ]; + + yield 'raw filter with _id and date' => [ + [ + 'find' => [ + [ + '$and' => [ + [ + '$or' => [ + ['foo._id' => 1], + ['created_at' => ['$gte' => new UTCDateTime(new DateTimeImmutable('2018-09-30 00:00:00.000 +00:00'))]], + ], + ], + ['age' => 15], + ], + ], + [], // options + ], + ], + fn (Builder $builder) => $builder->where([ + '$or' => [ + ['foo.id' => 1], + ['created_at' => ['$gte' => new DateTimeImmutable('2018-09-30 00:00:00 +00:00')]], + ], + ])->where('age', 15), + ]; } #[DataProvider('provideExceptions')] From 716d8e166809502a22017b476979678a57d5d91d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Fri, 20 Sep 2024 14:29:16 +0200 Subject: [PATCH 369/446] PHPORM-243 Alias `_id` to `id` in `Schema::getColumns()` (#3160) * PHPORM-243 Alias _id to id in Schema::getColumns * Support hasColumn for nested id --- CHANGELOG.md | 1 + src/Schema/Builder.php | 26 +++++++++++++++++++++++--- tests/SchemaTest.php | 15 ++++++++++++--- 3 files changed, 36 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c0e383338..e9f973800 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,7 @@ All notable changes to this project will be documented in this file. ## [5.1.0] - next * Convert `_id` and `UTCDateTime` in results of `Model::raw()` before hydratation by @GromNaN in [#3152](https://github.com/mongodb/laravel-mongodb/pull/3152) +* Alias `_id` to `id` in `Schema::getColumns()` by @GromNaN in [#3160](https://github.com/mongodb/laravel-mongodb/pull/3160) ## [5.0.2] - 2024-09-17 diff --git a/src/Schema/Builder.php b/src/Schema/Builder.php index 630ff4c75..ade4b0fb7 100644 --- a/src/Schema/Builder.php +++ b/src/Schema/Builder.php @@ -9,14 +9,19 @@ use MongoDB\Model\IndexInfo; use function array_fill_keys; +use function array_filter; use function array_keys; +use function array_map; use function assert; use function count; use function current; use function implode; +use function in_array; use function iterator_to_array; use function sort; use function sprintf; +use function str_ends_with; +use function substr; use function usort; class Builder extends \Illuminate\Database\Schema\Builder @@ -40,6 +45,16 @@ public function hasColumn($table, $column): bool */ public function hasColumns($table, array $columns): bool { + // The field "id" (alias of "_id") always exists in MongoDB documents + $columns = array_filter($columns, fn (string $column): bool => ! in_array($column, ['_id', 'id'], true)); + + // Any subfield named "*.id" is an alias of "*._id" + $columns = array_map(fn (string $column): string => str_ends_with($column, '.id') ? substr($column, 0, -3) . '._id' : $column, $columns); + + if ($columns === []) { + return true; + } + $collection = $this->connection->table($table); return $collection @@ -187,16 +202,21 @@ public function getColumns($table) foreach ($stats as $stat) { sort($stat->types); $type = implode(', ', $stat->types); + $name = $stat->_id; + if ($name === '_id') { + $name = 'id'; + } + $columns[] = [ - 'name' => $stat->_id, + 'name' => $name, 'type_name' => $type, 'type' => $type, 'collation' => null, - 'nullable' => $stat->_id !== '_id', + 'nullable' => $name !== 'id', 'default' => null, 'auto_increment' => false, 'comment' => sprintf('%d occurrences', $stat->total), - 'generation' => $stat->_id === '_id' ? ['type' => 'objectId', 'expression' => null] : null, + 'generation' => $name === 'id' ? ['type' => 'objectId', 'expression' => null] : null, ]; } diff --git a/tests/SchemaTest.php b/tests/SchemaTest.php index 0f04ab6d4..ff3dfe626 100644 --- a/tests/SchemaTest.php +++ b/tests/SchemaTest.php @@ -374,14 +374,22 @@ public function testRenameColumn(): void public function testHasColumn(): void { - DB::connection()->table('newcollection')->insert(['column1' => 'value']); + $this->assertTrue(Schema::hasColumn('newcollection', '_id')); + $this->assertTrue(Schema::hasColumn('newcollection', 'id')); + + DB::connection()->table('newcollection')->insert(['column1' => 'value', 'embed' => ['_id' => 1]]); $this->assertTrue(Schema::hasColumn('newcollection', 'column1')); $this->assertFalse(Schema::hasColumn('newcollection', 'column2')); + $this->assertTrue(Schema::hasColumn('newcollection', 'embed._id')); + $this->assertTrue(Schema::hasColumn('newcollection', 'embed.id')); } public function testHasColumns(): void { + $this->assertTrue(Schema::hasColumns('newcollection', ['_id'])); + $this->assertTrue(Schema::hasColumns('newcollection', ['id'])); + // Insert documents with both column1 and column2 DB::connection()->table('newcollection')->insert([ ['column1' => 'value1', 'column2' => 'value2'], @@ -451,8 +459,9 @@ public function testGetColumns() $this->assertIsString($column['comment']); }); - $this->assertEquals('objectId', $columns->get('_id')['type']); - $this->assertEquals('objectId', $columns->get('_id')['generation']['type']); + $this->assertNull($columns->get('_id'), '_id is renamed to id'); + $this->assertEquals('objectId', $columns->get('id')['type']); + $this->assertEquals('objectId', $columns->get('id')['generation']['type']); $this->assertNull($columns->get('text')['generation']); $this->assertEquals('string', $columns->get('text')['type']); $this->assertEquals('date', $columns->get('date')['type']); From 7a865e7bdc710f65d9876aab4ad5e296cea0b8a2 Mon Sep 17 00:00:00 2001 From: Mohammad Mortazavi <39920372+hans-thomas@users.noreply.github.com> Date: Mon, 30 Sep 2024 14:52:46 +0330 Subject: [PATCH 370/446] Owner key for morphTo relations (#3162) --- src/Relations/MorphTo.php | 2 +- tests/RelationsTest.php | 11 ++++++++++- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/src/Relations/MorphTo.php b/src/Relations/MorphTo.php index 692991372..4874b23bb 100644 --- a/src/Relations/MorphTo.php +++ b/src/Relations/MorphTo.php @@ -29,7 +29,7 @@ protected function getResultsByType($type) { $instance = $this->createModelByType($type); - $key = $instance->getKeyName(); + $key = $this->ownerKey ?? $instance->getKeyName(); $query = $instance->newQuery(); diff --git a/tests/RelationsTest.php b/tests/RelationsTest.php index 902f0499c..a58fef02f 100644 --- a/tests/RelationsTest.php +++ b/tests/RelationsTest.php @@ -634,11 +634,13 @@ public function testMorph(): void $photo = Photo::first(); $this->assertEquals($photo->hasImage->name, $user->name); + // eager load $user = User::with('photos')->find($user->id); $relations = $user->getRelations(); $this->assertArrayHasKey('photos', $relations); $this->assertEquals(1, $relations['photos']->count()); + // inverse eager load $photos = Photo::with('hasImage')->get(); $relations = $photos[0]->getRelations(); $this->assertArrayHasKey('hasImage', $relations); @@ -648,7 +650,7 @@ public function testMorph(): void $this->assertArrayHasKey('hasImage', $relations); $this->assertInstanceOf(Client::class, $photos[1]->hasImage); - // inverse + // inverse relationship $photo = Photo::query()->create(['url' => 'https://graph.facebook.com/hans.thomas/picture']); $client = Client::create(['name' => 'Hans Thomas']); $photo->hasImage()->associate($client)->save(); @@ -666,6 +668,13 @@ public function testMorph(): void $this->assertInstanceOf(Client::class, $photo->hasImageWithCustomOwnerKey); $this->assertEquals($client->cclient_id, $photo->has_image_with_custom_owner_key_id); $this->assertEquals($client->id, $photo->hasImageWithCustomOwnerKey->id); + + // inverse eager load with custom ownerKey + $photos = Photo::with('hasImageWithCustomOwnerKey')->get(); + $check = $photos->last(); + $relations = $check->getRelations(); + $this->assertArrayHasKey('hasImageWithCustomOwnerKey', $relations); + $this->assertInstanceOf(Client::class, $check->hasImageWithCustomOwnerKey); } public function testMorphToMany(): void From 8318822488261ad1c3aaf9c2dc83a4f643882295 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 1 Oct 2024 06:55:03 +0200 Subject: [PATCH 371/446] Remove changelog, use release notes instead (#3164) --- .github/PULL_REQUEST_TEMPLATE.md | 1 - CHANGELOG.md | 225 ------------------------------- CONTRIBUTING.md | 3 +- 3 files changed, 1 insertion(+), 228 deletions(-) delete mode 100644 CHANGELOG.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 321d843c0..a7081f5f3 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -6,4 +6,3 @@ This will help reviewers and should be a good start for the documentation. ### Checklist - [ ] Add tests and ensure they pass -- [ ] Add an entry to the CHANGELOG.md file diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index e9f973800..000000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,225 +0,0 @@ -# Changelog -All notable changes to this project will be documented in this file. - -## [5.1.0] - next - -* Convert `_id` and `UTCDateTime` in results of `Model::raw()` before hydratation by @GromNaN in [#3152](https://github.com/mongodb/laravel-mongodb/pull/3152) -* Alias `_id` to `id` in `Schema::getColumns()` by @GromNaN in [#3160](https://github.com/mongodb/laravel-mongodb/pull/3160) - -## [5.0.2] - 2024-09-17 - -* Fix missing return types in CommandSubscriber by @GromNaN in [#3158](https://github.com/mongodb/laravel-mongodb/pull/3158) - -## [5.0.1] - 2024-09-13 - -* Restore support for Laravel 10 by @GromNaN in [#3148](https://github.com/mongodb/laravel-mongodb/pull/3148) - -## [5.0.0] - 2024-09-12 - -* **BREAKING CHANGE** Use `id` as an alias for `_id` in commands and queries for compatibility with Eloquent packages by @GromNaN in [#3040](https://github.com/mongodb/laravel-mongodb/pull/3040) and [#3136](https://github.com/mongodb/laravel-mongodb/pull/3136) -* **BREAKING CHANGE** Make Query\Builder return objects instead of array to match Laravel behavior by @GromNaN in [#3107](https://github.com/mongodb/laravel-mongodb/pull/3107) -* **BREAKING CHANGE** In DB query results, convert BSON `UTCDateTime` objects into `Carbon` date with the default timezone by @GromNaN in [#3119](https://github.com/mongodb/laravel-mongodb/pull/3119) -* Remove `MongoFailedJobProvider`, replaced by Laravel `DatabaseFailedJobProvider` by @GromNaN in [#3122](https://github.com/mongodb/laravel-mongodb/pull/3122) -* Remove custom `PasswordResetServiceProvider`, use the default `DatabaseTokenRepository` by @GromNaN in [#3124](https://github.com/mongodb/laravel-mongodb/pull/3124) -* Remove `Blueprint::background()` method by @GromNaN in [#3132](https://github.com/mongodb/laravel-mongodb/pull/3132) -* Replace `Collection` proxy class with Driver monitoring by @GromNaN in [#3137]((https://github.com/mongodb/laravel-mongodb/pull/3137) -* Support options in `count()` queries by @verduck in [#3142](https://github.com/mongodb/laravel-mongodb/pull/3142) - -## [4.8.0] - 2024-08-27 - -* Add `Query\Builder::incrementEach()` and `decrementEach()` methods by @SmallRuralDog in [#2550](https://github.com/mongodb/laravel-mongodb/pull/2550) -* Add `Query\Builder::whereLike()` and `whereNotLike()` methods by @GromNaN in [#3108](https://github.com/mongodb/laravel-mongodb/pull/3108) -* Deprecate `Connection::collection()` and `Schema\Builder::collection()` methods by @GromNaN in [#3062](https://github.com/mongodb/laravel-mongodb/pull/3062) -* Deprecate `Model::$collection` property to customize collection name. Use `$table` instead by @GromNaN in [#3064](https://github.com/mongodb/laravel-mongodb/pull/3064) - -## [4.7.2] - 2024-08-27 - -* Add `Query\Builder::upsert()` method with a single document by @GromNaN in [#3100](https://github.com/mongodb/laravel-mongodb/pull/3100) - -## [4.7.1] - 2024-07-25 - -* Fix registration of `BusServiceProvider` for compatibility with Horizon by @GromNaN in [#3071](https://github.com/mongodb/laravel-mongodb/pull/3071) - -## [4.7.0] - 2024-07-19 - -* Add `Query\Builder::upsert()` method by @GromNaN in [#3052](https://github.com/mongodb/laravel-mongodb/pull/3052) -* Add `Connection::getServerVersion()` by @GromNaN in [#3043](https://github.com/mongodb/laravel-mongodb/pull/3043) -* Add `Schema\Builder::getTables()` and `getTableListing()` by @GromNaN in [#3044](https://github.com/mongodb/laravel-mongodb/pull/3044) -* Add `Schema\Builder::getColumns()` and `getIndexes()` by @GromNaN in [#3045](https://github.com/mongodb/laravel-mongodb/pull/3045) -* Add `Schema\Builder::hasColumn()` and `hasColumns()` method by @Alex-Belyi in [#3001](https://github.com/mongodb/laravel-mongodb/pull/3001) -* Fix unsetting a field in an embedded model by @GromNaN in [#3052](https://github.com/mongodb/laravel-mongodb/pull/3052) - -## [4.6.0] - 2024-07-09 - -* Add `DocumentModel` trait to use any 3rd party model with MongoDB @GromNaN in [#2580](https://github.com/mongodb/laravel-mongodb/pull/2580) -* Add `HasSchemaVersion` trait to help implementing the [schema versioning pattern](https://www.mongodb.com/docs/manual/tutorial/model-data-for-schema-versioning/) @florianJacques in [#3021](https://github.com/mongodb/laravel-mongodb/pull/3021) -* Add support for Closure for Embed pagination @GromNaN in [#3027](https://github.com/mongodb/laravel-mongodb/pull/3027) - -## [4.5.0] - 2024-06-20 - -* Add GridFS integration for Laravel File Storage by @GromNaN in [#2985](https://github.com/mongodb/laravel-mongodb/pull/2985) - -## [4.4.0] - 2024-05-31 - -* Support collection name prefix by @GromNaN in [#2930](https://github.com/mongodb/laravel-mongodb/pull/2930) -* Ignore `_id: null` to let MongoDB generate an `ObjectId` by @GromNaN in [#2969](https://github.com/mongodb/laravel-mongodb/pull/2969) -* Add `mongodb` driver for Batching by @GromNaN in [#2904](https://github.com/mongodb/laravel-mongodb/pull/2904) -* Rename queue option `table` to `collection` -* Replace queue option `expire` with `retry_after` -* Revert behavior of `createOrFirst` to delegate to `firstOrCreate` when in transaction by @GromNaN in [#2984](https://github.com/mongodb/laravel-mongodb/pull/2984) - -## [4.3.1] - 2024-05-31 - -* Fix memory leak when filling nested fields using dot notation by @GromNaN in [#2962](https://github.com/mongodb/laravel-mongodb/pull/2962) -* Fix PHP error when accessing the connection after disconnect by @SanderMuller in [#2967](https://github.com/mongodb/laravel-mongodb/pull/2967) -* Improve error message for invalid configuration by @GromNaN in [#2975](https://github.com/mongodb/laravel-mongodb/pull/2975) -* Remove `@mixin` annotation from `MongoDB\Laravel\Model` class by @GromNaN in [#2981](https://github.com/mongodb/laravel-mongodb/pull/2981) - -## [4.3.0] - 2024-04-26 - -* New aggregation pipeline builder by @GromNaN in [#2738](https://github.com/mongodb/laravel-mongodb/pull/2738) -* Drop support for Composer 1.x by @GromNaN in [#2784](https://github.com/mongodb/laravel-mongodb/pull/2784) -* Fix `artisan query:retry` command by @GromNaN in [#2838](https://github.com/mongodb/laravel-mongodb/pull/2838) -* Add `mongodb` cache and lock drivers by @GromNaN in [#2877](https://github.com/mongodb/laravel-mongodb/pull/2877) - -## [4.2.2] - 2024-04-25 - -* Add return types to `FindAndModifyCommandSubscriber`, used by `firstOrCreate` by @wivaku in [#2913](https://github.com/mongodb/laravel-mongodb/pull/2913) - -## [4.2.1] - 2024-04-25 - -* Set timestamps when using `Model::createOrFirst()` by @GromNaN in [#2905](https://github.com/mongodb/laravel-mongodb/pull/2905) - -## [4.2.0] - 2024-03-14 - -* Add support for Laravel 11 by @GromNaN in [#2735](https://github.com/mongodb/laravel-mongodb/pull/2735) -* Implement `Model::createOrFirst()` using findOneAndUpdate operation by @GromNaN in [#2742](https://github.com/mongodb/laravel-mongodb/pull/2742) - -## [4.1.3] - 2024-03-05 - -* Fix the timezone of `datetime` fields when they are read from the database. By @GromNaN in [#2739](https://github.com/mongodb/laravel-mongodb/pull/2739) -* Fix support for null values in `datetime` and reset `date` fields with custom format to the start of the day. By @GromNaN in [#2741](https://github.com/mongodb/laravel-mongodb/pull/2741) - -## [4.1.2] - 2024-02-22 - -* Fix support for subqueries using the query builder by @GromNaN in [#2717](https://github.com/mongodb/laravel-mongodb/pull/2717) -* Fix `Query\Builder::dump` and `dd` methods to dump the MongoDB query by @GromNaN in [#2727](https://github.com/mongodb/laravel-mongodb/pull/2727) and [#2730](https://github.com/mongodb/laravel-mongodb/pull/2730) - -## [4.1.1] - 2024-01-17 - -* Fix casting issues by [@stubbo](https://github.com/stubbo) in [#2705](https://github.com/mongodb/laravel-mongodb/pull/2705) -* Move documentation to the mongodb.com domain at [https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/) - -## [4.1.0] - 2023-12-14 - -* PHPORM-100 Support query on numerical field names by [@GromNaN](https://github.com/GromNaN) in [#2642](https://github.com/mongodb/laravel-mongodb/pull/2642) -* Fix casting issue by [@hans-thomas](https://github.com/hans-thomas) in [#2653](https://github.com/mongodb/laravel-mongodb/pull/2653) -* Upgrade minimum Laravel version to 10.30 by [@GromNaN](https://github.com/GromNaN) in [#2665](https://github.com/mongodb/laravel-mongodb/pull/2665) -* Handling single model in sync method by [@hans-thomas](https://github.com/hans-thomas) in [#2648](https://github.com/mongodb/laravel-mongodb/pull/2648) -* BelongsToMany sync does't use configured keys by [@hans-thomas](https://github.com/hans-thomas) in [#2667](https://github.com/mongodb/laravel-mongodb/pull/2667) -* morphTo relationship by [@hans-thomas](https://github.com/hans-thomas) in [#2669](https://github.com/mongodb/laravel-mongodb/pull/2669) -* Datetime casting with custom format by [@hans-thomas](https://github.com/hans-thomas) in [#2658](https://github.com/mongodb/laravel-mongodb/pull/2658) -* PHPORM-106 Implement pagination for groupBy queries by [@GromNaN](https://github.com/GromNaN) in [#2672](https://github.com/mongodb/laravel-mongodb/pull/2672) -* Add method `Connection::ping()` to check server connection by [@hans-thomas](https://github.com/hans-thomas) in [#2677](https://github.com/mongodb/laravel-mongodb/pull/2677) -* PHPORM-119 Fix integration with Spatie Query Builder - Don't qualify field names in document models by [@GromNaN](https://github.com/GromNaN) in [#2676](https://github.com/mongodb/laravel-mongodb/pull/2676) -* Support renaming columns in migrations by [@hans-thomas](https://github.com/hans-thomas) in [#2682](https://github.com/mongodb/laravel-mongodb/pull/2682) -* Add MorphToMany support by [@hans-thomas](https://github.com/hans-thomas) in [#2670](https://github.com/mongodb/laravel-mongodb/pull/2670) -* PHPORM-6 Fix doc Builder::timeout applies to find query, not the cursor by [@GromNaN](https://github.com/GromNaN) in [#2681](https://github.com/mongodb/laravel-mongodb/pull/2681) -* Add test for the `$hidden` property by [@Treggats](https://github.com/Treggats) in [#2687](https://github.com/mongodb/laravel-mongodb/pull/2687) -* Update `push` and `pull` docs by [@hans-thomas](https://github.com/hans-thomas) in [#2685](https://github.com/mongodb/laravel-mongodb/pull/2685) -* Hybrid support for BelongsToMany relationship by [@hans-thomas](https://github.com/hans-thomas) in [#2688](https://github.com/mongodb/laravel-mongodb/pull/2688) -* Avoid unnecessary data fetch for exists method by [@andersonls](https://github.com/andersonls) in [#2692](https://github.com/mongodb/laravel-mongodb/pull/2692) -* Hybrid support for MorphToMany relationship by [@hans-thomas](https://github.com/hans-thomas) in [#2690](https://github.com/mongodb/laravel-mongodb/pull/2690) - -## [4.0.3] - 2024-01-17 - -- Reset `Model::$unset` when a model is saved or refreshed [#2709](https://github.com/mongodb/laravel-mongodb/pull/2709) by [@richardfila](https://github.com/richardfila) - -## [4.0.2] - 2023-11-03 - -- Fix compatibility with Laravel 10.30 [#2661](https://github.com/mongodb/laravel-mongodb/pull/2661) by [@Treggats](https://github.com/Treggats) -- PHPORM-101 Allow empty insert batch for consistency with Eloquent SQL [#2661](https://github.com/mongodb/laravel-mongodb/pull/2645) by [@GromNaN](https://github.com/GromNaN) - -*4.0.1 skipped due to a mistake in the release process.* - -## [4.0.0] - 2023-09-28 - -- Rename package to `mongodb/laravel-mongodb` -- Change namespace to `MongoDB\Laravel` -- Add classes to cast `ObjectId` and `UUID` instances [5105553](https://github.com/mongodb/laravel-mongodb/commit/5105553cbb672a982ccfeaa5b653d33aaca1553e) by [@alcaeus](https://github.com/alcaeus). -- Add `Query\Builder::toMql()` to simplify comprehensive query tests [ae3e0d5](https://github.com/mongodb/laravel-mongodb/commit/ae3e0d5f72c24edcb2a78d321910397f4134e90f) by @GromNaN. -- Fix `Query\Builder::whereNot` to use MongoDB [`$not`](https://www.mongodb.com/docs/manual/reference/operator/query/not/) operator [e045fab](https://github.com/mongodb/laravel-mongodb/commit/e045fab6c315fe6d17f75669665898ed98b88107) by @GromNaN. -- Fix `Query\Builder::whereBetween` to accept `Carbon\Period` object [f729baa](https://github.com/mongodb/laravel-mongodb/commit/f729baad59b4baf3307121df7f60c5cd03a504f5) by @GromNaN. -- Throw an exception for unsupported `Query\Builder` methods [e1a83f4](https://github.com/mongodb/laravel-mongodb/commit/e1a83f47f16054286bc433fc9ccfee078bb40741) by @GromNaN. -- Throw an exception when `Query\Builder::orderBy()` is used with invalid direction [edd0871](https://github.com/mongodb/laravel-mongodb/commit/edd08715a0dd64bab9fd1194e70fface09e02900) by @GromNaN. -- Throw an exception when `Query\Builder::push()` is used incorrectly [19cf7a2](https://github.com/mongodb/laravel-mongodb/commit/19cf7a2ee2c0f2c69459952c4207ee8279b818d3) by @GromNaN. -- Remove public property `Query\Builder::$paginating` [e045fab](https://github.com/mongodb/laravel-mongodb/commit/e045fab6c315fe6d17f75669665898ed98b88107) by @GromNaN. -- Remove call to deprecated `Collection::count` for `countDocuments` [4514964](https://github.com/mongodb/laravel-mongodb/commit/4514964145c70c37e6221be8823f8f73a201c259) by @GromNaN. -- Accept operators prefixed by `$` in `Query\Builder::orWhere` [0fb83af](https://github.com/mongodb/laravel-mongodb/commit/0fb83af01284cb16def1eda6987432ebbd64bb8f) by @GromNaN. -- Remove `Query\Builder::whereAll($column, $values)`. Use `Query\Builder::where($column, 'all', $values)` instead. [1d74dc3](https://github.com/mongodb/laravel-mongodb/commit/1d74dc3d3df9f7a579b343f3109160762050ca01) by @GromNaN. -- Fix validation of unique values when the validated value is found as part of an existing value. [d5f1bb9](https://github.com/mongodb/laravel-mongodb/commit/d5f1bb901f3e3c6777bc604be1af0a8238dc089a) by @GromNaN. -- Support `%` and `_` in `like` expression [ea89e86](https://github.com/mongodb/laravel-mongodb/commit/ea89e8631350cd81c8d5bf977efb4c09e60d7807) by @GromNaN. -- Change signature of `Query\Builder::__constructor` to match the parent class [#2570](https://github.com/mongodb/laravel-mongodb/pull/2570) by @GromNaN. -- Fix Query on `whereDate`, `whereDay`, `whereMonth`, `whereYear`, `whereTime` to use MongoDB operators [#2376](https://github.com/mongodb/laravel-mongodb/pull/2376) by [@Davpyu](https://github.com/Davpyu) and @GromNaN. -- `Model::unset()` does not persist the change. Call `Model::save()` to persist the change [#2578](https://github.com/mongodb/laravel-mongodb/pull/2578) by @GromNaN. -- Support delete one document with `Query\Builder::limit(1)->delete()` [#2591](https://github.com/mongodb/laravel-mongodb/pull/2591) by @GromNaN -- Add trait `MongoDB\Laravel\Eloquent\MassPrunable` to replace the Eloquent trait on MongoDB models [#2598](https://github.com/mongodb/laravel-mongodb/pull/2598) by @GromNaN - -## [3.9.2] - 2022-09-01 - -### Added -- Add single word name mutators [#2438](https://github.com/mongodb/laravel-mongodb/pull/2438) by [@RosemaryOrchard](https://github.com/RosemaryOrchard) & [@mrneatly](https://github.com/mrneatly). - -### Fixed -- Fix stringable sort [#2420](https://github.com/mongodb/laravel-mongodb/pull/2420) by [@apeisa](https://github.com/apeisa). - -## [3.9.1] - 2022-03-11 - -### Added -- Backport support for cursor pagination [#2358](https://github.com/mongodb/laravel-mongodb/pull/2358) by [@Jeroenwv](https://github.com/Jeroenwv). - -### Fixed -- Check if queue service is disabled [#2357](https://github.com/mongodb/laravel-mongodb/pull/2357) by [@robjbrain](https://github.com/robjbrain). - -## [3.9.0] - 2022-02-17 - -### Added -- Compatibility with Laravel 9.x [#2344](https://github.com/mongodb/laravel-mongodb/pull/2344) by [@divine](https://github.com/divine). - -## [3.8.4] - 2021-05-27 - -### Fixed -- Fix getRelationQuery breaking changes [#2263](https://github.com/mongodb/laravel-mongodb/pull/2263) by [@divine](https://github.com/divine). -- Apply fixes produced by php-cs-fixer [#2250](https://github.com/mongodb/laravel-mongodb/pull/2250) by [@divine](https://github.com/divine). - -### Changed -- Add doesntExist to passthru [#2194](https://github.com/mongodb/laravel-mongodb/pull/2194) by [@simonschaufi](https://github.com/simonschaufi). -- Add Model query whereDate support [#2251](https://github.com/mongodb/laravel-mongodb/pull/2251) by [@yexk](https://github.com/yexk). -- Add transaction free deleteAndRelease() method [#2229](https://github.com/mongodb/laravel-mongodb/pull/2229) by [@sodoardi](https://github.com/sodoardi). -- Add setDatabase to Jenssegers\Mongodb\Connection [#2236](https://github.com/mongodb/laravel-mongodb/pull/2236) by [@ThomasWestrelin](https://github.com/ThomasWestrelin). -- Check dates against DateTimeInterface instead of DateTime [#2239](https://github.com/mongodb/laravel-mongodb/pull/2239) by [@jeromegamez](https://github.com/jeromegamez). -- Move from psr-0 to psr-4 [#2247](https://github.com/mongodb/laravel-mongodb/pull/2247) by [@divine](https://github.com/divine). - -## [3.8.3] - 2021-02-21 - -### Changed -- Fix query builder regression [#2204](https://github.com/mongodb/laravel-mongodb/pull/2204) by [@divine](https://github.com/divine). - -## [3.8.2] - 2020-12-18 - -### Changed -- MongodbQueueServiceProvider does not use the DB Facade anymore [#2149](https://github.com/mongodb/laravel-mongodb/pull/2149) by [@curosmj](https://github.com/curosmj). -- Add escape regex chars to DB Presence Verifier [#1992](https://github.com/mongodb/laravel-mongodb/pull/1992) by [@andrei-gafton-rtgt](https://github.com/andrei-gafton-rtgt). - -## [3.8.1] - 2020-10-23 - -### Added -- Laravel 8 support by [@divine](https://github.com/divine). - -### Changed -- Fix like with numeric values [#2127](https://github.com/mongodb/laravel-mongodb/pull/2127) by [@hnassr](https://github.com/hnassr). - -## [3.8.0] - 2020-09-03 - -### Added -- Laravel 8 support & updated versions of all dependencies [#2108](https://github.com/mongodb/laravel-mongodb/pull/2108) by [@divine](https://github.com/divine). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ddf63e799..94220d7b1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -70,8 +70,7 @@ If the project maintainer has any additional requirements, you will find them li - **Add tests!** - Your patch won't be accepted if it doesn't have tests. -- **Document any change in behaviour** - Make sure the documentation is kept up-to-date, and update the changelog for -new features and bug fixes. +- **Document any change in behaviour** - Make sure the documentation is kept up-to-date. - **Consider our release cycle** - We try to follow [SemVer v2.0.0](https://semver.org/). Randomly breaking public APIs is not an option. From 5c7e2401e98ddf9592e9360f0f17e2b595271055 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Tue, 1 Oct 2024 10:24:34 -0400 Subject: [PATCH 372/446] DOCSP-43806: getColumns id alias (#3165) * DOCSP-43806: getColumns id alias * JT tech review 1 --- docs/fundamentals/database-collection.txt | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/docs/fundamentals/database-collection.txt b/docs/fundamentals/database-collection.txt index 826e43220..a453d81a9 100644 --- a/docs/fundamentals/database-collection.txt +++ b/docs/fundamentals/database-collection.txt @@ -258,16 +258,21 @@ schema builder method in your application. You can also use the following methods to return more information about the collection fields: -- ``Schema::hasColumn(string $, string $)``: checks if the specified field exists - in at least one document -- ``Schema::hasColumns(string $, string[] $)``: checks if each specified field exists - in at least one document +- ``Schema::hasColumn(string $, string $)``: + checks if the specified field exists in at least one document +- ``Schema::hasColumns(string $, string[] $)``: + checks if each specified field exists in at least one document -.. note:: +MongoDB is a schemaless database, so the preceding methods query the collection +data rather than the database schema. If the specified collection doesn't exist +or is empty, these methods return a value of ``false``. + +.. note:: id Alias - MongoDB is a schemaless database, so the preceding methods query the collection - data rather than the database schema. If the specified collection doesn't exist - or is empty, these methods return a value of ``false``. + Starting in {+odm-long+} v5.1, the ``getColumns()`` method represents + the ``_id`` field name in a MongoDB collection as the alias ``id`` in + the returned list of field names. You can pass either ``_id`` or + ``id`` to the ``hasColumn()`` and ``hasColumns()`` methods. Example ``````` From a5ef5c034d18f43ed8652d9a3f58541e4bcb5f47 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Fri, 4 Oct 2024 17:45:45 +0200 Subject: [PATCH 373/446] PHPORM-248 register command subscriber only when logs are enabled (#3167) --- src/Connection.php | 41 +++++++++++++++++++++++++++++++++++----- tests/ConnectionTest.php | 25 ++++++++++++++++++++++++ 2 files changed, 61 insertions(+), 5 deletions(-) diff --git a/src/Connection.php b/src/Connection.php index a76ddc010..84ca97aba 100644 --- a/src/Connection.php +++ b/src/Connection.php @@ -48,7 +48,7 @@ class Connection extends BaseConnection */ protected $connection; - private ?CommandSubscriber $commandSubscriber; + private ?CommandSubscriber $commandSubscriber = null; /** * Create a new database connection instance. @@ -65,8 +65,6 @@ public function __construct(array $config) // Create the connection $this->connection = $this->createConnection($dsn, $config, $options); - $this->commandSubscriber = new CommandSubscriber($this); - $this->connection->addSubscriber($this->commandSubscriber); // Select database $this->db = $this->connection->selectDatabase($this->getDefaultDatabaseName($dsn, $config)); @@ -141,6 +139,40 @@ public function getDatabaseName() return $this->getMongoDB()->getDatabaseName(); } + public function enableQueryLog() + { + parent::enableQueryLog(); + + if (! $this->commandSubscriber) { + $this->commandSubscriber = new CommandSubscriber($this); + $this->connection->addSubscriber($this->commandSubscriber); + } + } + + public function disableQueryLog() + { + parent::disableQueryLog(); + + if ($this->commandSubscriber) { + $this->connection->removeSubscriber($this->commandSubscriber); + $this->commandSubscriber = null; + } + } + + protected function withFreshQueryLog($callback) + { + try { + return parent::withFreshQueryLog($callback); + } finally { + // The parent method enable query log using enableQueryLog() + // but disables it by setting $loggingQueries to false. We need to + // remove the subscriber for performance. + if (! $this->loggingQueries) { + $this->disableQueryLog(); + } + } + } + /** * Get the name of the default database based on db config or try to detect it from dsn. * @@ -203,8 +235,7 @@ public function ping(): void /** @inheritdoc */ public function disconnect() { - $this->connection?->removeSubscriber($this->commandSubscriber); - $this->commandSubscriber = null; + $this->disableQueryLog(); $this->connection = null; } diff --git a/tests/ConnectionTest.php b/tests/ConnectionTest.php index 4f9dfa10c..fe3272943 100644 --- a/tests/ConnectionTest.php +++ b/tests/ConnectionTest.php @@ -277,6 +277,31 @@ public function testQueryLog() } } + public function testDisableQueryLog() + { + // Disabled by default + DB::table('items')->get(); + $this->assertCount(0, DB::getQueryLog()); + + DB::enableQueryLog(); + DB::table('items')->get(); + $this->assertCount(1, DB::getQueryLog()); + + // Enable twice should only log once + DB::enableQueryLog(); + DB::table('items')->get(); + $this->assertCount(2, DB::getQueryLog()); + + DB::disableQueryLog(); + DB::table('items')->get(); + $this->assertCount(2, DB::getQueryLog()); + + // Disable twice should not log + DB::disableQueryLog(); + DB::table('items')->get(); + $this->assertCount(2, DB::getQueryLog()); + } + public function testSchemaBuilder() { $schema = DB::connection('mongodb')->getSchemaBuilder(); From a964156964dc34f2ff008e73fe41b7b0791a8012 Mon Sep 17 00:00:00 2001 From: Fuyuki Date: Fri, 4 Oct 2024 23:59:44 +0800 Subject: [PATCH 374/446] Fix `Query\Builder::pluck()` with `ObjectId` as key (#3169) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Conversion of ObjectId to string is done in Laravel https://github.com/laravel/framework/blob/646520ad682d98b5211c6e26092259cfbe130b5c/src/Illuminate/Collections/Arr.php#L562 --------- Co-authored-by: Jérôme Tamarelle --- src/Query/Builder.php | 9 --------- tests/QueryBuilderTest.php | 11 +++++++++++ 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 372dcf633..eeb5ffe8d 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -851,15 +851,6 @@ public function pluck($column, $key = null) { $results = $this->get($key === null ? [$column] : [$column, $key]); - // Convert ObjectID's to strings - if (((string) $key) === '_id') { - $results = $results->map(function ($item) { - $item['_id'] = (string) $item['_id']; - - return $item; - }); - } - $p = Arr::pluck($results, $column, $key); return new Collection($p); diff --git a/tests/QueryBuilderTest.php b/tests/QueryBuilderTest.php index 523ad3411..136b1cf72 100644 --- a/tests/QueryBuilderTest.php +++ b/tests/QueryBuilderTest.php @@ -525,6 +525,17 @@ public function testPluck() $this->assertEquals([25], $age); } + public function testPluckObjectId() + { + $id = new ObjectId(); + DB::table('users')->insert([ + ['id' => $id, 'name' => 'Jane Doe'], + ]); + + $names = DB::table('users')->pluck('name', 'id')->toArray(); + $this->assertEquals([(string) $id => 'Jane Doe'], $names); + } + public function testList() { DB::table('items')->insert([ From 39558070786b400c3a82f22ad9da3b77eb99ceaa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 7 Oct 2024 10:37:33 +0200 Subject: [PATCH 375/446] PHPORM-207 Convert arrow notation -> to dot . (#3170) --- src/Query/Builder.php | 20 +++++++++++++++++++- tests/Query/BuilderTest.php | 10 ++++++++++ 2 files changed, 29 insertions(+), 1 deletion(-) diff --git a/src/Query/Builder.php b/src/Query/Builder.php index eeb5ffe8d..c62709ce5 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -66,6 +66,7 @@ use function property_exists; use function serialize; use function sprintf; +use function str_contains; use function str_ends_with; use function str_replace; use function str_starts_with; @@ -1616,7 +1617,24 @@ private function aliasIdForQuery(array $values): array } foreach ($values as $key => $value) { - if (is_string($key) && str_ends_with($key, '.id')) { + if (! is_string($key)) { + continue; + } + + // "->" arrow notation for subfields is an alias for "." dot notation + if (str_contains($key, '->')) { + $newkey = str_replace('->', '.', $key); + if (array_key_exists($newkey, $values) && $value !== $values[$newkey]) { + throw new InvalidArgumentException(sprintf('Cannot have both "%s" and "%s" fields.', $key, $newkey)); + } + + $values[$newkey] = $value; + unset($values[$key]); + $key = $newkey; + } + + // ".id" subfield are alias for "._id" + if (str_ends_with($key, '.id')) { $newkey = substr($key, 0, -3) . '._id'; if (array_key_exists($newkey, $values) && $value !== $values[$newkey]) { throw new InvalidArgumentException(sprintf('Cannot have both "%s" and "%s" fields.', $key, $newkey)); diff --git a/tests/Query/BuilderTest.php b/tests/Query/BuilderTest.php index c1587dc73..20f4a4db2 100644 --- a/tests/Query/BuilderTest.php +++ b/tests/Query/BuilderTest.php @@ -1406,6 +1406,16 @@ function (Builder $elemMatchQuery): void { ], ])->where('age', 15), ]; + + yield 'arrow notation' => [ + ['find' => [['data.format' => 1], []]], + fn (Builder $builder) => $builder->where('data->format', 1), + ]; + + yield 'arrow notation with id' => [ + ['find' => [['embedded._id' => 1], []]], + fn (Builder $builder) => $builder->where('embedded->id', 1), + ]; } #[DataProvider('provideExceptions')] From 05f5b74709c48716cab5e493ee3cca9a414de853 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Fri, 11 Oct 2024 13:22:01 -0400 Subject: [PATCH 376/446] DOCSP-43615: raw() field conversions (#3172) * DOCSP-43615: raw() ID conversion * utcdatetime * wording --- docs/upgrade.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/upgrade.txt b/docs/upgrade.txt index 3032b8e1e..d730435fa 100644 --- a/docs/upgrade.txt +++ b/docs/upgrade.txt @@ -114,12 +114,19 @@ This library version introduces the following breaking changes: - In query results, the library converts BSON ``UTCDateTime`` objects to ``Carbon`` date classes, applying the default timezone. + In v5.1, the library also performs this conversion to the ``Model::raw()`` + method results before hydrating a Model instance. + - ``id`` is an alias for the ``_id`` field in MongoDB documents, and the library automatically converts between ``id`` and ``_id`` when querying data. The query result object includes an ``id`` field to represent the document's ``_id`` field. Because of this behavior, you cannot have two separate ``id`` and ``_id`` fields in your documents. + In v5.1, the library also performs this conversion to the ``Model::raw()`` + method results before hydrating a Model instance. When passing a complex query + filter, use the ``DB::where()`` method instead of ``Model::raw()``. + - Removes support for the ``$collection`` property. The following code shows how to assign a MongoDB collection to a variable in your ``User`` class in older versions compared to v5.0: From 99af0359da6dcf32f9e16e650693f9476b469084 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Fri, 11 Oct 2024 13:33:13 -0400 Subject: [PATCH 377/446] DOCSP-44172: Laravel Herd (#3171) Adds information about Laravel Herd to the quick start --- docs/quick-start/download-and-install.txt | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/quick-start/download-and-install.txt b/docs/quick-start/download-and-install.txt index 5e9139ec8..f4e480ce5 100644 --- a/docs/quick-start/download-and-install.txt +++ b/docs/quick-start/download-and-install.txt @@ -28,6 +28,19 @@ Download and Install the Dependencies Complete the following steps to install and add the {+odm-short+} dependencies to a Laravel web application. +.. tip:: + + As an alternative to the following installation steps, you can use Laravel Herd + to install MongoDB and configure a Laravel MongoDB development environment. For + more information about using Laravel Herd with MongoDB, see the following resources: + + - `Installing MongoDB via Herd Pro + `__ in the Herd + documentation + - `Laravel Herd Adds Native MongoDB Support + `__ + in the MongoDB Developer Center + .. procedure:: :style: connected From 9108d27e38fb8c7429e8ce32eb0d1127cf4059fe Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Fri, 11 Oct 2024 14:40:29 -0400 Subject: [PATCH 378/446] Docs changes v5.1 (#3174) Adds raw() field conversions and Laravel Herd information --- docs/quick-start/download-and-install.txt | 13 +++++++++++++ docs/upgrade.txt | 7 +++++++ 2 files changed, 20 insertions(+) diff --git a/docs/quick-start/download-and-install.txt b/docs/quick-start/download-and-install.txt index 5e9139ec8..f4e480ce5 100644 --- a/docs/quick-start/download-and-install.txt +++ b/docs/quick-start/download-and-install.txt @@ -28,6 +28,19 @@ Download and Install the Dependencies Complete the following steps to install and add the {+odm-short+} dependencies to a Laravel web application. +.. tip:: + + As an alternative to the following installation steps, you can use Laravel Herd + to install MongoDB and configure a Laravel MongoDB development environment. For + more information about using Laravel Herd with MongoDB, see the following resources: + + - `Installing MongoDB via Herd Pro + `__ in the Herd + documentation + - `Laravel Herd Adds Native MongoDB Support + `__ + in the MongoDB Developer Center + .. procedure:: :style: connected diff --git a/docs/upgrade.txt b/docs/upgrade.txt index 3032b8e1e..d730435fa 100644 --- a/docs/upgrade.txt +++ b/docs/upgrade.txt @@ -114,12 +114,19 @@ This library version introduces the following breaking changes: - In query results, the library converts BSON ``UTCDateTime`` objects to ``Carbon`` date classes, applying the default timezone. + In v5.1, the library also performs this conversion to the ``Model::raw()`` + method results before hydrating a Model instance. + - ``id`` is an alias for the ``_id`` field in MongoDB documents, and the library automatically converts between ``id`` and ``_id`` when querying data. The query result object includes an ``id`` field to represent the document's ``_id`` field. Because of this behavior, you cannot have two separate ``id`` and ``_id`` fields in your documents. + In v5.1, the library also performs this conversion to the ``Model::raw()`` + method results before hydrating a Model instance. When passing a complex query + filter, use the ``DB::where()`` method instead of ``Model::raw()``. + - Removes support for the ``$collection`` property. The following code shows how to assign a MongoDB collection to a variable in your ``User`` class in older versions compared to v5.0: From f6536fe87b1ab6d417021a66e72ef68a53cd085f Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Fri, 11 Oct 2024 15:12:18 -0400 Subject: [PATCH 379/446] DOCSP-44158: Convert arrow to dot notation (#3173) Adds information about dot and arrow notation conversion in v5.1 --- docs/query-builder.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/query-builder.txt b/docs/query-builder.txt index 2bb6f75f2..cac12a368 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -221,6 +221,13 @@ value greater than ``8.5`` and a ``year`` value of less than :start-after: begin query andWhere :end-before: end query andWhere +.. tip:: + + For compatibility with Laravel, Laravel MongoDB v5.1 supports both arrow + (``->``) and dot (``.``) notation to access nested fields in a query + filter. The preceding example uses dot notation to query the ``imdb.rating`` + nested field, which is the recommended syntax. + .. _laravel-query-builder-logical-not: Logical NOT Example From 78707488b2ced3a925eb1924708cde173841fef2 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Fri, 11 Oct 2024 15:54:49 -0400 Subject: [PATCH 380/446] DOCSP-44177: 5.1 compatibility (#3177) Compatibility table updates for v5.1 --- docs/compatibility.txt | 2 +- docs/includes/framework-compatibility-laravel.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/compatibility.txt b/docs/compatibility.txt index fb253f888..fd3e2da02 100644 --- a/docs/compatibility.txt +++ b/docs/compatibility.txt @@ -15,7 +15,7 @@ Compatibility :class: singlecol .. meta:: - :keywords: laravel 9, laravel 10, laravel 11, 4.0, 4.1, 4.2, 5.0 + :keywords: laravel 9, laravel 10, laravel 11, 4.0, 4.1, 4.2, 5.0, 5.1 Laravel Compatibility --------------------- diff --git a/docs/includes/framework-compatibility-laravel.rst b/docs/includes/framework-compatibility-laravel.rst index bdfbd4d4c..16c405e21 100644 --- a/docs/includes/framework-compatibility-laravel.rst +++ b/docs/includes/framework-compatibility-laravel.rst @@ -7,7 +7,7 @@ - Laravel 10.x - Laravel 9.x - * - 4.2 to 5.0 + * - 4.2 to 5.1 - ✓ - ✓ - From 7d6073dc124edc78583f8fde6a7136e2402bc8fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 15 Oct 2024 22:21:53 +0200 Subject: [PATCH 381/446] Typo in upgrade doc (#3180) --- docs/upgrade.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/upgrade.txt b/docs/upgrade.txt index d730435fa..a87d314a2 100644 --- a/docs/upgrade.txt +++ b/docs/upgrade.txt @@ -71,7 +71,7 @@ Version 5.x Breaking Changes This library version introduces the following breaking changes: -- The query builder returns results as as ``stdClass`` objects instead +- The query builder returns results as ``stdClass`` objects instead of as arrays. This change requires that you change array access to property access when interacting with query results. From 4123effc03f8e0f75381aa30d99532880d92ea1d Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Thu, 24 Oct 2024 15:29:52 -0400 Subject: [PATCH 382/446] DOCSP-44610: fix php links (#3185) * DOCSP-44610: fix php links * use php directive --- docs/eloquent-models/model-class.txt | 6 +++--- docs/fundamentals/connection/tls.txt | 5 +++-- docs/quick-start/download-and-install.txt | 4 ++-- 3 files changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/eloquent-models/model-class.txt b/docs/eloquent-models/model-class.txt index 8cedb4ece..4f5ae61b7 100644 --- a/docs/eloquent-models/model-class.txt +++ b/docs/eloquent-models/model-class.txt @@ -190,8 +190,8 @@ retrieving data by using a casting helper. This helper is a convenient alternative to defining equivalent accessor and mutator methods on your model. In the following example, the casting helper converts the ``discovery_dt`` -model attribute, stored in MongoDB as a `MongoDB\\BSON\\UTCDateTime `__ -type, to the Laravel ``datetime`` type. +model attribute, stored in MongoDB as a :php:`MongoDB\\BSON\\UTCDateTime +` type, to the Laravel ``datetime`` type. .. literalinclude:: /includes/eloquent-models/PlanetDate.php :language: php @@ -216,7 +216,7 @@ type, to the Laravel ``datetime`` type. To learn more, see `Attribute Casting `__ in the Laravel documentation. -This conversion lets you use the PHP `DateTime `__ +This conversion lets you use the PHP :php:`DateTime ` or the `Carbon class `__ to work with dates in this field. The following example shows a Laravel query that uses the casting helper on the model to query for planets with a ``discovery_dt`` of diff --git a/docs/fundamentals/connection/tls.txt b/docs/fundamentals/connection/tls.txt index 793157286..9bf98248b 100644 --- a/docs/fundamentals/connection/tls.txt +++ b/docs/fundamentals/connection/tls.txt @@ -188,8 +188,9 @@ The following example configures a connection with TLS enabled: Additional Information ---------------------- -To learn more about setting URI options, see the `MongoDB\Driver\Manager::__construct() -`__ +To learn more about setting URI options, see the +:php:`MongoDB\\Driver\\Manager::__construct() +` API documentation. To learn more about enabling TLS on a connection, see the diff --git a/docs/quick-start/download-and-install.txt b/docs/quick-start/download-and-install.txt index 5e9139ec8..23cb9b440 100644 --- a/docs/quick-start/download-and-install.txt +++ b/docs/quick-start/download-and-install.txt @@ -35,8 +35,8 @@ to a Laravel web application. {+odm-long+} requires the {+php-extension+} to manage MongoDB connections and commands. - Follow the `Installing the MongoDB PHP Driver with PECL `__ - guide to install the {+php-extension+}. + Follow the :php:`Installing the MongoDB PHP Driver with PECL + ` guide to install the {+php-extension+}. .. step:: Install Laravel From 05a090bc951403fb9a99cce7548ec7abf0140328 Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Wed, 6 Nov 2024 13:31:40 +0100 Subject: [PATCH 383/446] Don't add invalid regions to SARIF report (#3193) --- phpstan.neon.dist | 2 +- tests/PHPStan/SarifErrorFormatter.php | 7 ++++--- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/phpstan.neon.dist b/phpstan.neon.dist index 539536a11..926d9e726 100644 --- a/phpstan.neon.dist +++ b/phpstan.neon.dist @@ -13,7 +13,7 @@ parameters: ignoreErrors: - '#Unsafe usage of new static#' - - '#Call to an undefined method [a-zA-Z0-9\\_\<\>]+::[a-zA-Z]+\(\)#' + - '#Call to an undefined method [a-zA-Z0-9\\_\<\>\(\)]+::[a-zA-Z]+\(\)#' services: errorFormatter.sarif: diff --git a/tests/PHPStan/SarifErrorFormatter.php b/tests/PHPStan/SarifErrorFormatter.php index 1fb814cde..5ffd07e5f 100644 --- a/tests/PHPStan/SarifErrorFormatter.php +++ b/tests/PHPStan/SarifErrorFormatter.php @@ -63,9 +63,6 @@ public function formatErrors(AnalysisResult $analysisResult, Output $output): in 'uri' => $this->relativePathHelper->getRelativePath($fileSpecificError->getFile()), 'uriBaseId' => self::URI_BASE_ID, ], - 'region' => [ - 'startLine' => $fileSpecificError->getLine(), - ], ], ], ], @@ -78,6 +75,10 @@ public function formatErrors(AnalysisResult $analysisResult, Output $output): in $result['properties']['tip'] = $fileSpecificError->getTip(); } + if ($fileSpecificError->getLine() !== null) { + $result['locations'][0]['physicalLocation']['region']['startLine'] = $fileSpecificError->getLine(); + } + $results[] = $result; } From 8cf9f66fee93f0b7e1f461948e37b2f18405e1b5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 6 Nov 2024 14:27:25 +0100 Subject: [PATCH 384/446] PHPORM-259 Register MongoDB Session Handler with `SESSION_DRIVER=mongodb` (#3192) * PHPORM-259 Register MongoDB Session Handler with SESSION_DRIVER=mongodb * Explicit dependency to symfony/http-foundation --- composer.json | 3 ++- phpstan-baseline.neon | 5 ++++ src/MongoDBServiceProvider.php | 21 +++++++++++++++++ tests/SessionTest.php | 43 +++++++++++++++++++++++++++++++++- 4 files changed, 70 insertions(+), 2 deletions(-) diff --git a/composer.json b/composer.json index 9c958f1c4..68ec8bc4f 100644 --- a/composer.json +++ b/composer.json @@ -30,7 +30,8 @@ "illuminate/database": "^10.30|^11", "illuminate/events": "^10.0|^11", "illuminate/support": "^10.0|^11", - "mongodb/mongodb": "^1.18" + "mongodb/mongodb": "^1.18", + "symfony/http-foundation": "^6.4|^7" }, "require-dev": { "mongodb/builder": "^0.2", diff --git a/phpstan-baseline.neon b/phpstan-baseline.neon index e85adb7d2..7b34210ad 100644 --- a/phpstan-baseline.neon +++ b/phpstan-baseline.neon @@ -5,6 +5,11 @@ parameters: count: 3 path: src/MongoDBBusServiceProvider.php + - + message: "#^Access to an undefined property Illuminate\\\\Foundation\\\\Application\\:\\:\\$config\\.$#" + count: 4 + path: src/MongoDBServiceProvider.php + - message: "#^Method Illuminate\\\\Database\\\\Eloquent\\\\Model\\:\\:push\\(\\) invoked with 3 parameters, 0 required\\.$#" count: 3 diff --git a/src/MongoDBServiceProvider.php b/src/MongoDBServiceProvider.php index 0932048c9..9db2122dc 100644 --- a/src/MongoDBServiceProvider.php +++ b/src/MongoDBServiceProvider.php @@ -10,6 +10,7 @@ use Illuminate\Filesystem\FilesystemAdapter; use Illuminate\Filesystem\FilesystemManager; use Illuminate\Foundation\Application; +use Illuminate\Session\SessionManager; use Illuminate\Support\ServiceProvider; use InvalidArgumentException; use League\Flysystem\Filesystem; @@ -20,6 +21,7 @@ use MongoDB\Laravel\Eloquent\Model; use MongoDB\Laravel\Queue\MongoConnector; use RuntimeException; +use Symfony\Component\HttpFoundation\Session\Storage\Handler\MongoDbSessionHandler; use function assert; use function class_exists; @@ -53,6 +55,25 @@ public function register() }); }); + // Session handler for MongoDB + $this->app->resolving(SessionManager::class, function (SessionManager $sessionManager) { + $sessionManager->extend('mongodb', function (Application $app) { + $connectionName = $app->config->get('session.connection') ?: 'mongodb'; + $connection = $app->make('db')->connection($connectionName); + + assert($connection instanceof Connection, new InvalidArgumentException(sprintf('The database connection "%s" used for the session does not use the "mongodb" driver.', $connectionName))); + + return new MongoDbSessionHandler( + $connection->getMongoClient(), + $app->config->get('session.options', []) + [ + 'database' => $connection->getDatabaseName(), + 'collection' => $app->config->get('session.table') ?: 'sessions', + 'ttl' => $app->config->get('session.lifetime'), + ], + ); + }); + }); + // Add cache and lock drivers. $this->app->resolving('cache', function (CacheManager $cache) { $cache->extend('mongodb', function (Application $app, array $config): Repository { diff --git a/tests/SessionTest.php b/tests/SessionTest.php index 7ffbb51f0..ee086f5b8 100644 --- a/tests/SessionTest.php +++ b/tests/SessionTest.php @@ -3,7 +3,9 @@ namespace MongoDB\Laravel\Tests; use Illuminate\Session\DatabaseSessionHandler; +use Illuminate\Session\SessionManager; use Illuminate\Support\Facades\DB; +use Symfony\Component\HttpFoundation\Session\Storage\Handler\MongoDbSessionHandler; class SessionTest extends TestCase { @@ -14,7 +16,7 @@ protected function tearDown(): void parent::tearDown(); } - public function testDatabaseSessionHandler() + public function testDatabaseSessionHandlerCompatibility() { $sessionId = '123'; @@ -30,4 +32,43 @@ public function testDatabaseSessionHandler() $handler->write($sessionId, 'bar'); $this->assertEquals('bar', $handler->read($sessionId)); } + + public function testDatabaseSessionHandlerRegistration() + { + $this->app['config']->set('session.driver', 'database'); + $this->app['config']->set('session.connection', 'mongodb'); + + $session = $this->app['session']; + $this->assertInstanceOf(SessionManager::class, $session); + $this->assertInstanceOf(DatabaseSessionHandler::class, $session->getHandler()); + + $this->assertSessionCanStoreInMongoDB($session); + } + + public function testMongoDBSessionHandlerRegistration() + { + $this->app['config']->set('session.driver', 'mongodb'); + $this->app['config']->set('session.connection', 'mongodb'); + + $session = $this->app['session']; + $this->assertInstanceOf(SessionManager::class, $session); + $this->assertInstanceOf(MongoDbSessionHandler::class, $session->getHandler()); + + $this->assertSessionCanStoreInMongoDB($session); + } + + private function assertSessionCanStoreInMongoDB(SessionManager $session): void + { + $session->put('foo', 'bar'); + $session->save(); + + $this->assertNotNull($session->getId()); + + $data = DB::connection('mongodb') + ->getCollection('sessions') + ->findOne(['_id' => $session->getId()]); + + self::assertIsObject($data); + self::assertSame($session->getId(), $data->_id); + } } From c23cadd9ad34fccfa9e01594ec060171c098a2fe Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Thu, 7 Nov 2024 12:02:34 -0500 Subject: [PATCH 385/446] DOCSP-42964: Remove nested component (#3198) --- docs/fundamentals/connection/connect-to-mongodb.txt | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/fundamentals/connection/connect-to-mongodb.txt b/docs/fundamentals/connection/connect-to-mongodb.txt index d17bcf2be..f18d3b399 100644 --- a/docs/fundamentals/connection/connect-to-mongodb.txt +++ b/docs/fundamentals/connection/connect-to-mongodb.txt @@ -136,10 +136,8 @@ For a MongoDB database connection, you can specify the following details: 'host' => ['node1.example.com:27017', 'node2.example.com:27017', 'node3.example.com:27017'], - .. note:: - - This option does not accept hosts that use the DNS seedlist - connection format. + | This option does not accept hosts that use the DNS seedlist + connection format. * - ``database`` - Specifies the name of the MongoDB database to read and write to. From bbff3cb58ffad37964573d211a16deb01c194b1c Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Mon, 11 Nov 2024 12:29:24 +0100 Subject: [PATCH 386/446] Disable mongoc_client reuse between connections (#3197) --- src/Connection.php | 4 ++++ tests/ConnectionTest.php | 28 ++++++++++++++++++++++++++++ 2 files changed, 32 insertions(+) diff --git a/src/Connection.php b/src/Connection.php index 84ca97aba..592e500e5 100644 --- a/src/Connection.php +++ b/src/Connection.php @@ -217,6 +217,10 @@ protected function createConnection(string $dsn, array $config, array $options): $options['password'] = $config['password']; } + if (isset($config['name'])) { + $driverOptions += ['connectionName' => $config['name']]; + } + return new Client($dsn, $options, $driverOptions); } diff --git a/tests/ConnectionTest.php b/tests/ConnectionTest.php index fe3272943..affb6bd8a 100644 --- a/tests/ConnectionTest.php +++ b/tests/ConnectionTest.php @@ -277,6 +277,34 @@ public function testQueryLog() } } + public function testQueryLogWithMultipleClients() + { + $connection = DB::connection('mongodb'); + $this->assertInstanceOf(Connection::class, $connection); + + // Create a second connection with the same config as the first + // Make sure to change the name as it's used as a connection identifier + $config = $connection->getConfig(); + $config['name'] = 'mongodb2'; + $secondConnection = new Connection($config); + + $connection->enableQueryLog(); + $secondConnection->enableQueryLog(); + + $this->assertCount(0, $connection->getQueryLog()); + $this->assertCount(0, $secondConnection->getQueryLog()); + + $connection->table('items')->get(); + + $this->assertCount(1, $connection->getQueryLog()); + $this->assertCount(0, $secondConnection->getQueryLog()); + + $secondConnection->table('items')->get(); + + $this->assertCount(1, $connection->getQueryLog()); + $this->assertCount(1, $secondConnection->getQueryLog()); + } + public function testDisableQueryLog() { // Disabled by default From 4b91f7731a98b64bb4d93c11a5f5cb9ef7340ada Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Thu, 14 Nov 2024 21:19:52 +0100 Subject: [PATCH 387/446] Increase connection timeouts to allow using Atlas shared clusters (#3206) --- tests/ConnectionTest.php | 4 ++-- tests/config/database.php | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/tests/ConnectionTest.php b/tests/ConnectionTest.php index affb6bd8a..1efd17be0 100644 --- a/tests/ConnectionTest.php +++ b/tests/ConnectionTest.php @@ -350,8 +350,8 @@ public function testPingMethod() 'dsn' => env('MONGODB_URI', 'mongodb://127.0.0.1/'), 'database' => 'unittest', 'options' => [ - 'connectTimeoutMS' => 100, - 'serverSelectionTimeoutMS' => 250, + 'connectTimeoutMS' => 1000, + 'serverSelectionTimeoutMS' => 6000, ], ]; diff --git a/tests/config/database.php b/tests/config/database.php index 275dce61a..8a22d766c 100644 --- a/tests/config/database.php +++ b/tests/config/database.php @@ -10,8 +10,8 @@ 'dsn' => env('MONGODB_URI', 'mongodb://127.0.0.1/'), 'database' => env('MONGODB_DATABASE', 'unittest'), 'options' => [ - 'connectTimeoutMS' => 100, - 'serverSelectionTimeoutMS' => 250, + 'connectTimeoutMS' => 1000, + 'serverSelectionTimeoutMS' => 6000, ], ], From da3a46a1b4ca25117c1d388dd6348206d04e4a9f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 20 Nov 2024 16:01:02 +0100 Subject: [PATCH 388/446] PHPORM-263 Fix deprecation message for collection/table config in MongoDBQueueServiceProvider (#3209) --- src/MongoDBQueueServiceProvider.php | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/MongoDBQueueServiceProvider.php b/src/MongoDBQueueServiceProvider.php index ea7a06176..eaa455603 100644 --- a/src/MongoDBQueueServiceProvider.php +++ b/src/MongoDBQueueServiceProvider.php @@ -54,15 +54,15 @@ protected function registerFailedJobServices() */ protected function mongoFailedJobProvider(array $config): MongoFailedJobProvider { - if (! isset($config['collection']) && isset($config['table'])) { - trigger_error('Since mongodb/laravel-mongodb 4.4: Using "table" option for the queue is deprecated. Use "collection" instead.', E_USER_DEPRECATED); - $config['collection'] = $config['table']; + if (! isset($config['table']) && isset($config['collection'])) { + trigger_error('Since mongodb/laravel-mongodb 4.4: Using "collection" option for the queue is deprecated. Use "table" instead.', E_USER_DEPRECATED); + $config['table'] = $config['collection']; } return new MongoFailedJobProvider( $this->app['db'], $config['database'] ?? null, - $config['collection'] ?? 'failed_jobs', + $config['table'] ?? 'failed_jobs', ); } } From 0af56113bf8b123940911a32ec77d9e5c4212d3c Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Wed, 20 Nov 2024 10:29:33 -0500 Subject: [PATCH 389/446] DOCSP-45411: qb options (#3208) * DOCSP-45411: qb options * link * NR PR fixes 1 --- .../query-builder/QueryBuilderTest.php | 13 ++++++ docs/query-builder.txt | 44 ++++++++++++++++--- 2 files changed, 51 insertions(+), 6 deletions(-) diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index 46822f257..229db2867 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -46,6 +46,19 @@ protected function tearDown(): void parent::tearDown(); } + public function testOptions(): void + { + // begin options + $result = DB::connection('mongodb') + ->table('movies') + ->where('year', 2000) + ->options(['comment' => 'hello']) + ->get(); + // end options + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + public function testWhere(): void { // begin query where diff --git a/docs/query-builder.txt b/docs/query-builder.txt index 7d33c016d..649cdde34 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -46,15 +46,19 @@ The following example shows the syntax of a query builder call: DB::table('') // chain methods by using the "->" object operator ->get(); + .. tip:: - Before using the ``DB::table()`` method, ensure that you specify MongoDB as your application's - default database connection. For instructions on setting the database connection, - see the :ref:`laravel-quick-start-connect-to-mongodb` step in the Quick Start. + Before using the ``DB::table()`` method, ensure that you specify + MongoDB as your application's default database connection. For + instructions on setting the database connection, see the + :ref:`laravel-quick-start-connect-to-mongodb` step in the Quick + Start. - If MongoDB is not your application's default database, you can use the ``DB::connection()`` method - to specify a MongoDB connection. Pass the name of the connection to the ``connection()`` method, - as shown in the following code: + If MongoDB is not your application's default database, you can use + the ``DB::connection()`` method to specify a MongoDB connection. Pass + the name of the connection to the ``connection()`` method, as shown + in the following code: .. code-block:: php @@ -63,6 +67,7 @@ The following example shows the syntax of a query builder call: This guide provides examples of the following types of query builder operations: - :ref:`laravel-retrieve-query-builder` +- :ref:`laravel-options-query-builder` - :ref:`laravel-modify-results-query-builder` - :ref:`laravel-mongodb-read-query-builder` - :ref:`laravel-mongodb-write-query-builder` @@ -606,6 +611,33 @@ value of ``imdb.rating`` of those matches by using the :start-after: begin aggregation with filter :end-before: end aggregation with filter +.. _laravel-options-query-builder: + +Set Query-Level Options +----------------------- + +You can modify the way that the {+odm-short+} performs operations by +setting options on the query builder. You can pass an array of options +to the ``options()`` query builder method to specify options for the +query. + +The following code demonstrates how to attach a comment to +a query: + +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin options + :end-before: end options + +The query builder accepts the same options that you can set for +the :phpmethod:`find() ` method in the +{+php-library+}. Some of the options to modify query results, such as +``skip``, ``sort``, and ``limit``, are settable directly as query +builder methods and are described in the +:ref:`laravel-modify-results-query-builder` section of this guide. We +recommend that you use these methods instead of passing them as options. + .. _laravel-modify-results-query-builder: Modify Query Results From 3971a24277569c417def49078a8e1225c192a5fe Mon Sep 17 00:00:00 2001 From: lindseymoore <71525840+lindseymoore@users.noreply.github.com> Date: Fri, 22 Nov 2024 17:08:41 -0500 Subject: [PATCH 390/446] DOCSP-44949 TOC Relabel (#3204) * DOCSP-44949 TOC Relabel * indent --- docs/eloquent-models.txt | 12 ++++++------ docs/fundamentals.txt | 10 +++++----- docs/fundamentals/connection.txt | 6 +++--- docs/index.txt | 28 ++++++++++++++-------------- docs/quick-start.txt | 21 ++++++++++----------- docs/usage-examples.txt | 32 ++++++++++++++++---------------- 6 files changed, 54 insertions(+), 55 deletions(-) diff --git a/docs/eloquent-models.txt b/docs/eloquent-models.txt index 8aee6baf7..316313849 100644 --- a/docs/eloquent-models.txt +++ b/docs/eloquent-models.txt @@ -11,6 +11,12 @@ Eloquent Models .. meta:: :keywords: php framework, odm +.. toctree:: + + Eloquent Model Class + Relationships + Schema Builder + Eloquent models are part of the Laravel Eloquent object-relational mapping (ORM) framework, which lets you to work with data in a relational database by using model classes and Eloquent syntax. The {+odm-short+} extends @@ -26,9 +32,3 @@ the {+odm-short+} to work with MongoDB in the following ways: between models - :ref:`laravel-schema-builder` shows how to manage indexes on your MongoDB collections by using Laravel migrations - -.. toctree:: - - /eloquent-models/model-class/ - Relationships - Schema Builder diff --git a/docs/fundamentals.txt b/docs/fundamentals.txt index f0945ad63..db482b2b8 100644 --- a/docs/fundamentals.txt +++ b/docs/fundamentals.txt @@ -15,11 +15,11 @@ Fundamentals :titlesonly: :maxdepth: 1 - /fundamentals/connection - /fundamentals/database-collection - /fundamentals/read-operations - /fundamentals/write-operations - /fundamentals/aggregation-builder + Connections + Databases & Collections + Read Operations + Write Operations + Aggregation Builder Learn more about the following concepts related to {+odm-long+}: diff --git a/docs/fundamentals/connection.txt b/docs/fundamentals/connection.txt index 26a937323..2434448ab 100644 --- a/docs/fundamentals/connection.txt +++ b/docs/fundamentals/connection.txt @@ -13,9 +13,9 @@ Connections .. toctree:: - /fundamentals/connection/connect-to-mongodb - /fundamentals/connection/connection-options - /fundamentals/connection/tls + Connection Guide + Connection Options + Configure TLS .. contents:: On this page :local: diff --git a/docs/index.txt b/docs/index.txt index 12269e0c4..d97eae635 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -13,21 +13,21 @@ :titlesonly: :maxdepth: 1 - /quick-start - /usage-examples + Quick Start + Usage Examples Release Notes - /fundamentals - /eloquent-models - /query-builder - /user-authentication - /cache - /queues - /transactions - /filesystems - /issues-and-help - /feature-compatibility - /compatibility - /upgrade + Fundamentals + Eloquent Models + Query Builder + User Authentication + Cache & Locks + Queues + Transactions + GridFS Filesystems + Issues & Help + Feature Compatibility + Compatibility + Upgrade Introduction ------------ diff --git a/docs/quick-start.txt b/docs/quick-start.txt index 39d8ba0b4..1d188ad84 100644 --- a/docs/quick-start.txt +++ b/docs/quick-start.txt @@ -17,6 +17,16 @@ Quick Start :depth: 1 :class: singlecol +.. toctree:: + + Download & Install + Create a Deployment + Create a Connection String + Configure Your Connection + View Data + Write Data + Next Steps + Overview -------- @@ -55,14 +65,3 @@ that connects to a MongoDB deployment. You can download the complete web application project by cloning the `laravel-quickstart `__ GitHub repository. - -.. toctree:: - - /quick-start/download-and-install/ - /quick-start/create-a-deployment/ - /quick-start/create-a-connection-string/ - /quick-start/configure-mongodb/ - /quick-start/view-data/ - /quick-start/write-data/ - /quick-start/next-steps/ - diff --git a/docs/usage-examples.txt b/docs/usage-examples.txt index a17fd1b70..87a87df88 100644 --- a/docs/usage-examples.txt +++ b/docs/usage-examples.txt @@ -17,6 +17,22 @@ Usage Examples :depth: 2 :class: singlecol +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Find a Document + Find Multiple Documents + Insert a Document + Insert Multiple Documents + Update a Document + Update Multiple Documents + Delete a Document + Delete Multiple Documents + Count Documents + Distinct Field Values + Run a Command + Overview -------- @@ -89,19 +105,3 @@ See code examples of the following operations in this section: - :ref:`laravel-count-usage` - :ref:`laravel-distinct-usage` - :ref:`laravel-run-command-usage` - -.. toctree:: - :titlesonly: - :maxdepth: 1 - - /usage-examples/findOne - /usage-examples/find - /usage-examples/insertOne - /usage-examples/insertMany - /usage-examples/updateOne - /usage-examples/updateMany - /usage-examples/deleteOne - /usage-examples/deleteMany - /usage-examples/count - /usage-examples/distinct - /usage-examples/runCommand From 3ac8c216fcd9f081b482f439fe406cd264deaa56 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Mon, 2 Dec 2024 10:01:58 -0500 Subject: [PATCH 391/446] DOCSP-42020: queues feedback (#3221) * DOCSP-42020: queues feedback * JS small fix --- docs/queues.txt | 39 +++++++++++++++++++++++---------------- 1 file changed, 23 insertions(+), 16 deletions(-) diff --git a/docs/queues.txt b/docs/queues.txt index 5e25d868b..f2a3106f7 100644 --- a/docs/queues.txt +++ b/docs/queues.txt @@ -11,6 +11,16 @@ Queues .. meta:: :keywords: php framework, odm, code example, jobs +Overview +-------- + +In this guide, you can learn how to use MongoDB as your database for +Laravel Queue. Laravel Queue allows you to create queued jobs that are +processed in the background. + +Configuration +------------- + To use MongoDB as your database for Laravel Queue, change the driver in your application's ``config/queue.php`` file: @@ -22,7 +32,7 @@ the driver in your application's ``config/queue.php`` file: // You can also specify your jobs-specific database // in the config/database.php file 'connection' => 'mongodb', - 'collection' => 'jobs', + 'table' => 'jobs', 'queue' => 'default', // Optional setting // 'retry_after' => 60, @@ -48,7 +58,7 @@ the behavior of the queue: ``mongodb`` connection. The driver uses the default connection if a connection is not specified. - * - ``collection`` + * - ``table`` - **Required** Name of the MongoDB collection to store jobs to process. @@ -60,7 +70,7 @@ the behavior of the queue: before retrying a job that is being processed. The value is ``60`` by default. -To use MongoDB to handle failed jobs, create a ``failed`` entry in your +To use MongoDB to handle *failed jobs*, create a ``failed`` entry in your application's ``config/queue.php`` file and specify the database and collection: @@ -69,7 +79,7 @@ collection: 'failed' => [ 'driver' => 'mongodb', 'database' => 'mongodb', - 'collection' => 'failed_jobs', + 'table' => 'failed_jobs', ], The following table describes properties that you can specify to configure @@ -91,16 +101,13 @@ how to handle failed jobs: a ``mongodb`` connection. The driver uses the default connection if a connection is not specified. - * - ``collection`` + * - ``table`` - Name of the MongoDB collection to store failed jobs. The value is ``failed_jobs`` by default. -Then, add the service provider in your application's -``config/app.php`` file: - -.. code-block:: php - - MongoDB\Laravel\MongoDBQueueServiceProvider::class, +The {+odm-short+} automatically provides the +``MongoDB\Laravel\MongoDBQueueServiceProvider::class`` class as the +service provider to handle failed jobs. Job Batching ------------ @@ -124,7 +131,7 @@ application's ``config/queue.php`` file: 'batching' => [ 'driver' => 'mongodb', 'database' => 'mongodb', - 'collection' => 'job_batches', + 'table' => 'job_batches', ], The following table describes properties that you can specify to configure @@ -146,13 +153,13 @@ job batching: ``mongodb`` connection. The driver uses the default connection if a connection is not specified. - * - ``collection`` + * - ``table`` - Name of the MongoDB collection to store job batches. The value is ``job_batches`` by default. Then, add the service provider in your application's ``config/app.php`` file: -.. code-block:: php - - MongoDB\Laravel\MongoDBBusServiceProvider::class, +The {+odm-short+} automatically provides the +``MongoDB\Laravel\MongoDBBusServiceProvider::class`` class as the +service provider for job batching. From bd9c0a80e57732bd819721b5648b5d66fc5363be Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Mon, 2 Dec 2024 10:08:36 -0500 Subject: [PATCH 392/446] DOCSP-42020: queues feedback 5.0 (#3222) * DOCSP-42020: queues feedback (cherry picked from commit 830ba9f2ab00f637c30e1f2526ea4b18ddc4ab0c) * DOCSP-42020: queues feedback - 5.0+ * JS small fix * replace cxn with db in tables --- docs/queues.txt | 45 +++++++++++++++++++++++++++------------------ 1 file changed, 27 insertions(+), 18 deletions(-) diff --git a/docs/queues.txt b/docs/queues.txt index 5e25d868b..951853084 100644 --- a/docs/queues.txt +++ b/docs/queues.txt @@ -11,6 +11,16 @@ Queues .. meta:: :keywords: php framework, odm, code example, jobs +Overview +-------- + +In this guide, you can learn how to use MongoDB as your database for +Laravel Queue. Laravel Queue allows you to create queued jobs that are +processed in the background. + +Configuration +------------- + To use MongoDB as your database for Laravel Queue, change the driver in your application's ``config/queue.php`` file: @@ -22,7 +32,7 @@ the driver in your application's ``config/queue.php`` file: // You can also specify your jobs-specific database // in the config/database.php file 'connection' => 'mongodb', - 'collection' => 'jobs', + 'table' => 'jobs', 'queue' => 'default', // Optional setting // 'retry_after' => 60, @@ -48,7 +58,7 @@ the behavior of the queue: ``mongodb`` connection. The driver uses the default connection if a connection is not specified. - * - ``collection`` + * - ``table`` - **Required** Name of the MongoDB collection to store jobs to process. @@ -60,7 +70,7 @@ the behavior of the queue: before retrying a job that is being processed. The value is ``60`` by default. -To use MongoDB to handle failed jobs, create a ``failed`` entry in your +To use MongoDB to handle *failed jobs*, create a ``failed`` entry in your application's ``config/queue.php`` file and specify the database and collection: @@ -69,7 +79,7 @@ collection: 'failed' => [ 'driver' => 'mongodb', 'database' => 'mongodb', - 'collection' => 'failed_jobs', + 'table' => 'failed_jobs', ], The following table describes properties that you can specify to configure @@ -86,21 +96,20 @@ how to handle failed jobs: - **Required** Queue driver to use. The value of this property must be ``mongodb``. - * - ``connection`` + * - ``database`` - Database connection used to store jobs. It must be a ``mongodb`` connection. The driver uses the default connection if a connection is not specified. - * - ``collection`` + * - ``table`` - Name of the MongoDB collection to store failed jobs. The value is ``failed_jobs`` by default. -Then, add the service provider in your application's -``config/app.php`` file: - -.. code-block:: php - - MongoDB\Laravel\MongoDBQueueServiceProvider::class, +To register failed jobs, you can use the default failed +job provider from Laravel. To learn more, see +`Dealing With Failed Jobs +`__ in +the Laravel documentation on Queues. Job Batching ------------ @@ -124,7 +133,7 @@ application's ``config/queue.php`` file: 'batching' => [ 'driver' => 'mongodb', 'database' => 'mongodb', - 'collection' => 'job_batches', + 'table' => 'job_batches', ], The following table describes properties that you can specify to configure @@ -141,18 +150,18 @@ job batching: - **Required** Queue driver to use. The value of this property must be ``mongodb``. - * - ``connection`` + * - ``database`` - Database connection used to store jobs. It must be a ``mongodb`` connection. The driver uses the default connection if a connection is not specified. - * - ``collection`` + * - ``table`` - Name of the MongoDB collection to store job batches. The value is ``job_batches`` by default. Then, add the service provider in your application's ``config/app.php`` file: -.. code-block:: php - - MongoDB\Laravel\MongoDBBusServiceProvider::class, +The {+odm-short+} automatically provides the +``MongoDB\Laravel\MongoDBBusServiceProvider::class`` class as the +service provider for job batching. From 78905184d965daaaeb92436bba82c0f88d4831f6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Thu, 2 Jan 2025 14:41:48 +0100 Subject: [PATCH 393/446] PHPORM-274 List search indexes in `Schema::getIndexes()` introspection method (#3233) --- src/Schema/Builder.php | 47 ++++++++++++- tests/AtlasSearchTest.php | 138 ++++++++++++++++++++++++++++++++++++++ tests/SchemaTest.php | 49 ++++++++++---- 3 files changed, 217 insertions(+), 17 deletions(-) create mode 100644 tests/AtlasSearchTest.php diff --git a/src/Schema/Builder.php b/src/Schema/Builder.php index ade4b0fb7..a4e8149f3 100644 --- a/src/Schema/Builder.php +++ b/src/Schema/Builder.php @@ -5,13 +5,17 @@ namespace MongoDB\Laravel\Schema; use Closure; +use MongoDB\Collection; +use MongoDB\Driver\Exception\ServerException; use MongoDB\Model\CollectionInfo; use MongoDB\Model\IndexInfo; +use function array_column; use function array_fill_keys; use function array_filter; use function array_keys; use function array_map; +use function array_merge; use function assert; use function count; use function current; @@ -225,9 +229,11 @@ public function getColumns($table) public function getIndexes($table) { - $indexes = $this->connection->getMongoDB()->selectCollection($table)->listIndexes(); - + $collection = $this->connection->getMongoDB()->selectCollection($table); + assert($collection instanceof Collection); $indexList = []; + + $indexes = $collection->listIndexes(); foreach ($indexes as $index) { assert($index instanceof IndexInfo); $indexList[] = [ @@ -238,12 +244,35 @@ public function getIndexes($table) $index->isText() => 'text', $index->is2dSphere() => '2dsphere', $index->isTtl() => 'ttl', - default => 'default', + default => null, }, 'unique' => $index->isUnique(), ]; } + try { + $indexes = $collection->listSearchIndexes(['typeMap' => ['root' => 'array', 'array' => 'array', 'document' => 'array']]); + foreach ($indexes as $index) { + $indexList[] = [ + 'name' => $index['name'], + 'columns' => match ($index['type']) { + 'search' => array_merge( + $index['latestDefinition']['mappings']['dynamic'] ? ['dynamic'] : [], + array_keys($index['latestDefinition']['mappings']['fields'] ?? []), + ), + 'vectorSearch' => array_column($index['latestDefinition']['fields'], 'path'), + }, + 'type' => $index['type'], + 'primary' => false, + 'unique' => false, + ]; + } + } catch (ServerException $exception) { + if (! self::isAtlasSearchNotSupportedException($exception)) { + throw $exception; + } + } + return $indexList; } @@ -290,4 +319,16 @@ protected function getAllCollections() return $collections; } + + /** @internal */ + public static function isAtlasSearchNotSupportedException(ServerException $e): bool + { + return in_array($e->getCode(), [ + 59, // MongoDB 4 to 6, 7-community: no such command: 'createSearchIndexes' + 40324, // MongoDB 4 to 6: Unrecognized pipeline stage name: '$listSearchIndexes' + 115, // MongoDB 7-ent: Search index commands are only supported with Atlas. + 6047401, // MongoDB 7: $listSearchIndexes stage is only allowed on MongoDB Atlas + 31082, // MongoDB 8: Using Atlas Search Database Commands and the $listSearchIndexes aggregation stage requires additional configuration. + ], true); + } } diff --git a/tests/AtlasSearchTest.php b/tests/AtlasSearchTest.php new file mode 100644 index 000000000..cfab2347a --- /dev/null +++ b/tests/AtlasSearchTest.php @@ -0,0 +1,138 @@ + 'Introduction to Algorithms'], + ['title' => 'Clean Code: A Handbook of Agile Software Craftsmanship'], + ['title' => 'Design Patterns: Elements of Reusable Object-Oriented Software'], + ['title' => 'The Pragmatic Programmer: Your Journey to Mastery'], + ['title' => 'Artificial Intelligence: A Modern Approach'], + ['title' => 'Structure and Interpretation of Computer Programs'], + ['title' => 'Code Complete: A Practical Handbook of Software Construction'], + ['title' => 'The Art of Computer Programming'], + ['title' => 'Computer Networks'], + ['title' => 'Operating System Concepts'], + ['title' => 'Database System Concepts'], + ['title' => 'Compilers: Principles, Techniques, and Tools'], + ['title' => 'Introduction to the Theory of Computation'], + ['title' => 'Modern Operating Systems'], + ['title' => 'Computer Organization and Design'], + ['title' => 'The Mythical Man-Month: Essays on Software Engineering'], + ['title' => 'Algorithms'], + ['title' => 'Understanding Machine Learning: From Theory to Algorithms'], + ['title' => 'Deep Learning'], + ['title' => 'Pattern Recognition and Machine Learning'], + ]); + + $collection = $this->getConnection('mongodb')->getCollection('books'); + assert($collection instanceof MongoDBCollection); + try { + $collection->createSearchIndex([ + 'mappings' => [ + 'fields' => [ + 'title' => [ + ['type' => 'string', 'analyzer' => 'lucene.english'], + ['type' => 'autocomplete', 'analyzer' => 'lucene.english'], + ], + ], + ], + ]); + + $collection->createSearchIndex([ + 'mappings' => ['dynamic' => true], + ], ['name' => 'dynamic_search']); + + $collection->createSearchIndex([ + 'fields' => [ + ['type' => 'vector', 'numDimensions' => 16, 'path' => 'vector16', 'similarity' => 'cosine'], + ['type' => 'vector', 'numDimensions' => 32, 'path' => 'vector32', 'similarity' => 'euclidean'], + ], + ], ['name' => 'vector', 'type' => 'vectorSearch']); + } catch (ServerException $e) { + if (Builder::isAtlasSearchNotSupportedException($e)) { + self::markTestSkipped('Atlas Search not supported. ' . $e->getMessage()); + } + + throw $e; + } + + // Wait for the index to be ready + do { + $ready = true; + usleep(10_000); + foreach ($collection->listSearchIndexes() as $index) { + if ($index['status'] !== 'READY') { + $ready = false; + } + } + } while (! $ready); + } + + public function tearDown(): void + { + $this->getConnection('mongodb')->getCollection('books')->drop(); + + parent::tearDown(); + } + + public function testGetIndexes() + { + $indexes = Schema::getIndexes('books'); + + self::assertIsArray($indexes); + self::assertCount(4, $indexes); + + // Order of indexes is not guaranteed + usort($indexes, fn ($a, $b) => $a['name'] <=> $b['name']); + + $expected = [ + [ + 'name' => '_id_', + 'columns' => ['_id'], + 'primary' => true, + 'type' => null, + 'unique' => false, + ], + [ + 'name' => 'default', + 'columns' => ['title'], + 'type' => 'search', + 'primary' => false, + 'unique' => false, + ], + [ + 'name' => 'dynamic_search', + 'columns' => ['dynamic'], + 'type' => 'search', + 'primary' => false, + 'unique' => false, + ], + [ + 'name' => 'vector', + 'columns' => ['vector16', 'vector32'], + 'type' => 'vectorSearch', + 'primary' => false, + 'unique' => false, + ], + ]; + + self::assertSame($expected, $indexes); + } +} diff --git a/tests/SchemaTest.php b/tests/SchemaTest.php index ff3dfe626..ec1ae47dd 100644 --- a/tests/SchemaTest.php +++ b/tests/SchemaTest.php @@ -482,20 +482,41 @@ public function testGetIndexes() $collection->string('mykey3')->index(); }); $indexes = Schema::getIndexes('newcollection'); - $this->assertIsArray($indexes); - $this->assertCount(4, $indexes); - - $indexes = collect($indexes)->keyBy('name'); - - $indexes->each(function ($index) { - $this->assertIsString($index['name']); - $this->assertIsString($index['type']); - $this->assertIsArray($index['columns']); - $this->assertIsBool($index['unique']); - $this->assertIsBool($index['primary']); - }); - $this->assertTrue($indexes->get('_id_')['primary']); - $this->assertTrue($indexes->get('unique_index_1')['unique']); + self::assertIsArray($indexes); + self::assertCount(4, $indexes); + + $expected = [ + [ + 'name' => '_id_', + 'columns' => ['_id'], + 'primary' => true, + 'type' => null, + 'unique' => false, + ], + [ + 'name' => 'mykey1_1', + 'columns' => ['mykey1'], + 'primary' => false, + 'type' => null, + 'unique' => false, + ], + [ + 'name' => 'unique_index_1', + 'columns' => ['unique_index'], + 'primary' => false, + 'type' => null, + 'unique' => true, + ], + [ + 'name' => 'mykey3_1', + 'columns' => ['mykey3'], + 'primary' => false, + 'type' => null, + 'unique' => false, + ], + ]; + + self::assertSame($expected, $indexes); // Non-existent collection $indexes = Schema::getIndexes('missing'); From 6cb38385c4d2b5a70d327f193a4e5c56e829b7d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Thu, 2 Jan 2025 18:13:18 +0100 Subject: [PATCH 394/446] PHPORM-273 Add schema helpers to create search and vector indexes (#3230) --- phpcs.xml.dist | 4 +++ src/Schema/Blueprint.php | 36 +++++++++++++++++++++ src/Schema/Builder.php | 5 +++ tests/SchemaTest.php | 67 ++++++++++++++++++++++++++++++++++++++-- tests/TestCase.php | 15 +++++++++ 5 files changed, 125 insertions(+), 2 deletions(-) diff --git a/phpcs.xml.dist b/phpcs.xml.dist index 3b7cc671c..f83429905 100644 --- a/phpcs.xml.dist +++ b/phpcs.xml.dist @@ -53,4 +53,8 @@ tests/Ticket/*.php + + + src/Schema/Blueprint.php + diff --git a/src/Schema/Blueprint.php b/src/Schema/Blueprint.php index f107bd7e5..b77a7799e 100644 --- a/src/Schema/Blueprint.php +++ b/src/Schema/Blueprint.php @@ -303,6 +303,42 @@ public function sparse_and_unique($columns = null, $options = []) return $this; } + /** + * Create an Atlas Search Index. + * + * @see https://www.mongodb.com/docs/manual/reference/command/createSearchIndexes/#std-label-search-index-definition-create + * + * @phpstan-param array{ + * analyzer?: string, + * analyzers?: list, + * searchAnalyzer?: string, + * mappings: array{dynamic: true} | array{dynamic?: bool, fields: array}, + * storedSource?: bool|array, + * synonyms?: list, + * ... + * } $definition + */ + public function searchIndex(array $definition, string $name = 'default'): static + { + $this->collection->createSearchIndex($definition, ['name' => $name, 'type' => 'search']); + + return $this; + } + + /** + * Create an Atlas Vector Search Index. + * + * @see https://www.mongodb.com/docs/manual/reference/command/createSearchIndexes/#std-label-vector-search-index-definition-create + * + * @phpstan-param array{fields: array} $definition + */ + public function vectorSearchIndex(array $definition, string $name = 'default'): static + { + $this->collection->createSearchIndex($definition, ['name' => $name, 'type' => 'vectorSearch']); + + return $this; + } + /** * Allow fluent columns. * diff --git a/src/Schema/Builder.php b/src/Schema/Builder.php index a4e8149f3..fe806f0e5 100644 --- a/src/Schema/Builder.php +++ b/src/Schema/Builder.php @@ -253,6 +253,11 @@ public function getIndexes($table) try { $indexes = $collection->listSearchIndexes(['typeMap' => ['root' => 'array', 'array' => 'array', 'document' => 'array']]); foreach ($indexes as $index) { + // Status 'DOES_NOT_EXIST' means the index has been dropped but is still in the process of being removed + if ($index['status'] === 'DOES_NOT_EXIST') { + continue; + } + $indexList[] = [ 'name' => $index['name'], 'columns' => match ($index['type']) { diff --git a/tests/SchemaTest.php b/tests/SchemaTest.php index ec1ae47dd..e23fa3d25 100644 --- a/tests/SchemaTest.php +++ b/tests/SchemaTest.php @@ -8,8 +8,11 @@ use Illuminate\Support\Facades\Schema; use MongoDB\BSON\Binary; use MongoDB\BSON\UTCDateTime; +use MongoDB\Collection; +use MongoDB\Database; use MongoDB\Laravel\Schema\Blueprint; +use function assert; use function collect; use function count; @@ -17,8 +20,10 @@ class SchemaTest extends TestCase { public function tearDown(): void { - Schema::drop('newcollection'); - Schema::drop('newcollection_two'); + $database = $this->getConnection('mongodb')->getMongoDB(); + assert($database instanceof Database); + $database->dropCollection('newcollection'); + $database->dropCollection('newcollection_two'); } public function testCreate(): void @@ -474,6 +479,7 @@ public function testGetColumns() $this->assertSame([], $columns); } + /** @see AtlasSearchTest::testGetIndexes() */ public function testGetIndexes() { Schema::create('newcollection', function (Blueprint $collection) { @@ -523,9 +529,54 @@ public function testGetIndexes() $this->assertSame([], $indexes); } + public function testSearchIndex(): void + { + $this->skipIfSearchIndexManagementIsNotSupported(); + + Schema::create('newcollection', function (Blueprint $collection) { + $collection->searchIndex([ + 'mappings' => [ + 'dynamic' => false, + 'fields' => [ + 'foo' => ['type' => 'string', 'analyzer' => 'lucene.whitespace'], + ], + ], + ]); + }); + + $index = $this->getSearchIndex('newcollection', 'default'); + self::assertNotNull($index); + + self::assertSame('default', $index['name']); + self::assertSame('search', $index['type']); + self::assertFalse($index['latestDefinition']['mappings']['dynamic']); + self::assertSame('lucene.whitespace', $index['latestDefinition']['mappings']['fields']['foo']['analyzer']); + } + + public function testVectorSearchIndex() + { + $this->skipIfSearchIndexManagementIsNotSupported(); + + Schema::create('newcollection', function (Blueprint $collection) { + $collection->vectorSearchIndex([ + 'fields' => [ + ['type' => 'vector', 'path' => 'foo', 'numDimensions' => 128, 'similarity' => 'euclidean', 'quantization' => 'none'], + ], + ], 'vector'); + }); + + $index = $this->getSearchIndex('newcollection', 'vector'); + self::assertNotNull($index); + + self::assertSame('vector', $index['name']); + self::assertSame('vectorSearch', $index['type']); + self::assertSame('vector', $index['latestDefinition']['fields'][0]['type']); + } + protected function getIndex(string $collection, string $name) { $collection = DB::getCollection($collection); + assert($collection instanceof Collection); foreach ($collection->listIndexes() as $index) { if (isset($index['key'][$name])) { @@ -535,4 +586,16 @@ protected function getIndex(string $collection, string $name) return false; } + + protected function getSearchIndex(string $collection, string $name): ?array + { + $collection = DB::getCollection($collection); + assert($collection instanceof Collection); + + foreach ($collection->listSearchIndexes(['name' => $name, 'typeMap' => ['root' => 'array', 'array' => 'array', 'document' => 'array']]) as $index) { + return $index; + } + + return null; + } } diff --git a/tests/TestCase.php b/tests/TestCase.php index 5f5bbecdc..d924777ce 100644 --- a/tests/TestCase.php +++ b/tests/TestCase.php @@ -5,7 +5,9 @@ namespace MongoDB\Laravel\Tests; use Illuminate\Foundation\Application; +use MongoDB\Driver\Exception\ServerException; use MongoDB\Laravel\MongoDBServiceProvider; +use MongoDB\Laravel\Schema\Builder; use MongoDB\Laravel\Tests\Models\User; use MongoDB\Laravel\Validation\ValidationServiceProvider; use Orchestra\Testbench\TestCase as OrchestraTestCase; @@ -64,4 +66,17 @@ protected function getEnvironmentSetUp($app): void $app['config']->set('queue.failed.database', 'mongodb2'); $app['config']->set('queue.failed.driver', 'mongodb'); } + + public function skipIfSearchIndexManagementIsNotSupported(): void + { + try { + $this->getConnection('mongodb')->getCollection('test')->listSearchIndexes(['name' => 'just_for_testing']); + } catch (ServerException $e) { + if (Builder::isAtlasSearchNotSupportedException($e)) { + self::markTestSkipped('Search index management is not supported on this server'); + } + + throw $e; + } + } } From aae91708bf20e63221f11fd84171d189de449930 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Fri, 3 Jan 2025 18:07:36 +0100 Subject: [PATCH 395/446] Fix tests on Schema index helpers (#3236) Add helpers for index exists/not-exists --- tests/SchemaTest.php | 128 ++++++++++++++++++++++--------------------- 1 file changed, 66 insertions(+), 62 deletions(-) diff --git a/tests/SchemaTest.php b/tests/SchemaTest.php index e23fa3d25..61280a726 100644 --- a/tests/SchemaTest.php +++ b/tests/SchemaTest.php @@ -11,10 +11,12 @@ use MongoDB\Collection; use MongoDB\Database; use MongoDB\Laravel\Schema\Blueprint; +use MongoDB\Model\IndexInfo; use function assert; use function collect; use function count; +use function sprintf; class SchemaTest extends TestCase { @@ -81,21 +83,21 @@ public function testIndex(): void $collection->index('mykey1'); }); - $index = $this->getIndex('newcollection', 'mykey1'); + $index = $this->assertIndexExists('newcollection', 'mykey1_1'); $this->assertEquals(1, $index['key']['mykey1']); Schema::table('newcollection', function ($collection) { $collection->index(['mykey2']); }); - $index = $this->getIndex('newcollection', 'mykey2'); + $index = $this->assertIndexExists('newcollection', 'mykey2_1'); $this->assertEquals(1, $index['key']['mykey2']); Schema::table('newcollection', function ($collection) { $collection->string('mykey3')->index(); }); - $index = $this->getIndex('newcollection', 'mykey3'); + $index = $this->assertIndexExists('newcollection', 'mykey3_1'); $this->assertEquals(1, $index['key']['mykey3']); } @@ -105,7 +107,7 @@ public function testPrimary(): void $collection->string('mykey', 100)->primary(); }); - $index = $this->getIndex('newcollection', 'mykey'); + $index = $this->assertIndexExists('newcollection', 'mykey_1'); $this->assertEquals(1, $index['unique']); } @@ -115,7 +117,7 @@ public function testUnique(): void $collection->unique('uniquekey'); }); - $index = $this->getIndex('newcollection', 'uniquekey'); + $index = $this->assertIndexExists('newcollection', 'uniquekey_1'); $this->assertEquals(1, $index['unique']); } @@ -126,58 +128,52 @@ public function testDropIndex(): void $collection->dropIndex('uniquekey_1'); }); - $index = $this->getIndex('newcollection', 'uniquekey'); - $this->assertEquals(null, $index); + $this->assertIndexNotExists('newcollection', 'uniquekey_1'); Schema::table('newcollection', function ($collection) { $collection->unique('uniquekey'); $collection->dropIndex(['uniquekey']); }); - $index = $this->getIndex('newcollection', 'uniquekey'); - $this->assertEquals(null, $index); + $this->assertIndexNotExists('newcollection', 'uniquekey_1'); Schema::table('newcollection', function ($collection) { $collection->index(['field_a', 'field_b']); }); - $index = $this->getIndex('newcollection', 'field_a_1_field_b_1'); - $this->assertNotNull($index); + $this->assertIndexExists('newcollection', 'field_a_1_field_b_1'); Schema::table('newcollection', function ($collection) { $collection->dropIndex(['field_a', 'field_b']); }); - $index = $this->getIndex('newcollection', 'field_a_1_field_b_1'); - $this->assertFalse($index); + $this->assertIndexNotExists('newcollection', 'field_a_1_field_b_1'); + $indexName = 'field_a_-1_field_b_1'; Schema::table('newcollection', function ($collection) { $collection->index(['field_a' => -1, 'field_b' => 1]); }); - $index = $this->getIndex('newcollection', 'field_a_-1_field_b_1'); - $this->assertNotNull($index); + $this->assertIndexExists('newcollection', $indexName); Schema::table('newcollection', function ($collection) { $collection->dropIndex(['field_a' => -1, 'field_b' => 1]); }); - $index = $this->getIndex('newcollection', 'field_a_-1_field_b_1'); - $this->assertFalse($index); + $this->assertIndexNotExists('newcollection', $indexName); - Schema::table('newcollection', function ($collection) { - $collection->index(['field_a', 'field_b'], 'custom_index_name'); + $indexName = 'custom_index_name'; + Schema::table('newcollection', function ($collection) use ($indexName) { + $collection->index(['field_a', 'field_b'], $indexName); }); - $index = $this->getIndex('newcollection', 'custom_index_name'); - $this->assertNotNull($index); + $this->assertIndexExists('newcollection', $indexName); - Schema::table('newcollection', function ($collection) { - $collection->dropIndex('custom_index_name'); + Schema::table('newcollection', function ($collection) use ($indexName) { + $collection->dropIndex($indexName); }); - $index = $this->getIndex('newcollection', 'custom_index_name'); - $this->assertFalse($index); + $this->assertIndexNotExists('newcollection', $indexName); } public function testDropIndexIfExists(): void @@ -187,66 +183,58 @@ public function testDropIndexIfExists(): void $collection->dropIndexIfExists('uniquekey_1'); }); - $index = $this->getIndex('newcollection', 'uniquekey'); - $this->assertEquals(null, $index); + $this->assertIndexNotExists('newcollection', 'uniquekey'); Schema::table('newcollection', function (Blueprint $collection) { $collection->unique('uniquekey'); $collection->dropIndexIfExists(['uniquekey']); }); - $index = $this->getIndex('newcollection', 'uniquekey'); - $this->assertEquals(null, $index); + $this->assertIndexNotExists('newcollection', 'uniquekey'); Schema::table('newcollection', function (Blueprint $collection) { $collection->index(['field_a', 'field_b']); }); - $index = $this->getIndex('newcollection', 'field_a_1_field_b_1'); - $this->assertNotNull($index); + $this->assertIndexExists('newcollection', 'field_a_1_field_b_1'); Schema::table('newcollection', function (Blueprint $collection) { $collection->dropIndexIfExists(['field_a', 'field_b']); }); - $index = $this->getIndex('newcollection', 'field_a_1_field_b_1'); - $this->assertFalse($index); + $this->assertIndexNotExists('newcollection', 'field_a_1_field_b_1'); Schema::table('newcollection', function (Blueprint $collection) { $collection->index(['field_a', 'field_b'], 'custom_index_name'); }); - $index = $this->getIndex('newcollection', 'custom_index_name'); - $this->assertNotNull($index); + $this->assertIndexExists('newcollection', 'custom_index_name'); Schema::table('newcollection', function (Blueprint $collection) { $collection->dropIndexIfExists('custom_index_name'); }); - $index = $this->getIndex('newcollection', 'custom_index_name'); - $this->assertFalse($index); + $this->assertIndexNotExists('newcollection', 'custom_index_name'); } public function testHasIndex(): void { - $instance = $this; - - Schema::table('newcollection', function (Blueprint $collection) use ($instance) { + Schema::table('newcollection', function (Blueprint $collection) { $collection->index('myhaskey1'); - $instance->assertTrue($collection->hasIndex('myhaskey1_1')); - $instance->assertFalse($collection->hasIndex('myhaskey1')); + $this->assertTrue($collection->hasIndex('myhaskey1_1')); + $this->assertFalse($collection->hasIndex('myhaskey1')); }); - Schema::table('newcollection', function (Blueprint $collection) use ($instance) { + Schema::table('newcollection', function (Blueprint $collection) { $collection->index('myhaskey2'); - $instance->assertTrue($collection->hasIndex(['myhaskey2'])); - $instance->assertFalse($collection->hasIndex(['myhaskey2_1'])); + $this->assertTrue($collection->hasIndex(['myhaskey2'])); + $this->assertFalse($collection->hasIndex(['myhaskey2_1'])); }); - Schema::table('newcollection', function (Blueprint $collection) use ($instance) { + Schema::table('newcollection', function (Blueprint $collection) { $collection->index(['field_a', 'field_b']); - $instance->assertTrue($collection->hasIndex(['field_a_1_field_b'])); - $instance->assertFalse($collection->hasIndex(['field_a_1_field_b_1'])); + $this->assertTrue($collection->hasIndex(['field_a_1_field_b'])); + $this->assertFalse($collection->hasIndex(['field_a_1_field_b_1'])); }); } @@ -256,7 +244,7 @@ public function testSparse(): void $collection->sparse('sparsekey'); }); - $index = $this->getIndex('newcollection', 'sparsekey'); + $index = $this->assertIndexExists('newcollection', 'sparsekey_1'); $this->assertEquals(1, $index['sparse']); } @@ -266,7 +254,7 @@ public function testExpire(): void $collection->expire('expirekey', 60); }); - $index = $this->getIndex('newcollection', 'expirekey'); + $index = $this->assertIndexExists('newcollection', 'expirekey_1'); $this->assertEquals(60, $index['expireAfterSeconds']); } @@ -280,7 +268,7 @@ public function testSoftDeletes(): void $collection->string('email')->nullable()->index(); }); - $index = $this->getIndex('newcollection', 'email'); + $index = $this->assertIndexExists('newcollection', 'email_1'); $this->assertEquals(1, $index['key']['email']); } @@ -292,10 +280,10 @@ public function testFluent(): void $collection->timestamp('created_at'); }); - $index = $this->getIndex('newcollection', 'email'); + $index = $this->assertIndexExists('newcollection', 'email_1'); $this->assertEquals(1, $index['key']['email']); - $index = $this->getIndex('newcollection', 'token'); + $index = $this->assertIndexExists('newcollection', 'token_1'); $this->assertEquals(1, $index['key']['token']); } @@ -307,13 +295,13 @@ public function testGeospatial(): void $collection->geospatial('continent', '2dsphere'); }); - $index = $this->getIndex('newcollection', 'point'); + $index = $this->assertIndexExists('newcollection', 'point_2d'); $this->assertEquals('2d', $index['key']['point']); - $index = $this->getIndex('newcollection', 'area'); + $index = $this->assertIndexExists('newcollection', 'area_2d'); $this->assertEquals('2d', $index['key']['area']); - $index = $this->getIndex('newcollection', 'continent'); + $index = $this->assertIndexExists('newcollection', 'continent_2dsphere'); $this->assertEquals('2dsphere', $index['key']['continent']); } @@ -332,7 +320,7 @@ public function testSparseUnique(): void $collection->sparse_and_unique('sparseuniquekey'); }); - $index = $this->getIndex('newcollection', 'sparseuniquekey'); + $index = $this->assertIndexExists('newcollection', 'sparseuniquekey_1'); $this->assertEquals(1, $index['sparse']); $this->assertEquals(1, $index['unique']); } @@ -573,23 +561,39 @@ public function testVectorSearchIndex() self::assertSame('vector', $index['latestDefinition']['fields'][0]['type']); } - protected function getIndex(string $collection, string $name) + protected function assertIndexExists(string $collection, string $name): IndexInfo + { + $index = $this->getIndex($collection, $name); + + self::assertNotNull($index, sprintf('Index "%s.%s" does not exist.', $collection, $name)); + + return $index; + } + + protected function assertIndexNotExists(string $collection, string $name): void { - $collection = DB::getCollection($collection); + $index = $this->getIndex($collection, $name); + + self::assertNull($index, sprintf('Index "%s.%s" exists.', $collection, $name)); + } + + protected function getIndex(string $collection, string $name): ?IndexInfo + { + $collection = $this->getConnection('mongodb')->getCollection($collection); assert($collection instanceof Collection); foreach ($collection->listIndexes() as $index) { - if (isset($index['key'][$name])) { + if ($index->getName() === $name) { return $index; } } - return false; + return null; } protected function getSearchIndex(string $collection, string $name): ?array { - $collection = DB::getCollection($collection); + $collection = $this->getConnection('mongodb')->getCollection($collection); assert($collection instanceof Collection); foreach ($collection->listSearchIndexes(['name' => $name, 'typeMap' => ['root' => 'array', 'array' => 'array', 'document' => 'array']]) as $index) { From 3960aeba3f9d065a3be6263ac47964066a039e41 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Fri, 3 Jan 2025 19:16:24 +0100 Subject: [PATCH 396/446] PHPORM-266 Run tests on Atlas Local (#3216) --- .github/workflows/build-ci.yml | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/.github/workflows/build-ci.yml b/.github/workflows/build-ci.yml index 45833d579..7a987d251 100644 --- a/.github/workflows/build-ci.yml +++ b/.github/workflows/build-ci.yml @@ -19,6 +19,7 @@ jobs: - "5.0" - "6.0" - "7.0" + - "Atlas" php: - "8.1" - "8.2" @@ -45,15 +46,24 @@ jobs: - uses: "actions/checkout@v4" - name: "Create MongoDB Replica Set" + if: ${{ matrix.mongodb != 'Atlas' }} run: | docker run --name mongodb -p 27017:27017 -e MONGO_INITDB_DATABASE=unittest --detach mongo:${{ matrix.mongodb }} mongod --replSet rs --setParameter transactionLifetimeLimitSeconds=5 if [ "${{ matrix.mongodb }}" = "4.4" ]; then MONGOSH_BIN="mongo"; else MONGOSH_BIN="mongosh"; fi until docker exec --tty mongodb $MONGOSH_BIN 127.0.0.1:27017 --eval "db.runCommand({ ping: 1 })"; do - sleep 1 + sleep 1 done sudo docker exec --tty mongodb $MONGOSH_BIN 127.0.0.1:27017 --eval "rs.initiate({\"_id\":\"rs\",\"members\":[{\"_id\":0,\"host\":\"127.0.0.1:27017\" }]})" + - name: "Create MongoDB Atlas Local" + if: ${{ matrix.mongodb == 'Atlas' }} + run: | + docker run --name mongodb -p 27017:27017 --detach mongodb/mongodb-atlas-local:latest + until docker exec --tty mongodb mongosh 127.0.0.1:27017 --eval "db.runCommand({ ping: 1 })"; do + sleep 1 + done + - name: "Show MongoDB server status" run: | if [ "${{ matrix.mongodb }}" = "4.4" ]; then MONGOSH_BIN="mongo"; else MONGOSH_BIN="mongosh"; fi @@ -91,6 +101,10 @@ jobs: $([[ "${{ matrix.mode }}" == low-deps ]] && echo ' --prefer-lowest') \ $([[ "${{ matrix.mode }}" == ignore-php-req ]] && echo ' --ignore-platform-req=php+') - name: "Run tests" - run: "./vendor/bin/phpunit --coverage-clover coverage.xml" - env: - MONGODB_URI: 'mongodb://127.0.0.1/?replicaSet=rs' + run: | + if [ "${{ matrix.mongodb }}" = "Atlas" ]; then + export MONGODB_URI="mongodb://127.0.0.1:27017/" + else + export MONGODB_URI="mongodb://127.0.0.1:27017/?replicaSet=rs" + fi + ./vendor/bin/phpunit --coverage-clover coverage.xml From 223a9f76d5120660bfb509763309c127946b7805 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Fri, 3 Jan 2025 19:31:00 +0100 Subject: [PATCH 397/446] PHPORM-283 Add `Schema::dropSearchIndex()` (#3235) --- src/Schema/Blueprint.php | 10 ++++++++++ tests/SchemaTest.php | 15 +++++++++++++++ 2 files changed, 25 insertions(+) diff --git a/src/Schema/Blueprint.php b/src/Schema/Blueprint.php index b77a7799e..e3d7a230b 100644 --- a/src/Schema/Blueprint.php +++ b/src/Schema/Blueprint.php @@ -339,6 +339,16 @@ public function vectorSearchIndex(array $definition, string $name = 'default'): return $this; } + /** + * Drop an Atlas Search or Vector Search index + */ + public function dropSearchIndex(string $name): static + { + $this->collection->dropSearchIndex($name); + + return $this; + } + /** * Allow fluent columns. * diff --git a/tests/SchemaTest.php b/tests/SchemaTest.php index 61280a726..34029aa32 100644 --- a/tests/SchemaTest.php +++ b/tests/SchemaTest.php @@ -539,6 +539,13 @@ public function testSearchIndex(): void self::assertSame('search', $index['type']); self::assertFalse($index['latestDefinition']['mappings']['dynamic']); self::assertSame('lucene.whitespace', $index['latestDefinition']['mappings']['fields']['foo']['analyzer']); + + Schema::table('newcollection', function (Blueprint $collection) { + $collection->dropSearchIndex('default'); + }); + + $index = $this->getSearchIndex('newcollection', 'default'); + self::assertNull($index); } public function testVectorSearchIndex() @@ -559,6 +566,14 @@ public function testVectorSearchIndex() self::assertSame('vector', $index['name']); self::assertSame('vectorSearch', $index['type']); self::assertSame('vector', $index['latestDefinition']['fields'][0]['type']); + + // Drop the index + Schema::table('newcollection', function (Blueprint $collection) { + $collection->dropSearchIndex('vector'); + }); + + $index = $this->getSearchIndex('newcollection', 'vector'); + self::assertNull($index); } protected function assertIndexExists(string $collection, string $name): IndexInfo From cc7e5ffd0e8e3a9acfebd7aa5a5aabac2fc5eac4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bar=C4=B1=C5=9F=20Kartal?= Date: Mon, 6 Jan 2025 12:22:28 +0300 Subject: [PATCH 398/446] Update param types in docblocks (#3237) --- src/Eloquent/HybridRelations.php | 33 ++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/src/Eloquent/HybridRelations.php b/src/Eloquent/HybridRelations.php index 8ca4ea289..21344c8e9 100644 --- a/src/Eloquent/HybridRelations.php +++ b/src/Eloquent/HybridRelations.php @@ -334,15 +334,15 @@ public function belongsToMany( /** * Define a morph-to-many relationship. * - * @param string $related - * @param string $name - * @param null $table - * @param null $foreignPivotKey - * @param null $relatedPivotKey - * @param null $parentKey - * @param null $relatedKey - * @param null $relation - * @param bool $inverse + * @param class-string $related + * @param string $name + * @param string|null $table + * @param string|null $foreignPivotKey + * @param string|null $relatedPivotKey + * @param string|null $parentKey + * @param string|null $relatedKey + * @param string|null $relation + * @param bool $inverse * * @return \Illuminate\Database\Eloquent\Relations\MorphToMany */ @@ -410,13 +410,14 @@ public function morphToMany( /** * Define a polymorphic, inverse many-to-many relationship. * - * @param string $related - * @param string $name - * @param null $table - * @param null $foreignPivotKey - * @param null $relatedPivotKey - * @param null $parentKey - * @param null $relatedKey + * @param class-string $related + * @param string $name + * @param string|null $table + * @param string|null $foreignPivotKey + * @param string|null $relatedPivotKey + * @param string|null $parentKey + * @param string|null $relatedKey + * @param string|null $relation * * @return \Illuminate\Database\Eloquent\Relations\MorphToMany */ From d6d8004b675369d2bc0f9c1b3091cbbd9c6057d8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 6 Jan 2025 18:33:33 +0100 Subject: [PATCH 399/446] PHPORM-275 PHPORM-276 Add `Query\Builder::search()` and `autocomplete()` (#3232) --- src/Eloquent/Builder.php | 34 +++++++++++++++++++- src/Query/Builder.php | 65 +++++++++++++++++++++++++++++++++++++++ tests/AtlasSearchTest.php | 64 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 162 insertions(+), 1 deletion(-) diff --git a/src/Eloquent/Builder.php b/src/Eloquent/Builder.php index 4fd4880df..fe0fec95d 100644 --- a/src/Eloquent/Builder.php +++ b/src/Eloquent/Builder.php @@ -5,7 +5,10 @@ namespace MongoDB\Laravel\Eloquent; use Illuminate\Database\Eloquent\Builder as EloquentBuilder; +use Illuminate\Database\Eloquent\Collection; +use Illuminate\Database\Eloquent\Model; use MongoDB\BSON\Document; +use MongoDB\Builder\Type\SearchOperatorInterface; use MongoDB\Driver\CursorInterface; use MongoDB\Driver\Exception\WriteException; use MongoDB\Laravel\Connection; @@ -21,7 +24,10 @@ use function iterator_to_array; use function property_exists; -/** @method \MongoDB\Laravel\Query\Builder toBase() */ +/** + * @method \MongoDB\Laravel\Query\Builder toBase() + * @template TModel of Model + */ class Builder extends EloquentBuilder { private const DUPLICATE_KEY_ERROR = 11000; @@ -49,6 +55,7 @@ class Builder extends EloquentBuilder 'insertusing', 'max', 'min', + 'autocomplete', 'pluck', 'pull', 'push', @@ -69,6 +76,31 @@ public function aggregate($function = null, $columns = ['*']) return $result ?: $this; } + /** + * Performs a full-text search of the field or fields in an Atlas collection. + * + * @see https://www.mongodb.com/docs/atlas/atlas-search/aggregation-stages/search/ + * + * @return Collection + */ + public function search( + SearchOperatorInterface|array $operator, + ?string $index = null, + ?array $highlight = null, + ?bool $concurrent = null, + ?string $count = null, + ?string $searchAfter = null, + ?string $searchBefore = null, + ?bool $scoreDetails = null, + ?array $sort = null, + ?bool $returnStoredSource = null, + ?array $tracking = null, + ): Collection { + $results = $this->toBase()->search($operator, $index, $highlight, $concurrent, $count, $searchAfter, $searchBefore, $scoreDetails, $sort, $returnStoredSource, $tracking); + + return $this->model->hydrate($results->all()); + } + /** @inheritdoc */ public function update(array $values, array $options = []) { diff --git a/src/Query/Builder.php b/src/Query/Builder.php index c62709ce5..0e9e028bb 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -23,13 +23,16 @@ use MongoDB\BSON\ObjectID; use MongoDB\BSON\Regex; use MongoDB\BSON\UTCDateTime; +use MongoDB\Builder\Search; use MongoDB\Builder\Stage\FluentFactoryTrait; +use MongoDB\Builder\Type\SearchOperatorInterface; use MongoDB\Driver\Cursor; use Override; use RuntimeException; use stdClass; use function array_fill_keys; +use function array_filter; use function array_is_list; use function array_key_exists; use function array_map; @@ -1490,6 +1493,68 @@ public function options(array $options) return $this; } + /** + * Performs a full-text search of the field or fields in an Atlas collection. + * NOTE: $search is only available for MongoDB Atlas clusters, and is not available for self-managed deployments. + * + * @see https://www.mongodb.com/docs/atlas/atlas-search/aggregation-stages/search/ + * + * @return Collection + */ + public function search( + SearchOperatorInterface|array $operator, + ?string $index = null, + ?array $highlight = null, + ?bool $concurrent = null, + ?string $count = null, + ?string $searchAfter = null, + ?string $searchBefore = null, + ?bool $scoreDetails = null, + ?array $sort = null, + ?bool $returnStoredSource = null, + ?array $tracking = null, + ): Collection { + // Forward named arguments to the search stage, skip null values + $args = array_filter([ + 'operator' => $operator, + 'index' => $index, + 'highlight' => $highlight, + 'concurrent' => $concurrent, + 'count' => $count, + 'searchAfter' => $searchAfter, + 'searchBefore' => $searchBefore, + 'scoreDetails' => $scoreDetails, + 'sort' => $sort, + 'returnStoredSource' => $returnStoredSource, + 'tracking' => $tracking, + ], fn ($arg) => $arg !== null); + + return $this->aggregate()->search(...$args)->get(); + } + + /** + * Performs an autocomplete search of the field using an Atlas Search index. + * NOTE: $search is only available for MongoDB Atlas clusters, and is not available for self-managed deployments. + * You must create an Atlas Search index with an autocomplete configuration before you can use this stage. + * + * @see https://www.mongodb.com/docs/atlas/atlas-search/autocomplete/ + * + * @return Collection + */ + public function autocomplete(string $path, string $query, bool|array $fuzzy = false, string $tokenOrder = 'any'): Collection + { + $args = ['path' => $path, 'query' => $query, 'tokenOrder' => $tokenOrder]; + if ($fuzzy === true) { + $args['fuzzy'] = ['maxEdits' => 2]; + } elseif ($fuzzy !== false) { + $args['fuzzy'] = $fuzzy; + } + + return $this->aggregate()->search( + Search::autocomplete(...$args), + )->get()->pluck($path); + } + /** * Apply the connection's session to options if it's not already specified. */ diff --git a/tests/AtlasSearchTest.php b/tests/AtlasSearchTest.php index cfab2347a..4dc58e902 100644 --- a/tests/AtlasSearchTest.php +++ b/tests/AtlasSearchTest.php @@ -2,7 +2,10 @@ namespace MongoDB\Laravel\Tests; +use Illuminate\Database\Eloquent\Collection as EloquentCollection; +use Illuminate\Support\Collection as LaravelCollection; use Illuminate\Support\Facades\Schema; +use MongoDB\Builder\Search; use MongoDB\Collection as MongoDBCollection; use MongoDB\Driver\Exception\ServerException; use MongoDB\Laravel\Schema\Builder; @@ -43,6 +46,7 @@ public function setUp(): void $collection = $this->getConnection('mongodb')->getCollection('books'); assert($collection instanceof MongoDBCollection); + try { $collection->createSearchIndex([ 'mappings' => [ @@ -50,6 +54,7 @@ public function setUp(): void 'title' => [ ['type' => 'string', 'analyzer' => 'lucene.english'], ['type' => 'autocomplete', 'analyzer' => 'lucene.english'], + ['type' => 'token'], ], ], ], @@ -135,4 +140,63 @@ public function testGetIndexes() self::assertSame($expected, $indexes); } + + public function testEloquentBuilderSearch() + { + $results = Book::search( + sort: ['title' => 1], + operator: Search::text('title', 'systems'), + ); + + self::assertInstanceOf(EloquentCollection::class, $results); + self::assertCount(3, $results); + self::assertInstanceOf(Book::class, $results->first()); + self::assertSame([ + 'Database System Concepts', + 'Modern Operating Systems', + 'Operating System Concepts', + ], $results->pluck('title')->all()); + } + + public function testDatabaseBuilderSearch() + { + $results = $this->getConnection('mongodb')->table('books') + ->search(Search::text('title', 'systems'), sort: ['title' => 1]); + + self::assertInstanceOf(LaravelCollection::class, $results); + self::assertCount(3, $results); + self::assertIsArray($results->first()); + self::assertSame([ + 'Database System Concepts', + 'Modern Operating Systems', + 'Operating System Concepts', + ], $results->pluck('title')->all()); + } + + public function testEloquentBuilderAutocomplete() + { + $results = Book::autocomplete('title', 'system'); + + self::assertInstanceOf(LaravelCollection::class, $results); + self::assertCount(3, $results); + self::assertSame([ + 'Operating System Concepts', + 'Database System Concepts', + 'Modern Operating Systems', + ], $results->all()); + } + + public function testDatabaseBuilderAutocomplete() + { + $results = $this->getConnection('mongodb')->table('books') + ->autocomplete('title', 'system'); + + self::assertInstanceOf(LaravelCollection::class, $results); + self::assertCount(3, $results); + self::assertSame([ + 'Operating System Concepts', + 'Database System Concepts', + 'Modern Operating Systems', + ], $results->all()); + } } From 35f469918ca513378d6536aa38299a3a27f33462 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 13 Jan 2025 17:40:52 +0100 Subject: [PATCH 400/446] PHPORM-277 Add `Builder::vectorSearch()` (#3242) --- src/Eloquent/Builder.php | 23 ++++++++++++ src/Query/Builder.php | 35 ++++++++++++++++++ tests/AtlasSearchTest.php | 78 +++++++++++++++++++++++++++++++++++---- 3 files changed, 128 insertions(+), 8 deletions(-) diff --git a/src/Eloquent/Builder.php b/src/Eloquent/Builder.php index fe0fec95d..afe968e4b 100644 --- a/src/Eloquent/Builder.php +++ b/src/Eloquent/Builder.php @@ -8,6 +8,7 @@ use Illuminate\Database\Eloquent\Collection; use Illuminate\Database\Eloquent\Model; use MongoDB\BSON\Document; +use MongoDB\Builder\Type\QueryInterface; use MongoDB\Builder\Type\SearchOperatorInterface; use MongoDB\Driver\CursorInterface; use MongoDB\Driver\Exception\WriteException; @@ -101,6 +102,28 @@ public function search( return $this->model->hydrate($results->all()); } + /** + * Performs a semantic search on data in your Atlas Vector Search index. + * NOTE: $vectorSearch is only available for MongoDB Atlas clusters, and is not available for self-managed deployments. + * + * @see https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-stage/ + * + * @return Collection + */ + public function vectorSearch( + string $index, + array|string $path, + array $queryVector, + int $limit, + bool $exact = false, + QueryInterface|array $filter = [], + int|null $numCandidates = null, + ): Collection { + $results = $this->toBase()->vectorSearch($index, $path, $queryVector, $limit, $exact, $filter, $numCandidates); + + return $this->model->hydrate($results->all()); + } + /** @inheritdoc */ public function update(array $values, array $options = []) { diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 0e9e028bb..06eb5ac47 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -25,6 +25,7 @@ use MongoDB\BSON\UTCDateTime; use MongoDB\Builder\Search; use MongoDB\Builder\Stage\FluentFactoryTrait; +use MongoDB\Builder\Type\QueryInterface; use MongoDB\Builder\Type\SearchOperatorInterface; use MongoDB\Driver\Cursor; use Override; @@ -1532,6 +1533,40 @@ public function search( return $this->aggregate()->search(...$args)->get(); } + /** + * Performs a semantic search on data in your Atlas Vector Search index. + * NOTE: $vectorSearch is only available for MongoDB Atlas clusters, and is not available for self-managed deployments. + * + * @see https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-stage/ + * + * @return Collection + */ + public function vectorSearch( + string $index, + array|string $path, + array $queryVector, + int $limit, + bool $exact = false, + QueryInterface|array|null $filter = null, + int|null $numCandidates = null, + ): Collection { + // Forward named arguments to the vectorSearch stage, skip null values + $args = array_filter([ + 'index' => $index, + 'limit' => $limit, + 'path' => $path, + 'queryVector' => $queryVector, + 'exact' => $exact, + 'filter' => $filter, + 'numCandidates' => $numCandidates, + ], fn ($arg) => $arg !== null); + + return $this->aggregate() + ->vectorSearch(...$args) + ->addFields(vectorSearchScore: ['$meta' => 'vectorSearchScore']) + ->get(); + } + /** * Performs an autocomplete search of the field using an Atlas Search index. * NOTE: $search is only available for MongoDB Atlas clusters, and is not available for self-managed deployments. diff --git a/tests/AtlasSearchTest.php b/tests/AtlasSearchTest.php index 4dc58e902..c9cd2d5e3 100644 --- a/tests/AtlasSearchTest.php +++ b/tests/AtlasSearchTest.php @@ -5,23 +5,31 @@ use Illuminate\Database\Eloquent\Collection as EloquentCollection; use Illuminate\Support\Collection as LaravelCollection; use Illuminate\Support\Facades\Schema; +use MongoDB\Builder\Query; use MongoDB\Builder\Search; use MongoDB\Collection as MongoDBCollection; use MongoDB\Driver\Exception\ServerException; use MongoDB\Laravel\Schema\Builder; use MongoDB\Laravel\Tests\Models\Book; +use function array_map; use function assert; +use function mt_getrandmax; +use function rand; +use function range; +use function srand; use function usleep; use function usort; class AtlasSearchTest extends TestCase { + private array $vectors; + public function setUp(): void { parent::setUp(); - Book::insert([ + Book::insert($this->addVector([ ['title' => 'Introduction to Algorithms'], ['title' => 'Clean Code: A Handbook of Agile Software Craftsmanship'], ['title' => 'Design Patterns: Elements of Reusable Object-Oriented Software'], @@ -42,7 +50,7 @@ public function setUp(): void ['title' => 'Understanding Machine Learning: From Theory to Algorithms'], ['title' => 'Deep Learning'], ['title' => 'Pattern Recognition and Machine Learning'], - ]); + ])); $collection = $this->getConnection('mongodb')->getCollection('books'); assert($collection instanceof MongoDBCollection); @@ -66,8 +74,9 @@ public function setUp(): void $collection->createSearchIndex([ 'fields' => [ - ['type' => 'vector', 'numDimensions' => 16, 'path' => 'vector16', 'similarity' => 'cosine'], + ['type' => 'vector', 'numDimensions' => 4, 'path' => 'vector4', 'similarity' => 'cosine'], ['type' => 'vector', 'numDimensions' => 32, 'path' => 'vector32', 'similarity' => 'euclidean'], + ['type' => 'filter', 'path' => 'title'], ], ], ['name' => 'vector', 'type' => 'vectorSearch']); } catch (ServerException $e) { @@ -131,7 +140,7 @@ public function testGetIndexes() ], [ 'name' => 'vector', - 'columns' => ['vector16', 'vector32'], + 'columns' => ['vector4', 'vector32', 'title'], 'type' => 'vectorSearch', 'primary' => false, 'unique' => false, @@ -180,10 +189,10 @@ public function testEloquentBuilderAutocomplete() self::assertInstanceOf(LaravelCollection::class, $results); self::assertCount(3, $results); self::assertSame([ - 'Operating System Concepts', 'Database System Concepts', 'Modern Operating Systems', - ], $results->all()); + 'Operating System Concepts', + ], $results->sort()->values()->all()); } public function testDatabaseBuilderAutocomplete() @@ -194,9 +203,62 @@ public function testDatabaseBuilderAutocomplete() self::assertInstanceOf(LaravelCollection::class, $results); self::assertCount(3, $results); self::assertSame([ - 'Operating System Concepts', 'Database System Concepts', 'Modern Operating Systems', - ], $results->all()); + 'Operating System Concepts', + ], $results->sort()->values()->all()); + } + + public function testDatabaseBuilderVectorSearch() + { + $results = $this->getConnection('mongodb')->table('books') + ->vectorSearch( + index: 'vector', + path: 'vector4', + queryVector: $this->vectors[7], // This is an exact match of the vector + limit: 4, + exact: true, + ); + + self::assertInstanceOf(LaravelCollection::class, $results); + self::assertCount(4, $results); + self::assertSame('The Art of Computer Programming', $results->first()['title']); + self::assertSame(1.0, $results->first()['vectorSearchScore']); + } + + public function testEloquentBuilderVectorSearch() + { + $results = Book::vectorSearch( + index: 'vector', + path: 'vector4', + queryVector: $this->vectors[7], + limit: 5, + numCandidates: 15, + // excludes the exact match + filter: Query::query( + title: Query::ne('The Art of Computer Programming'), + ), + ); + + self::assertInstanceOf(EloquentCollection::class, $results); + self::assertCount(5, $results); + self::assertInstanceOf(Book::class, $results->first()); + self::assertNotSame('The Art of Computer Programming', $results->first()->title); + self::assertSame('The Mythical Man-Month: Essays on Software Engineering', $results->first()->title); + self::assertThat( + $results->first()->vectorSearchScore, + self::logicalAnd(self::isType('float'), self::greaterThan(0.9), self::lessThan(1.0)), + ); + } + + /** Generate random vectors using fixed seed to make tests deterministic */ + private function addVector(array $items): array + { + srand(1); + foreach ($items as &$item) { + $this->vectors[] = $item['vector4'] = array_map(fn () => rand() / mt_getrandmax(), range(0, 3)); + } + + return $items; } } From 8829052cf11613c8038664a4d6ee19cc3dffa469 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 13 Jan 2025 18:08:48 +0100 Subject: [PATCH 401/446] PHPORM-286 Add `Query::countByGroup()` and other `aggregateByGroup()` functions (#3243) * PHPORM-286 Add Query::countByGroup and other aggregateByGroup functions * Support counting distinct values with aggregate by group * Disable fail-fast due to Atlas issues --- .github/workflows/build-ci.yml | 2 ++ src/Query/Builder.php | 48 ++++++++++++++++++++++++++--- tests/QueryBuilderTest.php | 55 ++++++++++++++++++++++++++++++++++ 3 files changed, 101 insertions(+), 4 deletions(-) diff --git a/.github/workflows/build-ci.yml b/.github/workflows/build-ci.yml index 7a987d251..4fea1b84d 100644 --- a/.github/workflows/build-ci.yml +++ b/.github/workflows/build-ci.yml @@ -11,6 +11,8 @@ jobs: name: "PHP ${{ matrix.php }} Laravel ${{ matrix.laravel }} MongoDB ${{ matrix.mongodb }} ${{ matrix.mode }}" strategy: + # Tests with Atlas fail randomly + fail-fast: false matrix: os: - "ubuntu-latest" diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 06eb5ac47..910844cdd 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -31,6 +31,7 @@ use Override; use RuntimeException; use stdClass; +use TypeError; use function array_fill_keys; use function array_filter; @@ -315,6 +316,7 @@ public function toMql(): array if ($this->groups || $this->aggregate) { $group = []; $unwinds = []; + $set = []; // Add grouping columns to the $group part of the aggregation pipeline. if ($this->groups) { @@ -325,8 +327,10 @@ public function toMql(): array // this mimics SQL's behaviour a bit. $group[$column] = ['$last' => '$' . $column]; } + } - // Do the same for other columns that are selected. + // Add the last value of each column when there is no aggregate function. + if ($this->groups && ! $this->aggregate) { foreach ($columns as $column) { $key = str_replace('.', '_', $column); @@ -350,15 +354,22 @@ public function toMql(): array $aggregations = blank($this->aggregate['columns']) ? [] : $this->aggregate['columns']; - if (in_array('*', $aggregations) && $function === 'count') { + if ($column === '*' && $function === 'count' && ! $this->groups) { $options = $this->inheritConnectionOptions($this->options); return ['countDocuments' => [$wheres, $options]]; } + // "aggregate" is the name of the field that will hold the aggregated value. if ($function === 'count') { - // Translate count into sum. - $group['aggregate'] = ['$sum' => 1]; + if ($column === '*' || $aggregations === []) { + // Translate count into sum. + $group['aggregate'] = ['$sum' => 1]; + } else { + // Count the number of distinct values. + $group['aggregate'] = ['$addToSet' => '$' . $column]; + $set['aggregate'] = ['$size' => '$aggregate']; + } } else { $group['aggregate'] = ['$' . $function => '$' . $column]; } @@ -385,6 +396,10 @@ public function toMql(): array $pipeline[] = ['$group' => $group]; } + if ($set) { + $pipeline[] = ['$set' => $set]; + } + // Apply order and limit if ($this->orders) { $pipeline[] = ['$sort' => $this->aliasIdForQuery($this->orders)]; @@ -560,6 +575,8 @@ public function generateCacheKey() /** @return ($function is null ? AggregationBuilder : mixed) */ public function aggregate($function = null, $columns = ['*']) { + assert(is_array($columns), new TypeError(sprintf('Argument #2 ($columns) must be of type array, %s given', get_debug_type($columns)))); + if ($function === null) { if (! trait_exists(FluentFactoryTrait::class)) { // This error will be unreachable when the mongodb/builder package will be merged into mongodb/mongodb @@ -600,6 +617,15 @@ public function aggregate($function = null, $columns = ['*']) $this->columns = $previousColumns; $this->bindings['select'] = $previousSelectBindings; + // When the aggregation is per group, we return the results as is. + if ($this->groups) { + return $results->map(function (object $result) { + unset($result->id); + + return $result; + }); + } + if (isset($results[0])) { $result = (array) $results[0]; @@ -607,6 +633,20 @@ public function aggregate($function = null, $columns = ['*']) } } + /** + * {@inheritDoc} + * + * @see \Illuminate\Database\Query\Builder::aggregateByGroup() + */ + public function aggregateByGroup(string $function, array $columns = ['*']) + { + if (count($columns) > 1) { + throw new InvalidArgumentException('Aggregating by group requires zero or one columns.'); + } + + return $this->aggregate($function, $columns); + } + /** @inheritdoc */ public function exists() { diff --git a/tests/QueryBuilderTest.php b/tests/QueryBuilderTest.php index 136b1cf72..01f937915 100644 --- a/tests/QueryBuilderTest.php +++ b/tests/QueryBuilderTest.php @@ -7,6 +7,7 @@ use Carbon\Carbon; use DateTime; use DateTimeImmutable; +use Illuminate\Support\Collection as LaravelCollection; use Illuminate\Support\Facades\Date; use Illuminate\Support\Facades\DB; use Illuminate\Support\LazyCollection; @@ -32,6 +33,7 @@ use function count; use function key; use function md5; +use function method_exists; use function sort; use function strlen; @@ -617,6 +619,59 @@ public function testSubdocumentArrayAggregate() $this->assertEquals(12, DB::table('items')->avg('amount.*.hidden')); } + public function testAggregateGroupBy() + { + DB::table('users')->insert([ + ['name' => 'John Doe', 'role' => 'admin', 'score' => 1, 'active' => true], + ['name' => 'Jane Doe', 'role' => 'admin', 'score' => 2, 'active' => true], + ['name' => 'Robert Roe', 'role' => 'user', 'score' => 4], + ]); + + $results = DB::table('users')->groupBy('role')->orderBy('role')->aggregateByGroup('count'); + $this->assertInstanceOf(LaravelCollection::class, $results); + $this->assertEquals([(object) ['role' => 'admin', 'aggregate' => 2], (object) ['role' => 'user', 'aggregate' => 1]], $results->toArray()); + + $results = DB::table('users')->groupBy('role')->orderBy('role')->aggregateByGroup('count', ['active']); + $this->assertInstanceOf(LaravelCollection::class, $results); + $this->assertEquals([(object) ['role' => 'admin', 'aggregate' => 1], (object) ['role' => 'user', 'aggregate' => 0]], $results->toArray()); + + $results = DB::table('users')->groupBy('role')->orderBy('role')->aggregateByGroup('max', ['score']); + $this->assertInstanceOf(LaravelCollection::class, $results); + $this->assertEquals([(object) ['role' => 'admin', 'aggregate' => 2], (object) ['role' => 'user', 'aggregate' => 4]], $results->toArray()); + + if (! method_exists(Builder::class, 'countByGroup')) { + $this->markTestSkipped('*byGroup functions require Laravel v11.38+'); + } + + $results = DB::table('users')->groupBy('role')->orderBy('role')->countByGroup(); + $this->assertInstanceOf(LaravelCollection::class, $results); + $this->assertEquals([(object) ['role' => 'admin', 'aggregate' => 2], (object) ['role' => 'user', 'aggregate' => 1]], $results->toArray()); + + $results = DB::table('users')->groupBy('role')->orderBy('role')->maxByGroup('score'); + $this->assertInstanceOf(LaravelCollection::class, $results); + $this->assertEquals([(object) ['role' => 'admin', 'aggregate' => 2], (object) ['role' => 'user', 'aggregate' => 4]], $results->toArray()); + + $results = DB::table('users')->groupBy('role')->orderBy('role')->minByGroup('score'); + $this->assertInstanceOf(LaravelCollection::class, $results); + $this->assertEquals([(object) ['role' => 'admin', 'aggregate' => 1], (object) ['role' => 'user', 'aggregate' => 4]], $results->toArray()); + + $results = DB::table('users')->groupBy('role')->orderBy('role')->sumByGroup('score'); + $this->assertInstanceOf(LaravelCollection::class, $results); + $this->assertEquals([(object) ['role' => 'admin', 'aggregate' => 3], (object) ['role' => 'user', 'aggregate' => 4]], $results->toArray()); + + $results = DB::table('users')->groupBy('role')->orderBy('role')->avgByGroup('score'); + $this->assertInstanceOf(LaravelCollection::class, $results); + $this->assertEquals([(object) ['role' => 'admin', 'aggregate' => 1.5], (object) ['role' => 'user', 'aggregate' => 4]], $results->toArray()); + } + + public function testAggregateByGroupException(): void + { + $this->expectException(InvalidArgumentException::class); + $this->expectExceptionMessage('Aggregating by group requires zero or one columns.'); + + DB::table('users')->aggregateByGroup('max', ['foo', 'bar']); + } + public function testUpdateWithUpsert() { DB::table('items')->where('name', 'knife') From 697c36f322ecffc44f6b1116d8b3e9ec0e8da012 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 14 Jan 2025 08:49:35 +0100 Subject: [PATCH 402/446] PHPORM-209 Add query builder helper to set read preference (#3244) * PHPORM-209 Add query builder helper to set read preference * Support query timeout as decimal number of seconds --- src/Query/Builder.php | 31 ++++++++++++++++++++++++++++--- tests/Query/BuilderTest.php | 26 ++++++++++++++++++++++++++ 2 files changed, 54 insertions(+), 3 deletions(-) diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 910844cdd..4c7c8513f 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -28,6 +28,7 @@ use MongoDB\Builder\Type\QueryInterface; use MongoDB\Builder\Type\SearchOperatorInterface; use MongoDB\Driver\Cursor; +use MongoDB\Driver\ReadPreference; use Override; use RuntimeException; use stdClass; @@ -102,7 +103,7 @@ class Builder extends BaseBuilder /** * The maximum amount of seconds to allow the query to run. * - * @var int + * @var int|float */ public $timeout; @@ -113,6 +114,8 @@ class Builder extends BaseBuilder */ public $hint; + private ReadPreference $readPreference; + /** * Custom options to add to the query. * @@ -211,7 +214,7 @@ public function project($columns) /** * The maximum amount of seconds to allow the query to run. * - * @param int $seconds + * @param int|float $seconds * * @return $this */ @@ -454,7 +457,7 @@ public function toMql(): array // Apply order, offset, limit and projection if ($this->timeout) { - $options['maxTimeMS'] = $this->timeout * 1000; + $options['maxTimeMS'] = (int) ($this->timeout * 1000); } if ($this->orders) { @@ -1534,6 +1537,24 @@ public function options(array $options) return $this; } + /** + * Set the read preference for the query + * + * @see https://www.php.net/manual/en/class.mongodb-driver-readpreference.php + * + * @param string $mode + * @param array $tagSets + * @param array $options + * + * @return $this + */ + public function readPreference(string $mode, ?array $tagSets = null, ?array $options = null): static + { + $this->readPreference = new ReadPreference($mode, $tagSets, $options); + + return $this; + } + /** * Performs a full-text search of the field or fields in an Atlas collection. * NOTE: $search is only available for MongoDB Atlas clusters, and is not available for self-managed deployments. @@ -1642,6 +1663,10 @@ private function inheritConnectionOptions(array $options = []): array } } + if (! isset($options['readPreference']) && isset($this->readPreference)) { + $options['readPreference'] = $this->readPreference; + } + return $options; } diff --git a/tests/Query/BuilderTest.php b/tests/Query/BuilderTest.php index 20f4a4db2..2cc0c5764 100644 --- a/tests/Query/BuilderTest.php +++ b/tests/Query/BuilderTest.php @@ -15,6 +15,7 @@ use Mockery as m; use MongoDB\BSON\Regex; use MongoDB\BSON\UTCDateTime; +use MongoDB\Driver\ReadPreference; use MongoDB\Laravel\Connection; use MongoDB\Laravel\Query\Builder; use MongoDB\Laravel\Query\Grammar; @@ -1416,6 +1417,31 @@ function (Builder $elemMatchQuery): void { ['find' => [['embedded._id' => 1], []]], fn (Builder $builder) => $builder->where('embedded->id', 1), ]; + + yield 'options' => [ + ['find' => [[], ['comment' => 'hello']]], + fn (Builder $builder) => $builder->options(['comment' => 'hello']), + ]; + + yield 'readPreference' => [ + ['find' => [[], ['readPreference' => new ReadPreference(ReadPreference::SECONDARY_PREFERRED)]]], + fn (Builder $builder) => $builder->readPreference(ReadPreference::SECONDARY_PREFERRED), + ]; + + yield 'readPreference advanced' => [ + ['find' => [[], ['readPreference' => new ReadPreference(ReadPreference::NEAREST, [['dc' => 'ny']], ['maxStalenessSeconds' => 120])]]], + fn (Builder $builder) => $builder->readPreference(ReadPreference::NEAREST, [['dc' => 'ny']], ['maxStalenessSeconds' => 120]), + ]; + + yield 'hint' => [ + ['find' => [[], ['hint' => ['foo' => 1]]]], + fn (Builder $builder) => $builder->hint(['foo' => 1]), + ]; + + yield 'timeout' => [ + ['find' => [[], ['maxTimeMS' => 2345]]], + fn (Builder $builder) => $builder->timeout(2.3456), + ]; } #[DataProvider('provideExceptions')] From 19ed55e75767405d8ed9a901c9b19435fa4bff9f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 14 Jan 2025 22:13:55 +0100 Subject: [PATCH 403/446] PHPORM-28 Add Scout engine to index into MongoDB Search (#3205) --- .github/workflows/build-ci.yml | 3 + composer.json | 1 + docker-compose.yml | 6 +- phpstan-baseline.neon | 5 + phpunit.xml.dist | 2 +- src/MongoDBServiceProvider.php | 21 + src/Scout/ScoutEngine.php | 551 +++++++++++++++++ tests/ModelTest.php | 3 +- tests/Models/SchemaVersion.php | 4 +- tests/Scout/Models/ScoutUser.php | 43 ++ .../Models/SearchableInSameNamespace.php | 30 + tests/Scout/Models/SearchableModel.php | 50 ++ tests/Scout/ScoutEngineTest.php | 582 ++++++++++++++++++ tests/Scout/ScoutIntegrationTest.php | 262 ++++++++ 14 files changed, 1555 insertions(+), 8 deletions(-) create mode 100644 src/Scout/ScoutEngine.php create mode 100644 tests/Scout/Models/ScoutUser.php create mode 100644 tests/Scout/Models/SearchableInSameNamespace.php create mode 100644 tests/Scout/Models/SearchableModel.php create mode 100644 tests/Scout/ScoutEngineTest.php create mode 100644 tests/Scout/ScoutIntegrationTest.php diff --git a/.github/workflows/build-ci.yml b/.github/workflows/build-ci.yml index 4fea1b84d..16bd213ec 100644 --- a/.github/workflows/build-ci.yml +++ b/.github/workflows/build-ci.yml @@ -65,6 +65,9 @@ jobs: until docker exec --tty mongodb mongosh 127.0.0.1:27017 --eval "db.runCommand({ ping: 1 })"; do sleep 1 done + until docker exec --tty mongodb mongosh 127.0.0.1:27017 --eval "db.createCollection('connection_test') && db.getCollection('connection_test').createSearchIndex({mappings:{dynamic: true}})"; do + sleep 1 + done - name: "Show MongoDB server status" run: | diff --git a/composer.json b/composer.json index 68ec8bc4f..dce593ed5 100644 --- a/composer.json +++ b/composer.json @@ -35,6 +35,7 @@ }, "require-dev": { "mongodb/builder": "^0.2", + "laravel/scout": "^11", "league/flysystem-gridfs": "^3.28", "league/flysystem-read-only": "^3.0", "phpunit/phpunit": "^10.3", diff --git a/docker-compose.yml b/docker-compose.yml index f757ec3cd..fc0f0e49a 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,5 +1,3 @@ -version: '3.5' - services: app: tty: true @@ -16,11 +14,11 @@ services: mongodb: container_name: mongodb - image: mongo:latest + image: mongodb/mongodb-atlas-local:latest ports: - "27017:27017" healthcheck: - test: echo 'db.runCommand("ping").ok' | mongosh mongodb:27017 --quiet + test: mongosh --quiet --eval 'db.runCommand("ping").ok' interval: 10s timeout: 10s retries: 5 diff --git a/phpstan-baseline.neon b/phpstan-baseline.neon index 7b34210ad..737e31f17 100644 --- a/phpstan-baseline.neon +++ b/phpstan-baseline.neon @@ -24,3 +24,8 @@ parameters: message: "#^Method Illuminate\\\\Database\\\\Schema\\\\Blueprint\\:\\:create\\(\\) invoked with 1 parameter, 0 required\\.$#" count: 1 path: src/Schema/Builder.php + + - + message: "#^Call to an undefined method Illuminate\\\\Support\\\\HigherOrderCollectionProxy\\<\\(int\\|string\\), Illuminate\\\\Database\\\\Eloquent\\\\Model\\>\\:\\:pushSoftDeleteMetadata\\(\\)\\.$#" + count: 1 + path: src/Scout/ScoutEngine.php diff --git a/phpunit.xml.dist b/phpunit.xml.dist index 5431164d8..7044f9069 100644 --- a/phpunit.xml.dist +++ b/phpunit.xml.dist @@ -17,7 +17,7 @@ - + diff --git a/src/MongoDBServiceProvider.php b/src/MongoDBServiceProvider.php index 9db2122dc..b0c085b8e 100644 --- a/src/MongoDBServiceProvider.php +++ b/src/MongoDBServiceProvider.php @@ -7,12 +7,14 @@ use Closure; use Illuminate\Cache\CacheManager; use Illuminate\Cache\Repository; +use Illuminate\Container\Container; use Illuminate\Filesystem\FilesystemAdapter; use Illuminate\Filesystem\FilesystemManager; use Illuminate\Foundation\Application; use Illuminate\Session\SessionManager; use Illuminate\Support\ServiceProvider; use InvalidArgumentException; +use Laravel\Scout\EngineManager; use League\Flysystem\Filesystem; use League\Flysystem\GridFS\GridFSAdapter; use League\Flysystem\ReadOnly\ReadOnlyFilesystemAdapter; @@ -20,6 +22,7 @@ use MongoDB\Laravel\Cache\MongoStore; use MongoDB\Laravel\Eloquent\Model; use MongoDB\Laravel\Queue\MongoConnector; +use MongoDB\Laravel\Scout\ScoutEngine; use RuntimeException; use Symfony\Component\HttpFoundation\Session\Storage\Handler\MongoDbSessionHandler; @@ -102,6 +105,7 @@ public function register() }); $this->registerFlysystemAdapter(); + $this->registerScoutEngine(); } private function registerFlysystemAdapter(): void @@ -155,4 +159,21 @@ private function registerFlysystemAdapter(): void }); }); } + + private function registerScoutEngine(): void + { + $this->app->resolving(EngineManager::class, function (EngineManager $engineManager) { + $engineManager->extend('mongodb', function (Container $app) { + $connectionName = $app->get('config')->get('scout.mongodb.connection', 'mongodb'); + $connection = $app->get('db')->connection($connectionName); + $softDelete = (bool) $app->get('config')->get('scout.soft_delete', false); + + assert($connection instanceof Connection, new InvalidArgumentException(sprintf('The connection "%s" is not a MongoDB connection.', $connectionName))); + + return new ScoutEngine($connection->getMongoDB(), $softDelete); + }); + + return $engineManager; + }); + } } diff --git a/src/Scout/ScoutEngine.php b/src/Scout/ScoutEngine.php new file mode 100644 index 000000000..e3c9c68c3 --- /dev/null +++ b/src/Scout/ScoutEngine.php @@ -0,0 +1,551 @@ + [ + 'dynamic' => true, + ], + ]; + + private const TYPEMAP = ['root' => 'object', 'document' => 'bson', 'array' => 'bson']; + + public function __construct( + private Database $database, + private bool $softDelete, + ) { + } + + /** + * Update the given model in the index. + * + * @see Engine::update() + * + * @param EloquentCollection $models + * + * @throws MongoDBRuntimeException + */ + #[Override] + public function update($models) + { + assert($models instanceof EloquentCollection, new TypeError(sprintf('Argument #1 ($models) must be of type %s, %s given', EloquentCollection::class, get_debug_type($models)))); + + if ($models->isEmpty()) { + return; + } + + if ($this->softDelete && $this->usesSoftDelete($models)) { + $models->each->pushSoftDeleteMetadata(); + } + + $bulk = []; + foreach ($models as $model) { + assert($model instanceof Model && method_exists($model, 'toSearchableArray'), new LogicException(sprintf('Model "%s" must use "%s" trait', $model::class, Searchable::class))); + + $searchableData = $model->toSearchableArray(); + $searchableData = self::serialize($searchableData); + + // Skip/remove the model if it doesn't provide any searchable data + if (! $searchableData) { + $bulk[] = [ + 'deleteOne' => [ + ['_id' => $model->getScoutKey()], + ], + ]; + + continue; + } + + unset($searchableData['_id']); + + $searchableData = array_merge($searchableData, $model->scoutMetadata()); + + /** Convert the __soft_deleted set by {@see Searchable::pushSoftDeleteMetadata()} + * into a boolean for efficient storage and indexing. */ + if (isset($searchableData['__soft_deleted'])) { + $searchableData['__soft_deleted'] = (bool) $searchableData['__soft_deleted']; + } + + $bulk[] = [ + 'updateOne' => [ + ['_id' => $model->getScoutKey()], + [ + // The _id field is added automatically when the document is inserted + // Update all other fields + '$set' => $searchableData, + ], + ['upsert' => true], + ], + ]; + } + + $this->getIndexableCollection($models)->bulkWrite($bulk); + } + + /** + * Remove the given model from the index. + * + * @see Engine::delete() + * + * @param EloquentCollection $models + */ + #[Override] + public function delete($models): void + { + assert($models instanceof EloquentCollection, new TypeError(sprintf('Argument #1 ($models) must be of type %s, %s given', Collection::class, get_debug_type($models)))); + + if ($models->isEmpty()) { + return; + } + + $collection = $this->getIndexableCollection($models); + $ids = $models->map(fn (Model $model) => $model->getScoutKey())->all(); + $collection->deleteMany(['_id' => ['$in' => $ids]]); + } + + /** + * Perform the given search on the engine. + * + * @see Engine::search() + * + * @return array + */ + #[Override] + public function search(Builder $builder) + { + return $this->performSearch($builder); + } + + /** + * Perform the given search on the engine with pagination. + * + * @see Engine::paginate() + * + * @param int $perPage + * @param int $page + * + * @return array + */ + #[Override] + public function paginate(Builder $builder, $perPage, $page) + { + assert(is_int($perPage), new TypeError(sprintf('Argument #2 ($perPage) must be of type int, %s given', get_debug_type($perPage)))); + assert(is_int($page), new TypeError(sprintf('Argument #3 ($page) must be of type int, %s given', get_debug_type($page)))); + + $builder = clone $builder; + $builder->take($perPage); + + return $this->performSearch($builder, $perPage * ($page - 1)); + } + + /** + * Perform the given search on the engine. + */ + private function performSearch(Builder $builder, ?int $offset = null): array + { + $collection = $this->getSearchableCollection($builder->model); + + if ($builder->callback) { + $cursor = call_user_func( + $builder->callback, + $collection, + $builder->query, + $offset, + ); + assert($cursor instanceof CursorInterface, new LogicException(sprintf('The search builder closure must return a MongoDB cursor, %s returned', get_debug_type($cursor)))); + $cursor->setTypeMap(self::TYPEMAP); + + return $cursor->toArray(); + } + + // Using compound to combine search operators + // https://www.mongodb.com/docs/atlas/atlas-search/compound/#options + // "should" specifies conditions that contribute to the relevance score + // at least one of them must match, + // - "text" search for the text including fuzzy matching + // - "wildcard" allows special characters like * and ?, similar to LIKE in SQL + // These are the only search operators to accept wildcard path. + $compound = [ + 'should' => [ + [ + 'text' => [ + 'query' => $builder->query, + 'path' => ['wildcard' => '*'], + 'fuzzy' => ['maxEdits' => 2], + 'score' => ['boost' => ['value' => 5]], + ], + ], + [ + 'wildcard' => [ + 'query' => $builder->query . '*', + 'path' => ['wildcard' => '*'], + 'allowAnalyzedField' => true, + ], + ], + ], + 'minimumShouldMatch' => 1, + ]; + + // "filter" specifies conditions on exact values to match + // "mustNot" specifies conditions on exact values that must not match + // They don't contribute to the relevance score + foreach ($builder->wheres as $field => $value) { + if ($field === '__soft_deleted') { + $value = (bool) $value; + } + + $compound['filter'][] = ['equals' => ['path' => $field, 'value' => $value]]; + } + + foreach ($builder->whereIns as $field => $value) { + $compound['filter'][] = ['in' => ['path' => $field, 'value' => $value]]; + } + + foreach ($builder->whereNotIns as $field => $value) { + $compound['mustNot'][] = ['in' => ['path' => $field, 'value' => $value]]; + } + + // Sort by field value only if specified + $sort = []; + foreach ($builder->orders as $order) { + $sort[$order['column']] = $order['direction'] === 'asc' ? 1 : -1; + } + + $pipeline = [ + [ + '$search' => [ + 'index' => self::INDEX_NAME, + 'compound' => $compound, + 'count' => ['type' => 'lowerBound'], + ...($sort ? ['sort' => $sort] : []), + ], + ], + [ + '$addFields' => [ + // Metadata field with the total count of documents + '__count' => '$$SEARCH_META.count.lowerBound', + ], + ], + ]; + + if ($offset) { + $pipeline[] = ['$skip' => $offset]; + } + + if ($builder->limit) { + $pipeline[] = ['$limit' => $builder->limit]; + } + + $cursor = $collection->aggregate($pipeline); + $cursor->setTypeMap(self::TYPEMAP); + + return $cursor->toArray(); + } + + /** + * Pluck and return the primary keys of the given results. + * + * @see Engine::mapIds() + * + * @param list $results + */ + #[Override] + public function mapIds($results): Collection + { + assert(is_array($results), new TypeError(sprintf('Argument #1 ($results) must be of type array, %s given', get_debug_type($results)))); + + return new Collection(array_column($results, '_id')); + } + + /** + * Map the given results to instances of the given model. + * + * @see Engine::map() + * + * @param Builder $builder + * @param array $results + * @param Model $model + * + * @return Collection + */ + #[Override] + public function map(Builder $builder, $results, $model): Collection + { + return $this->performMap($builder, $results, $model, false); + } + + /** + * Map the given results to instances of the given model via a lazy collection. + * + * @see Engine::lazyMap() + * + * @param Builder $builder + * @param array $results + * @param Model $model + * + * @return LazyCollection + */ + #[Override] + public function lazyMap(Builder $builder, $results, $model): LazyCollection + { + return $this->performMap($builder, $results, $model, true); + } + + /** @return ($lazy is true ? LazyCollection : Collection) */ + private function performMap(Builder $builder, array $results, Model $model, bool $lazy): Collection|LazyCollection + { + if (! $results) { + $collection = $model->newCollection(); + + return $lazy ? LazyCollection::make($collection) : $collection; + } + + $objectIds = array_column($results, '_id'); + $objectIdPositions = array_flip($objectIds); + + return $model->queryScoutModelsByIds($builder, $objectIds) + ->{$lazy ? 'cursor' : 'get'}() + ->filter(function ($model) use ($objectIds) { + return in_array($model->getScoutKey(), $objectIds); + }) + ->map(function ($model) use ($results, $objectIdPositions) { + $result = $results[$objectIdPositions[$model->getScoutKey()]] ?? []; + + foreach ($result as $key => $value) { + if ($key[0] === '_' && $key !== '_id') { + $model->withScoutMetadata($key, $value); + } + } + + return $model; + }) + ->sortBy(function ($model) use ($objectIdPositions) { + return $objectIdPositions[$model->getScoutKey()]; + }) + ->values(); + } + + /** + * Get the total count from a raw result returned by the engine. + * This is an estimate if the count is larger than 1000. + * + * @see Engine::getTotalCount() + * @see https://www.mongodb.com/docs/atlas/atlas-search/counting/ + * + * @param stdClass[] $results + */ + #[Override] + public function getTotalCount($results): int + { + if (! $results) { + return 0; + } + + // __count field is added by the aggregation pipeline in performSearch() + // using the count.lowerBound in the $search stage + return $results[0]->__count; + } + + /** + * Flush all records from the engine. + * + * @see Engine::flush() + * + * @param Model $model + */ + #[Override] + public function flush($model): void + { + assert($model instanceof Model, new TypeError(sprintf('Argument #1 ($model) must be of type %s, %s given', Model::class, get_debug_type($model)))); + + $collection = $this->getIndexableCollection($model); + + $collection->deleteMany([]); + } + + /** + * Create the MongoDB Atlas Search index. + * + * Accepted options: + * - wait: bool, default true. Wait for the index to be created. + * + * @see Engine::createIndex() + * + * @param string $name Collection name + * @param array{wait?:bool} $options + */ + #[Override] + public function createIndex($name, array $options = []): void + { + assert(is_string($name), new TypeError(sprintf('Argument #1 ($name) must be of type string, %s given', get_debug_type($name)))); + + // Ensure the collection exists before creating the search index + $this->database->createCollection($name); + + $collection = $this->database->selectCollection($name); + $collection->createSearchIndex( + self::DEFAULT_DEFINITION, + ['name' => self::INDEX_NAME], + ); + + if ($options['wait'] ?? true) { + $this->wait(function () use ($collection) { + $indexes = $collection->listSearchIndexes([ + 'name' => self::INDEX_NAME, + 'typeMap' => ['root' => 'bson'], + ]); + + return $indexes->current() && $indexes->current()->status === 'READY'; + }); + } + } + + /** + * Delete a "search index", i.e. a MongoDB collection. + * + * @see Engine::deleteIndex() + */ + #[Override] + public function deleteIndex($name): void + { + assert(is_string($name), new TypeError(sprintf('Argument #1 ($name) must be of type string, %s given', get_debug_type($name)))); + + $this->database->dropCollection($name); + } + + /** Get the MongoDB collection used to search for the provided model */ + private function getSearchableCollection(Model|EloquentCollection $model): MongoDBCollection + { + if ($model instanceof EloquentCollection) { + $model = $model->first(); + } + + assert(method_exists($model, 'searchableAs'), sprintf('Model "%s" must use "%s" trait', $model::class, Searchable::class)); + + return $this->database->selectCollection($model->searchableAs()); + } + + /** Get the MongoDB collection used to index the provided model */ + private function getIndexableCollection(Model|EloquentCollection $model): MongoDBCollection + { + if ($model instanceof EloquentCollection) { + $model = $model->first(); + } + + assert($model instanceof Model); + assert(method_exists($model, 'indexableAs'), sprintf('Model "%s" must use "%s" trait', $model::class, Searchable::class)); + + if ( + $model->getConnection() instanceof Connection + && $model->getConnection()->getDatabaseName() === $this->database->getDatabaseName() + && $model->getTable() === $model->indexableAs() + ) { + throw new LogicException(sprintf('The MongoDB Scout collection "%s.%s" must use a different collection from the collection name of the model "%s". Set the "scout.prefix" configuration or use a distinct MongoDB database', $this->database->getDatabaseName(), $model->indexableAs(), $model::class)); + } + + return $this->database->selectCollection($model->indexableAs()); + } + + private static function serialize(mixed $value): mixed + { + if ($value instanceof DateTimeInterface) { + return new UTCDateTime($value); + } + + if ($value instanceof Serializable || ! is_iterable($value)) { + return $value; + } + + // Convert Laravel Collections and other Iterators to arrays + if ($value instanceof Traversable) { + $value = iterator_to_array($value); + } + + // Recursively serialize arrays + return array_map(self::serialize(...), $value); + } + + private function usesSoftDelete(Model|EloquentCollection $model): bool + { + if ($model instanceof EloquentCollection) { + $model = $model->first(); + } + + return in_array(SoftDeletes::class, class_uses_recursive($model)); + } + + /** + * Wait for the callback to return true, use it for asynchronous + * Atlas Search index management operations. + */ + private function wait(Closure $callback): void + { + // Fallback to time() if hrtime() is not supported + $timeout = (hrtime()[0] ?? time()) + self::WAIT_TIMEOUT_SEC; + while ((hrtime()[0] ?? time()) < $timeout) { + if ($callback()) { + return; + } + + sleep(1); + } + + throw new MongoDBRuntimeException(sprintf('Atlas search index operation time out after %s seconds', self::WAIT_TIMEOUT_SEC)); + } +} diff --git a/tests/ModelTest.php b/tests/ModelTest.php index c532eea55..ef71a5fe0 100644 --- a/tests/ModelTest.php +++ b/tests/ModelTest.php @@ -406,8 +406,9 @@ public function testSoftDelete(): void $this->assertEquals(2, Soft::count()); } + /** @param class-string $model */ #[DataProvider('provideId')] - public function testPrimaryKey(string $model, $id, $expected, bool $expectedFound): void + public function testPrimaryKey(string $model, mixed $id, mixed $expected, bool $expectedFound): void { $model::truncate(); $expectedType = get_debug_type($expected); diff --git a/tests/Models/SchemaVersion.php b/tests/Models/SchemaVersion.php index 8acd73545..b142d8bda 100644 --- a/tests/Models/SchemaVersion.php +++ b/tests/Models/SchemaVersion.php @@ -5,9 +5,9 @@ namespace MongoDB\Laravel\Tests\Models; use MongoDB\Laravel\Eloquent\HasSchemaVersion; -use MongoDB\Laravel\Eloquent\Model as Eloquent; +use MongoDB\Laravel\Eloquent\Model; -class SchemaVersion extends Eloquent +class SchemaVersion extends Model { use HasSchemaVersion; diff --git a/tests/Scout/Models/ScoutUser.php b/tests/Scout/Models/ScoutUser.php new file mode 100644 index 000000000..50fa39a94 --- /dev/null +++ b/tests/Scout/Models/ScoutUser.php @@ -0,0 +1,43 @@ +dropIfExists('scout_users'); + $schema->create('scout_users', function (Blueprint $table) { + $table->increments('id'); + $table->string('name'); + $table->string('email')->nullable(); + $table->date('email_verified_at')->nullable(); + $table->timestamps(); + $table->softDeletes(); + }); + } +} diff --git a/tests/Scout/Models/SearchableInSameNamespace.php b/tests/Scout/Models/SearchableInSameNamespace.php new file mode 100644 index 000000000..91b909067 --- /dev/null +++ b/tests/Scout/Models/SearchableInSameNamespace.php @@ -0,0 +1,30 @@ +getTable(); + } +} diff --git a/tests/Scout/Models/SearchableModel.php b/tests/Scout/Models/SearchableModel.php new file mode 100644 index 000000000..e53200f1a --- /dev/null +++ b/tests/Scout/Models/SearchableModel.php @@ -0,0 +1,50 @@ +getAttribute($this->getScoutKeyName()) ?: 'key_' . $this->getKey(); + } + + /** + * This method must be overridden when the `getScoutKey` method is also overridden, + * to support model serialization for async indexing jobs. + * + * @see Searchable::getScoutKeyName() + */ + public function getScoutKeyName(): string + { + return 'scout_key'; + } +} diff --git a/tests/Scout/ScoutEngineTest.php b/tests/Scout/ScoutEngineTest.php new file mode 100644 index 000000000..a079ae530 --- /dev/null +++ b/tests/Scout/ScoutEngineTest.php @@ -0,0 +1,582 @@ + 'object', 'document' => 'bson', 'array' => 'bson']; + + /** @param callable(): Builder $builder */ + #[DataProvider('provideSearchPipelines')] + public function testSearch(Closure $builder, array $expectedPipeline): void + { + $data = [['_id' => 'key_1', '__count' => 15], ['_id' => 'key_2', '__count' => 15]]; + $database = m::mock(Database::class); + $collection = m::mock(Collection::class); + $database->shouldReceive('selectCollection') + ->with('collection_searchable') + ->andReturn($collection); + $cursor = m::mock(CursorInterface::class); + $cursor->shouldReceive('setTypeMap')->once()->with(self::EXPECTED_TYPEMAP); + $cursor->shouldReceive('toArray')->once()->with()->andReturn($data); + + $collection->shouldReceive('getCollectionName') + ->zeroOrMoreTimes() + ->andReturn('collection_searchable'); + $collection->shouldReceive('aggregate') + ->once() + ->withArgs(function ($pipeline) use ($expectedPipeline) { + self::assertEquals($expectedPipeline, $pipeline); + + return true; + }) + ->andReturn($cursor); + + $engine = new ScoutEngine($database, softDelete: false); + $result = $engine->search($builder()); + $this->assertEquals($data, $result); + } + + public function provideSearchPipelines(): iterable + { + $defaultPipeline = [ + [ + '$search' => [ + 'index' => 'scout', + 'compound' => [ + 'should' => [ + [ + 'text' => [ + 'path' => ['wildcard' => '*'], + 'query' => 'lar', + 'fuzzy' => ['maxEdits' => 2], + 'score' => ['boost' => ['value' => 5]], + ], + ], + [ + 'wildcard' => [ + 'query' => 'lar*', + 'path' => ['wildcard' => '*'], + 'allowAnalyzedField' => true, + ], + ], + ], + 'minimumShouldMatch' => 1, + ], + 'count' => [ + 'type' => 'lowerBound', + ], + ], + ], + [ + '$addFields' => [ + '__count' => '$$SEARCH_META.count.lowerBound', + ], + ], + ]; + + yield 'simple string' => [ + function () { + return new Builder(new SearchableModel(), 'lar'); + }, + $defaultPipeline, + ]; + + yield 'where conditions' => [ + function () { + $builder = new Builder(new SearchableModel(), 'lar'); + $builder->where('foo', 'bar'); + $builder->where('key', 'value'); + + return $builder; + }, + array_replace_recursive($defaultPipeline, [ + [ + '$search' => [ + 'compound' => [ + 'filter' => [ + ['equals' => ['path' => 'foo', 'value' => 'bar']], + ['equals' => ['path' => 'key', 'value' => 'value']], + ], + ], + ], + ], + ]), + ]; + + yield 'where in conditions' => [ + function () { + $builder = new Builder(new SearchableModel(), 'lar'); + $builder->where('foo', 'bar'); + $builder->where('bar', 'baz'); + $builder->whereIn('qux', [1, 2]); + $builder->whereIn('quux', [1, 2]); + + return $builder; + }, + array_replace_recursive($defaultPipeline, [ + [ + '$search' => [ + 'compound' => [ + 'filter' => [ + ['equals' => ['path' => 'foo', 'value' => 'bar']], + ['equals' => ['path' => 'bar', 'value' => 'baz']], + ['in' => ['path' => 'qux', 'value' => [1, 2]]], + ['in' => ['path' => 'quux', 'value' => [1, 2]]], + ], + ], + ], + ], + ]), + ]; + + yield 'where not in conditions' => [ + function () { + $builder = new Builder(new SearchableModel(), 'lar'); + $builder->where('foo', 'bar'); + $builder->where('bar', 'baz'); + $builder->whereIn('qux', [1, 2]); + $builder->whereIn('quux', [1, 2]); + $builder->whereNotIn('eaea', [3]); + + return $builder; + }, + array_replace_recursive($defaultPipeline, [ + [ + '$search' => [ + 'compound' => [ + 'filter' => [ + ['equals' => ['path' => 'foo', 'value' => 'bar']], + ['equals' => ['path' => 'bar', 'value' => 'baz']], + ['in' => ['path' => 'qux', 'value' => [1, 2]]], + ['in' => ['path' => 'quux', 'value' => [1, 2]]], + ], + 'mustNot' => [ + ['in' => ['path' => 'eaea', 'value' => [3]]], + ], + ], + ], + ], + ]), + ]; + + yield 'where in conditions without other conditions' => [ + function () { + $builder = new Builder(new SearchableModel(), 'lar'); + $builder->whereIn('qux', [1, 2]); + $builder->whereIn('quux', [1, 2]); + + return $builder; + }, + array_replace_recursive($defaultPipeline, [ + [ + '$search' => [ + 'compound' => [ + 'filter' => [ + ['in' => ['path' => 'qux', 'value' => [1, 2]]], + ['in' => ['path' => 'quux', 'value' => [1, 2]]], + ], + ], + ], + ], + ]), + ]; + + yield 'where not in conditions without other conditions' => [ + function () { + $builder = new Builder(new SearchableModel(), 'lar'); + $builder->whereIn('qux', [1, 2]); + $builder->whereIn('quux', [1, 2]); + $builder->whereNotIn('eaea', [3]); + + return $builder; + }, + array_replace_recursive($defaultPipeline, [ + [ + '$search' => [ + 'compound' => [ + 'filter' => [ + ['in' => ['path' => 'qux', 'value' => [1, 2]]], + ['in' => ['path' => 'quux', 'value' => [1, 2]]], + ], + 'mustNot' => [ + ['in' => ['path' => 'eaea', 'value' => [3]]], + ], + ], + ], + ], + ]), + ]; + + yield 'empty where in conditions' => [ + function () { + $builder = new Builder(new SearchableModel(), 'lar'); + $builder->whereIn('qux', [1, 2]); + $builder->whereIn('quux', [1, 2]); + $builder->whereNotIn('eaea', [3]); + + return $builder; + }, + array_replace_recursive($defaultPipeline, [ + [ + '$search' => [ + 'compound' => [ + 'filter' => [ + ['in' => ['path' => 'qux', 'value' => [1, 2]]], + ['in' => ['path' => 'quux', 'value' => [1, 2]]], + ], + 'mustNot' => [ + ['in' => ['path' => 'eaea', 'value' => [3]]], + ], + ], + ], + ], + ]), + ]; + + yield 'exclude soft-deleted' => [ + function () { + return new Builder(new SearchableModel(), 'lar', softDelete: true); + }, + array_replace_recursive($defaultPipeline, [ + [ + '$search' => [ + 'compound' => [ + 'filter' => [ + ['equals' => ['path' => '__soft_deleted', 'value' => false]], + ], + ], + ], + ], + ]), + ]; + + yield 'only trashed' => [ + function () { + $builder = new Builder(new SearchableModel(), 'lar', softDelete: true); + $builder->onlyTrashed(); + + return $builder; + }, + array_replace_recursive($defaultPipeline, [ + [ + '$search' => [ + 'compound' => [ + 'filter' => [ + ['equals' => ['path' => '__soft_deleted', 'value' => true]], + ], + ], + ], + ], + ]), + ]; + + yield 'with callback' => [ + fn () => new Builder(new SearchableModel(), 'query', callback: function (...$args) { + $this->assertCount(3, $args); + $this->assertInstanceOf(Collection::class, $args[0]); + $this->assertSame('collection_searchable', $args[0]->getCollectionName()); + $this->assertSame('query', $args[1]); + $this->assertNull($args[2]); + + return $args[0]->aggregate(['pipeline']); + }), + ['pipeline'], + ]; + + yield 'ordered' => [ + function () { + $builder = new Builder(new SearchableModel(), 'lar'); + $builder->orderBy('name', 'desc'); + $builder->orderBy('age', 'asc'); + + return $builder; + }, + array_replace_recursive($defaultPipeline, [ + [ + '$search' => [ + 'sort' => [ + 'name' => -1, + 'age' => 1, + ], + ], + ], + ]), + ]; + } + + public function testPaginate() + { + $perPage = 5; + $page = 3; + + $database = m::mock(Database::class); + $collection = m::mock(Collection::class); + $cursor = m::mock(CursorInterface::class); + $database->shouldReceive('selectCollection') + ->with('collection_searchable') + ->andReturn($collection); + $collection->shouldReceive('aggregate') + ->once() + ->withArgs(function (...$args) { + self::assertSame([ + [ + '$search' => [ + 'index' => 'scout', + 'compound' => [ + 'should' => [ + [ + 'text' => [ + 'query' => 'mustang', + 'path' => ['wildcard' => '*'], + 'fuzzy' => ['maxEdits' => 2], + 'score' => ['boost' => ['value' => 5]], + ], + ], + [ + 'wildcard' => [ + 'query' => 'mustang*', + 'path' => ['wildcard' => '*'], + 'allowAnalyzedField' => true, + ], + ], + ], + 'minimumShouldMatch' => 1, + ], + 'count' => [ + 'type' => 'lowerBound', + ], + 'sort' => [ + 'name' => -1, + ], + ], + ], + [ + '$addFields' => [ + '__count' => '$$SEARCH_META.count.lowerBound', + ], + ], + [ + '$skip' => 10, + ], + [ + '$limit' => 5, + ], + ], $args[0]); + + return true; + }) + ->andReturn($cursor); + $cursor->shouldReceive('setTypeMap')->once()->with(self::EXPECTED_TYPEMAP); + $cursor->shouldReceive('toArray') + ->once() + ->with() + ->andReturn([['_id' => 'key_1', '__count' => 17], ['_id' => 'key_2', '__count' => 17]]); + + $engine = new ScoutEngine($database, softDelete: false); + $builder = new Builder(new SearchableModel(), 'mustang'); + $builder->orderBy('name', 'desc'); + $engine->paginate($builder, $perPage, $page); + } + + public function testMapMethodRespectsOrder() + { + $database = m::mock(Database::class); + $engine = new ScoutEngine($database, false); + + $model = m::mock(Model::class); + $model->shouldReceive(['getScoutKeyName' => 'id']); + $model->shouldReceive('queryScoutModelsByIds->get') + ->andReturn(LaravelCollection::make([ + new ScoutUser(['id' => 1]), + new ScoutUser(['id' => 2]), + new ScoutUser(['id' => 3]), + new ScoutUser(['id' => 4]), + ])); + + $builder = m::mock(Builder::class); + + $results = $engine->map($builder, [ + ['_id' => 1, '__count' => 4], + ['_id' => 2, '__count' => 4], + ['_id' => 4, '__count' => 4], + ['_id' => 3, '__count' => 4], + ], $model); + + $this->assertEquals(4, count($results)); + $this->assertEquals([ + 0 => ['id' => 1], + 1 => ['id' => 2], + 2 => ['id' => 4], + 3 => ['id' => 3], + ], $results->toArray()); + } + + public function testLazyMapMethodRespectsOrder() + { + $lazy = false; + $database = m::mock(Database::class); + $engine = new ScoutEngine($database, false); + + $model = m::mock(Model::class); + $model->shouldReceive(['getScoutKeyName' => 'id']); + $model->shouldReceive('queryScoutModelsByIds->cursor') + ->andReturn(LazyCollection::make([ + new ScoutUser(['id' => 1]), + new ScoutUser(['id' => 2]), + new ScoutUser(['id' => 3]), + new ScoutUser(['id' => 4]), + ])); + + $builder = m::mock(Builder::class); + + $results = $engine->lazyMap($builder, [ + ['_id' => 1, '__count' => 4], + ['_id' => 2, '__count' => 4], + ['_id' => 4, '__count' => 4], + ['_id' => 3, '__count' => 4], + ], $model); + + $this->assertEquals(4, count($results)); + $this->assertEquals([ + 0 => ['id' => 1], + 1 => ['id' => 2], + 2 => ['id' => 4], + 3 => ['id' => 3], + ], $results->toArray()); + } + + public function testUpdate(): void + { + $date = new DateTimeImmutable('2000-01-02 03:04:05'); + $database = m::mock(Database::class); + $collection = m::mock(Collection::class); + $database->shouldReceive('selectCollection') + ->with('collection_indexable') + ->andReturn($collection); + $collection->shouldReceive('bulkWrite') + ->once() + ->with([ + [ + 'updateOne' => [ + ['_id' => 'key_1'], + ['$set' => ['id' => 1, 'date' => new UTCDateTime($date)]], + ['upsert' => true], + ], + ], + [ + 'updateOne' => [ + ['_id' => 'key_2'], + ['$set' => ['id' => 2]], + ['upsert' => true], + ], + ], + ]); + + $engine = new ScoutEngine($database, softDelete: false); + $engine->update(EloquentCollection::make([ + new SearchableModel([ + 'id' => 1, + 'date' => $date, + ]), + new SearchableModel([ + 'id' => 2, + ]), + ])); + } + + public function testUpdateWithSoftDelete(): void + { + $date = new DateTimeImmutable('2000-01-02 03:04:05'); + $database = m::mock(Database::class); + $collection = m::mock(Collection::class); + $database->shouldReceive('selectCollection') + ->with('collection_indexable') + ->andReturn($collection); + $collection->shouldReceive('bulkWrite') + ->once() + ->withArgs(function ($pipeline) { + $this->assertSame([ + [ + 'updateOne' => [ + ['_id' => 'key_1'], + ['$set' => ['id' => 1, '__soft_deleted' => false]], + ['upsert' => true], + ], + ], + ], $pipeline); + + return true; + }); + + $model = new SearchableModel(['id' => 1]); + $model->delete(); + + $engine = new ScoutEngine($database, softDelete: true); + $engine->update(EloquentCollection::make([$model])); + } + + public function testDelete(): void + { + $database = m::mock(Database::class); + $collection = m::mock(Collection::class); + $database->shouldReceive('selectCollection') + ->with('collection_indexable') + ->andReturn($collection); + $collection->shouldReceive('deleteMany') + ->once() + ->with(['_id' => ['$in' => ['key_1', 'key_2']]]); + + $engine = new ScoutEngine($database, softDelete: false); + $engine->delete(EloquentCollection::make([ + new SearchableModel(['id' => 1]), + new SearchableModel(['id' => 2]), + ])); + } + + public function testDeleteWithRemoveableScoutCollection(): void + { + $job = new RemoveFromSearch(EloquentCollection::make([ + new SearchableModel(['id' => 5, 'scout_key' => 'key_5']), + ])); + + $job = unserialize(serialize($job)); + + $database = m::mock(Database::class); + $collection = m::mock(Collection::class); + $database->shouldReceive('selectCollection') + ->with('collection_indexable') + ->andReturn($collection); + $collection->shouldReceive('deleteMany') + ->once() + ->with(['_id' => ['$in' => ['key_5']]]); + + $engine = new ScoutEngine($database, softDelete: false); + $engine->delete($job->models); + } +} diff --git a/tests/Scout/ScoutIntegrationTest.php b/tests/Scout/ScoutIntegrationTest.php new file mode 100644 index 000000000..7b9d704f6 --- /dev/null +++ b/tests/Scout/ScoutIntegrationTest.php @@ -0,0 +1,262 @@ +set('scout.driver', 'mongodb'); + $app['config']->set('scout.prefix', 'prefix_'); + } + + public function setUp(): void + { + parent::setUp(); + + $this->skipIfSearchIndexManagementIsNotSupported(); + + // Init the SQL database with some objects that will be indexed + // Test data copied from Laravel Scout tests + // https://github.com/laravel/scout/blob/10.x/tests/Integration/SearchableTests.php + ScoutUser::executeSchema(); + + $collect = LazyCollection::make(function () { + yield ['name' => 'Laravel Framework']; + + foreach (range(2, 10) as $key) { + yield ['name' => 'Example ' . $key]; + } + + yield ['name' => 'Larry Casper', 'email_verified_at' => null]; + yield ['name' => 'Reta Larkin']; + + foreach (range(13, 19) as $key) { + yield ['name' => 'Example ' . $key]; + } + + yield ['name' => 'Prof. Larry Prosacco DVM', 'email_verified_at' => null]; + + foreach (range(21, 38) as $key) { + yield ['name' => 'Example ' . $key, 'email_verified_at' => null]; + } + + yield ['name' => 'Linkwood Larkin', 'email_verified_at' => null]; + yield ['name' => 'Otis Larson MD']; + yield ['name' => 'Gudrun Larkin']; + yield ['name' => 'Dax Larkin']; + yield ['name' => 'Dana Larson Sr.']; + yield ['name' => 'Amos Larson Sr.']; + }); + + $id = 0; + $date = new DateTimeImmutable('2021-01-01 00:00:00'); + foreach ($collect as $data) { + $data = array_merge(['id' => ++$id, 'email_verified_at' => $date], $data); + ScoutUser::create($data)->save(); + } + + self::assertSame(44, ScoutUser::count()); + } + + /** This test create the search index for tests performing search */ + public function testItCanCreateTheCollection() + { + $collection = DB::connection('mongodb')->getCollection('prefix_scout_users'); + $collection->drop(); + + // Recreate the indexes using the artisan commands + // Ensure they return a success exit code (0) + self::assertSame(0, artisan($this, 'scout:delete-index', ['name' => ScoutUser::class])); + self::assertSame(0, artisan($this, 'scout:index', ['name' => ScoutUser::class])); + self::assertSame(0, artisan($this, 'scout:import', ['model' => ScoutUser::class])); + + self::assertSame(44, $collection->countDocuments()); + + $searchIndexes = $collection->listSearchIndexes(['name' => 'scout']); + self::assertCount(1, $searchIndexes); + + // Wait for all documents to be indexed asynchronously + $i = 100; + while (true) { + $indexedDocuments = $collection->aggregate([ + ['$search' => ['index' => 'scout', 'exists' => ['path' => 'name']]], + ])->toArray(); + + if (count($indexedDocuments) >= 44) { + break; + } + + if ($i-- === 0) { + self::fail('Documents not indexed'); + } + + usleep(100_000); + } + + self::assertCount(44, $indexedDocuments); + } + + #[Depends('testItCanCreateTheCollection')] + public function testItCanUseBasicSearch() + { + // All the search queries use "sort" option to ensure the results are deterministic + $results = ScoutUser::search('lar')->take(10)->orderBy('id')->get(); + + self::assertSame([ + 1 => 'Laravel Framework', + 11 => 'Larry Casper', + 12 => 'Reta Larkin', + 20 => 'Prof. Larry Prosacco DVM', + 39 => 'Linkwood Larkin', + 40 => 'Otis Larson MD', + 41 => 'Gudrun Larkin', + 42 => 'Dax Larkin', + 43 => 'Dana Larson Sr.', + 44 => 'Amos Larson Sr.', + ], $results->pluck('name', 'id')->all()); + } + + #[Depends('testItCanCreateTheCollection')] + public function testItCanUseBasicSearchCursor() + { + // All the search queries use "sort" option to ensure the results are deterministic + $results = ScoutUser::search('lar')->take(10)->orderBy('id')->cursor(); + + self::assertSame([ + 1 => 'Laravel Framework', + 11 => 'Larry Casper', + 12 => 'Reta Larkin', + 20 => 'Prof. Larry Prosacco DVM', + 39 => 'Linkwood Larkin', + 40 => 'Otis Larson MD', + 41 => 'Gudrun Larkin', + 42 => 'Dax Larkin', + 43 => 'Dana Larson Sr.', + 44 => 'Amos Larson Sr.', + ], $results->pluck('name', 'id')->all()); + } + + #[Depends('testItCanCreateTheCollection')] + public function testItCanUseBasicSearchWithQueryCallback() + { + $results = ScoutUser::search('lar')->take(10)->orderBy('id')->query(function ($query) { + return $query->whereNotNull('email_verified_at'); + })->get(); + + self::assertSame([ + 1 => 'Laravel Framework', + 12 => 'Reta Larkin', + 40 => 'Otis Larson MD', + 41 => 'Gudrun Larkin', + 42 => 'Dax Larkin', + 43 => 'Dana Larson Sr.', + 44 => 'Amos Larson Sr.', + ], $results->pluck('name', 'id')->all()); + } + + #[Depends('testItCanCreateTheCollection')] + public function testItCanUseBasicSearchToFetchKeys() + { + $results = ScoutUser::search('lar')->orderBy('id')->take(10)->keys(); + + self::assertSame([1, 11, 12, 20, 39, 40, 41, 42, 43, 44], $results->all()); + } + + #[Depends('testItCanCreateTheCollection')] + public function testItCanUseBasicSearchWithQueryCallbackToFetchKeys() + { + $results = ScoutUser::search('lar')->take(10)->orderBy('id', 'desc')->query(function ($query) { + return $query->whereNotNull('email_verified_at'); + })->keys(); + + self::assertSame([44, 43, 42, 41, 40, 39, 20, 12, 11, 1], $results->all()); + } + + #[Depends('testItCanCreateTheCollection')] + public function testItCanUsePaginatedSearch() + { + $page1 = ScoutUser::search('lar')->take(10)->orderBy('id')->paginate(5, 'page', 1); + $page2 = ScoutUser::search('lar')->take(10)->orderBy('id')->paginate(5, 'page', 2); + + self::assertSame([ + 1 => 'Laravel Framework', + 11 => 'Larry Casper', + 12 => 'Reta Larkin', + 20 => 'Prof. Larry Prosacco DVM', + 39 => 'Linkwood Larkin', + ], $page1->pluck('name', 'id')->all()); + + self::assertSame([ + 40 => 'Otis Larson MD', + 41 => 'Gudrun Larkin', + 42 => 'Dax Larkin', + 43 => 'Dana Larson Sr.', + 44 => 'Amos Larson Sr.', + ], $page2->pluck('name', 'id')->all()); + } + + #[Depends('testItCanCreateTheCollection')] + public function testItCanUsePaginatedSearchWithQueryCallback() + { + $queryCallback = function ($query) { + return $query->whereNotNull('email_verified_at'); + }; + + $page1 = ScoutUser::search('lar')->take(10)->orderBy('id')->query($queryCallback)->paginate(5, 'page', 1); + $page2 = ScoutUser::search('lar')->take(10)->orderBy('id')->query($queryCallback)->paginate(5, 'page', 2); + + self::assertSame([ + 1 => 'Laravel Framework', + 12 => 'Reta Larkin', + ], $page1->pluck('name', 'id')->all()); + + self::assertSame([ + 40 => 'Otis Larson MD', + 41 => 'Gudrun Larkin', + 42 => 'Dax Larkin', + 43 => 'Dana Larson Sr.', + 44 => 'Amos Larson Sr.', + ], $page2->pluck('name', 'id')->all()); + } + + public function testItCannotIndexInTheSameNamespace() + { + self::expectException(LogicException::class); + self::expectExceptionMessage(sprintf( + 'The MongoDB Scout collection "%s.searchable_in_same_namespaces" must use a different collection from the collection name of the model "%s". Set the "scout.prefix" configuration or use a distinct MongoDB database', + env('MONGODB_DATABASE', 'unittest'), + SearchableInSameNamespace::class, + ),); + + SearchableInSameNamespace::create(['name' => 'test']); + } +} From 2b2c70a66279f9206085c857cb30f44ed52d8785 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Thu, 16 Jan 2025 09:08:54 +0100 Subject: [PATCH 404/446] Split Atlas tests into a distinct workflow matrix (#3245) --- .github/workflows/build-ci-atlas.yml | 74 ++++++++++++++++++++++++++++ .github/workflows/build-ci.yml | 32 +++--------- tests/AtlasSearchTest.php | 2 + tests/Scout/ScoutIntegrationTest.php | 2 + 4 files changed, 85 insertions(+), 25 deletions(-) create mode 100644 .github/workflows/build-ci-atlas.yml diff --git a/.github/workflows/build-ci-atlas.yml b/.github/workflows/build-ci-atlas.yml new file mode 100644 index 000000000..7a4ebd03f --- /dev/null +++ b/.github/workflows/build-ci-atlas.yml @@ -0,0 +1,74 @@ +name: "Atlas CI" + +on: + push: + pull_request: + +jobs: + build: + runs-on: "${{ matrix.os }}" + + name: "PHP ${{ matrix.php }} Laravel ${{ matrix.laravel }} Atlas" + + strategy: + matrix: + os: + - "ubuntu-latest" + php: + - "8.2" + - "8.3" + - "8.4" + laravel: + - "11.*" + + steps: + - uses: "actions/checkout@v4" + + - name: "Create MongoDB Atlas Local" + run: | + docker run --name mongodb -p 27017:27017 --detach mongodb/mongodb-atlas-local:latest + until docker exec --tty mongodb mongosh --eval "db.runCommand({ ping: 1 })"; do + sleep 1 + done + until docker exec --tty mongodb mongosh --eval "db.createCollection('connection_test') && db.getCollection('connection_test').createSearchIndex({mappings:{dynamic: true}})"; do + sleep 1 + done + + - name: "Show MongoDB server status" + run: | + docker exec --tty mongodb mongosh --eval "db.runCommand({ serverStatus: 1 })" + + - name: "Installing php" + uses: "shivammathur/setup-php@v2" + with: + php-version: ${{ matrix.php }} + extensions: "curl,mbstring,xdebug" + coverage: "xdebug" + tools: "composer" + + - name: "Show Docker version" + if: ${{ runner.debug }} + run: "docker version && env" + + - name: "Restrict Laravel version" + run: "composer require --dev --no-update 'laravel/framework:${{ matrix.laravel }}'" + + - name: "Download Composer cache dependencies from cache" + id: "composer-cache" + run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT + + - name: "Cache Composer dependencies" + uses: "actions/cache@v4" + with: + path: ${{ steps.composer-cache.outputs.dir }} + key: "${{ matrix.os }}-composer-${{ hashFiles('**/composer.json') }}" + restore-keys: "${{ matrix.os }}-composer-" + + - name: "Install dependencies" + run: | + composer update --no-interaction + + - name: "Run tests" + run: | + export MONGODB_URI="mongodb://127.0.0.1:27017/?directConnection=true" + ./vendor/bin/phpunit --coverage-clover coverage.xml --group atlas-search diff --git a/.github/workflows/build-ci.yml b/.github/workflows/build-ci.yml index 16bd213ec..d16a5885f 100644 --- a/.github/workflows/build-ci.yml +++ b/.github/workflows/build-ci.yml @@ -11,8 +11,6 @@ jobs: name: "PHP ${{ matrix.php }} Laravel ${{ matrix.laravel }} MongoDB ${{ matrix.mongodb }} ${{ matrix.mode }}" strategy: - # Tests with Atlas fail randomly - fail-fast: false matrix: os: - "ubuntu-latest" @@ -21,11 +19,12 @@ jobs: - "5.0" - "6.0" - "7.0" - - "Atlas" + - "8.0" php: - "8.1" - "8.2" - "8.3" + - "8.4" laravel: - "10.*" - "11.*" @@ -38,7 +37,6 @@ jobs: - php: "8.4" laravel: "11.*" mongodb: "7.0" - mode: "ignore-php-req" os: "ubuntu-latest" exclude: - php: "8.1" @@ -48,31 +46,19 @@ jobs: - uses: "actions/checkout@v4" - name: "Create MongoDB Replica Set" - if: ${{ matrix.mongodb != 'Atlas' }} run: | docker run --name mongodb -p 27017:27017 -e MONGO_INITDB_DATABASE=unittest --detach mongo:${{ matrix.mongodb }} mongod --replSet rs --setParameter transactionLifetimeLimitSeconds=5 if [ "${{ matrix.mongodb }}" = "4.4" ]; then MONGOSH_BIN="mongo"; else MONGOSH_BIN="mongosh"; fi - until docker exec --tty mongodb $MONGOSH_BIN 127.0.0.1:27017 --eval "db.runCommand({ ping: 1 })"; do - sleep 1 - done - sudo docker exec --tty mongodb $MONGOSH_BIN 127.0.0.1:27017 --eval "rs.initiate({\"_id\":\"rs\",\"members\":[{\"_id\":0,\"host\":\"127.0.0.1:27017\" }]})" - - - name: "Create MongoDB Atlas Local" - if: ${{ matrix.mongodb == 'Atlas' }} - run: | - docker run --name mongodb -p 27017:27017 --detach mongodb/mongodb-atlas-local:latest - until docker exec --tty mongodb mongosh 127.0.0.1:27017 --eval "db.runCommand({ ping: 1 })"; do - sleep 1 - done - until docker exec --tty mongodb mongosh 127.0.0.1:27017 --eval "db.createCollection('connection_test') && db.getCollection('connection_test').createSearchIndex({mappings:{dynamic: true}})"; do + until docker exec --tty mongodb $MONGOSH_BIN --eval "db.runCommand({ ping: 1 })"; do sleep 1 done + sudo docker exec --tty mongodb $MONGOSH_BIN --eval "rs.initiate({\"_id\":\"rs\",\"members\":[{\"_id\":0,\"host\":\"127.0.0.1:27017\" }]})" - name: "Show MongoDB server status" run: | if [ "${{ matrix.mongodb }}" = "4.4" ]; then MONGOSH_BIN="mongo"; else MONGOSH_BIN="mongosh"; fi - docker exec --tty mongodb $MONGOSH_BIN 127.0.0.1:27017 --eval "db.runCommand({ serverStatus: 1 })" + docker exec --tty mongodb $MONGOSH_BIN --eval "db.runCommand({ serverStatus: 1 })" - name: "Installing php" uses: "shivammathur/setup-php@v2" @@ -107,9 +93,5 @@ jobs: $([[ "${{ matrix.mode }}" == ignore-php-req ]] && echo ' --ignore-platform-req=php+') - name: "Run tests" run: | - if [ "${{ matrix.mongodb }}" = "Atlas" ]; then - export MONGODB_URI="mongodb://127.0.0.1:27017/" - else - export MONGODB_URI="mongodb://127.0.0.1:27017/?replicaSet=rs" - fi - ./vendor/bin/phpunit --coverage-clover coverage.xml + export MONGODB_URI="mongodb://127.0.0.1:27017/?replicaSet=rs" + ./vendor/bin/phpunit --coverage-clover coverage.xml --exclude-group atlas-search diff --git a/tests/AtlasSearchTest.php b/tests/AtlasSearchTest.php index c9cd2d5e3..43848c09a 100644 --- a/tests/AtlasSearchTest.php +++ b/tests/AtlasSearchTest.php @@ -11,6 +11,7 @@ use MongoDB\Driver\Exception\ServerException; use MongoDB\Laravel\Schema\Builder; use MongoDB\Laravel\Tests\Models\Book; +use PHPUnit\Framework\Attributes\Group; use function array_map; use function assert; @@ -21,6 +22,7 @@ use function usleep; use function usort; +#[Group('atlas-search')] class AtlasSearchTest extends TestCase { private array $vectors; diff --git a/tests/Scout/ScoutIntegrationTest.php b/tests/Scout/ScoutIntegrationTest.php index 7b9d704f6..ff4617352 100644 --- a/tests/Scout/ScoutIntegrationTest.php +++ b/tests/Scout/ScoutIntegrationTest.php @@ -12,6 +12,7 @@ use MongoDB\Laravel\Tests\TestCase; use Override; use PHPUnit\Framework\Attributes\Depends; +use PHPUnit\Framework\Attributes\Group; use function array_merge; use function count; @@ -21,6 +22,7 @@ use function sprintf; use function usleep; +#[Group('atlas-search')] class ScoutIntegrationTest extends TestCase { #[Override] From b89a52eef5910b1a56ec3d4c322cf320582fcaae Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Fri, 24 Jan 2025 09:54:57 -0500 Subject: [PATCH 405/446] DOCSP-45877: txn parallel ops not supported (#3247) * DOCSP-45877: txn parallel ops not supported * small fix --- docs/transactions.txt | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/transactions.txt b/docs/transactions.txt index 377423d67..b4a7827ba 100644 --- a/docs/transactions.txt +++ b/docs/transactions.txt @@ -24,8 +24,8 @@ In this guide, you can learn how to perform a **transaction** in MongoDB by using {+odm-long+}. Transactions let you run a sequence of write operations that update the data only after the transaction is committed. -If the transaction fails, the {+php-library+} that manages MongoDB operations -for the {+odm-short+} ensures that MongoDB discards all the changes made within +If the transaction fails, the {+php-library+}, which manages MongoDB operations +for the {+odm-short+}, ensures that MongoDB discards all the changes made within the transaction before they become visible. This property of transactions that ensures that all changes within a transaction are either applied or discarded is called **atomicity**. @@ -74,15 +74,20 @@ MongoDB Server and the {+odm-short+} have the following limitations: you perform write operations in a transaction. To learn more about this limitation, see :manual:`Create Collections and Indexes in a Transaction ` in the {+server-docs-name+}. + - MongoDB does not support nested transactions. If you attempt to start a transaction within another one, the extension raises a ``RuntimeException``. To learn more about this limitation, see :manual:`Transactions and Sessions ` in the {+server-docs-name+}. + - {+odm-long+} does not support the database testing traits ``Illuminate\Foundation\Testing\DatabaseTransactions`` and ``Illuminate\Foundation\Testing\RefreshDatabase``. As a workaround, you can create migrations with the ``Illuminate\Foundation\Testing\DatabaseMigrations`` trait to reset the database after each test. +- {+odm-long+} does not support running parallel operations within a + single transaction. + .. _laravel-transaction-callback: Run a Transaction in a Callback From 3eac5eb0bd86892c785ed72f8a48633fe5ca9a2e Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Fri, 24 Jan 2025 10:04:32 -0500 Subject: [PATCH 406/446] DOCSP-45877: txn parallel ops not supported (#3247) (#3250) * DOCSP-45877: txn parallel ops not supported * small fix (cherry picked from commit b89a52eef5910b1a56ec3d4c322cf320582fcaae) --- docs/transactions.txt | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/transactions.txt b/docs/transactions.txt index 377423d67..b4a7827ba 100644 --- a/docs/transactions.txt +++ b/docs/transactions.txt @@ -24,8 +24,8 @@ In this guide, you can learn how to perform a **transaction** in MongoDB by using {+odm-long+}. Transactions let you run a sequence of write operations that update the data only after the transaction is committed. -If the transaction fails, the {+php-library+} that manages MongoDB operations -for the {+odm-short+} ensures that MongoDB discards all the changes made within +If the transaction fails, the {+php-library+}, which manages MongoDB operations +for the {+odm-short+}, ensures that MongoDB discards all the changes made within the transaction before they become visible. This property of transactions that ensures that all changes within a transaction are either applied or discarded is called **atomicity**. @@ -74,15 +74,20 @@ MongoDB Server and the {+odm-short+} have the following limitations: you perform write operations in a transaction. To learn more about this limitation, see :manual:`Create Collections and Indexes in a Transaction ` in the {+server-docs-name+}. + - MongoDB does not support nested transactions. If you attempt to start a transaction within another one, the extension raises a ``RuntimeException``. To learn more about this limitation, see :manual:`Transactions and Sessions ` in the {+server-docs-name+}. + - {+odm-long+} does not support the database testing traits ``Illuminate\Foundation\Testing\DatabaseTransactions`` and ``Illuminate\Foundation\Testing\RefreshDatabase``. As a workaround, you can create migrations with the ``Illuminate\Foundation\Testing\DatabaseMigrations`` trait to reset the database after each test. +- {+odm-long+} does not support running parallel operations within a + single transaction. + .. _laravel-transaction-callback: Run a Transaction in a Callback From 4af26e7ef356435c40e48d81a71c3104f5135532 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Fri, 24 Jan 2025 10:04:43 -0500 Subject: [PATCH 407/446] DOCSP-45877: txn parallel ops not supported (#3247) (#3249) * DOCSP-45877: txn parallel ops not supported * small fix (cherry picked from commit b89a52eef5910b1a56ec3d4c322cf320582fcaae) --- docs/transactions.txt | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/transactions.txt b/docs/transactions.txt index 377423d67..b4a7827ba 100644 --- a/docs/transactions.txt +++ b/docs/transactions.txt @@ -24,8 +24,8 @@ In this guide, you can learn how to perform a **transaction** in MongoDB by using {+odm-long+}. Transactions let you run a sequence of write operations that update the data only after the transaction is committed. -If the transaction fails, the {+php-library+} that manages MongoDB operations -for the {+odm-short+} ensures that MongoDB discards all the changes made within +If the transaction fails, the {+php-library+}, which manages MongoDB operations +for the {+odm-short+}, ensures that MongoDB discards all the changes made within the transaction before they become visible. This property of transactions that ensures that all changes within a transaction are either applied or discarded is called **atomicity**. @@ -74,15 +74,20 @@ MongoDB Server and the {+odm-short+} have the following limitations: you perform write operations in a transaction. To learn more about this limitation, see :manual:`Create Collections and Indexes in a Transaction ` in the {+server-docs-name+}. + - MongoDB does not support nested transactions. If you attempt to start a transaction within another one, the extension raises a ``RuntimeException``. To learn more about this limitation, see :manual:`Transactions and Sessions ` in the {+server-docs-name+}. + - {+odm-long+} does not support the database testing traits ``Illuminate\Foundation\Testing\DatabaseTransactions`` and ``Illuminate\Foundation\Testing\RefreshDatabase``. As a workaround, you can create migrations with the ``Illuminate\Foundation\Testing\DatabaseMigrations`` trait to reset the database after each test. +- {+odm-long+} does not support running parallel operations within a + single transaction. + .. _laravel-transaction-callback: Run a Transaction in a Callback From 867731c3df701c444a1e0c965d4aebcf4fe055e3 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Wed, 29 Jan 2025 11:21:00 -0500 Subject: [PATCH 408/446] DOCSP-45065: sessions documentation (#3254) * DOCSP-45065: sessions documentation * MW PR fixes 1 * JT tech review 1 * small fix error in build --- docs/eloquent-models/schema-builder.txt | 2 + docs/index.txt | 2 + docs/query-builder.txt | 2 +- docs/sessions.txt | 102 ++++++++++++++++++++++++ 4 files changed, 107 insertions(+), 1 deletion(-) create mode 100644 docs/sessions.txt diff --git a/docs/eloquent-models/schema-builder.txt b/docs/eloquent-models/schema-builder.txt index 510365d06..dad3c8eed 100644 --- a/docs/eloquent-models/schema-builder.txt +++ b/docs/eloquent-models/schema-builder.txt @@ -248,6 +248,8 @@ field: To learn more about index options, see :manual:`Options for All Index Types ` in the {+server-docs-name+}. +.. _laravel-schema-builder-special-idx: + Create Sparse, TTL, and Unique Indexes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/index.txt b/docs/index.txt index 104a6aa77..892be3c3e 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -21,6 +21,7 @@ Query Builder User Authentication Cache & Locks + HTTP Sessions Queues Transactions GridFS Filesystems @@ -84,6 +85,7 @@ see the following content: - :ref:`laravel-aggregation-builder` - :ref:`laravel-user-authentication` - :ref:`laravel-cache` +- :ref:`laravel-sessions` - :ref:`laravel-queues` - :ref:`laravel-transactions` - :ref:`laravel-filesystems` diff --git a/docs/query-builder.txt b/docs/query-builder.txt index 9bf4ea857..b3c89b0ae 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -678,7 +678,7 @@ a query: :end-before: end options The query builder accepts the same options that you can set for -the :phpmethod:`find() ` method in the +the :phpmethod:`MongoDB\Collection::find()` method in the {+php-library+}. Some of the options to modify query results, such as ``skip``, ``sort``, and ``limit``, are settable directly as query builder methods and are described in the diff --git a/docs/sessions.txt b/docs/sessions.txt new file mode 100644 index 000000000..ea33b0d66 --- /dev/null +++ b/docs/sessions.txt @@ -0,0 +1,102 @@ +.. _laravel-sessions: + +============= +HTTP Sessions +============= + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: php framework, odm, cookies, multiple requests + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to set up HTTP sessions by +using {+odm-long+}. Sessions allow your application to store information +about a user across multiple server requests. Your application stores this +information in a specified location that it can access in future +requests that the user makes. The session driver in {+odm-long+} uses +the ``MongoDbSessionHandler`` class from the Symfony framework to store +session information. + +To learn more about support for sessions, see `HTTP Session +`__ in the +Laravel documentation. + +Register a Session +------------------ + +Before you can register a session, you must configure your connection to +MongoDB in your application's ``config/database.php`` file. To learn how +to set up this connection, see the +:ref:`laravel-quick-start-connect-to-mongodb` step of the Quick Start +guide. + +Next, you can select the session driver and connection in one of the +following ways: + +1. In an ``.env`` file, by setting the following environment variables: + + .. code-block:: ini + :caption: .env + + SESSION_DRIVER=mongodb + # Optional, this is the default value + SESSION_CONNECTION=mongodb + +#. In the ``config/session.php`` file, as shown in the following code: + + .. code-block:: php + :caption: config/session.php + + 'mongodb', // Required + 'connection' => 'mongodb', // Database connection name, default is "mongodb" + 'table' => 'sessions', // Collection name, default is "sessions" + 'lifetime' => null, // TTL of session in minutes, default is 120 + 'options' => [] // Other driver options + ]; + +The following list describes other driver options that you can set in +the ``options`` array: + +- ``id_field``: Field name for storing the session ID (default: ``_id``) +- ``data_field``: Field name for storing the session data (default: ``data``) +- ``time_field``: Field name for storing the timestamp (default: ``time``) +- ``expiry_field``: Field name for storing the expiry-timestamp (default: ``expires_at``) +- ``ttl``: Time to live in seconds + +We recommend that you create an index on the ``expiry_field`` field for +garbage collection. You can also automatically expire sessions in the +database by creating a TTL index on the collection that stores session +information. + +You can use the ``Schema`` builder to create a TTL index, as shown in +the following code: + +.. code-block:: php + + Schema::create('sessions', function (Blueprint $collection) { + $collection->expire('expiry_field', 0); + }); + +Setting the time value to ``0`` in the index +definition instructs MongoDB to expire documents at the clock time +specified in the ``expiry_field`` field. + +To learn more about using the ``Schema`` builder to create indexes, see +the :ref:`laravel-schema-builder-special-idx` section of the Schema +Builder guide. + +To learn more about TTL indexes, see :manual:`Expire Data from +Collections by Setting TTL ` in the +{+server-docs-name+}. From af50a44548298db565c44dd6d38623c3505429bc Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Wed, 29 Jan 2025 15:36:28 -0500 Subject: [PATCH 409/446] DOCSP-45065: sessions page quick fix (#3256) * DOCSP-45065: sessions documentation * MW PR fixes 1 * JT tech review 1 * small fix error in build * DOCSP-45065: quick fix to full PR --- docs/sessions.txt | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/sessions.txt b/docs/sessions.txt index ea33b0d66..e8ed10e7a 100644 --- a/docs/sessions.txt +++ b/docs/sessions.txt @@ -69,10 +69,10 @@ following ways: The following list describes other driver options that you can set in the ``options`` array: -- ``id_field``: Field name for storing the session ID (default: ``_id``) -- ``data_field``: Field name for storing the session data (default: ``data``) -- ``time_field``: Field name for storing the timestamp (default: ``time``) -- ``expiry_field``: Field name for storing the expiry-timestamp (default: ``expires_at``) +- ``id_field``: Custom field name for storing the session ID (default: ``_id``) +- ``data_field``: Custom field name for storing the session data (default: ``data``) +- ``time_field``: Custom field name for storing the timestamp (default: ``time``) +- ``expiry_field``: Custom field name for storing the expiry timestamp (default: ``expires_at``) - ``ttl``: Time to live in seconds We recommend that you create an index on the ``expiry_field`` field for @@ -86,12 +86,12 @@ the following code: .. code-block:: php Schema::create('sessions', function (Blueprint $collection) { - $collection->expire('expiry_field', 0); + $collection->expire('expires_at', 0); }); -Setting the time value to ``0`` in the index -definition instructs MongoDB to expire documents at the clock time -specified in the ``expiry_field`` field. +Setting the time value to ``0`` in the index definition instructs +MongoDB to expire documents at the clock time specified in the +``expires_at`` field. To learn more about using the ``Schema`` builder to create indexes, see the :ref:`laravel-schema-builder-special-idx` section of the Schema From ce2ba2f4891492dd8b548ba529a2900057f25fe1 Mon Sep 17 00:00:00 2001 From: Brad Miller <28307684+mad-briller@users.noreply.github.com> Date: Thu, 6 Feb 2025 15:45:56 +0000 Subject: [PATCH 410/446] Add template types to relation classes (#3262) --- phpstan-baseline.neon | 30 ++++++++++++++++++++++++++++++ src/Relations/BelongsTo.php | 8 +++++++- src/Relations/BelongsToMany.php | 5 +++++ src/Relations/EmbedsMany.php | 6 ++++++ src/Relations/EmbedsOne.php | 6 ++++++ src/Relations/EmbedsOneOrMany.php | 6 ++++++ src/Relations/HasMany.php | 5 +++++ src/Relations/HasOne.php | 5 +++++ src/Relations/MorphMany.php | 5 +++++ src/Relations/MorphTo.php | 5 +++++ src/Relations/MorphToMany.php | 5 +++++ 11 files changed, 85 insertions(+), 1 deletion(-) diff --git a/phpstan-baseline.neon b/phpstan-baseline.neon index 737e31f17..67fdd4154 100644 --- a/phpstan-baseline.neon +++ b/phpstan-baseline.neon @@ -10,11 +10,41 @@ parameters: count: 4 path: src/MongoDBServiceProvider.php + - + message: "#^Call to an undefined method TDeclaringModel of Illuminate\\\\Database\\\\Eloquent\\\\Model\\:\\:pull\\(\\)\\.$#" + count: 1 + path: src/Relations/BelongsToMany.php + - message: "#^Method Illuminate\\\\Database\\\\Eloquent\\\\Model\\:\\:push\\(\\) invoked with 3 parameters, 0 required\\.$#" count: 3 path: src/Relations/BelongsToMany.php + - + message: "#^Call to an undefined method MongoDB\\\\Laravel\\\\Relations\\\\EmbedsMany\\\\:\\:contains\\(\\)\\.$#" + count: 1 + path: src/Relations/EmbedsMany.php + + - + message: "#^Call to an undefined method TDeclaringModel of Illuminate\\\\Database\\\\Eloquent\\\\Model\\:\\:getParentRelation\\(\\)\\.$#" + count: 1 + path: src/Relations/EmbedsOneOrMany.php + + - + message: "#^Call to an undefined method TDeclaringModel of Illuminate\\\\Database\\\\Eloquent\\\\Model\\:\\:setParentRelation\\(\\)\\.$#" + count: 1 + path: src/Relations/EmbedsOneOrMany.php + + - + message: "#^Call to an undefined method TRelatedModel of Illuminate\\\\Database\\\\Eloquent\\\\Model\\:\\:setParentRelation\\(\\)\\.$#" + count: 2 + path: src/Relations/EmbedsOneOrMany.php + + - + message: "#^Call to an undefined method TDeclaringModel of Illuminate\\\\Database\\\\Eloquent\\\\Model\\:\\:pull\\(\\)\\.$#" + count: 2 + path: src/Relations/MorphToMany.php + - message: "#^Method Illuminate\\\\Database\\\\Eloquent\\\\Model\\:\\:push\\(\\) invoked with 3 parameters, 0 required\\.$#" count: 6 diff --git a/src/Relations/BelongsTo.php b/src/Relations/BelongsTo.php index 175a53e49..93eb11f8e 100644 --- a/src/Relations/BelongsTo.php +++ b/src/Relations/BelongsTo.php @@ -6,8 +6,14 @@ use Illuminate\Database\Eloquent\Builder; use Illuminate\Database\Eloquent\Model; +use Illuminate\Database\Eloquent\Relations\BelongsTo as EloquentBelongsTo; -class BelongsTo extends \Illuminate\Database\Eloquent\Relations\BelongsTo +/** + * @template TRelatedModel of Model + * @template TDeclaringModel of Model + * @extends EloquentBelongsTo + */ +class BelongsTo extends EloquentBelongsTo { /** * Get the key for comparing against the parent key in "has" query. diff --git a/src/Relations/BelongsToMany.php b/src/Relations/BelongsToMany.php index b68c79d4c..a150fccf7 100644 --- a/src/Relations/BelongsToMany.php +++ b/src/Relations/BelongsToMany.php @@ -21,6 +21,11 @@ use function in_array; use function is_numeric; +/** + * @template TRelatedModel of Model + * @template TDeclaringModel of Model + * @extends EloquentBelongsToMany + */ class BelongsToMany extends EloquentBelongsToMany { /** diff --git a/src/Relations/EmbedsMany.php b/src/Relations/EmbedsMany.php index e4bbf535f..49e1afa2d 100644 --- a/src/Relations/EmbedsMany.php +++ b/src/Relations/EmbedsMany.php @@ -21,6 +21,12 @@ use function throw_if; use function value; +/** + * @template TRelatedModel of Model + * @template TDeclaringModel of Model + * @template TResult + * @extends EmbedsOneOrMany + */ class EmbedsMany extends EmbedsOneOrMany { /** @inheritdoc */ diff --git a/src/Relations/EmbedsOne.php b/src/Relations/EmbedsOne.php index 95d5cc15d..be7fb192f 100644 --- a/src/Relations/EmbedsOne.php +++ b/src/Relations/EmbedsOne.php @@ -11,6 +11,12 @@ use function throw_if; +/** + * @template TRelatedModel of Model + * @template TDeclaringModel of Model + * @template TResult + * @extends EmbedsOneOrMany + */ class EmbedsOne extends EmbedsOneOrMany { public function initRelation(array $models, $relation) diff --git a/src/Relations/EmbedsOneOrMany.php b/src/Relations/EmbedsOneOrMany.php index f18d3d526..a46593cf4 100644 --- a/src/Relations/EmbedsOneOrMany.php +++ b/src/Relations/EmbedsOneOrMany.php @@ -21,6 +21,12 @@ use function str_starts_with; use function throw_if; +/** + * @template TRelatedModel of Model + * @template TDeclaringModel of Model + * @template TResult + * @extends Relation + */ abstract class EmbedsOneOrMany extends Relation { /** diff --git a/src/Relations/HasMany.php b/src/Relations/HasMany.php index a38fba15a..c8e7e0590 100644 --- a/src/Relations/HasMany.php +++ b/src/Relations/HasMany.php @@ -8,6 +8,11 @@ use Illuminate\Database\Eloquent\Model; use Illuminate\Database\Eloquent\Relations\HasMany as EloquentHasMany; +/** + * @template TRelatedModel of Model + * @template TDeclaringModel of Model + * @extends EloquentHasMany + */ class HasMany extends EloquentHasMany { /** diff --git a/src/Relations/HasOne.php b/src/Relations/HasOne.php index 740a489d8..ea26761d3 100644 --- a/src/Relations/HasOne.php +++ b/src/Relations/HasOne.php @@ -8,6 +8,11 @@ use Illuminate\Database\Eloquent\Model; use Illuminate\Database\Eloquent\Relations\HasOne as EloquentHasOne; +/** + * @template TRelatedModel of Model + * @template TDeclaringModel of Model + * @extends EloquentHasOne + */ class HasOne extends EloquentHasOne { /** diff --git a/src/Relations/MorphMany.php b/src/Relations/MorphMany.php index 88f825dc0..5f395950f 100644 --- a/src/Relations/MorphMany.php +++ b/src/Relations/MorphMany.php @@ -7,6 +7,11 @@ use Illuminate\Database\Eloquent\Model; use Illuminate\Database\Eloquent\Relations\MorphMany as EloquentMorphMany; +/** + * @template TRelatedModel of Model + * @template TDeclaringModel of Model + * @extends EloquentMorphMany + */ class MorphMany extends EloquentMorphMany { /** diff --git a/src/Relations/MorphTo.php b/src/Relations/MorphTo.php index 4874b23bb..4888b2d97 100644 --- a/src/Relations/MorphTo.php +++ b/src/Relations/MorphTo.php @@ -7,6 +7,11 @@ use Illuminate\Database\Eloquent\Model; use Illuminate\Database\Eloquent\Relations\MorphTo as EloquentMorphTo; +/** + * @template TRelatedModel of Model + * @template TDeclaringModel of Model + * @extends EloquentMorphTo + */ class MorphTo extends EloquentMorphTo { /** @inheritdoc */ diff --git a/src/Relations/MorphToMany.php b/src/Relations/MorphToMany.php index f11d25473..929738360 100644 --- a/src/Relations/MorphToMany.php +++ b/src/Relations/MorphToMany.php @@ -24,6 +24,11 @@ use function is_array; use function is_numeric; +/** + * @template TRelatedModel of Model + * @template TDeclaringModel of Model + * @extends EloquentMorphToMany + */ class MorphToMany extends EloquentMorphToMany { /** @inheritdoc */ From 1c27b2a461cfcf22407a6531cae09025a801008c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Thu, 6 Feb 2025 19:36:29 +0100 Subject: [PATCH 411/446] Add tests on doesntExist (#3257) --- tests/QueryTest.php | 2 ++ 1 file changed, 2 insertions(+) diff --git a/tests/QueryTest.php b/tests/QueryTest.php index 78a7b1bee..4fd362ae9 100644 --- a/tests/QueryTest.php +++ b/tests/QueryTest.php @@ -411,6 +411,8 @@ public function testExists(): void { $this->assertFalse(User::where('age', '>', 37)->exists()); $this->assertTrue(User::where('age', '<', 37)->exists()); + $this->assertTrue(User::where('age', '>', 37)->doesntExist()); + $this->assertFalse(User::where('age', '<', 37)->doesntExist()); } public function testSubQuery(): void From 453139ac2bda2950d0aca0998f51538ba44cb120 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Thu, 6 Feb 2025 15:04:29 -0500 Subject: [PATCH 412/446] DOCSP-38327: add Query Builder examples to usage examples (#3259) * DOCSP-38327: add qb examples to usage exs * add imports * wip * formatting * wip * fix tests? * fix tests? * wip * wip * wip: * formatting * formatting * formatting * fix tests * fix tests * small text changes * fix error * JS PR fixes 1 * add extra tests for each type of query * formatting * remove sort from deleteOne --- docs/includes/usage-examples/CountTest.php | 17 +- .../usage-examples/DeleteManyTest.php | 28 +++- .../includes/usage-examples/DeleteOneTest.php | 26 ++- docs/includes/usage-examples/DistinctTest.php | 17 +- docs/includes/usage-examples/FindManyTest.php | 14 +- docs/includes/usage-examples/FindOneTest.php | 35 +++- .../usage-examples/InsertManyTest.php | 29 +++- .../includes/usage-examples/InsertOneTest.php | 32 +++- .../usage-examples/UpdateManyTest.php | 34 +++- .../includes/usage-examples/UpdateOneTest.php | 4 +- .../usage-examples/operation-description.rst | 5 +- docs/query-builder.txt | 2 +- docs/usage-examples.txt | 4 + docs/usage-examples/count.txt | 96 ++++++++--- docs/usage-examples/deleteMany.txt | 119 +++++++++----- docs/usage-examples/deleteOne.txt | 123 +++++++++----- docs/usage-examples/distinct.txt | 129 ++++++++++----- docs/usage-examples/find.txt | 151 ++++++++++++------ docs/usage-examples/findOne.txt | 129 ++++++++++----- docs/usage-examples/insertMany.txt | 102 ++++++++---- docs/usage-examples/insertOne.txt | 124 +++++++++----- docs/usage-examples/updateMany.txt | 112 +++++++++---- docs/usage-examples/updateOne.txt | 49 +++--- 23 files changed, 979 insertions(+), 402 deletions(-) diff --git a/docs/includes/usage-examples/CountTest.php b/docs/includes/usage-examples/CountTest.php index ecf53db47..5e7e34c62 100644 --- a/docs/includes/usage-examples/CountTest.php +++ b/docs/includes/usage-examples/CountTest.php @@ -5,6 +5,7 @@ namespace App\Http\Controllers; use App\Models\Movie; +use Illuminate\Support\Facades\DB; use MongoDB\Laravel\Tests\TestCase; class CountTest extends TestCase @@ -29,14 +30,24 @@ public function testCount(): void ], ]); - // begin-count + // begin-eloquent-count $count = Movie::where('genres', 'Biography') ->count(); echo 'Number of documents: ' . $count; - // end-count + // end-eloquent-count $this->assertEquals(2, $count); - $this->expectOutputString('Number of documents: 2'); + + // begin-qb-count + $count = DB::table('movies') + ->where('genres', 'Biography') + ->count(); + + echo 'Number of documents: ' . $count; + // end-qb-count + + $this->assertEquals(2, $count); + $this->expectOutputString('Number of documents: 2Number of documents: 2'); } } diff --git a/docs/includes/usage-examples/DeleteManyTest.php b/docs/includes/usage-examples/DeleteManyTest.php index 5050f952e..8948c06fb 100644 --- a/docs/includes/usage-examples/DeleteManyTest.php +++ b/docs/includes/usage-examples/DeleteManyTest.php @@ -5,6 +5,7 @@ namespace App\Http\Controllers; use App\Models\Movie; +use Illuminate\Support\Facades\DB; use MongoDB\Laravel\Tests\TestCase; class DeleteManyTest extends TestCase @@ -29,14 +30,35 @@ public function testDeleteMany(): void ], ]); - // begin-delete-many + // begin-eloquent-delete-many $deleted = Movie::where('year', '<=', 1910) ->delete(); echo 'Deleted documents: ' . $deleted; - // end-delete-many + // end-eloquent-delete-many $this->assertEquals(2, $deleted); - $this->expectOutputString('Deleted documents: 2'); + + Movie::insert([ + [ + 'title' => 'Train Pulling into a Station', + 'year' => 1896, + ], + [ + 'title' => 'The Ball Game', + 'year' => 1898, + ], + ]); + + // begin-qb-delete-many + $deleted = DB::table('movies') + ->where('year', '<=', 1910) + ->delete(); + + echo 'Deleted documents: ' . $deleted; + // end-qb-delete-many + + $this->assertEquals(2, $deleted); + $this->expectOutputString('Deleted documents: 2Deleted documents: 2'); } } diff --git a/docs/includes/usage-examples/DeleteOneTest.php b/docs/includes/usage-examples/DeleteOneTest.php index 1a2acd4e0..9038618f8 100644 --- a/docs/includes/usage-examples/DeleteOneTest.php +++ b/docs/includes/usage-examples/DeleteOneTest.php @@ -5,6 +5,7 @@ namespace App\Http\Controllers; use App\Models\Movie; +use Illuminate\Support\Facades\DB; use MongoDB\Laravel\Tests\TestCase; class DeleteOneTest extends TestCase @@ -25,16 +26,33 @@ public function testDeleteOne(): void ], ]); - // begin-delete-one + // begin-eloquent-delete-one $deleted = Movie::where('title', 'Quiz Show') - ->orderBy('_id') ->limit(1) ->delete(); echo 'Deleted documents: ' . $deleted; - // end-delete-one + // end-eloquent-delete-one $this->assertEquals(1, $deleted); - $this->expectOutputString('Deleted documents: 1'); + + Movie::insert([ + [ + 'title' => 'Quiz Show', + 'runtime' => 133, + ], + ]); + + // begin-qb-delete-one + $deleted = DB::table('movies') + ->where('title', 'Quiz Show') + ->limit(1) + ->delete(); + + echo 'Deleted documents: ' . $deleted; + // end-qb-delete-one + + $this->assertEquals(1, $deleted); + $this->expectOutputString('Deleted documents: 1Deleted documents: 1'); } } diff --git a/docs/includes/usage-examples/DistinctTest.php b/docs/includes/usage-examples/DistinctTest.php index 0b7812241..35a0e63ce 100644 --- a/docs/includes/usage-examples/DistinctTest.php +++ b/docs/includes/usage-examples/DistinctTest.php @@ -5,6 +5,7 @@ namespace App\Http\Controllers; use App\Models\Movie; +use Illuminate\Support\Facades\DB; use MongoDB\Laravel\Tests\TestCase; class DistinctTest extends TestCase @@ -45,15 +46,25 @@ public function testDistinct(): void ], ]); - // begin-distinct + // begin-eloquent-distinct $ratings = Movie::where('directors', 'Sofia Coppola') ->select('imdb.rating') ->distinct() ->get(); echo $ratings; - // end-distinct + // end-eloquent-distinct - $this->expectOutputString('[[6.4],[7.8]]'); + // begin-qb-distinct + $ratings = DB::table('movies') + ->where('directors', 'Sofia Coppola') + ->select('imdb.rating') + ->distinct() + ->get(); + + echo $ratings; + // end-qb-distinct + + $this->expectOutputString('[[6.4],[7.8]][6.4,7.8]'); } } diff --git a/docs/includes/usage-examples/FindManyTest.php b/docs/includes/usage-examples/FindManyTest.php index 18324c62d..e136c65d7 100644 --- a/docs/includes/usage-examples/FindManyTest.php +++ b/docs/includes/usage-examples/FindManyTest.php @@ -5,6 +5,7 @@ namespace App\Http\Controllers; use App\Models\Movie; +use Illuminate\Support\Facades\DB; use MongoDB\Laravel\Tests\TestCase; class FindManyTest extends TestCase @@ -33,11 +34,20 @@ public function testFindMany(): void ], ]); - // begin-find + // begin-eloquent-find $movies = Movie::where('runtime', '>', 900) ->orderBy('_id') ->get(); - // end-find + // end-eloquent-find + + $this->assertEquals(2, $movies->count()); + + // begin-qb-find + $movies = DB::table('movies') + ->where('runtime', '>', 900) + ->orderBy('_id') + ->get(); + // end-qb-find $this->assertEquals(2, $movies->count()); } diff --git a/docs/includes/usage-examples/FindOneTest.php b/docs/includes/usage-examples/FindOneTest.php index 98452a6a6..c5304d378 100644 --- a/docs/includes/usage-examples/FindOneTest.php +++ b/docs/includes/usage-examples/FindOneTest.php @@ -5,6 +5,7 @@ namespace App\Http\Controllers; use App\Models\Movie; +use Illuminate\Support\Facades\DB; use MongoDB\Laravel\Tests\TestCase; class FindOneTest extends TestCase @@ -13,7 +14,7 @@ class FindOneTest extends TestCase * @runInSeparateProcess * @preserveGlobalState disabled */ - public function testFindOne(): void + public function testEloquentFindOne(): void { require_once __DIR__ . '/Movie.php'; @@ -22,15 +23,41 @@ public function testFindOne(): void ['title' => 'The Shawshank Redemption', 'directors' => ['Frank Darabont', 'Rob Reiner']], ]); - // begin-find-one + // begin-eloquent-find-one $movie = Movie::where('directors', 'Rob Reiner') - ->orderBy('_id') + ->orderBy('id') ->first(); echo $movie->toJson(); - // end-find-one + // end-eloquent-find-one $this->assertInstanceOf(Movie::class, $movie); $this->expectOutputRegex('/^{"_id":"[a-z0-9]{24}","title":"The Shawshank Redemption","directors":\["Frank Darabont","Rob Reiner"\]}$/'); } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function testQBFindOne(): void + { + require_once __DIR__ . '/Movie.php'; + + Movie::truncate(); + Movie::insert([ + ['title' => 'The Shawshank Redemption', 'directors' => ['Frank Darabont', 'Rob Reiner']], + ]); + + // begin-qb-find-one + $movie = DB::table('movies') + ->where('directors', 'Rob Reiner') + ->orderBy('_id') + ->first(); + + echo $movie['title']; + // end-qb-find-one + + $this->assertSame($movie['title'], 'The Shawshank Redemption'); + $this->expectOutputString('The Shawshank Redemption'); + } } diff --git a/docs/includes/usage-examples/InsertManyTest.php b/docs/includes/usage-examples/InsertManyTest.php index e1bf4539a..79e00971f 100644 --- a/docs/includes/usage-examples/InsertManyTest.php +++ b/docs/includes/usage-examples/InsertManyTest.php @@ -6,6 +6,7 @@ use App\Models\Movie; use DateTimeImmutable; +use Illuminate\Support\Facades\DB; use MongoDB\BSON\UTCDateTime; use MongoDB\Laravel\Tests\TestCase; @@ -21,7 +22,7 @@ public function testInsertMany(): void Movie::truncate(); - // begin-insert-many + // begin-eloquent-insert-many $success = Movie::insert([ [ 'title' => 'Anatomy of a Fall', @@ -38,9 +39,31 @@ public function testInsertMany(): void ]); echo 'Insert operation success: ' . ($success ? 'yes' : 'no'); - // end-insert-many + // end-eloquent-insert-many $this->assertTrue($success); - $this->expectOutputString('Insert operation success: yes'); + + // begin-qb-insert-many + $success = DB::table('movies') + ->insert([ + [ + 'title' => 'Anatomy of a Fall', + 'release_date' => new UTCDateTime(new DateTimeImmutable('2023-08-23')), + ], + [ + 'title' => 'The Boy and the Heron', + 'release_date' => new UTCDateTime(new DateTimeImmutable('2023-12-08')), + ], + [ + 'title' => 'Passages', + 'release_date' => new UTCDateTime(new DateTimeImmutable('2023-06-28')), + ], + ]); + + echo 'Insert operation success: ' . ($success ? 'yes' : 'no'); + // end-qb-insert-many + + $this->assertTrue($success); + $this->expectOutputString('Insert operation success: yesInsert operation success: yes'); } } diff --git a/docs/includes/usage-examples/InsertOneTest.php b/docs/includes/usage-examples/InsertOneTest.php index 15eadf419..821029499 100644 --- a/docs/includes/usage-examples/InsertOneTest.php +++ b/docs/includes/usage-examples/InsertOneTest.php @@ -5,6 +5,7 @@ namespace App\Http\Controllers; use App\Models\Movie; +use Illuminate\Support\Facades\DB; use MongoDB\Laravel\Tests\TestCase; class InsertOneTest extends TestCase @@ -13,13 +14,13 @@ class InsertOneTest extends TestCase * @runInSeparateProcess * @preserveGlobalState disabled */ - public function testInsertOne(): void + public function testEloquentInsertOne(): void { require_once __DIR__ . '/Movie.php'; Movie::truncate(); - // begin-insert-one + // begin-eloquent-insert-one $movie = Movie::create([ 'title' => 'Marriage Story', 'year' => 2019, @@ -27,9 +28,34 @@ public function testInsertOne(): void ]); echo $movie->toJson(); - // end-insert-one + // end-eloquent-insert-one $this->assertInstanceOf(Movie::class, $movie); + $this->assertSame($movie->title, 'Marriage Story'); $this->expectOutputRegex('/^{"title":"Marriage Story","year":2019,"runtime":136,"updated_at":".{27}","created_at":".{27}","_id":"[a-z0-9]{24}"}$/'); } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function testQBInsertOne(): void + { + require_once __DIR__ . '/Movie.php'; + + Movie::truncate(); + + // begin-qb-insert-one + $success = DB::table('movies') + ->insert([ + 'title' => 'Marriage Story', + 'year' => 2019, + 'runtime' => 136, + ]); + + echo 'Insert operation success: ' . ($success ? 'yes' : 'no'); + // end-qb-insert-one + + $this->expectOutputString('Insert operation success: yes'); + } } diff --git a/docs/includes/usage-examples/UpdateManyTest.php b/docs/includes/usage-examples/UpdateManyTest.php index 49a77dd95..9d4a11ac8 100644 --- a/docs/includes/usage-examples/UpdateManyTest.php +++ b/docs/includes/usage-examples/UpdateManyTest.php @@ -5,6 +5,7 @@ namespace App\Http\Controllers; use App\Models\Movie; +use Illuminate\Support\Facades\DB; use MongoDB\Laravel\Tests\TestCase; class UpdateManyTest extends TestCase @@ -35,14 +36,41 @@ public function testUpdateMany(): void ], ]); - // begin-update-many + // begin-eloquent-update-many $updates = Movie::where('imdb.rating', '>', 9.0) ->update(['acclaimed' => true]); echo 'Updated documents: ' . $updates; - // end-update-many + // end-eloquent-update-many $this->assertEquals(2, $updates); - $this->expectOutputString('Updated documents: 2'); + + Movie::insert([ + [ + 'title' => 'ABCD', + 'imdb' => [ + 'rating' => 9.5, + 'votes' => 1, + ], + ], + [ + 'title' => 'Testing', + 'imdb' => [ + 'rating' => 9.3, + 'votes' => 1, + ], + ], + ]); + + // begin-qb-update-many + $updates = DB::table('movies') + ->where('imdb.rating', '>', 9.0) + ->update(['acclaimed' => true]); + + echo 'Updated documents: ' . $updates; + // end-qb-update-many + + $this->assertEquals(2, $updates); + $this->expectOutputString('Updated documents: 2Updated documents: 2'); } } diff --git a/docs/includes/usage-examples/UpdateOneTest.php b/docs/includes/usage-examples/UpdateOneTest.php index e1f864170..2ed356d5a 100644 --- a/docs/includes/usage-examples/UpdateOneTest.php +++ b/docs/includes/usage-examples/UpdateOneTest.php @@ -28,7 +28,7 @@ public function testUpdateOne(): void ], ]); - // begin-update-one + // begin-eloquent-update-one $updates = Movie::where('title', 'Carol') ->orderBy('_id') ->first() @@ -40,7 +40,7 @@ public function testUpdateOne(): void ]); echo 'Updated documents: ' . $updates; - // end-update-one + // end-eloquent-update-one $this->assertTrue($updates); $this->expectOutputString('Updated documents: 1'); diff --git a/docs/includes/usage-examples/operation-description.rst b/docs/includes/usage-examples/operation-description.rst index 68119a249..c68754475 100644 --- a/docs/includes/usage-examples/operation-description.rst +++ b/docs/includes/usage-examples/operation-description.rst @@ -1,2 +1,3 @@ -|operator-description| by creating a query builder, using a method such -as ``Model::where()`` or the ``DB`` facade to match documents in a collection, and then calling |result-operation|. +|operator-description| by using a method such as ``Model::where()`` or +methods from the ``DB`` facade to match documents, and then calling +|result-operation|. diff --git a/docs/query-builder.txt b/docs/query-builder.txt index 649cdde34..990c1005c 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -631,7 +631,7 @@ a query: :end-before: end options The query builder accepts the same options that you can set for -the :phpmethod:`find() ` method in the +the :phpmethod:`MongoDB\Collection::find()` method in the {+php-library+}. Some of the options to modify query results, such as ``skip``, ``sort``, and ``limit``, are settable directly as query builder methods and are described in the diff --git a/docs/usage-examples.txt b/docs/usage-examples.txt index 87a87df88..14478c004 100644 --- a/docs/usage-examples.txt +++ b/docs/usage-examples.txt @@ -43,6 +43,10 @@ operations. Each usage example includes the following components: - Example code that you can run from an application controller - Output displayed by the print statement +To learn more about the operations demonstrated in the usage examples, +see the :ref:`laravel-fundamentals-read-ops` and +:ref:`laravel-fundamentals-write-ops` guides. + How to Use the Usage Examples ----------------------------- diff --git a/docs/usage-examples/count.txt b/docs/usage-examples/count.txt index c3af477ee..aadd1e0c6 100644 --- a/docs/usage-examples/count.txt +++ b/docs/usage-examples/count.txt @@ -25,35 +25,79 @@ Count Documents .. replacement:: result-operation - the ``count()`` method to retrieve the results. + the ``count()`` method to retrieve the results Example ------- -This usage example performs the following actions: - -- Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the - ``sample_mflix`` database -- Counts the documents from the ``movies`` collection that match a query filter -- Prints the matching document count - -The example calls the following methods on the ``Movie`` model: - -- ``where()``: Matches documents in which the value of the ``genres`` field includes ``"Biography"``. -- ``count()``: Counts the number of matching documents. This method returns an integer value. - -.. io-code-block:: - - .. input:: ../includes/usage-examples/CountTest.php - :start-after: begin-count - :end-before: end-count - :language: php - :dedent: - - .. output:: - :language: console - :visible: false - - Number of documents: 1267 +Select from the following :guilabel:`Eloquent` and :guilabel:`Query +Builder` tabs to view usage examples for the same operation that use +each corresponding query syntax: + +.. tabs:: + + .. tab:: Eloquent + :tabid: eloquent-model-count + + This example performs the following actions: + + - Uses the ``Movie`` Eloquent model to represent the ``movies`` + collection in the ``sample_mflix`` database + - Counts the documents from the ``movies`` collection that match a + query filter + - Prints the matching document count + + The example calls the following methods on the ``Movie`` model: + + - ``where()``: Matches documents in which the value of the + ``genres`` field includes ``"Biography"`` + - ``count()``: Counts the number of matching documents and returns + the count as an integer + + .. io-code-block:: + + .. input:: ../includes/usage-examples/CountTest.php + :start-after: begin-eloquent-count + :end-before: end-eloquent-count + :language: php + :dedent: + + .. output:: + :language: console + :visible: false + + Number of documents: 1267 + + .. tab:: Query Builder + :tabid: query-builder-count + + This example performs the following actions: + + - Accesses the ``movies`` collection by calling the ``table()`` + method from the ``DB`` facade + - Counts the documents from the ``movies`` collection that match a + query filter + - Prints the matching document count + + The example calls the following query builder methods: + + - ``where()``: Matches documents in which the value of the + ``genres`` field includes ``"Biography"`` + - ``count()``: Counts the number of matching documents and returns + the count as an integer + + .. io-code-block:: + + .. input:: ../includes/usage-examples/CountTest.php + :start-after: begin-qb-count + :end-before: end-qb-count + :language: php + :dedent: + + .. output:: + :language: console + :visible: false + + Number of documents: 1267 .. include:: /includes/usage-examples/fact-edit-laravel-app.rst diff --git a/docs/usage-examples/deleteMany.txt b/docs/usage-examples/deleteMany.txt index cf8680184..22cc8d183 100644 --- a/docs/usage-examples/deleteMany.txt +++ b/docs/usage-examples/deleteMany.txt @@ -17,48 +17,91 @@ Delete Multiple Documents :depth: 1 :class: singlecol -You can delete multiple documents in a collection by calling the ``delete()`` method on an -object collection or a query builder. +You can delete multiple documents in a collection by calling the +``delete()`` method on an object collection or a query builder. -To delete multiple documents, pass a query filter to the ``where()`` method. Then, delete the -matching documents by calling the ``delete()`` method. +To delete multiple documents, pass a query filter to the ``where()`` +method. Then, delete the matching documents by calling the ``delete()`` +method. -Example -------- - -This usage example performs the following actions: - -- Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the - ``sample_mflix`` database -- Deletes documents from the ``movies`` collection that match a query filter -- Prints the number of deleted documents - -The example calls the following methods on the ``Movie`` model: - -- ``where()``: matches documents in which the value of the ``year`` field is less than or - equal to ``1910``. -- ``delete()``: deletes the matched documents. This method returns the number - of documents that the method successfully deletes. - -.. io-code-block:: - :copyable: true +.. tip:: - .. input:: ../includes/usage-examples/DeleteManyTest.php - :start-after: begin-delete-many - :end-before: end-delete-many - :language: php - :dedent: + To learn more about deleting documents with the {+odm-short+}, see + the :ref:`laravel-fundamentals-delete-documents` section of the Write + Operations guide. - .. output:: - :language: console - :visible: false +Example +------- - Deleted documents: 7 +Select from the following :guilabel:`Eloquent` and :guilabel:`Query +Builder` tabs to view usage examples for the same operation that use +each corresponding query syntax: + +.. tabs:: + + .. tab:: Eloquent + :tabid: eloquent-model-count + + This example performs the following actions: + + - Uses the ``Movie`` Eloquent model to represent the ``movies`` + collection in the ``sample_mflix`` database + - Deletes documents from the ``movies`` collection that match a + query filter + - Prints the number of deleted documents + + The example calls the following methods on the ``Movie`` model: + + - ``where()``: Matches documents in which the value of the + ``year`` field is less than or equal to ``1910`` + - ``delete()``: Deletes the matched documents and returns the + number of documents successfully deleted + + .. io-code-block:: + :copyable: true + + .. input:: ../includes/usage-examples/DeleteManyTest.php + :start-after: begin-eloquent-delete-many + :end-before: end-eloquent-delete-many + :language: php + :dedent: + + .. output:: + :language: console + :visible: false + + Deleted documents: 7 + + .. tab:: Query Builder + :tabid: query-builder-count + + This example performs the following actions: + + - Accesses the ``movies`` collection by calling the ``table()`` + method from the ``DB`` facade + - Deletes documents from the ``movies`` collection that match a + query filter + - Prints the number of deleted documents + + The example calls the following query builder methods: + + - ``where()``: Matches documents in which the value of the + ``year`` field is less than or equal to ``1910`` + - ``delete()``: Deletes the matched documents and returns the + number of documents successfully deleted + + .. io-code-block:: + + .. input:: ../includes/usage-examples/DeleteManyTest.php + :start-after: begin-qb-delete-many + :end-before: end-qb-delete-many + :language: php + :dedent: + + .. output:: + :language: console + :visible: false + + Deleted documents: 7 .. include:: /includes/usage-examples/fact-edit-laravel-app.rst - -.. tip:: - - To learn more about deleting documents with the {+odm-short+}, see the :ref:`laravel-fundamentals-delete-documents` - section of the Write Operations guide. - diff --git a/docs/usage-examples/deleteOne.txt b/docs/usage-examples/deleteOne.txt index 1298255da..8a88c0241 100644 --- a/docs/usage-examples/deleteOne.txt +++ b/docs/usage-examples/deleteOne.txt @@ -17,50 +17,93 @@ Delete a Document :depth: 1 :class: singlecol -You can delete a document in a collection by retrieving a single Eloquent model and calling -the ``delete()`` method, or by calling ``delete()`` directly on a query builder. +You can delete a document in a collection by retrieving a single +Eloquent model and calling the ``delete()`` method, or by calling +``delete()`` directly on a query builder. -To delete a document, pass a query filter to the ``where()`` method, sort the matching documents, -and call the ``limit()`` method to retrieve only the first document. Then, delete this matching -document by calling the ``delete()`` method. +To delete a document, pass a query filter to the ``where()`` method, +sort the matching documents, and call the ``limit()`` method to retrieve +only the first document. Then, delete this matching document by calling +the ``delete()`` method. -Example -------- - -This usage example performs the following actions: - -- Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the - ``sample_mflix`` database -- Deletes a document from the ``movies`` collection that matches a query filter -- Prints the number of deleted documents - -The example calls the following methods on the ``Movie`` model: - -- ``where()``: matches documents in which the value of the ``title`` field is ``"Quiz Show"`` -- ``orderBy()``: sorts matched documents by their ascending ``_id`` values -- ``limit()``: retrieves only the first matching document -- ``delete()``: deletes the retrieved document - -.. io-code-block:: - :copyable: true +.. tip:: - .. input:: ../includes/usage-examples/DeleteOneTest.php - :start-after: begin-delete-one - :end-before: end-delete-one - :language: php - :dedent: + To learn more about deleting documents with the {+odm-short+}, see + the :ref:`laravel-fundamentals-delete-documents` section of the Write + Operations guide. - .. output:: - :language: console - :visible: false +Example +------- - Deleted documents: 1 +Select from the following :guilabel:`Eloquent` and :guilabel:`Query +Builder` tabs to view usage examples for the same operation that use +each corresponding query syntax: + +.. tabs:: + + .. tab:: Eloquent + :tabid: eloquent-model-count + + This example performs the following actions: + + - Uses the ``Movie`` Eloquent model to represent the ``movies`` + collection in the ``sample_mflix`` database + - Deletes a document from the ``movies`` collection that matches a + query filter + - Prints the number of deleted documents + + The example calls the following methods on the ``Movie`` model: + + - ``where()``: Matches documents in which the value of the + ``title`` field is ``"Quiz Show"`` + - ``limit()``: Retrieves only the first matching document + - ``delete()``: Deletes the retrieved document + + .. io-code-block:: + :copyable: true + + .. input:: ../includes/usage-examples/DeleteOneTest.php + :start-after: begin-eloquent-delete-one + :end-before: end-eloquent-delete-one + :language: php + :dedent: + + .. output:: + :language: console + :visible: false + + Deleted documents: 1 + + .. tab:: Query Builder + :tabid: query-builder-count + + This example performs the following actions: + + - Accesses the ``movies`` collection by calling the ``table()`` + method from the ``DB`` facade + - Deletes a document from the ``movies`` collection that matches a + query filter + - Prints the number of deleted documents + + The example calls the following query builder methods: + + - ``where()``: Matches documents in which the value of the + ``title`` field is ``"Quiz Show"`` + - ``limit()``: Retrieves only the first matching document + - ``delete()``: Deletes the retrieved document + + .. io-code-block:: + + .. input:: ../includes/usage-examples/DeleteOneTest.php + :start-after: begin-qb-delete-one + :end-before: end-qb-delete-one + :language: php + :dedent: + + .. output:: + :language: console + :visible: false + + Deleted documents: 1 .. include:: /includes/usage-examples/fact-edit-laravel-app.rst - -.. tip:: - - To learn more about deleting documents with the {+odm-short+}, see the `Deleting Models - `__ section of the - Laravel documentation. - diff --git a/docs/usage-examples/distinct.txt b/docs/usage-examples/distinct.txt index 5d62ec8be..cfe1e4644 100644 --- a/docs/usage-examples/distinct.txt +++ b/docs/usage-examples/distinct.txt @@ -17,50 +17,99 @@ Retrieve Distinct Field Values :depth: 1 :class: singlecol -You can retrieve distinct field values of documents in a collection by calling the ``distinct()`` -method on an object collection or a query builder. +You can retrieve distinct field values of documents in a collection by +calling the ``distinct()`` method on an object collection or a query +builder. -To retrieve distinct field values, pass a query filter to the ``where()`` method and a field name -to the ``select()`` method. Then, call ``distinct()`` to return the unique values of the selected -field in documents that match the query filter. +To retrieve distinct field values, pass a query filter to the +``where()`` method and a field name to the ``select()`` method. Then, +call ``distinct()`` to return the unique values of the selected field in +documents that match the query filter. -Example -------- - -This usage example performs the following actions: - -- Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the - ``sample_mflix`` database -- Retrieves distinct field values of documents from the ``movies`` collection that match a query filter -- Prints the distinct values - -The example calls the following methods on the ``Movie`` model: - -- ``where()``: matches documents in which the value of the ``directors`` field includes ``"Sofia Coppola"``. -- ``select()``: retrieves the matching documents' ``imdb.rating`` field values. -- ``distinct()``: retrieves the unique values of the selected field and returns - the list of values. -- ``get()``: retrieves the query results. - -.. io-code-block:: - :copyable: true +.. tip:: - .. input:: ../includes/usage-examples/DistinctTest.php - :start-after: begin-distinct - :end-before: end-distinct - :language: php - :dedent: + For more information about query filters, see the + :ref:`laravel-retrieve-matching` section of the Read Operations + guide. - .. output:: - :language: console - :visible: false +Example +------- - [[5.6],[6.4],[7.2],[7.8]] +Select from the following :guilabel:`Eloquent` and :guilabel:`Query +Builder` tabs to view usage examples for the same operation that use +each corresponding query syntax: + +.. tabs:: + + .. tab:: Eloquent + :tabid: eloquent-model-count + + This example performs the following actions: + + - Uses the ``Movie`` Eloquent model to represent the ``movies`` + collection in the ``sample_mflix`` database + - Retrieves distinct field values of documents from the ``movies`` + collection that match a query filter + - Prints the distinct values + + The example calls the following methods on the ``Movie`` model: + + - ``where()``: Matches documents in which the value of the + ``directors`` field includes ``"Sofia Coppola"`` + - ``select()``: Retrieves the matching documents' ``imdb.rating`` + field values + - ``distinct()``: Retrieves the unique values of the selected + field and returns the list of values + - ``get()``: Retrieves the query results + + .. io-code-block:: + :copyable: true + + .. input:: ../includes/usage-examples/DistinctTest.php + :start-after: begin-eloquent-distinct + :end-before: end-eloquent-distinct + :language: php + :dedent: + + .. output:: + :language: console + :visible: false + + [[5.6],[6.4],[7.2],[7.8]] + + .. tab:: Query Builder + :tabid: query-builder-count + + This example performs the following actions: + + - Accesses the ``movies`` collection by calling the ``table()`` + method from the ``DB`` facade + - Retrieves distinct field values of documents from the ``movies`` + collection that match a query filter + - Prints the distinct values + + The example calls the following query builder methods: + + - ``where()``: Matches documents in which the value of the + ``directors`` field includes ``"Sofia Coppola"`` + - ``select()``: Retrieves the matching documents' ``imdb.rating`` + field values + - ``distinct()``: Retrieves the unique values of the selected + field and returns the list of values + - ``get()``: Retrieves the query results + + .. io-code-block:: + + .. input:: ../includes/usage-examples/DistinctTest.php + :start-after: begin-qb-distinct + :end-before: end-qb-distinct + :language: php + :dedent: + + .. output:: + :language: console + :visible: false + + [5.6,6.4,7.2,7.8] .. include:: /includes/usage-examples/fact-edit-laravel-app.rst - -.. tip:: - - For more information about query filters, see the :ref:`laravel-retrieve-matching` section of - the Read Operations guide. - diff --git a/docs/usage-examples/find.txt b/docs/usage-examples/find.txt index 957ece537..187676392 100644 --- a/docs/usage-examples/find.txt +++ b/docs/usage-examples/find.txt @@ -25,66 +25,115 @@ Find Multiple Documents .. replacement:: result-operation - the ``get()`` method to retrieve the results. + the ``get()`` method to retrieve the results Pass a query filter to the ``where()`` method to retrieve documents that meet a set of criteria. When you call the ``get()`` method, MongoDB returns the -matching documents according to their :term:`natural order` in the database or +matching documents according to their :term:`natural order` in the collection or according to the sort order that you can specify by using the ``orderBy()`` method. -To learn more about query builder methods, see the :ref:`laravel-query-builder` -guide. +.. tip:: + + To learn about other ways to retrieve documents with the + {+odm-short+}, see the :ref:`laravel-fundamentals-retrieve` guide. Example ------- -This usage example performs the following actions: - -- Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the - ``sample_mflix`` database -- Retrieves and prints documents from the ``movies`` collection that match a query filter - -The example calls the following methods on the ``Movie`` model: - -- ``where()``: matches documents in which the value of the ``runtime`` field is greater than ``900`` -- ``orderBy()``: sorts matched documents by their ascending ``_id`` values -- ``get()``: retrieves the query results as a Laravel collection object - -.. io-code-block:: - :copyable: true - - .. input:: ../includes/usage-examples/FindManyTest.php - :start-after: begin-find - :end-before: end-find - :language: php - :dedent: - - .. output:: - :language: json - :visible: false - - // Results are truncated - - [ - { - "_id": ..., - "runtime": 1256, - "title": "Centennial", - ..., - }, - { - "_id": ..., - "runtime": 1140, - "title": "Baseball", - ..., - }, - ... - ] +Select from the following :guilabel:`Eloquent` and :guilabel:`Query +Builder` tabs to view usage examples for the same operation that use +each corresponding query syntax: + +.. tabs:: + + .. tab:: Eloquent + :tabid: eloquent-model-count + + This example performs the following actions: + + - Uses the ``Movie`` Eloquent model to represent the ``movies`` + collection in the ``sample_mflix`` database + - Retrieves and prints documents from the ``movies`` collection + that match a query filter + + The example calls the following methods on the ``Movie`` model: + + - ``where()``: Matches documents in which the value of the + ``runtime`` field is greater than ``900`` + - ``orderBy()``: Sorts matched documents by their ascending + ``_id`` values + - ``get()``: Retrieves the query results as a Laravel collection + object + + .. io-code-block:: + :copyable: true + + .. input:: ../includes/usage-examples/FindManyTest.php + :start-after: begin-eloquent-find + :end-before: end-eloquent-find + :language: php + :dedent: + + .. output:: + :language: console + :visible: false + + // Results are truncated + + [ + { + "_id": ..., + "runtime": 1256, + "title": "Centennial", + ..., + }, + { + "_id": ..., + "runtime": 1140, + "title": "Baseball", + ..., + }, + ... + ] + + .. tab:: Query Builder + :tabid: query-builder-count + + This example performs the following actions: + + - Accesses the ``movies`` collection by calling the ``table()`` + method from the ``DB`` facade + - Retrieves and prints documents from the ``movies`` collection + that match a query filter + + The example calls the following query builder methods: + + - ``where()``: Matches documents in which the value of the + ``runtime`` field is greater than ``900`` + - ``orderBy()``: Sorts matched documents by their ascending + ``_id`` values + - ``get()``: Retrieves the query results as a Laravel collection + object + + .. io-code-block:: + + .. input:: ../includes/usage-examples/FindManyTest.php + :start-after: begin-qb-find + :end-before: end-qb-find + :language: php + :dedent: + + .. output:: + :language: console + :visible: false + + // Results are truncated + + Illuminate\Support\Collection Object ( [items:protected] => + Array ( [0] => Array ( [_id] => ... [runtime] => 1256 + [title] => Centennial [1] => Array + ( [_id] => ... [runtime] => 1140 + [title] => Baseball ) ... .. include:: /includes/usage-examples/fact-edit-laravel-app.rst - -.. tip:: - - To learn about other ways to retrieve documents with the {+odm-short+}, see the - :ref:`laravel-fundamentals-retrieve` guide. diff --git a/docs/usage-examples/findOne.txt b/docs/usage-examples/findOne.txt index aa0e035f1..d5df8aae1 100644 --- a/docs/usage-examples/findOne.txt +++ b/docs/usage-examples/findOne.txt @@ -19,52 +19,97 @@ Find a Document .. replacement:: result-operation - the ``first()`` method to return one document. + the ``first()`` method to return one document -If multiple documents match the query filter, ``first()`` returns the first matching document according to the documents' -:term:`natural order` in the database or according to the sort order that you can specify -by using the ``orderBy()`` method. +If multiple documents match the query filter, ``first()`` returns the +first matching document according to the documents' :term:`natural +order` in the database or according to the sort order that you can +specify by using the ``orderBy()`` method. -Example -------- - -This usage example performs the following actions: - -- Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the - ``sample_mflix`` database -- Retrieves a document from the ``movies`` collection that matches a query filter -- Prints the retrieved document - -The example calls the following methods on the ``Movie`` model: - -- ``where()``: matches documents in which the value of the ``directors`` field includes ``"Rob Reiner"``. -- ``orderBy()``: sorts matched documents by their ascending ``_id`` values. -- ``first()``: retrieves only the first matching document. - -.. io-code-block:: - - .. input:: ../includes/usage-examples/FindOneTest.php - :start-after: begin-find-one - :end-before: end-find-one - :language: php - :dedent: +.. tip:: - .. output:: - :language: console - :visible: false + To learn about other ways to retrieve documents with the + {+odm-short+}, see the :ref:`laravel-fundamentals-retrieve` guide. - // Result is truncated +Example +------- - { - "_id": ..., - "title": "This Is Spinal Tap", - "directors": [ "Rob Reiner" ], - ... - } +Select from the following :guilabel:`Eloquent` and :guilabel:`Query +Builder` tabs to view usage examples for the same operation that use +each corresponding query syntax: + +.. tabs:: + + .. tab:: Eloquent + :tabid: eloquent-model-count + + This example performs the following actions: + + - Uses the ``Movie`` Eloquent model to represent the ``movies`` + collection in the ``sample_mflix`` database + - Retrieves a document from the ``movies`` collection that matches + a query filter + - Prints the retrieved document + + The example calls the following methods on the ``Movie`` model: + + - ``where()``: Matches documents in which the value of the + ``directors`` field includes ``"Rob Reiner"`` + - ``orderBy()``: Sorts matched documents by their ascending ``_id`` values + - ``first()``: Retrieves only the first matching document + + .. io-code-block:: + :copyable: true + + .. input:: ../includes/usage-examples/FindOneTest.php + :start-after: begin-eloquent-find-one + :end-before: end-eloquent-find-one + :language: php + :dedent: + + .. output:: + :language: console + :visible: false + + // Result is truncated + + { + "_id": ..., + "title": "This Is Spinal Tap", + "directors": [ "Rob Reiner" ], + ... + } + + .. tab:: Query Builder + :tabid: query-builder-count + + This example performs the following actions: + + - Accesses the ``movies`` collection by calling the ``table()`` + method from the ``DB`` facade + - Retrieves a document from the ``movies`` collection that matches + a query filter + - Prints the ``title`` field of the retrieved document + + The example calls the following query builder methods: + + - ``where()``: Matches documents in which the value of the + ``directors`` field includes ``"Rob Reiner"`` + - ``orderBy()``: Sorts matched documents by their ascending ``_id`` values + - ``first()``: Retrieves only the first matching document + + .. io-code-block:: + + .. input:: ../includes/usage-examples/FindOneTest.php + :start-after: begin-qb-find-one + :end-before: end-qb-find-one + :language: php + :dedent: + + .. output:: + :language: console + :visible: false + + This Is Spinal Tap .. include:: /includes/usage-examples/fact-edit-laravel-app.rst - -.. tip:: - - To learn more about retrieving documents with the {+odm-short+}, see the - :ref:`laravel-fundamentals-retrieve` guide. diff --git a/docs/usage-examples/insertMany.txt b/docs/usage-examples/insertMany.txt index 2d59a78ab..48acfe17e 100644 --- a/docs/usage-examples/insertMany.txt +++ b/docs/usage-examples/insertMany.txt @@ -24,40 +24,78 @@ To insert multiple documents, call the ``insert()`` method and specify the new d as an array inside the method call. Each array entry contains a single document's field values. -Example -------- - -This usage example performs the following actions: - -- Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the - ``sample_mflix`` database -- Inserts documents into the ``movies`` collection -- Prints whether the insert operation succeeds - -The example calls the ``insert()`` method to insert documents that contain -information about movies released in ``2023``. If the insert operation is -successful, it returns a value of ``1``. If the operation fails, it throws -an exception. - -.. io-code-block:: - :copyable: true +.. tip:: - .. input:: ../includes/usage-examples/InsertManyTest.php - :start-after: begin-insert-many - :end-before: end-insert-many - :language: php - :dedent: + To learn more about insert operations, see the + :ref:`laravel-fundamentals-insert-documents` section + of the Write Operations guide. - .. output:: - :language: console - :visible: false +Example +------- - Insert operation success: yes +Select from the following :guilabel:`Eloquent` and :guilabel:`Query +Builder` tabs to view usage examples for the same operation that use +each corresponding query syntax: + +.. tabs:: + + .. tab:: Eloquent + :tabid: eloquent-model-count + + This example performs the following actions: + + - Uses the ``Movie`` Eloquent model to represent the ``movies`` + collection in the ``sample_mflix`` database + - Inserts documents into the ``movies`` collection + - Prints whether the insert operation succeeds + + The example calls the ``insert()`` method to insert documents that represent + movies released in ``2023``. If the insert operation is + successful, it returns a value of ``1``. If the operation fails, it throws + an exception. + + .. io-code-block:: + :copyable: true + + .. input:: ../includes/usage-examples/InsertManyTest.php + :start-after: begin-eloquent-insert-many + :end-before: end-eloquent-insert-many + :language: php + :dedent: + + .. output:: + :language: console + :visible: false + + Insert operation success: yes + + .. tab:: Query Builder + :tabid: query-builder-count + + This example performs the following actions: + + - Accesses the ``movies`` collection by calling the ``table()`` + method from the ``DB`` facade + - Inserts documents into the ``movies`` collection + - Prints whether the insert operation succeeds + + The example calls the ``insert()`` method to insert documents that represent + movies released in ``2023``. If the insert operation is + successful, it returns a value of ``1``. If the operation fails, it throws + an exception. + + .. io-code-block:: + + .. input:: ../includes/usage-examples/InsertManyTest.php + :start-after: begin-qb-insert-many + :end-before: end-qb-insert-many + :language: php + :dedent: + + .. output:: + :language: console + :visible: false + + Insert operation success: yes .. include:: /includes/usage-examples/fact-edit-laravel-app.rst - -.. tip:: - - To learn more about insert operations, see the :ref:`laravel-fundamentals-insert-documents` section - of the Write Operations guide. - diff --git a/docs/usage-examples/insertOne.txt b/docs/usage-examples/insertOne.txt index e28e12090..1a246ab72 100644 --- a/docs/usage-examples/insertOne.txt +++ b/docs/usage-examples/insertOne.txt @@ -23,50 +23,90 @@ an Eloquent model or query builder. To insert a document, pass the data you need to insert as a document containing the fields and values to the ``create()`` method. -Example -------- - -This usage example performs the following actions: - -- Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the - ``sample_mflix`` database -- Inserts a document into the ``movies`` collection - -The example calls the ``create()`` method to insert a document that contains the following -information: - -- ``title`` value of ``"Marriage Story"`` -- ``year`` value of ``2019`` -- ``runtime`` value of ``136`` - -.. io-code-block:: - :copyable: true +.. tip:: - .. input:: ../includes/usage-examples/InsertOneTest.php - :start-after: begin-insert-one - :end-before: end-insert-one - :language: php - :dedent: + You can also use the ``save()`` or ``insert()`` methods to insert a + document into a collection. To learn more about insert operations, + see the :ref:`laravel-fundamentals-insert-documents` section of the + Write Operations guide. - .. output:: - :language: json - :visible: false +Example +------- - { - "title": "Marriage Story", - "year": 2019, - "runtime": 136, - "updated_at": "...", - "created_at": "...", - "_id": "..." - } +Select from the following :guilabel:`Eloquent` and :guilabel:`Query +Builder` tabs to view usage examples for the same operation that use +each corresponding query syntax: + +.. tabs:: + + .. tab:: Eloquent + :tabid: eloquent-model-count + + This example performs the following actions: + + - Uses the ``Movie`` Eloquent model to represent the ``movies`` + collection in the ``sample_mflix`` database + - Inserts a document into the ``movies`` collection + - Prints the newly inserted document + + The example calls the ``create()`` method to insert a document + that contains the following fields and values: + + - ``title`` value of ``"Marriage Story"`` + - ``year`` value of ``2019`` + - ``runtime`` value of ``136`` + + .. io-code-block:: + :copyable: true + + .. input:: ../includes/usage-examples/InsertOneTest.php + :start-after: begin-eloquent-insert-one + :end-before: end-eloquent-insert-one + :language: php + :dedent: + + .. output:: + :language: console + :visible: false + + { + "title": "Marriage Story", + "year": 2019, + "runtime": 136, + "updated_at": "...", + "created_at": "...", + "_id": "..." + } + + .. tab:: Query Builder + :tabid: query-builder-count + + This example performs the following actions: + + - Accesses the ``movies`` collection by calling the ``table()`` + method from the ``DB`` facade + - Inserts a document into the ``movies`` collection + - Prints whether the insert operation succeeds + + The example calls the ``insert()`` method to insert a document + that contains the following fields and values: + + - ``title`` value of ``"Marriage Story"`` + - ``year`` value of ``2019`` + - ``runtime`` value of ``136`` + + .. io-code-block:: + + .. input:: ../includes/usage-examples/InsertOneTest.php + :start-after: begin-qb-insert-one + :end-before: end-qb-insert-one + :language: php + :dedent: + + .. output:: + :language: console + :visible: false + + Insert operation success: yes .. include:: /includes/usage-examples/fact-edit-laravel-app.rst - -.. tip:: - - You can also use the ``save()`` or ``insert()`` methods to insert a document into a collection. - To learn more about insert operations, see the :ref:`laravel-fundamentals-insert-documents` section - of the Write Operations guide. - - diff --git a/docs/usage-examples/updateMany.txt b/docs/usage-examples/updateMany.txt index 89c262da7..c2c83ce1c 100644 --- a/docs/usage-examples/updateMany.txt +++ b/docs/usage-examples/updateMany.txt @@ -24,43 +24,85 @@ Pass a query filter to the ``where()`` method to retrieve documents that meet a set of criteria. Then, update the matching documents 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 documents from the ``movies`` collection that match a query filter -- Prints the number of updated documents - -The example calls the following methods on the ``Movie`` model: - -- ``where()``: matches documents in which the value of the ``imdb.rating`` nested field - is greater than ``9.0``. -- ``update()``: updates the matching documents by adding an ``acclaimed`` field and setting - its value to ``true``. This method returns the number of documents that were successfully - updated. - -.. io-code-block:: - :copyable: true - - .. input:: ../includes/usage-examples/UpdateManyTest.php - :start-after: begin-update-many - :end-before: end-update-many - :language: php - :dedent: - - .. output:: - :language: console - :visible: false - - Updated documents: 20 - -.. include:: /includes/usage-examples/fact-edit-laravel-app.rst - .. tip:: To learn more about updating data with the {+odm-short+}, see the :ref:`laravel-fundamentals-modify-documents` section of the Write Operations guide. +Example +------- + +Select from the following :guilabel:`Eloquent` and :guilabel:`Query +Builder` tabs to view usage examples for the same operation that use +each corresponding query syntax: + +.. tabs:: + + .. tab:: Eloquent + :tabid: eloquent-model-count + + This example performs the following actions: + + - Uses the ``Movie`` Eloquent model to represent the ``movies`` + collection in the ``sample_mflix`` database + - Updates documents from the ``movies`` collection that match a + query filter + - Prints the number of updated documents + + The example calls the following methods on the ``Movie`` model: + + - ``where()``: Matches documents in which the value of the + ``imdb.rating`` nested field is greater than ``9.0`` + - ``update()``: Updates the matching documents by adding an + ``acclaimed`` field and setting its value to ``true``, then + returns the number of updated documents + + .. io-code-block:: + :copyable: true + + .. input:: ../includes/usage-examples/UpdateManyTest.php + :start-after: begin-eloquent-update-many + :end-before: end-eloquent-update-many + :language: php + :dedent: + + .. output:: + :language: console + :visible: false + + Updated documents: 20 + + .. tab:: Query Builder + :tabid: query-builder-count + + This example performs the following actions: + + - Accesses the ``movies`` collection by calling the ``table()`` + method from the ``DB`` facade + - Updates documents from the ``movies`` collection that match a + query filter + - Prints the number of updated documents + + The example calls the following query builder methods: + + - ``where()``: Matches documents in which the value of the + ``imdb.rating`` nested field is greater than ``9.0`` + - ``update()``: Updates the matching documents by adding an + ``acclaimed`` field and setting its value to ``true``, then + returns the number of updated documents + + .. io-code-block:: + + .. input:: ../includes/usage-examples/UpdateManyTest.php + :start-after: begin-qb-update-many + :end-before: end-qb-update-many + :language: php + :dedent: + + .. output:: + :language: console + :visible: false + + Updated documents: 20 + +.. include:: /includes/usage-examples/fact-edit-laravel-app.rst diff --git a/docs/usage-examples/updateOne.txt b/docs/usage-examples/updateOne.txt index ecdc8982d..785ba3b09 100644 --- a/docs/usage-examples/updateOne.txt +++ b/docs/usage-examples/updateOne.txt @@ -17,37 +17,46 @@ Update a Document :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. +You can update a document in a collection by retrieving a single +document and calling the ``update()`` method on an Eloquent model. -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. +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. + +.. tip:: + + To learn more about updating data with the {+odm-short+}, see the :ref:`laravel-fundamentals-modify-documents` + section of the Write Operations guide. 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 the query filter +This 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 + the query filter - Prints the number of updated documents 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`` and the value of the ``imdb.votes`` nested field from ``493`` to ``142000``. +- ``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`` and the value of 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 + :start-after: begin-eloquent-update-one + :end-before: end-eloquent-update-one :language: php :dedent: @@ -58,9 +67,3 @@ The example calls the following methods on the ``Movie`` model: Updated documents: 1 .. include:: /includes/usage-examples/fact-edit-laravel-app.rst - -.. tip:: - - To learn more about updating data with the {+odm-short+}, see the :ref:`laravel-fundamentals-modify-documents` - section of the Write Operations guide. - From e95b8d32728a1a0af37a934dda2d3101526807b5 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Thu, 6 Feb 2025 15:14:29 -0500 Subject: [PATCH 413/446] fix CI error --- docs/includes/usage-examples/FindOneTest.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/includes/usage-examples/FindOneTest.php b/docs/includes/usage-examples/FindOneTest.php index d641556d2..594bb5144 100644 --- a/docs/includes/usage-examples/FindOneTest.php +++ b/docs/includes/usage-examples/FindOneTest.php @@ -54,10 +54,10 @@ public function testQBFindOne(): void ->orderBy('_id') ->first(); - echo $movie['title']; + echo $movie->title; // end-qb-find-one - $this->assertSame($movie['title'], 'The Shawshank Redemption'); + $this->assertSame($movie->title, 'The Shawshank Redemption'); $this->expectOutputString('The Shawshank Redemption'); } } From fb004edb1c68b83404900bfa72f207c865df3dcc Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Thu, 6 Feb 2025 16:01:03 -0500 Subject: [PATCH 414/446] Update output based on return type --- docs/usage-examples/find.txt | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/docs/usage-examples/find.txt b/docs/usage-examples/find.txt index 187676392..2939a5c48 100644 --- a/docs/usage-examples/find.txt +++ b/docs/usage-examples/find.txt @@ -130,10 +130,20 @@ each corresponding query syntax: // Results are truncated - Illuminate\Support\Collection Object ( [items:protected] => - Array ( [0] => Array ( [_id] => ... [runtime] => 1256 - [title] => Centennial [1] => Array - ( [_id] => ... [runtime] => 1140 - [title] => Baseball ) ... + [ + { + "_id": ..., + "runtime": 1256, + "title": "Centennial", + ..., + }, + { + "_id": ..., + "runtime": 1140, + "title": "Baseball", + ..., + }, + ... + ] .. include:: /includes/usage-examples/fact-edit-laravel-app.rst From 08d54d8164a0499a067a4a68a3199a28fea874be Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Fri, 7 Feb 2025 12:58:54 -0500 Subject: [PATCH 415/446] DOCSP-46438: Read preference (#3260) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * DOCSP-46438: Read preference * edits * tip * fix test * fix * code * JS feedback * Switch example to SECONDARY_PREFERRED * JT feedback * apply phpcbf formatting * tests --------- Co-authored-by: Jérôme Tamarelle --- docs/fundamentals/read-operations.txt | 109 ++++++++++++++++++ .../read-operations/ReadOperationsTest.php | 19 +++ .../query-builder/QueryBuilderTest.php | 13 +++ docs/query-builder.txt | 34 +++++- 4 files changed, 171 insertions(+), 4 deletions(-) diff --git a/docs/fundamentals/read-operations.txt b/docs/fundamentals/read-operations.txt index d5605033b..f3b02c5ec 100644 --- a/docs/fundamentals/read-operations.txt +++ b/docs/fundamentals/read-operations.txt @@ -359,6 +359,8 @@ method: results in a specified order based on field values - :ref:`laravel-retrieve-one` uses the ``first()`` method to return the first document that matches the query filter +- :ref:`laravel-read-pref` uses the ``readPreference()`` method to direct the query + to specific replica set members .. _laravel-skip-limit: @@ -606,3 +608,110 @@ field. To learn more about the ``orderBy()`` method, see the :ref:`laravel-sort` section of this guide. + +.. _laravel-read-pref: + +Set a Read Preference +~~~~~~~~~~~~~~~~~~~~~ + +To specify which replica set members receive your read operations, +set a read preference by using the ``readPreference()`` method. + +The ``readPreference()`` method accepts the following parameters: + +- ``mode``: *(Required)* A string value specifying the read preference + mode. + +- ``tagSets``: *(Optional)* An array value specifying key-value tags that correspond to + certain replica set members. + +- ``options``: *(Optional)* An array value specifying additional read preference options. + +.. tip:: + + To view a full list of available read preference modes and options, see + :php:`MongoDB\Driver\ReadPreference::__construct ` + in the MongoDB PHP extension documentation. + +The following example queries for documents in which the value of the ``title`` +field is ``"Carrie"`` and sets the read preference to ``ReadPreference::SECONDARY_PREFERRED``. +As a result, the query retrieves the results from secondary replica set +members or the primary member if no secondaries are available: + +.. tabs:: + + .. tab:: Query Syntax + :tabid: query-syntax + + Use the following syntax to specify the query: + + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-read-pref + :end-before: end-read-pref + + .. tab:: Controller Method + :tabid: controller + + To see the query results in the ``browse_movies`` view, edit the ``show()`` function + in the ``MovieController.php`` file to resemble the following code: + + .. io-code-block:: + :copyable: true + + .. input:: + :language: php + + class MovieController + { + public function show() + { + $movies = Movie::where('title', 'Carrie') + ->readPreference(ReadPreference::SECONDARY_PREFERRED) + ->get(); + + return view('browse_movies', [ + 'movies' => $movies + ]); + } + } + + .. output:: + :language: none + :visible: false + + Title: Carrie + Year: 1952 + Runtime: 118 + IMDB Rating: 7.5 + IMDB Votes: 1458 + Plot: Carrie boards the train to Chicago with big ambitions. She gets a + job stitching shoes and her sister's husband takes almost all of her pay + for room and board. Then she injures a finger and ... + + Title: Carrie + Year: 1976 + Runtime: 98 + IMDB Rating: 7.4 + IMDB Votes: 115528 + Plot: A shy, outcast 17-year old girl is humiliated by her classmates for the + last time. + + Title: Carrie + Year: 2002 + Runtime: 132 + IMDB Rating: 5.5 + IMDB Votes: 7412 + Plot: Carrie White is a lonely and painfully shy teenage girl with telekinetic + powers who is slowly pushed to the edge of insanity by frequent bullying from + both her classmates and her domineering, religious mother. + + Title: Carrie + Year: 2013 + Runtime: 100 + IMDB Rating: 6 + IMDB Votes: 98171 + Plot: A reimagining of the classic horror tale about Carrie White, a shy girl + outcast by her peers and sheltered by her deeply religious mother, who unleashes + telekinetic terror on her small town after being pushed too far at her senior prom. diff --git a/docs/includes/fundamentals/read-operations/ReadOperationsTest.php b/docs/includes/fundamentals/read-operations/ReadOperationsTest.php index c27680fb5..207fd442e 100644 --- a/docs/includes/fundamentals/read-operations/ReadOperationsTest.php +++ b/docs/includes/fundamentals/read-operations/ReadOperationsTest.php @@ -6,6 +6,7 @@ use App\Models\Movie; use Illuminate\Support\Facades\DB; +use MongoDB\Driver\ReadPreference; use MongoDB\Laravel\Tests\TestCase; class ReadOperationsTest extends TestCase @@ -33,6 +34,8 @@ protected function setUp(): void ['title' => 'movie_a', 'plot' => 'this is a love story'], ['title' => 'movie_b', 'plot' => 'love is a long story'], ['title' => 'movie_c', 'plot' => 'went on a trip'], + ['title' => 'Carrie', 'year' => 1976], + ['title' => 'Carrie', 'year' => 2002], ]); } @@ -164,4 +167,20 @@ public function arrayElemMatch(): void $this->assertNotNull($movies); $this->assertCount(2, $movies); } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function testReadPreference(): void + { + // start-read-pref + $movies = Movie::where('title', 'Carrie') + ->readPreference(ReadPreference::SECONDARY_PREFERRED) + ->get(); + // end-read-pref + + $this->assertNotNull($movies); + $this->assertCount(2, $movies); + } } diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index d99796fb2..f7525bf6e 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -11,6 +11,7 @@ use MongoDB\BSON\ObjectId; use MongoDB\BSON\Regex; use MongoDB\Collection; +use MongoDB\Driver\ReadPreference; use MongoDB\Laravel\Tests\TestCase; use function file_get_contents; @@ -452,6 +453,18 @@ public function testCursorTimeout(): void $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); } + public function testReadPreference(): void + { + // begin query read pref + $result = DB::table('movies') + ->where('runtime', '>', 240) + ->readPreference(ReadPreference::SECONDARY_PREFERRED) + ->get(); + // end query read pref + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + public function testNear(): void { $this->importTheaters(); diff --git a/docs/query-builder.txt b/docs/query-builder.txt index b3c89b0ae..89caf8846 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -840,6 +840,7 @@ to use the following MongoDB-specific query operations: - :ref:`Run MongoDB Query API operations ` - :ref:`Match documents that contain array elements ` - :ref:`Specify a cursor timeout ` +- :ref:`Specify a read preference ` - :ref:`Match locations by using geospatial searches ` .. _laravel-query-builder-exists: @@ -1033,6 +1034,31 @@ to specify a maximum duration to wait for cursor operations to complete. `MongoDB\Collection::find() `__ in the PHP Library documentation. +.. _laravel-query-builder-read-pref: + +Specify a Read Preference Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can control how the {+odm-short+} directs read operations to replica +set members by setting a read preference. + +The following example queries the ``movies`` collection for documents +in which the ``runtime`` value is greater than ``240``. The example passes a +value of ``ReadPreference::SECONDARY_PREFERRED`` to the ``readPreference()`` +method, which sends the query to secondary replica set members +or the primary member if no secondaries are available: + +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query read pref + :end-before: end query read pref + +.. tip:: + + To learn more about read preferences, see :manual:`Read Preference + ` in the MongoDB {+server-docs-name+}. + .. _laravel-query-builder-geospatial: Match Locations by Using Geospatial Operations @@ -1061,7 +1087,7 @@ in the {+server-docs-name+}. .. _laravel-query-builder-geospatial-near: Near a Position Example -~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^ The following example shows how to use the ``near`` query operator with the ``where()`` query builder method to match documents that @@ -1081,7 +1107,7 @@ in the {+server-docs-name+}. .. _laravel-query-builder-geospatial-geoWithin: Within an Area Example -~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^ The following example shows how to use the ``geoWithin`` query operator with the ``where()`` @@ -1098,7 +1124,7 @@ GeoJSON object: .. _laravel-query-builder-geospatial-geoIntersects: Intersecting a Geometry Example -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The following example shows how to use the ``geoInstersects`` query operator with the ``where()`` query builder method to @@ -1114,7 +1140,7 @@ the specified ``LineString`` GeoJSON object: .. _laravel-query-builder-geospatial-geoNear: Proximity Data for Nearby Matches Example -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The following example shows how to use the ``geoNear`` aggregation operator with the ``raw()`` query builder method to perform an aggregation that returns From f68e0c20533635eb4dff13b75fa66cf49a7c59a0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Fri, 7 Feb 2025 20:38:44 +0100 Subject: [PATCH 416/446] PHPORM-295 VectorSearch path cannot be an array (#3263) --- src/Eloquent/Builder.php | 2 +- src/Query/Builder.php | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Eloquent/Builder.php b/src/Eloquent/Builder.php index afe968e4b..eedbe8712 100644 --- a/src/Eloquent/Builder.php +++ b/src/Eloquent/Builder.php @@ -112,7 +112,7 @@ public function search( */ public function vectorSearch( string $index, - array|string $path, + string $path, array $queryVector, int $limit, bool $exact = false, diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 4c7c8513f..f613b6467 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -1604,7 +1604,7 @@ public function search( */ public function vectorSearch( string $index, - array|string $path, + string $path, array $queryVector, int $limit, bool $exact = false, From 9fdfbe59d78bc2fdcab9145a6b510d325c246aa8 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Mon, 10 Feb 2025 09:16:37 -0500 Subject: [PATCH 417/446] DOCSP-46269: atlas search & atlas vector search pages (#3255) * DOCSP-46269: as & avs * wip * wip * wip * JT small fix * wip * wip * link fix * merge upstream and make some changes from last PR * revert changes to sessions page - will separate into another PR * LM PR fixes 1 * small note * filename change * LM PR fixes 2 * wip * wip * fix term links * fixes * JT small fixes * indentation fix --- docs/fundamentals.txt | 4 + docs/fundamentals/atlas-search.txt | 241 ++++++++++++++++++ docs/fundamentals/vector-search.txt | 162 ++++++++++++ .../fundamentals/as-avs/AtlasSearchTest.php | 157 ++++++++++++ docs/includes/fundamentals/as-avs/Movie.php | 12 + 5 files changed, 576 insertions(+) create mode 100644 docs/fundamentals/atlas-search.txt create mode 100644 docs/fundamentals/vector-search.txt create mode 100644 docs/includes/fundamentals/as-avs/AtlasSearchTest.php create mode 100644 docs/includes/fundamentals/as-avs/Movie.php diff --git a/docs/fundamentals.txt b/docs/fundamentals.txt index db482b2b8..dafc427c3 100644 --- a/docs/fundamentals.txt +++ b/docs/fundamentals.txt @@ -20,6 +20,8 @@ Fundamentals Read Operations Write Operations Aggregation Builder + Atlas Search + Atlas Vector Search Learn more about the following concepts related to {+odm-long+}: @@ -28,3 +30,5 @@ Learn more about the following concepts related to {+odm-long+}: - :ref:`laravel-fundamentals-read-ops` - :ref:`laravel-fundamentals-write-ops` - :ref:`laravel-aggregation-builder` +- :ref:`laravel-atlas-search` +- :ref:`laravel-vector-search` diff --git a/docs/fundamentals/atlas-search.txt b/docs/fundamentals/atlas-search.txt new file mode 100644 index 000000000..9aaa9156b --- /dev/null +++ b/docs/fundamentals/atlas-search.txt @@ -0,0 +1,241 @@ +.. _laravel-atlas-search: + +============ +Atlas Search +============ + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, semantic, text + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to perform searches on your documents +by using the Atlas Search feature. {+odm-long+} provides an API to +perform Atlas Search queries directly with your models. This guide +describes how to create Atlas Search indexes and provides examples of +how to use the {+odm-short+} to perform searches. + +.. note:: Deployment Compatibility + + You can use the Atlas Search feature only when + you connect to MongoDB Atlas clusters. This feature is not + available for self-managed deployments. + +To learn more about Atlas Search, see the :atlas:`Overview +` in the +Atlas documentation. The Atlas Search API internally uses the +``$search`` aggregation operator to perform queries. To learn more about +this operator, see the :atlas:`$search +` reference in the Atlas +documentation. + +.. note:: + + You might not be able to use the methods described in + this guide for every type of Atlas Search query. + For more complex use cases, create an aggregation pipeline by using + the :ref:`laravel-aggregation-builder`. + + To perform searches on vector embeddings in MongoDB, you can use the + {+odm-long+} Atlas Vector Search API. To learn about this feature, see + the :ref:`laravel-vector-search` guide. + +.. _laravel-as-index: + +Create an Atlas Search Index +---------------------------- + +.. TODO in DOCSP-46230 + +Perform Queries +--------------- + +In this section, you can learn how to use the Atlas Search API in the +{+odm-short+}. + +General Queries +~~~~~~~~~~~~~~~ + +The {+odm-short+} provides the ``search()`` method as a query +builder method and as an Eloquent model method. You can use the +``search()`` method to run Atlas Search queries on documents in your +collections. + +You must pass an ``operator`` parameter to the ``search()`` method that +is an instance of ``SearchOperatorInterface`` or an array that contains +the operator type, field name, and query value. You can +create an instance of ``SearchOperatorInterface`` by calling the +``Search::text()`` method and passing the field you are +querying and your search term or phrase. + +You must include the following import statement in your application to +create a ``SearchOperatorInterface`` instance: + +.. code-block:: php + + use MongoDB\Builder\Search; + +The following code performs an Atlas Search query on the ``Movie`` +model's ``title`` field for the term ``'dream'``: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/fundamentals/as-avs/AtlasSearchTest.php + :language: php + :dedent: + :start-after: start-search-query + :end-before: end-search-query + + .. output:: + :language: json + :visible: false + + [ + { "title": "Dreaming of Jakarta", + "year": 1990 + }, + { "title": "See You in My Dreams", + "year": 1996 + } + ] + +You can use the ``search()`` method to perform many types of Atlas +Search queries. Depending on your desired query, you can pass the +following optional parameters to ``search()``: + +.. list-table:: + :header-rows: 1 + + * - Optional Parameter + - Type + - Description + + * - ``index`` + - ``string`` + - Provides the name of the Atlas Search index to use + + * - ``highlight`` + - ``array`` + - Specifies highlighting options for displaying search terms in their + original context + + * - ``concurrent`` + - ``bool`` + - Parallelizes search query across segments on dedicated search nodes + + * - ``count`` + - ``string`` + - Specifies the count options for retrieving a count of the results + + * - ``searchAfter`` + - ``string`` + - Specifies a reference point for returning documents starting + immediately following that point + + * - ``searchBefore`` + - ``string`` + - Specifies a reference point for returning documents starting + immediately preceding that point + + * - ``scoreDetails`` + - ``bool`` + - Specifies whether to retrieve a detailed breakdown of the score + for results + + * - ``sort`` + - ``array`` + - Specifies the fields on which to sort the results + + * - ``returnStoredSource`` + - ``bool`` + - Specifies whether to perform a full document lookup on the + backend database or return only stored source fields directly + from Atlas Search + + * - ``tracking`` + - ``array`` + - Specifies the tracking option to retrieve analytics information + on the search terms + +To learn more about these parameters, see the :atlas:`Fields +` section of the +``$search`` operator reference in the Atlas documentation. + +Autocomplete Queries +~~~~~~~~~~~~~~~~~~~~ + +The {+odm-short+} provides the ``autocomplete()`` method as a query +builder method and as an Eloquent model method. You can use the +``autocomplete()`` method to run autocomplete searches on documents in your +collections. This method returns only the values of the field you +specify as the query path. + +To learn more about this type of Atlas Search query, see the +:atlas:`autocomplete ` reference in the +Atlas documentation. + +.. note:: + + You must create an Atlas Search index with an autocomplete configuration + on your collection before you can perform autocomplete searches. See the + :ref:`laravel-as-index` section of this guide to learn more about + creating Search indexes. + +The following code performs an Atlas Search autocomplete query for the +string ``"jak"`` on the ``title`` field: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/fundamentals/as-avs/AtlasSearchTest.php + :language: php + :dedent: + :start-after: start-auto-query + :end-before: end-auto-query + + .. output:: + :language: json + :visible: false + + [ + "Dreaming of Jakarta", + "Jakob the Liar", + "Emily Calling Jake" + ] + +You can also pass the following optional parameters to the ``autocomplete()`` +method to customize the query: + +.. list-table:: + :header-rows: 1 + + * - Optional Parameter + - Type + - Description + - Default Value + + * - ``fuzzy`` + - ``bool`` or ``array`` + - Enables fuzzy search and fuzzy search options + - ``false`` + + * - ``tokenOrder`` + - ``string`` + - Specifies order in which to search for tokens + - ``'any'`` + +To learn more about these parameters, see the :atlas:`Options +` section of the +``autocomplete`` operator reference in the Atlas documentation. diff --git a/docs/fundamentals/vector-search.txt b/docs/fundamentals/vector-search.txt new file mode 100644 index 000000000..116cb75a0 --- /dev/null +++ b/docs/fundamentals/vector-search.txt @@ -0,0 +1,162 @@ +.. _laravel-vector-search: + +=================== +Atlas Vector Search +=================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, semantic, text, embeddings + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to perform searches on your documents +by using the Atlas Vector Search feature. {+odm-long+} provides an API to +perform Atlas Vector Search queries directly with your models. This guide +describes how to create Atlas Vector Search indexes and provides +examples of how to use the {+odm-short+} to perform searches. + +.. note:: Deployment Compatibility + + You can use the Atlas Vector Search feature only when + you connect to MongoDB Atlas clusters. This feature is not + available for self-managed deployments. + +To learn more about Atlas Vector Search, see the :atlas:`Overview +` in the +Atlas documentation. The Atlas Vector Search API internally uses the +``$vectorSearch`` aggregation operator to perform queries. To learn more about +this operator, see the :atlas:`$vectorSearch +` reference in the Atlas +documentation. + +.. note:: + + You might not be able to use the methods described in + this guide for every type of Atlas Vector Search query. + For more complex use cases, create an aggregation pipeline by using + the :ref:`laravel-aggregation-builder`. + + To perform advanced full-text searches on your documents, you can use the + {+odm-long+} Atlas Search API. To learn about this feature, see + the :ref:`laravel-atlas-search` guide. + +.. _laravel-avs-index: + +Create an Atlas Vector Search Index +----------------------------------- + +.. TODO in DOCSP-46230 + +Perform Queries +--------------- + +In this section, you can learn how to use the Atlas Vector Search API in +the {+odm-short+}. The {+odm-short+} provides the ``vectorSearch()`` +method as a query builder method and as an Eloquent model method. You +can use the ``vectorSearch()`` method to run Atlas Vector Search queries +on documents in your collections. + +You must pass the following parameters to the ``vectorSearch()`` method: + +.. list-table:: + :header-rows: 1 + + * - Parameter + - Type + - Description + + * - ``index`` + - ``string`` + - Name of the vector search index + + * - ``path`` + - ``string`` + - Field that stores vector embeddings + + * - ``queryVector`` + - ``array`` + - Vector representation of your query + + * - ``limit`` + - ``int`` + - Number of results to return + +The following code uses the ``vector`` index created in the preceding +:ref:`laravel-avs-index` section to perform an Atlas Vector Search query on the +``movies`` collection: + +.. io-code-block:: + :copyable: true + + .. input:: + :language: php + + $movies = Book::vectorSearch( + index: 'vector', + path: 'vector_embeddings', + // Vector representation of the query `coming of age` + queryVector: [-0.0016261312, -0.028070757, ...], + limit: 3, + ); + + .. output:: + :language: json + :visible: false + + [ + { "title": "Sunrising", + "plot": "A shy teenager discovers confidence and new friendships during a transformative summer camp experience." + }, + { "title": "Last Semester", + "plot": "High school friends navigate love, identity, and unexpected challenges before graduating together." + } + ] + +You can use the ``vectorSearch()`` method to perform many types of Atlas +Search queries. Depending on your desired query, you can pass the +following optional parameters to ``vectorSearch()``: + +.. list-table:: + :header-rows: 1 + + * - Optional Parameter + - Type + - Description + - Default Value + + * - ``exact`` + - ``bool`` + - Specifies whether to run an Exact Nearest Neighbor (``true``) or + Approximate Nearest Neighbor (``false``) search + - ``false`` + + * - ``filter`` + - ``QueryInterface`` or ``array`` + - Specifies a pre-filter for documents to search on + - no filtering + + * - ``numCandidates`` + - ``int`` or ``null`` + - Specifies the number of nearest neighbors to use during the + search + - ``null`` + +.. note:: + + To construct a ``QueryInterface`` instance, you must import the + ``MongoDB\Builder\Query`` class into your application. + +To learn more about these parameters, see the :atlas:`Fields +` section of the +``$vectorSearch`` operator reference in the Atlas documentation. diff --git a/docs/includes/fundamentals/as-avs/AtlasSearchTest.php b/docs/includes/fundamentals/as-avs/AtlasSearchTest.php new file mode 100644 index 000000000..1d9336f76 --- /dev/null +++ b/docs/includes/fundamentals/as-avs/AtlasSearchTest.php @@ -0,0 +1,157 @@ +getCollection('movies'); + $moviesCollection->drop(); + + Movie::insert([ + ['title' => 'Dreaming of Jakarta', 'year' => 1990], + ['title' => 'See You in My Dreams', 'year' => 1996], + ['title' => 'On the Run', 'year' => 2004], + ['title' => 'Jakob the Liar', 'year' => 1999], + ['title' => 'Emily Calling Jake', 'year' => 2001], + ]); + + Movie::insert($this->addVector([ + ['title' => 'A', 'plot' => 'A shy teenager discovers confidence and new friendships during a transformative summer camp experience.'], + ['title' => 'B', 'plot' => 'A detective teams up with a hacker to unravel a global conspiracy threatening personal freedoms.'], + ['title' => 'C', 'plot' => 'High school friends navigate love, identity, and unexpected challenges before graduating together.'], + ['title' => 'D', 'plot' => 'Stranded on a distant planet, astronauts must repair their ship before supplies run out.'], + ])); + + $moviesCollection = DB::connection('mongodb')->getCollection('movies'); + + try { + $moviesCollection->createSearchIndex([ + 'mappings' => [ + 'fields' => [ + 'title' => [ + ['type' => 'string', 'analyzer' => 'lucene.english'], + ['type' => 'autocomplete', 'analyzer' => 'lucene.english'], + ['type' => 'token'], + ], + ], + ], + ]); + + $moviesCollection->createSearchIndex([ + 'mappings' => ['dynamic' => true], + ], ['name' => 'dynamic_search']); + + $moviesCollection->createSearchIndex([ + 'fields' => [ + ['type' => 'vector', 'numDimensions' => 4, 'path' => 'vector4', 'similarity' => 'cosine'], + ['type' => 'filter', 'path' => 'title'], + ], + ], ['name' => 'vector', 'type' => 'vectorSearch']); + } catch (ServerException $e) { + if (Builder::isAtlasSearchNotSupportedException($e)) { + self::markTestSkipped('Atlas Search not supported. ' . $e->getMessage()); + } + + throw $e; + } + + // Waits for the index to be ready + do { + $ready = true; + usleep(10_000); + foreach ($collection->listSearchIndexes() as $index) { + if ($index['status'] !== 'READY') { + $ready = false; + } + } + } while (! $ready); + } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function testSimpleSearch(): void + { + // start-search-query + $movies = Movie::search( + sort: ['title' => 1], + operator: Search::text('title', 'dream'), + )->get(); + // end-search-query + + $this->assertNotNull($movies); + $this->assertCount(2, $movies); + } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function autocompleteSearchTest(): void + { + // start-auto-query + $movies = Movie::autocomplete('title', 'jak')->get(); + // end-auto-query + + $this->assertNotNull($movies); + $this->assertCount(3, $movies); + } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function vectorSearchTest(): void + { + $results = Book::vectorSearch( + index: 'vector', + path: 'vector4', + queryVector: $this->vectors[0], + limit: 3, + numCandidates: 10, + filter: Query::query( + title: Query::ne('A'), + ), + ); + + $this->assertNotNull($results); + $this->assertSame('C', $results->first()->title); + } + + /** Generates random vectors using fixed seed to make tests deterministic */ + private function addVector(array $items): array + { + srand(1); + foreach ($items as &$item) { + $this->vectors[] = $item['vector4'] = array_map(fn () => rand() / mt_getrandmax(), range(0, 3)); + } + + return $items; + } +} diff --git a/docs/includes/fundamentals/as-avs/Movie.php b/docs/includes/fundamentals/as-avs/Movie.php new file mode 100644 index 000000000..2098db9ec --- /dev/null +++ b/docs/includes/fundamentals/as-avs/Movie.php @@ -0,0 +1,12 @@ + Date: Thu, 13 Feb 2025 13:54:16 -0500 Subject: [PATCH 418/446] DOCSP-35943: write operations reorg (#3275) * DOCSP-35943: write operations reorg * reusability * wip * NR PR fixes 1 * title fix --- docs/fundamentals/write-operations.txt | 771 +++--------------- docs/fundamentals/write-operations/delete.txt | 173 ++++ docs/fundamentals/write-operations/insert.txt | 134 +++ docs/fundamentals/write-operations/modify.txt | 436 ++++++++++ .../write-operations/sample-model-section.rst | 21 + 5 files changed, 891 insertions(+), 644 deletions(-) create mode 100644 docs/fundamentals/write-operations/delete.txt create mode 100644 docs/fundamentals/write-operations/insert.txt create mode 100644 docs/fundamentals/write-operations/modify.txt create mode 100644 docs/includes/fundamentals/write-operations/sample-model-section.rst diff --git a/docs/fundamentals/write-operations.txt b/docs/fundamentals/write-operations.txt index 6554d2dd0..0a4d8a6ca 100644 --- a/docs/fundamentals/write-operations.txt +++ b/docs/fundamentals/write-operations.txt @@ -11,6 +11,12 @@ Write Operations .. meta:: :keywords: insert, insert one, update, update one, upsert, code example, mass assignment, push, pull, delete, delete many, primary key, destroy, eloquent model +.. toctree:: + + Insert + Modify + Delete + .. contents:: On this page :local: :backlinks: none @@ -20,679 +26,156 @@ Write Operations Overview -------- -In this guide, you can learn how to use {+odm-long+} 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` -- :ref:`laravel-fundamentals-modify-documents` -- :ref:`laravel-fundamentals-delete-documents` - -.. _laravel-fundamentals-write-sample-model: - -Sample Model -~~~~~~~~~~~~ - -The write operations in this guide reference the following Eloquent model class: - -.. literalinclude:: /includes/fundamentals/write-operations/Concert.php - :language: php - :dedent: - :caption: Concert.php +In this guide, you can see code templates of common +methods that you can use to write data to MongoDB by using +{+odm-long+}. .. 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. - -.. _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 {+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. - -To learn more about Eloquent models in the {+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 an array of strings to the ``genre`` field -- Assigns a number to the ``ticketsSold`` field -- 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 - :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: - -.. 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 - -.. _laravel-fundamentals-modify-documents: - -Modify Documents ----------------- - -In this section, you can learn how to modify documents in your MongoDB -collection from your Laravel application. Use update operations to modify -existing documents or to insert a document if none match the search -criteria. - -You can persist changes on an instance of an Eloquent model or use -Eloquent's fluent syntax to chain an update operation on methods that -return a Laravel collection object. - -This section provides examples of the following update operations: - -- :ref:`Update a document ` -- :ref:`Update multiple documents ` -- :ref:`Update or insert in a single operation ` -- :ref:`Update arrays in a document ` - -.. _laravel-modify-documents-update-one: - -Update a Document Examples -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can update a document in the following ways: - -- Modify an instance of the model and save the changes by calling the ``save()`` - method. -- Chain methods to retrieve an instance of a model and perform updates on it - by calling the ``update()`` method. - -The following example shows how to update a document by modifying an instance -of the model and calling its ``save()`` method: - -.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php - :language: php - :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. - -If the operation fails, the {+odm-short+} assigns the model instance a ``null`` value. - -The following example shows how to update a document by chaining methods to -retrieve and update the first matching document: - -.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php - :language: php - :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. - -.. include:: /includes/fact-orderby-id.rst - -When the ``update()`` method succeeds, the operation returns the number of -documents updated. - -If the retrieve part of the call does not match any documents, the {+odm-short+} -returns the following error: - -.. code-block:: none - :copyable: false - - Error: Call to a member function update() on null - -.. _laravel-modify-documents-update-multiple: - -Update Multiple Documents Example -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To perform an update on one or more documents, chain the ``update()`` -method to the results of a method that retrieves the documents as a -Laravel collection object, such as ``where()``. - -The following example shows how to chain calls to retrieve matching documents -and update them: - -.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php - :language: php - :dedent: - :start-after: begin model update multiple - :end-before: end model update multiple - -When the ``update()`` method succeeds, the operation returns the number of -documents updated. - -If the retrieve part of the call does not match any documents in the -collection, the {+odm-short+} returns the following error: - -.. code-block:: none - :copyable: false - - Error: Call to a member function update() on null - -.. _laravel-modify-documents-upsert: - -Update or Insert in a Single Operation --------------------------------------- + To learn more about any of the methods included in this guide, + see the links provided in each section. -An **upsert** operation lets you perform an update or insert in a single -operation. This operation streamlines the task of updating a document or -inserting one if it does not exist. +Insert One +---------- -Starting in v4.7, you can perform an upsert operation by using either of -the following methods: +The following code shows how to insert a single document into a +collection: -- ``upsert()``: When you use this method, you can perform a **batch - upsert** to change or insert multiple documents in one operation. - -- ``update()``: When you use this method, you must specify the - ``upsert`` option to update all documents that match the query filter - or insert one document if no documents are matched. Only this upsert method - is supported in versions v4.6 and earlier. +.. code-block:: php + + SampleModel::create([ + '' => '', + '' => '', + ... + ]); -Upsert Method -~~~~~~~~~~~~~ +To view a runnable example that inserts one document, see the +:ref:`laravel-insert-one-usage` usage example. -The ``upsert(array $values, array|string $uniqueBy, array|null -$update)`` method accepts the following parameters: +To learn more about inserting documents, see the +:ref:`laravel-fundamentals-write-insert` guide. -- ``$values``: Array of fields and values that specify documents to update or insert. -- ``$uniqueBy``: List of fields that uniquely identify documents in your - first array parameter. -- ``$update``: Optional list of fields to update if a matching document - exists. If you omit this parameter, the {+odm-short+} updates all fields. +Insert Multiple +--------------- -To specify an upsert in the ``upsert()`` method, set parameters -as shown in the following code example: +The following code shows how to insert multiple documents into a +collection: .. code-block:: php - :copyable: false - - YourModel::upsert( - [/* documents to update or insert */], - '/* unique field */', - [/* fields to update */], - ); - -Example -^^^^^^^ - -This example shows how to use the ``upsert()`` -method to perform an update or insert in a single operation. Click the -:guilabel:`{+code-output-label+}` button to see the resulting data changes when -there is a document in which the value of ``performer`` is ``'Angel -Olsen'`` in the collection already: - -.. io-code-block:: - - .. input:: /includes/fundamentals/write-operations/WriteOperationsTest.php - :language: php - :dedent: - :start-after: begin model upsert - :end-before: end model upsert - - .. output:: - :language: json - :visible: false - - { - "_id": "...", - "performer": "Angel Olsen", - "venue": "State Theatre", - "genres": [ - "indie", - "rock" - ], - "ticketsSold": 275, - "updated_at": ... - }, - { - "_id": "...", - "performer": "Darondo", - "venue": "Cafe du Nord", - "ticketsSold": 300, - "updated_at": ... - } - -In the document in which the value of ``performer`` is ``'Angel -Olsen'``, the ``venue`` field value is not updated, as the upsert -specifies that the update applies only to the ``ticketsSold`` field. - -Update Method -~~~~~~~~~~~~~ - -To specify an upsert in an ``update()`` method, set the ``upsert`` option to -``true`` as shown in the following code example: + + SampleModel::insert([ + [ + '' => '', + '' => '', + ], + [ + '' => '', + '' => '', + ], + ... + ]); + +To view a runnable example that inserts multiple documents, see the +:ref:`laravel-insert-many-usage` usage example. + +To learn more about inserting documents, see the +:ref:`laravel-fundamentals-write-insert` guide. + +Update One +---------- + +The following code shows how to update a single document in a +collection by creating or editing a field: .. code-block:: php - :emphasize-lines: 4 - :copyable: false - - YourModel::where(/* match criteria */) - ->update( - [/* update data */], - ['upsert' => true]); - -When the ``update()`` method is chained to a query, it performs one of the -following actions: - -- If the query matches documents, the ``update()`` method modifies the matching - documents. -- If the query matches zero documents, the ``update()`` method inserts a - document that contains the update data and the equality match criteria data. - -Example -^^^^^^^ - -This example shows how to pass the ``upsert`` option to the ``update()`` -method to perform an update or insert in a single operation. Click the -:guilabel:`{+code-output-label+}` button to see the example document inserted when no -matching documents exist: - -.. io-code-block:: - - .. input:: /includes/fundamentals/write-operations/WriteOperationsTest.php - :language: php - :dedent: - :start-after: begin model update upsert - :end-before: end model update upsert - - .. output:: - :language: json - :visible: false - - { - "_id": "660c...", - "performer": "Jon Batiste", - "venue": "Radio City Music Hall", - "genres": [ - "R&B", - "soul" - ], - "ticketsSold": 4000, - "updated_at": ... - } - -.. _laravel-modify-documents-arrays: - -Update Arrays in a Document ---------------------------- - -In this section, you can see examples of the following operations that -update array values in a MongoDB document: - -- :ref:`Add values to an array ` -- :ref:`Remove values from an array ` -- :ref:`Update the value of an array element ` - -These examples modify the sample document created by the following insert -operation: - -.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php - :language: php - :dedent: - :start-after: begin array example document - :end-before: end array example document - -.. _laravel-modify-documents-add-array-values: - -Add Values to an Array Example -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This section shows how to use the ``push()`` method to add values to an array -in a MongoDB document. You can pass one or more values to add and set the -optional parameter ``unique`` to ``true`` to skip adding any duplicate values -in the array. The following code example shows the structure of a ``push()`` -method call: - -.. code-block:: none - :copyable: false - - YourModel::where() - ->push( - , - [], // array or single value to add - unique: true); // whether to skip existing values - -The following example shows how to add the value ``"baroque"`` to -the ``genres`` array field of a matching document. Click the -:guilabel:`{+code-output-label+}` button to see the updated document: - -.. io-code-block:: - - .. input:: /includes/fundamentals/write-operations/WriteOperationsTest.php - :language: php - :dedent: - :start-after: begin model array push - :end-before: end model array push - - .. output:: - :language: json - :visible: false - - { - "_id": "660eb...", - "performer": "Mitsuko Uchida", - "genres": [ - "classical", - "dance-pop", - - ], - "updated_at": ..., - "created_at": ... - } - - -.. _laravel-modify-documents-remove-array-values: - -Remove Values From an Array Example -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This section shows how to use the ``pull()`` method to remove values from -an array in a MongoDB document. You can pass one or more values to remove -from the array. The following code example shows the structure of a -``pull()`` method call: - -.. code-block:: none - :copyable: false - - YourModel::where() - ->pull( - , - []); // array or single value to remove - -The following example shows how to remove array values ``"classical"`` and -``"dance-pop"`` from the ``genres`` array field. Click the -:guilabel:`{+code-output-label+}` button to see the updated document: - -.. io-code-block:: - - .. input:: /includes/fundamentals/write-operations/WriteOperationsTest.php - :language: php - :dedent: - :start-after: begin model array pull - :end-before: end model array pull - - .. output:: - :language: json - :visible: false - - { - "_id": "660e...", - "performer": "Mitsuko Uchida", - "genres": [], - "updated_at": ..., - "created_at": ... - } - - -.. _laravel-modify-documents-update-array-values: - -Update the Value of an Array Element Example -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This section shows how to use the ``$`` positional operator to update specific -array elements in a MongoDB document. The ``$`` operator represents the first -array element that matches the query. The following code example shows the -structure of a positional operator update call on a single matching document: - - -.. note:: - - Currently, the {+odm-short+} offers this operation only on the ``DB`` facade - and not on the Eloquent ORM. - -.. code-block:: none - :copyable: false - - DB::connection('mongodb') - ->getCollection() - ->updateOne( - , - ['$set' => ['.$' => ]]); - + + SampleModel::where('', '') + ->orderBy('') + ->first() + ->update([ + '' => '', + ]); -The following example shows how to replace the array value ``"dance-pop"`` -with ``"contemporary"`` in the ``genres`` array field. Click the -:guilabel:`{+code-output-label+}` button to see the updated document: +To view a runnable example that updates one document, see the +:ref:`laravel-update-one-usage` usage example. -.. io-code-block:: +To learn more about updating documents, see the +:ref:`laravel-fundamentals-write-modify` guide. - .. input:: /includes/fundamentals/write-operations/WriteOperationsTest.php - :language: php - :dedent: - :start-after: begin model array positional - :end-before: end model array positional +Update Multiple +--------------- - .. output:: - :language: json - :visible: false +The following code shows how to update multiple documents in a +collection: - { - "_id": "660e...", - "performer": "Mitsuko Uchida", - "genres": [ - "classical", - "contemporary" - ], - "updated_at": ..., - "created_at": ... - } - -To learn more about array update operators, see :manual:`Array Update Operators ` -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 the {+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 ` -- :ref:`Delete multiple documents ` - -To learn about the Laravel features available in the {+odm-short+} that modify -delete behavior, see the following sections: - -- :ref:`Soft delete `, which lets you mark - documents as deleted instead of removing them from the database -- :ref:`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: +.. code-block:: php + + SampleModel::where('', '', '') + ->update(['' => '']); +To view a runnable example that updates multiple documents, see the +:ref:`laravel-update-many-usage` usage example. -- 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. +To learn more about updating documents, see the +:ref:`laravel-fundamentals-write-modify` guide. -The following example shows how to delete a document by passing an array of -id values, represented by ``$ids``, to the ``destroy()`` method: +Upsert +------ -.. 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. +The following code shows how to update a document, or insert one if a +matching document doesn't exist: -.. tip:: +.. code-block:: php + + SampleModel::where(['' => '']) + ->update( + ['' => '', ...], + ['upsert' => true], + ); + + /* Or, use the upsert() method. */ + + SampleModel::upsert( + [], + '', + [], + ); + +To learn more about upserting documents, see the +:ref:`laravel-fundamentals-write-modify` guide. + +Delete One +---------- + +The following code shows how to delete a single document in a +collection: - The ``destroy()`` method performance suffers when passed large lists. For - better performance, use ``Model::whereIn('id', $ids)->delete()`` instead. +.. code-block:: php + + SampleModel::where('', '') + ->orderBy('') + ->limit(1) + ->delete(); -When the ``destroy()`` method succeeds, it returns the number of documents -deleted. +To view a runnable example that deletes one document, see the +:ref:`laravel-delete-one-usage` usage example. -If the id values do not match any documents, the ``destroy()`` method -returns returns ``0``. +To learn more about deleting documents, see the +:ref:`laravel-fundamentals-write-delete` guide. -The following example shows how to chain calls to retrieve matching documents -and delete them: +Delete Multiple +--------------- -.. 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. +The following code shows how to delete multiple documents in a +collection: -When the ``delete()`` method succeeds, it returns the number of documents -deleted. +.. code-block:: php + + SampleModel::where('', '') + ->delete(); -If the ``where()`` method does not match any documents, the ``delete()`` method -returns ``0``. +To view a runnable example that deletes multiple documents, see the +:ref:`laravel-delete-many-usage` usage example. +To learn more about deleting documents, see the +:ref:`laravel-fundamentals-write-delete` guide. diff --git a/docs/fundamentals/write-operations/delete.txt b/docs/fundamentals/write-operations/delete.txt new file mode 100644 index 000000000..cd89111db --- /dev/null +++ b/docs/fundamentals/write-operations/delete.txt @@ -0,0 +1,173 @@ +.. _laravel-fundamentals-delete-documents: +.. _laravel-fundamentals-write-delete: + +================ +Delete Documents +================ + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: delete, delete many, primary key, destroy, eloquent model, code example + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to delete documents from a MongoDB +collection by using the {+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 ` +- :ref:`Delete multiple documents ` + +.. include:: /includes/fundamentals/write-operations/sample-model-section.rst + +.. _laravel-fundamentals-delete-one: + +Delete One Document +------------------- + +You can delete one document in the following ways: + +- Call the ``$model->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::destroy($id)`` method on the model, passing it the + ``_id`` value of the document to be deleted. + +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 + +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 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 + +.. 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 ``0``. + +destroy() Method +~~~~~~~~~~~~~~~~ + +The following example shows how to delete a document by passing the value of +its ``_id`` value 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 + +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 ``0``. + +.. _laravel-fundamentals-delete-many: + +Delete Multiple Documents +------------------------- + +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. + +destroy() 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 + +.. 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 ``0``. + +delete() Method +~~~~~~~~~~~~~~~ + +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 + +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``. + +Additional Information +---------------------- + +To learn about the Laravel features available in the {+odm-short+} that +modify delete behavior, see the following sections: + +- :ref:`Soft delete `, which lets you mark + documents as deleted instead of removing them from the database +- :ref:`Pruning `, which lets you define conditions + that qualify a document for automatic deletion + +To view runnable code examples that demonstrate how to delete documents +by using the {+odm-short+}, see the following usage examples: + +- :ref:`laravel-delete-one-usage` +- :ref:`laravel-delete-many-usage` + +To learn how to insert documents into a MongoDB collection, see the +:ref:`laravel-fundamentals-write-insert` guide. diff --git a/docs/fundamentals/write-operations/insert.txt b/docs/fundamentals/write-operations/insert.txt new file mode 100644 index 000000000..ce8c3e725 --- /dev/null +++ b/docs/fundamentals/write-operations/insert.txt @@ -0,0 +1,134 @@ +.. _laravel-fundamentals-insert-documents: +.. _laravel-fundamentals-write-insert: + +================ +Insert Documents +================ + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: update, update one, upsert, code example, mass assignment, eloquent model, push, pull + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to insert documents into MongoDB +collections from your Laravel application by using {+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. + +To learn more about Eloquent models in the {+odm-short+}, see the +:ref:`laravel-eloquent-models` section. + +.. include:: /includes/fundamentals/write-operations/sample-model-section.rst + +Insert One Document +------------------- + +The examples in this section show how to use the ``save()`` and +``create()`` Eloquent methods to insert an instance of a ``Concert`` +model as a MongoDB document. + +save() Method +~~~~~~~~~~~~~ + +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 an array of strings to the ``genre`` field +- Assigns a number to the ``ticketsSold`` field +- 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 + +create() Method +~~~~~~~~~~~~~~~ + +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 +------------------------- + +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 following example saves multiple models in a single call by passing +them as an array to the ``insert()`` method: + +.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php + :language: php + :dedent: + :start-after: begin model insert many + :end-before: end model insert many + +.. 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. + +Additional Information +---------------------- + +To view runnable code examples that demonstrate how to insert documents +by using the {+odm-short+}, see the following usage examples: + +- :ref:`laravel-insert-one-usage` +- :ref:`laravel-insert-many-usage` + +To learn how to modify data that is already in MongoDB, see the +:ref:`laravel-fundamentals-write-modify` guide. diff --git a/docs/fundamentals/write-operations/modify.txt b/docs/fundamentals/write-operations/modify.txt new file mode 100644 index 000000000..b1ac4ac9c --- /dev/null +++ b/docs/fundamentals/write-operations/modify.txt @@ -0,0 +1,436 @@ +.. _laravel-fundamentals-modify-documents: +.. _laravel-fundamentals-write-modify: + +================ +Modify Documents +================ + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: insert, insert one, 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 modify documents in your MongoDB +collection from your Laravel application by using {+odm-long+}. Use +update operations to modify existing documents or to insert a document +if none match the search criteria. + +You can persist changes on an instance of an Eloquent model or use +Eloquent's fluent syntax to chain an update operation on methods that +return a Laravel collection object. + +This guide provides examples of the following update operations: + +- :ref:`Update a document ` +- :ref:`Update multiple documents ` +- :ref:`Update or insert in a single operation ` +- :ref:`Update arrays in a document ` + +.. include:: /includes/fundamentals/write-operations/sample-model-section.rst + +.. _laravel-modify-documents-update-one: + +Update One Document +------------------- + +You can update a document in the following ways: + +- Modify an instance of the model and save the changes by calling the + ``save()`` method. +- Chain methods to retrieve an instance of a model and perform updates + on it by calling the ``update()`` method. + +The following example shows how to update a document by modifying an instance +of the model and calling its ``save()`` method: + +.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php + :language: php + :dedent: + :start-after: begin model update one save + :end-before: end model update one save + +When the ``save()`` method succeeds, the model instance on which you called the +method contains the updated values. + +If the operation fails, the {+odm-short+} assigns the model instance a ``null`` value. + +The following example shows how to update a document by chaining methods to +retrieve and update the first matching document: + +.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php + :language: php + :dedent: + :start-after: begin model update one fluent + :end-before: end model update one fluent + +.. include:: /includes/fact-orderby-id.rst + +When the ``update()`` method succeeds, the operation returns the number of +documents updated. + +If the retrieve part of the call does not match any documents, the {+odm-short+} +returns the following error: + +.. code-block:: none + :copyable: false + + Error: Call to a member function update() on null + +.. _laravel-modify-documents-update-multiple: + +Update Multiple Documents +------------------------- + +To perform an update on one or more documents, chain the ``update()`` +method to the results of a method that retrieves the documents as a +Laravel collection object, such as ``where()``. + +The following example shows how to chain calls to retrieve matching documents +and update them: + +.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php + :language: php + :dedent: + :start-after: begin model update multiple + :end-before: end model update multiple + +When the ``update()`` method succeeds, the operation returns the number of +documents updated. + +If the retrieve part of the call does not match any documents in the +collection, the {+odm-short+} returns the following error: + +.. code-block:: none + :copyable: false + + Error: Call to a member function update() on null + +.. _laravel-modify-documents-upsert: + +Update or Insert in a Single Operation +-------------------------------------- + +An **upsert** operation lets you perform an update or insert in a single +operation. This operation streamlines the task of updating a document or +inserting one if it does not exist. + +Starting in v4.7, you can perform an upsert operation by using either of +the following methods: + +- ``upsert()``: When you use this method, you can perform a **batch + upsert** to change or insert multiple documents in one operation. + +- ``update()``: When you use this method, you must specify the + ``upsert`` option to update all documents that match the query filter + or insert one document if no documents are matched. Only this upsert method + is supported in versions v4.6 and earlier. + +Upsert Method +~~~~~~~~~~~~~ + +The ``upsert()`` method accepts the following parameters: + +- ``$values``: Array of fields and values that specify documents to update or insert. +- ``$uniqueBy``: One or more fields that uniquely identify documents in your + first array parameter. +- ``$update``: Optional array of fields to update if a matching document + exists. If you omit this parameter, the {+odm-short+} updates all fields. + +To specify an upsert in the ``upsert()`` method, pass the required +parameters as shown in the following code example: + +.. code-block:: php + :copyable: false + + YourModel::upsert( + [/* documents to update or insert */], + '/* unique field */', + [/* fields to update */], + ); + +Example +^^^^^^^ + +This example shows how to use the ``upsert()`` +method to perform an update or insert in a single operation. Click the +:guilabel:`{+code-output-label+}` button to see the resulting data changes when +there is a document in which the value of ``performer`` is ``'Angel +Olsen'`` in the collection already: + +.. io-code-block:: + + .. input:: /includes/fundamentals/write-operations/WriteOperationsTest.php + :language: php + :dedent: + :start-after: begin model upsert + :end-before: end model upsert + + .. output:: + :language: json + :visible: false + + { + "_id": "...", + "performer": "Angel Olsen", + "venue": "State Theatre", + "genres": [ + "indie", + "rock" + ], + "ticketsSold": 275, + "updated_at": ... + }, + { + "_id": "...", + "performer": "Darondo", + "venue": "Cafe du Nord", + "ticketsSold": 300, + "updated_at": ... + } + +In the document in which the value of ``performer`` is ``'Angel +Olsen'``, the ``venue`` field value is not updated, as the upsert +specifies that the update applies only to the ``ticketsSold`` field. + +Update Method +~~~~~~~~~~~~~ + +To specify an upsert in an ``update()`` method, set the ``upsert`` option to +``true`` as shown in the following code example: + +.. code-block:: php + :emphasize-lines: 4 + :copyable: false + + YourModel::where(/* match criteria */) + ->update( + [/* update data */], + ['upsert' => true]); + +When the ``update()`` method is chained to a query, it performs one of the +following actions: + +- If the query matches documents, the ``update()`` method modifies the matching + documents. +- If the query matches zero documents, the ``update()`` method inserts a + document that contains the update data and the equality match criteria data. + +Example +^^^^^^^ + +This example shows how to pass the ``upsert`` option to the ``update()`` +method to perform an update or insert in a single operation. Click the +:guilabel:`{+code-output-label+}` button to see the example document inserted when no +matching documents exist: + +.. io-code-block:: + + .. input:: /includes/fundamentals/write-operations/WriteOperationsTest.php + :language: php + :dedent: + :start-after: begin model update upsert + :end-before: end model update upsert + + .. output:: + :language: json + :visible: false + + { + "_id": "660c...", + "performer": "Jon Batiste", + "venue": "Radio City Music Hall", + "genres": [ + "R&B", + "soul" + ], + "ticketsSold": 4000, + "updated_at": ... + } + +.. _laravel-modify-documents-arrays: + +Update Arrays in a Document +--------------------------- + +In this section, you can see examples of the following operations that +update array values in a MongoDB document: + +- :ref:`Add values to an array ` +- :ref:`Remove values from an array ` +- :ref:`Update the value of an array element ` + +These examples modify the sample document created by the following insert +operation: + +.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php + :language: php + :dedent: + :start-after: begin array example document + :end-before: end array example document + +.. _laravel-modify-documents-add-array-values: + +Add Values to an Array Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section shows how to use the ``push()`` method to add values to an array +in a MongoDB document. You can pass one or more values to add and set the +optional parameter ``unique`` to ``true`` to skip adding any duplicate values +in the array. The following code example shows the structure of a ``push()`` +method call: + +.. code-block:: php + :copyable: false + + YourModel::where() + ->push( + , + [], // array or single value to add + unique: true); // whether to skip existing values + +The following example shows how to add the value ``"baroque"`` to +the ``genres`` array field of a matching document. Click the +:guilabel:`{+code-output-label+}` button to see the updated document: + +.. io-code-block:: + + .. input:: /includes/fundamentals/write-operations/WriteOperationsTest.php + :language: php + :dedent: + :start-after: begin model array push + :end-before: end model array push + + .. output:: + :language: json + :visible: false + + { + "_id": "660eb...", + "performer": "Mitsuko Uchida", + "genres": [ + "classical", + "dance-pop", + + ], + "updated_at": ..., + "created_at": ... + } + +.. _laravel-modify-documents-remove-array-values: + +Remove Values From an Array Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section shows how to use the ``pull()`` method to remove values from +an array in a MongoDB document. You can pass one or more values to remove +from the array. The following code example shows the structure of a +``pull()`` method call: + +.. code-block:: php + :copyable: false + + YourModel::where() + ->pull( + , + []); // array or single value to remove + +The following example shows how to remove array values ``"classical"`` and +``"dance-pop"`` from the ``genres`` array field. Click the +:guilabel:`{+code-output-label+}` button to see the updated document: + +.. io-code-block:: + + .. input:: /includes/fundamentals/write-operations/WriteOperationsTest.php + :language: php + :dedent: + :start-after: begin model array pull + :end-before: end model array pull + + .. output:: + :language: json + :visible: false + + { + "_id": "660e...", + "performer": "Mitsuko Uchida", + "genres": [], + "updated_at": ..., + "created_at": ... + } + +.. _laravel-modify-documents-update-array-values: + +Update the Value of an Array Element Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section shows how to use the ``$`` positional operator to update specific +array elements in a MongoDB document. The ``$`` operator represents the first +array element that matches the query. The following code example shows the +structure of a positional operator update call on a single matching document: + +.. note:: + + Currently, the {+odm-short+} offers this operation only on the ``DB`` facade + and not on the Eloquent ORM. + +.. code-block:: php + :copyable: false + + DB::connection('mongodb') + ->getCollection() + ->updateOne( + , + ['$set' => ['.$' => ]]); + +The following example shows how to replace the array value ``"dance-pop"`` +with ``"contemporary"`` in the ``genres`` array field. Click the +:guilabel:`{+code-output-label+}` button to see the updated document: + +.. io-code-block:: + + .. input:: /includes/fundamentals/write-operations/WriteOperationsTest.php + :language: php + :dedent: + :start-after: begin model array positional + :end-before: end model array positional + + .. output:: + :language: json + :visible: false + + { + "_id": "660e...", + "performer": "Mitsuko Uchida", + "genres": [ + "classical", + "contemporary" + ], + "updated_at": ..., + "created_at": ... + } + +To learn more about array update operators, see :manual:`Array Update Operators ` +in the {+server-docs-name+}. + +Additional Information +---------------------- + +To view runnable code examples that demonstrate how to update documents +by using the {+odm-short+}, see the following usage examples: + +- :ref:`laravel-update-one-usage` +- :ref:`laravel-update-many-usage` + +To learn how to insert documents into a MongoDB collection, see the +:ref:`laravel-fundamentals-write-insert` guide. diff --git a/docs/includes/fundamentals/write-operations/sample-model-section.rst b/docs/includes/fundamentals/write-operations/sample-model-section.rst new file mode 100644 index 000000000..a98870b50 --- /dev/null +++ b/docs/includes/fundamentals/write-operations/sample-model-section.rst @@ -0,0 +1,21 @@ +Sample Model +~~~~~~~~~~~~ + +The operations in this guide reference the following Eloquent +model class: + +.. 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. From 73d6b94f8be3687dea720b79cdd6fbc03b86bcb3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 18 Feb 2025 16:58:15 +0100 Subject: [PATCH 419/446] DOCSP-46269 Fix doc examples on atlas search (#3279) --- .../fundamentals/as-avs/AtlasSearchTest.php | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/includes/fundamentals/as-avs/AtlasSearchTest.php b/docs/includes/fundamentals/as-avs/AtlasSearchTest.php index 1d9336f76..79dfe46df 100644 --- a/docs/includes/fundamentals/as-avs/AtlasSearchTest.php +++ b/docs/includes/fundamentals/as-avs/AtlasSearchTest.php @@ -11,6 +11,7 @@ use MongoDB\Driver\Exception\ServerException; use MongoDB\Laravel\Schema\Builder; use MongoDB\Laravel\Tests\TestCase; +use PHPUnit\Framework\Attributes\Group; use function array_map; use function mt_getrandmax; @@ -19,6 +20,7 @@ use function srand; use function usleep; +#[Group('atlas-search')] class AtlasSearchTest extends TestCase { private array $vectors; @@ -84,7 +86,7 @@ protected function setUp(): void do { $ready = true; usleep(10_000); - foreach ($collection->listSearchIndexes() as $index) { + foreach ($moviesCollection->listSearchIndexes() as $index) { if ($index['status'] !== 'READY') { $ready = false; } @@ -102,7 +104,7 @@ public function testSimpleSearch(): void $movies = Movie::search( sort: ['title' => 1], operator: Search::text('title', 'dream'), - )->get(); + )->all(); // end-search-query $this->assertNotNull($movies); @@ -113,10 +115,10 @@ public function testSimpleSearch(): void * @runInSeparateProcess * @preserveGlobalState disabled */ - public function autocompleteSearchTest(): void + public function testAutocompleteSearch(): void { // start-auto-query - $movies = Movie::autocomplete('title', 'jak')->get(); + $movies = Movie::autocomplete('title', 'jak')->all(); // end-auto-query $this->assertNotNull($movies); @@ -127,9 +129,9 @@ public function autocompleteSearchTest(): void * @runInSeparateProcess * @preserveGlobalState disabled */ - public function vectorSearchTest(): void + public function testVectorSearch(): void { - $results = Book::vectorSearch( + $results = Movie::vectorSearch( index: 'vector', path: 'vector4', queryVector: $this->vectors[0], @@ -141,7 +143,7 @@ public function vectorSearchTest(): void ); $this->assertNotNull($results); - $this->assertSame('C', $results->first()->title); + $this->assertSame('D', $results->first()->title); } /** Generates random vectors using fixed seed to make tests deterministic */ From 11f3cc1478f21da15911f01a55a2994edc73f7eb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 18 Feb 2025 19:25:28 +0100 Subject: [PATCH 420/446] PHPORM-296 Enable support for Scout v10 (#3280) --- composer.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/composer.json b/composer.json index dce593ed5..82c980859 100644 --- a/composer.json +++ b/composer.json @@ -35,12 +35,12 @@ }, "require-dev": { "mongodb/builder": "^0.2", - "laravel/scout": "^11", + "laravel/scout": "^10.3", "league/flysystem-gridfs": "^3.28", "league/flysystem-read-only": "^3.0", "phpunit/phpunit": "^10.3", "orchestra/testbench": "^8.0|^9.0", - "mockery/mockery": "^1.4.4", + "mockery/mockery": "^1.4.4@stable", "doctrine/coding-standard": "12.0.x-dev", "spatie/laravel-query-builder": "^5.6", "phpstan/phpstan": "^1.10", From cb3b32c388a16c8fe01323b89ac3313758825864 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Wed, 19 Feb 2025 11:27:51 +0100 Subject: [PATCH 421/446] PHPORM-268 Add configuration for scout search indexes (#3281) --- src/MongoDBServiceProvider.php | 3 +- src/Scout/ScoutEngine.php | 13 +++-- tests/Scout/ScoutEngineTest.php | 79 ++++++++++++++++++++++++++++ tests/Scout/ScoutIntegrationTest.php | 7 ++- 4 files changed, 96 insertions(+), 6 deletions(-) diff --git a/src/MongoDBServiceProvider.php b/src/MongoDBServiceProvider.php index b0c085b8e..dc9caf082 100644 --- a/src/MongoDBServiceProvider.php +++ b/src/MongoDBServiceProvider.php @@ -167,10 +167,11 @@ private function registerScoutEngine(): void $connectionName = $app->get('config')->get('scout.mongodb.connection', 'mongodb'); $connection = $app->get('db')->connection($connectionName); $softDelete = (bool) $app->get('config')->get('scout.soft_delete', false); + $indexDefinitions = $app->get('config')->get('scout.mongodb.index-definitions', []); assert($connection instanceof Connection, new InvalidArgumentException(sprintf('The connection "%s" is not a MongoDB connection.', $connectionName))); - return new ScoutEngine($connection->getMongoDB(), $softDelete); + return new ScoutEngine($connection->getMongoDB(), $softDelete, $indexDefinitions); }); return $engineManager; diff --git a/src/Scout/ScoutEngine.php b/src/Scout/ScoutEngine.php index e3c9c68c3..dc70a39e2 100644 --- a/src/Scout/ScoutEngine.php +++ b/src/Scout/ScoutEngine.php @@ -9,6 +9,7 @@ use Illuminate\Database\Eloquent\SoftDeletes; use Illuminate\Support\Collection; use Illuminate\Support\LazyCollection; +use InvalidArgumentException; use Laravel\Scout\Builder; use Laravel\Scout\Engines\Engine; use Laravel\Scout\Searchable; @@ -66,9 +67,11 @@ final class ScoutEngine extends Engine private const TYPEMAP = ['root' => 'object', 'document' => 'bson', 'array' => 'bson']; + /** @param array $indexDefinitions */ public function __construct( private Database $database, private bool $softDelete, + private array $indexDefinitions = [], ) { } @@ -435,14 +438,16 @@ public function createIndex($name, array $options = []): void { assert(is_string($name), new TypeError(sprintf('Argument #1 ($name) must be of type string, %s given', get_debug_type($name)))); + $definition = $this->indexDefinitions[$name] ?? self::DEFAULT_DEFINITION; + if (! isset($definition['mappings'])) { + throw new InvalidArgumentException(sprintf('Invalid search index definition for collection "%s", the "mappings" key is required. Find documentation at https://www.mongodb.com/docs/manual/reference/command/createSearchIndexes/#search-index-definition-syntax', $name)); + } + // Ensure the collection exists before creating the search index $this->database->createCollection($name); $collection = $this->database->selectCollection($name); - $collection->createSearchIndex( - self::DEFAULT_DEFINITION, - ['name' => self::INDEX_NAME], - ); + $collection->createSearchIndex($definition, ['name' => self::INDEX_NAME]); if ($options['wait'] ?? true) { $this->wait(function () use ($collection) { diff --git a/tests/Scout/ScoutEngineTest.php b/tests/Scout/ScoutEngineTest.php index a079ae530..f1244d060 100644 --- a/tests/Scout/ScoutEngineTest.php +++ b/tests/Scout/ScoutEngineTest.php @@ -2,6 +2,7 @@ namespace MongoDB\Laravel\Tests\Scout; +use ArrayIterator; use Closure; use DateTimeImmutable; use Illuminate\Database\Eloquent\Collection as EloquentCollection; @@ -9,7 +10,9 @@ use Illuminate\Support\LazyCollection; use Laravel\Scout\Builder; use Laravel\Scout\Jobs\RemoveFromSearch; +use LogicException; use Mockery as m; +use MongoDB\BSON\Document; use MongoDB\BSON\UTCDateTime; use MongoDB\Collection; use MongoDB\Database; @@ -31,6 +34,82 @@ class ScoutEngineTest extends TestCase { private const EXPECTED_TYPEMAP = ['root' => 'object', 'document' => 'bson', 'array' => 'bson']; + public function testCreateIndexInvalidDefinition(): void + { + $database = m::mock(Database::class); + $engine = new ScoutEngine($database, false, ['collection_invalid' => ['foo' => 'bar']]); + + $this->expectException(LogicException::class); + $this->expectExceptionMessage('Invalid search index definition for collection "collection_invalid", the "mappings" key is required.'); + $engine->createIndex('collection_invalid'); + } + + public function testCreateIndex(): void + { + $collectionName = 'collection_custom'; + $expectedDefinition = [ + 'mappings' => [ + 'dynamic' => true, + ], + ]; + + $database = m::mock(Database::class); + $collection = m::mock(Collection::class); + $database->shouldReceive('createCollection') + ->once() + ->with($collectionName); + $database->shouldReceive('selectCollection') + ->with($collectionName) + ->andReturn($collection); + $collection->shouldReceive('createSearchIndex') + ->once() + ->with($expectedDefinition, ['name' => 'scout']); + $collection->shouldReceive('listSearchIndexes') + ->once() + ->with(['name' => 'scout', 'typeMap' => ['root' => 'bson']]) + ->andReturn(new ArrayIterator([Document::fromPHP(['name' => 'scout', 'status' => 'READY'])])); + + $engine = new ScoutEngine($database, false, []); + $engine->createIndex($collectionName); + } + + public function testCreateIndexCustomDefinition(): void + { + $collectionName = 'collection_custom'; + $expectedDefinition = [ + 'mappings' => [ + [ + 'analyzer' => 'lucene.standard', + 'fields' => [ + [ + 'name' => 'wildcard', + 'type' => 'string', + ], + ], + ], + ], + ]; + + $database = m::mock(Database::class); + $collection = m::mock(Collection::class); + $database->shouldReceive('createCollection') + ->once() + ->with($collectionName); + $database->shouldReceive('selectCollection') + ->with($collectionName) + ->andReturn($collection); + $collection->shouldReceive('createSearchIndex') + ->once() + ->with($expectedDefinition, ['name' => 'scout']); + $collection->shouldReceive('listSearchIndexes') + ->once() + ->with(['name' => 'scout', 'typeMap' => ['root' => 'bson']]) + ->andReturn(new ArrayIterator([Document::fromPHP(['name' => 'scout', 'status' => 'READY'])])); + + $engine = new ScoutEngine($database, false, [$collectionName => $expectedDefinition]); + $engine->createIndex($collectionName); + } + /** @param callable(): Builder $builder */ #[DataProvider('provideSearchPipelines')] public function testSearch(Closure $builder, array $expectedPipeline): void diff --git a/tests/Scout/ScoutIntegrationTest.php b/tests/Scout/ScoutIntegrationTest.php index ff4617352..b40a455ab 100644 --- a/tests/Scout/ScoutIntegrationTest.php +++ b/tests/Scout/ScoutIntegrationTest.php @@ -17,6 +17,7 @@ use function array_merge; use function count; use function env; +use function iterator_to_array; use function Orchestra\Testbench\artisan; use function range; use function sprintf; @@ -38,6 +39,9 @@ protected function getEnvironmentSetUp($app): void $app['config']->set('scout.driver', 'mongodb'); $app['config']->set('scout.prefix', 'prefix_'); + $app['config']->set('scout.mongodb.index-definitions', [ + 'prefix_scout_users' => ['mappings' => ['dynamic' => true, 'fields' => ['bool_field' => ['type' => 'boolean']]]], + ]); } public function setUp(): void @@ -103,8 +107,9 @@ public function testItCanCreateTheCollection() self::assertSame(44, $collection->countDocuments()); - $searchIndexes = $collection->listSearchIndexes(['name' => 'scout']); + $searchIndexes = $collection->listSearchIndexes(['name' => 'scout', 'typeMap' => ['root' => 'array', 'document' => 'array', 'array' => 'array']]); self::assertCount(1, $searchIndexes); + self::assertSame(['mappings' => ['dynamic' => true, 'fields' => ['bool_field' => ['type' => 'boolean']]]], iterator_to_array($searchIndexes)[0]['latestDefinition']); // Wait for all documents to be indexed asynchronously $i = 100; From f62046d0a159a9e3df207eeed929c4b1743fdc7a Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Fri, 21 Feb 2025 15:08:51 -0500 Subject: [PATCH 422/446] DOCSP-38130: Time series collections (#3274) * DOCSP-38130: Time sereies collections * apply phpcbf formatting * fix * build error * JT feedback * apply phpcbf formatting * fixes * apply phpcbf formatting * JT feedback 2 --- .../database-collection.txt | 6 + docs/database-collection/time-series.txt | 174 ++++++++++++++++++ docs/fundamentals.txt | 2 - .../time-series-migration.php | 35 ++++ .../query-builder/QueryBuilderTest.php | 24 +++ docs/index.txt | 7 + 6 files changed, 246 insertions(+), 2 deletions(-) rename docs/{fundamentals => }/database-collection.txt (98%) create mode 100644 docs/database-collection/time-series.txt create mode 100644 docs/includes/database-collection/time-series-migration.php diff --git a/docs/fundamentals/database-collection.txt b/docs/database-collection.txt similarity index 98% rename from docs/fundamentals/database-collection.txt rename to docs/database-collection.txt index a453d81a9..fb6573147 100644 --- a/docs/fundamentals/database-collection.txt +++ b/docs/database-collection.txt @@ -17,6 +17,12 @@ Databases and Collections :depth: 2 :class: singlecol +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Time Series + Overview -------- diff --git a/docs/database-collection/time-series.txt b/docs/database-collection/time-series.txt new file mode 100644 index 000000000..cfd17828d --- /dev/null +++ b/docs/database-collection/time-series.txt @@ -0,0 +1,174 @@ +.. _laravel-time-series: + +======================= +Time Series Collections +======================= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: chronological, data format, code example + +Overview +-------- + +In this guide, you can learn how to use the {+odm-short+} to create +and interact with **time series collections**. These collections store +time series data, which is composed of the following components: + +- Measured quantity +- Timestamp for the measurement +- Metadata that describes the measurement + +The following table describes sample situations for which you can store time +series data: + +.. list-table:: + :widths: 33, 33, 33 + :header-rows: 1 + :stub-columns: 1 + + * - Situation + - Measured Quantity + - Metadata + + * - Recording monthly sales by industry + - Revenue in USD + - Company, country + + * - Tracking weather changes + - Precipitation level + - Location, sensor type + + * - Recording fluctuations in housing prices + - Monthly rent price + - Location, currency + +.. _laravel-time-series-create: + +Create a Time Series Collection +------------------------------- + +.. important:: Server Version for Time Series Collections + + To create and interact with time series collections, you must be + connected to a deployment running MongoDB Server 5.0 or later. + +You can create a time series collection to store time series data. +To create a time series collection, create a migration class and +add an ``up()`` function to specify the collection configuration. +In the ``up()`` function, pass the new collection's name +and the ``timeseries`` option to the ``Schema::create()`` method. + +.. tip:: + + To learn more about creating a migration class, see :ref:`laravel-eloquent-migrations` + in the Schema Builder guide. + +When setting the ``timeseries`` option, include the following fields: + +- ``timeField``: Specifies the field that stores a timestamp in each time series document. +- ``metaField``: Specifies the field that stores metadata in each time series document. +- ``granularity``: Specifies the approximate time between consecutive timestamps. The possible + values are ``'seconds'``, ``'minutes'``, and ``'hours'``. + +.. _laravel-time-series-create-example: + +Example +~~~~~~~ + +This example migration class creates the ``precipitation`` time series collection +with the following configuration: + +- ``timeField`` is set to ``'timestamp'`` +- ``metaField`` is set to ``'location'`` +- ``granularity`` is set to ``'minutes'`` + +.. literalinclude:: /includes/database-collection/time-series-migration.php + :language: php + :dedent: + +To verify that you successfully created the time series collection, call +the ``Schema::hasCollection()`` method and pass the collection name as +a parameter: + +.. code-block:: php + + $result = Schema::hasCollection('precipitation'); + echo $result; + +If the collection exists, the ``hasCollection()`` method returns a +value of ``true``. + +.. _laravel-time-series-insert: + +Insert Time Series Data +----------------------- + +You can insert data into a time series collection by passing your documents to the ``insert()`` +method and specifying the measurement, timestamp, and metadata in each inserted document. + +.. tip:: + + To learn more about inserting documents into a collection, see :ref:`laravel-fundamentals-insert-documents` + in the Write Operations guide. + +Example +~~~~~~~ + +This example inserts New York City precipitation data into the ``precipitation`` +time series collection created in the :ref:`Create a Time Series Collection example +`. Each document contains the following fields: + +- ``precipitation_mm``, which stores precipitation measurements in millimeters +- ``location``, which stores location metadata +- ``timestamp``, which stores the time of the measurement collection + +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin time series + :end-before: end time series + +.. note:: + + The preceding example uses the :ref:`Laravel query builder ` + to insert documents into the time series collection. Alternatively, + you can create an Eloquent model that represents the collection and + perform insert operations on your model. To learn more, see + the :ref:`laravel-eloquent-model-class` guide. + +.. _laravel-time-series-query: + +Query Time Series Collections +----------------------------- + +You can use the same syntax and conventions to query data stored in a time +series collection as you use when performing read or aggregation operations on +other collections. To find more information about these operations, see +the :ref:`Additional Information ` section. + +.. _laravel-time-series-addtl-info: + +Additional Information +---------------------- + +To learn more about the concepts mentioned in this guide, see the +following MongoDB {+server-docs-name+} entries: + +- :manual:`Time Series ` +- :manual:`Create and Query a Time Series Collection ` +- :manual:`Set Granularity for Time Series Data ` + +To learn more about querying data, see the :ref:`laravel-query-builder` guide. + +To learn more about performing aggregation operations, see the :ref:`laravel-aggregation-builder` +guide. diff --git a/docs/fundamentals.txt b/docs/fundamentals.txt index db482b2b8..fc67d4c48 100644 --- a/docs/fundamentals.txt +++ b/docs/fundamentals.txt @@ -16,7 +16,6 @@ Fundamentals :maxdepth: 1 Connections - Databases & Collections Read Operations Write Operations Aggregation Builder @@ -24,7 +23,6 @@ Fundamentals Learn more about the following concepts related to {+odm-long+}: - :ref:`laravel-fundamentals-connection` -- :ref:`laravel-db-coll` - :ref:`laravel-fundamentals-read-ops` - :ref:`laravel-fundamentals-write-ops` - :ref:`laravel-aggregation-builder` diff --git a/docs/includes/database-collection/time-series-migration.php b/docs/includes/database-collection/time-series-migration.php new file mode 100644 index 000000000..2ea817822 --- /dev/null +++ b/docs/includes/database-collection/time-series-migration.php @@ -0,0 +1,35 @@ + [ + 'timeField' => 'timestamp', + 'metaField' => 'location', + 'granularity' => 'minutes', + ], + ]; + + Schema::create('precipitation', null, $options); + } + + /** + * Reverse the migrations. + */ + public function down(): void + { + Schema::drop('precipitation'); + } +}; diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index d99796fb2..884c54b5f 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -10,6 +10,7 @@ use Illuminate\Support\Facades\DB; use MongoDB\BSON\ObjectId; use MongoDB\BSON\Regex; +use MongoDB\BSON\UTCDateTime; use MongoDB\Collection; use MongoDB\Laravel\Tests\TestCase; @@ -665,4 +666,27 @@ public function testUnset(): void $this->assertIsInt($result); } + + public function testTimeSeries(): void + { + // begin time series + $data = [ + [ + 'precipitation_mm' => 0.5, + 'location' => 'New York City', + 'timestamp' => new UTCDateTime(Carbon::create(2023, 9, 12, 0, 0, 0, 'CET')), + ], + [ + 'precipitation_mm' => 2.8, + 'location' => 'New York City', + 'timestamp' => new UTCDateTime(Carbon::create(2023, 9, 17, 0, 0, 0, 'CET')), + ], + ]; + + $result = DB::table('precipitation') + ->insert($data); + // end time series + + $this->assertTrue($result); + } } diff --git a/docs/index.txt b/docs/index.txt index 104a6aa77..6b91880f9 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -19,6 +19,7 @@ Fundamentals Eloquent Models Query Builder + Databases & Collections User Authentication Cache & Locks Queues @@ -88,6 +89,12 @@ see the following content: - :ref:`laravel-transactions` - :ref:`laravel-filesystems` +Databases and Collections +------------------------- + +Learn how to use the {+odm-short+} to work with MongoDB databases and collections +in the :ref:`laravel-db-coll` section. + Issues & Help ------------- From 56fa399aeda0e45564bc7a4a43572ffd9117412b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 24 Feb 2025 17:08:35 +0100 Subject: [PATCH 423/446] PHPORM-302 Compatibility with spatie/laravel-query-builder v6 (#3285) --- composer.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/composer.json b/composer.json index 82c980859..6df5c0575 100644 --- a/composer.json +++ b/composer.json @@ -42,7 +42,7 @@ "orchestra/testbench": "^8.0|^9.0", "mockery/mockery": "^1.4.4@stable", "doctrine/coding-standard": "12.0.x-dev", - "spatie/laravel-query-builder": "^5.6", + "spatie/laravel-query-builder": "^5.6|^6", "phpstan/phpstan": "^1.10", "rector/rector": "^1.2" }, From a8f38d9aecaef29d1adb0a620a6700ce69926898 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 24 Feb 2025 21:10:52 +0100 Subject: [PATCH 424/446] PHPORM-303 Require mongodb library v1.21 with aggregation builder (#3287) --- composer.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/composer.json b/composer.json index 6df5c0575..6618fac67 100644 --- a/composer.json +++ b/composer.json @@ -30,11 +30,10 @@ "illuminate/database": "^10.30|^11", "illuminate/events": "^10.0|^11", "illuminate/support": "^10.0|^11", - "mongodb/mongodb": "^1.18", + "mongodb/mongodb": "^1.21", "symfony/http-foundation": "^6.4|^7" }, "require-dev": { - "mongodb/builder": "^0.2", "laravel/scout": "^10.3", "league/flysystem-gridfs": "^3.28", "league/flysystem-read-only": "^3.0", @@ -54,6 +53,7 @@ "mongodb/builder": "Provides a fluent aggregation builder for MongoDB pipelines" }, "minimum-stability": "dev", + "prefer-stable": true, "replace": { "jenssegers/mongodb": "self.version" }, From faacf63ac1586cb82f17a8b26bb839d56f68ddca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 24 Feb 2025 21:18:54 +0100 Subject: [PATCH 425/446] PHPORM-299 Enable PHPUnit 11 (#3286) --- composer.json | 2 +- tests/AuthTest.php | 4 ++-- tests/Eloquent/CallBuilderTest.php | 2 ++ tests/Eloquent/MassPrunableTest.php | 2 ++ tests/EmbeddedRelationsTest.php | 2 ++ tests/GeospatialTest.php | 2 ++ tests/HybridRelationsTest.php | 2 ++ tests/ModelTest.php | 2 ++ tests/QueryBuilderTest.php | 2 ++ tests/RelationsTest.php | 2 ++ tests/SchemaTest.php | 18 ++++++++---------- tests/SchemaVersionTest.php | 2 ++ tests/Scout/ScoutEngineTest.php | 12 ++++++------ tests/SeederTest.php | 2 ++ tests/Ticket/GH2489Test.php | 2 ++ tests/ValidationTest.php | 2 ++ 16 files changed, 41 insertions(+), 19 deletions(-) diff --git a/composer.json b/composer.json index 6618fac67..2855a9546 100644 --- a/composer.json +++ b/composer.json @@ -37,7 +37,7 @@ "laravel/scout": "^10.3", "league/flysystem-gridfs": "^3.28", "league/flysystem-read-only": "^3.0", - "phpunit/phpunit": "^10.3", + "phpunit/phpunit": "^10.3|^11.5.3", "orchestra/testbench": "^8.0|^9.0", "mockery/mockery": "^1.4.4@stable", "doctrine/coding-standard": "12.0.x-dev", diff --git a/tests/AuthTest.php b/tests/AuthTest.php index 98d42832e..998c07f2d 100644 --- a/tests/AuthTest.php +++ b/tests/AuthTest.php @@ -17,10 +17,10 @@ class AuthTest extends TestCase { public function tearDown(): void { - parent::setUp(); - User::truncate(); DB::table('password_reset_tokens')->truncate(); + + parent::tearDown(); } public function testAuthAttempt() diff --git a/tests/Eloquent/CallBuilderTest.php b/tests/Eloquent/CallBuilderTest.php index fa4cb4580..39643f1c1 100644 --- a/tests/Eloquent/CallBuilderTest.php +++ b/tests/Eloquent/CallBuilderTest.php @@ -21,6 +21,8 @@ final class CallBuilderTest extends TestCase protected function tearDown(): void { User::truncate(); + + parent::tearDown(); } #[Dataprovider('provideFunctionNames')] diff --git a/tests/Eloquent/MassPrunableTest.php b/tests/Eloquent/MassPrunableTest.php index 0f6f2ab15..884f90ac6 100644 --- a/tests/Eloquent/MassPrunableTest.php +++ b/tests/Eloquent/MassPrunableTest.php @@ -20,6 +20,8 @@ public function tearDown(): void { User::truncate(); Soft::truncate(); + + parent::tearDown(); } public function testPruneWithQuery(): void diff --git a/tests/EmbeddedRelationsTest.php b/tests/EmbeddedRelationsTest.php index 8ee8297f7..1c68e2d34 100644 --- a/tests/EmbeddedRelationsTest.php +++ b/tests/EmbeddedRelationsTest.php @@ -20,6 +20,8 @@ public function tearDown(): void { Mockery::close(); User::truncate(); + + parent::tearDown(); } public function testEmbedsManySave() diff --git a/tests/GeospatialTest.php b/tests/GeospatialTest.php index 724bb580b..b29a3240a 100644 --- a/tests/GeospatialTest.php +++ b/tests/GeospatialTest.php @@ -53,6 +53,8 @@ public function setUp(): void public function tearDown(): void { Schema::drop('locations'); + + parent::tearDown(); } public function testGeoWithin() diff --git a/tests/HybridRelationsTest.php b/tests/HybridRelationsTest.php index 71958d27d..08423007c 100644 --- a/tests/HybridRelationsTest.php +++ b/tests/HybridRelationsTest.php @@ -42,6 +42,8 @@ public function tearDown(): void Skill::truncate(); Experience::truncate(); Label::truncate(); + + parent::tearDown(); } public function testSqlRelations() diff --git a/tests/ModelTest.php b/tests/ModelTest.php index ef71a5fe0..ecfcb2b6a 100644 --- a/tests/ModelTest.php +++ b/tests/ModelTest.php @@ -56,6 +56,8 @@ public function tearDown(): void Book::truncate(); Item::truncate(); Guarded::truncate(); + + parent::tearDown(); } public function testNewModel(): void diff --git a/tests/QueryBuilderTest.php b/tests/QueryBuilderTest.php index 01f937915..9592bbe7c 100644 --- a/tests/QueryBuilderTest.php +++ b/tests/QueryBuilderTest.php @@ -43,6 +43,8 @@ public function tearDown(): void { DB::table('users')->truncate(); DB::table('items')->truncate(); + + parent::tearDown(); } public function testDeleteWithId() diff --git a/tests/RelationsTest.php b/tests/RelationsTest.php index a58fef02f..a55c8c0e0 100644 --- a/tests/RelationsTest.php +++ b/tests/RelationsTest.php @@ -35,6 +35,8 @@ public function tearDown(): void Photo::truncate(); Label::truncate(); Skill::truncate(); + + parent::tearDown(); } public function testHasMany(): void diff --git a/tests/SchemaTest.php b/tests/SchemaTest.php index 34029aa32..e2f4f7b7e 100644 --- a/tests/SchemaTest.php +++ b/tests/SchemaTest.php @@ -26,6 +26,8 @@ public function tearDown(): void assert($database instanceof Database); $database->dropCollection('newcollection'); $database->dropCollection('newcollection_two'); + + parent::tearDown(); } public function testCreate(): void @@ -37,10 +39,8 @@ public function testCreate(): void public function testCreateWithCallback(): void { - $instance = $this; - - Schema::create('newcollection', function ($collection) use ($instance) { - $instance->assertInstanceOf(Blueprint::class, $collection); + Schema::create('newcollection', static function ($collection) { + self::assertInstanceOf(Blueprint::class, $collection); }); $this->assertTrue(Schema::hasCollection('newcollection')); @@ -66,14 +66,12 @@ public function testDrop(): void public function testBluePrint(): void { - $instance = $this; - - Schema::table('newcollection', function ($collection) use ($instance) { - $instance->assertInstanceOf(Blueprint::class, $collection); + Schema::table('newcollection', static function ($collection) { + self::assertInstanceOf(Blueprint::class, $collection); }); - Schema::table('newcollection', function ($collection) use ($instance) { - $instance->assertInstanceOf(Blueprint::class, $collection); + Schema::table('newcollection', static function ($collection) { + self::assertInstanceOf(Blueprint::class, $collection); }); } diff --git a/tests/SchemaVersionTest.php b/tests/SchemaVersionTest.php index 4a205c77b..b8048b71a 100644 --- a/tests/SchemaVersionTest.php +++ b/tests/SchemaVersionTest.php @@ -15,6 +15,8 @@ class SchemaVersionTest extends TestCase public function tearDown(): void { SchemaVersion::truncate(); + + parent::tearDown(); } public function testWithBasicDocument() diff --git a/tests/Scout/ScoutEngineTest.php b/tests/Scout/ScoutEngineTest.php index f1244d060..40d943ffb 100644 --- a/tests/Scout/ScoutEngineTest.php +++ b/tests/Scout/ScoutEngineTest.php @@ -141,7 +141,7 @@ public function testSearch(Closure $builder, array $expectedPipeline): void $this->assertEquals($data, $result); } - public function provideSearchPipelines(): iterable + public static function provideSearchPipelines(): iterable { $defaultPipeline = [ [ @@ -377,11 +377,11 @@ function () { yield 'with callback' => [ fn () => new Builder(new SearchableModel(), 'query', callback: function (...$args) { - $this->assertCount(3, $args); - $this->assertInstanceOf(Collection::class, $args[0]); - $this->assertSame('collection_searchable', $args[0]->getCollectionName()); - $this->assertSame('query', $args[1]); - $this->assertNull($args[2]); + self::assertCount(3, $args); + self::assertInstanceOf(Collection::class, $args[0]); + self::assertSame('collection_searchable', $args[0]->getCollectionName()); + self::assertSame('query', $args[1]); + self::assertNull($args[2]); return $args[0]->aggregate(['pipeline']); }), diff --git a/tests/SeederTest.php b/tests/SeederTest.php index a6122ce17..71f36943c 100644 --- a/tests/SeederTest.php +++ b/tests/SeederTest.php @@ -14,6 +14,8 @@ class SeederTest extends TestCase public function tearDown(): void { User::truncate(); + + parent::tearDown(); } public function testSeed(): void diff --git a/tests/Ticket/GH2489Test.php b/tests/Ticket/GH2489Test.php index 62ce11d0e..09fa111ea 100644 --- a/tests/Ticket/GH2489Test.php +++ b/tests/Ticket/GH2489Test.php @@ -13,6 +13,8 @@ class GH2489Test extends TestCase public function tearDown(): void { Location::truncate(); + + parent::tearDown(); } public function testQuerySubdocumentsUsingWhereInId() diff --git a/tests/ValidationTest.php b/tests/ValidationTest.php index d5122ce7b..9d2089af5 100644 --- a/tests/ValidationTest.php +++ b/tests/ValidationTest.php @@ -12,6 +12,8 @@ class ValidationTest extends TestCase public function tearDown(): void { User::truncate(); + + parent::tearDown(); } public function testUnique(): void From 1974aec772fe0a8baefcffb4303032595eb25831 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Tue, 25 Feb 2025 10:26:01 -0500 Subject: [PATCH 426/446] DOCSP-46230: atlas search index mgmt (#3270) * DOCSP-46230: atlas search index mgmt * fix * fix * small fix * wip * wip * wip * wip * test php link * test php link * RM PR fixes 1 * JT suggestion - move code to tests --- docs/eloquent-models/schema-builder.txt | 208 ++++++++++++++++-- docs/fundamentals/atlas-search.txt | 20 +- docs/fundamentals/vector-search.txt | 27 ++- .../schema-builder/galaxies_migration.php | 119 ++++++++++ docs/query-builder.txt | 2 +- 5 files changed, 355 insertions(+), 21 deletions(-) create mode 100644 docs/includes/schema-builder/galaxies_migration.php diff --git a/docs/eloquent-models/schema-builder.txt b/docs/eloquent-models/schema-builder.txt index dad3c8eed..3cdec0f03 100644 --- a/docs/eloquent-models/schema-builder.txt +++ b/docs/eloquent-models/schema-builder.txt @@ -157,10 +157,15 @@ drop various types of indexes on a collection. Create an Index ~~~~~~~~~~~~~~~ -To create indexes, call the ``create()`` method on the ``Schema`` facade -in your migration file. Pass it the collection name and a callback -method with a ``MongoDB\Laravel\Schema\Blueprint`` parameter. Specify the -index creation details on the ``Blueprint`` instance. +To create indexes, perform the following actions: + +1. Call the ``create()`` method on the ``Schema`` facade + in your migration file. + +#. Pass it the collection name and a callback method with a + ``MongoDB\Laravel\Schema\Blueprint`` parameter. + +#. Specify the index creation details on the ``Blueprint`` instance. The following example migration creates indexes on the following collection fields: @@ -262,11 +267,16 @@ indexes: - Unique indexes, which prevent inserting documents that contain duplicate values for the indexed field -To create these index types, call the ``create()`` method on the ``Schema`` facade -in your migration file. Pass ``create()`` the collection name and a callback -method with a ``MongoDB\Laravel\Schema\Blueprint`` parameter. Call the -appropriate helper method on the ``Blueprint`` instance and pass the -index creation details. +To create these index types, perform the following actions: + +1. Call the ``create()`` method on the ``Schema`` facade + in your migration file. + +#. Pass ``create()`` the collection name and a callback method with a + ``MongoDB\Laravel\Schema\Blueprint`` parameter. + +#. Call the appropriate helper method for the index type on the + ``Blueprint`` instance and pass the index creation details. The following migration code shows how to create a sparse and a TTL index by using the index helpers. Click the :guilabel:`{+code-output-label+}` button to see @@ -339,10 +349,16 @@ Create a Geospatial Index In MongoDB, geospatial indexes let you query geospatial coordinate data for inclusion, intersection, and proximity. -To create geospatial indexes, call the ``create()`` method on the ``Schema`` facade -in your migration file. Pass ``create()`` the collection name and a callback -method with a ``MongoDB\Laravel\Schema\Blueprint`` parameter. Specify the -geospatial index creation details on the ``Blueprint`` instance. +To create geospatial indexes, perform the following actions: + +1. Call the ``create()`` method on the ``Schema`` facade + in your migration file. + +#. Pass ``create()`` the collection name and a callback method with a + ``MongoDB\Laravel\Schema\Blueprint`` parameter. + +#. Specify the geospatial index creation details on the ``Blueprint`` + instance. The following example migration creates a ``2d`` and ``2dsphere`` geospatial index on the ``spaceports`` collection. Click the :guilabel:`{+code-output-label+}` @@ -379,11 +395,16 @@ the {+server-docs-name+}. Drop an Index ~~~~~~~~~~~~~ -To drop indexes from a collection, call the ``table()`` method on the -``Schema`` facade in your migration file. Pass it the table name and a -callback method with a ``MongoDB\Laravel\Schema\Blueprint`` parameter. -Call the ``dropIndex()`` method with the index name on the ``Blueprint`` -instance. +To drop indexes from a collection, perform the following actions: + +1. Call the ``table()`` method on the ``Schema`` facade in your + migration file. + +#. Pass it the table name and a callback method with a + ``MongoDB\Laravel\Schema\Blueprint`` parameter. + +#. Call the ``dropIndex()`` method with the index name on the + ``Blueprint`` instance. .. note:: @@ -399,4 +420,155 @@ from the ``flights`` collection: :start-after: begin drop index :end-before: end drop index +.. _laravel-schema-builder-atlas-idx: + +Manage Atlas Search and Vector Search Indexes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In MongoDB, :atlas:`Atlas Search indexes +` support your full-text queries. +:atlas:`Atlas Vector Search indexes +` support similarity +searches that compare query vectors to vector embeddings in your +documents. + +View the following guides to learn more about the Atlas Search and +Vector Search features: + +- :ref:`laravel-atlas-search` guide +- :ref:`laravel-vector-search` guide + +Atlas Search +```````````` + +To create Atlas Search indexes, perform the following actions: + +1. Call the ``create()`` method on the ``Schema`` facade in your + migration file. + +#. Pass ``create()`` the collection name and a callback method with a + ``MongoDB\Laravel\Schema\Blueprint`` parameter. + +#. Pass the Atlas index creation details to the ``searchIndex()`` method + on the ``Blueprint`` instance. + +This example migration creates the following Atlas Search indexes on the +``galaxies`` collection: + +- ``dynamic_index``: Creates dynamic mappings +- ``auto_index``: Supports autocomplete queries on the ``name`` field + +Click the :guilabel:`{+code-output-label+}` button to see the Search +indexes created by running the migration: + +.. io-code-block:: + + .. input:: /includes/schema-builder/galaxies_migration.php + :language: php + :dedent: + :start-after: begin-create-search-indexes + :end-before: end-create-search-indexes + + .. output:: + :language: json + :visible: false + + { + "id": "...", + "name": "dynamic_index", + "type": "search", + "status": "READY", + "queryable": true, + "latestDefinition": { + "mappings": { "dynamic": true } + }, + ... + } + { + "id": "...", + "name": "auto_index", + "type": "search", + "status": "READY", + "queryable": true, + "latestDefinition": { + "mappings": { + "fields": { "name": [ + { "type": "string", "analyzer": "lucene.english" }, + { "type": "autocomplete", "analyzer": "lucene.english" }, + { "type": "token" } + ] } + } + }, + ... + } + +Vector Search +````````````` + +To create Vector Search indexes, perform the following actions: + +1. Call the ``create()`` method on the ``Schema`` facade in your + migration file. + +#. Pass ``create()`` the collection name and a callback method with a + ``MongoDB\Laravel\Schema\Blueprint`` parameter. + +#. Pass the vector index creation details to the ``vectorSearchIndex()`` + method on the ``Blueprint`` instance. + +The following example migration creates a Vector Search index called +``vs_index`` on the ``galaxies`` collection. + +Click the :guilabel:`{+code-output-label+}` button to see the Search +indexes created by running the migration: + +.. io-code-block:: + .. input:: /includes/schema-builder/galaxies_migration.php + :language: php + :dedent: + :start-after: begin-create-vs-index + :end-before: end-create-vs-index + .. output:: + :language: json + :visible: false + + { + "id": "...", + "name": "vs_index", + "type": "vectorSearch", + "status": "READY", + "queryable": true, + "latestDefinition": { + "fields": [ { + "type": "vector", + "numDimensions": 4, + "path": "embeddings", + "similarity": "cosine" + } ] + }, + ... + } + +Drop a Search Index +``````````````````` + +To drop an Atlas Search or Vector Search index from a collection, +perform the following actions: + +1. Call the ``table()`` method on the ``Schema`` facade in your migration file. + +#. Pass it the collection name and a callback method with a + ``MongoDB\Laravel\Schema\Blueprint`` parameter. + +#. Call the ``dropSearchIndex()`` method with the Search index name on + the ``Blueprint`` instance. + +The following example migration drops an index called ``auto_index`` +from the ``galaxies`` collection: + +.. literalinclude:: /includes/schema-builder/galaxies_migration.php + :language: php + :dedent: + :start-after: begin-drop-search-index + :end-before: end-drop-search-index diff --git a/docs/fundamentals/atlas-search.txt b/docs/fundamentals/atlas-search.txt index 9aaa9156b..ab957f9fa 100644 --- a/docs/fundamentals/atlas-search.txt +++ b/docs/fundamentals/atlas-search.txt @@ -56,7 +56,25 @@ documentation. Create an Atlas Search Index ---------------------------- -.. TODO in DOCSP-46230 +You can create an Atlas Search index in either of the following ways: + +- Call the ``create()`` method on the ``Schema`` facade and pass the + ``searchIndex()`` helper method with index creation details. To learn + more about this strategy, see the + :ref:`laravel-schema-builder-atlas-idx` section of the Schema Builder guide. + +- Access a collection, then call the + :phpmethod:`createSearchIndex() ` + method from the {+php-library+}, as shown in the following code: + + .. code-block:: php + + $collection = DB::connection('mongodb')->getCollection('movies'); + + $collection->createSearchIndex( + ['mappings' => ['dynamic' => true]], + ['name' => 'search_index'] + ); Perform Queries --------------- diff --git a/docs/fundamentals/vector-search.txt b/docs/fundamentals/vector-search.txt index 116cb75a0..c06b28320 100644 --- a/docs/fundamentals/vector-search.txt +++ b/docs/fundamentals/vector-search.txt @@ -56,7 +56,32 @@ documentation. Create an Atlas Vector Search Index ----------------------------------- -.. TODO in DOCSP-46230 +You can create an Atlas Search index in either of the following ways: + +- Call the ``create()`` method on the ``Schema`` facade and pass the + ``vectorSearchIndex()`` helper method with index creation details. To learn + more about this strategy, see the + :ref:`laravel-schema-builder-atlas-idx` section of the Schema Builder guide. + +- Access a collection, then call the + :phpmethod:`createSearchIndex() ` + method from the {+php-library+}. You must specify the ``type`` option as + ``'vectorSearch'``, as shown in the following code: + + .. code-block:: php + + $collection = DB::connection('mongodb')->getCollection('movies'); + + $collection->createSearchIndex([ + 'fields' => [ + [ + 'type' => 'vector', + 'numDimensions' => 4, + 'path' => 'embeddings', + 'similarity' => 'cosine' + ], + ], + ], ['name' => 'vector_index', 'type' => 'vectorSearch']); Perform Queries --------------- diff --git a/docs/includes/schema-builder/galaxies_migration.php b/docs/includes/schema-builder/galaxies_migration.php new file mode 100644 index 000000000..fc92ff026 --- /dev/null +++ b/docs/includes/schema-builder/galaxies_migration.php @@ -0,0 +1,119 @@ +searchIndex([ + 'mappings' => [ + 'dynamic' => true, + ], + ], 'dynamic_index'); + $collection->searchIndex([ + 'mappings' => [ + 'fields' => [ + 'name' => [ + ['type' => 'string', 'analyzer' => 'lucene.english'], + ['type' => 'autocomplete', 'analyzer' => 'lucene.english'], + ['type' => 'token'], + ], + ], + ], + ], 'auto_index'); + }); + // end-create-search-indexes + + $index = $this->getSearchIndex('galaxies', 'dynamic_index'); + self::assertNotNull($index); + + self::assertSame('dynamic_index', $index['name']); + self::assertSame('search', $index['type']); + self::assertTrue($index['latestDefinition']['mappings']['dynamic']); + + $index = $this->getSearchIndex('galaxies', 'auto_index'); + self::assertNotNull($index); + + self::assertSame('auto_index', $index['name']); + self::assertSame('search', $index['type']); + } + + public function testVectorSearchIdx(): void + { + // begin-create-vs-index + Schema::create('galaxies', function (Blueprint $collection) { + $collection->vectorSearchIndex([ + 'fields' => [ + [ + 'type' => 'vector', + 'numDimensions' => 4, + 'path' => 'embeddings', + 'similarity' => 'cosine', + ], + ], + ], 'vs_index'); + }); + // end-create-vs-index + + $index = $this->getSearchIndex('galaxies', 'vs_index'); + self::assertNotNull($index); + + self::assertSame('vs_index', $index['name']); + self::assertSame('vectorSearch', $index['type']); + self::assertSame('vector', $index['latestDefinition']['fields'][0]['type']); + } + + public function testDropIndexes(): void + { + // begin-drop-search-index + Schema::table('galaxies', function (Blueprint $collection) { + $collection->dropSearchIndex('auto_index'); + }); + // end-drop-search-index + + Schema::table('galaxies', function (Blueprint $collection) { + $collection->dropSearchIndex('dynamic_index'); + }); + + Schema::table('galaxies', function (Blueprint $collection) { + $collection->dropSearchIndex('vs_index'); + }); + + $index = $this->getSearchIndex('galaxies', 'auto_index'); + self::assertNull($index); + + $index = $this->getSearchIndex('galaxies', 'dynamic_index'); + self::assertNull($index); + + $index = $this->getSearchIndex('galaxies', 'vs_index'); + self::assertNull($index); + } + + protected function getSearchIndex(string $collection, string $name): ?array + { + $collection = $this->getConnection('mongodb')->getCollection($collection); + assert($collection instanceof Collection); + + foreach ($collection->listSearchIndexes(['name' => $name, 'typeMap' => ['root' => 'array', 'array' => 'array', 'document' => 'array']]) as $index) { + return $index; + } + + return null; + } +} diff --git a/docs/query-builder.txt b/docs/query-builder.txt index 89caf8846..76a0d144a 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -678,7 +678,7 @@ a query: :end-before: end options The query builder accepts the same options that you can set for -the :phpmethod:`MongoDB\Collection::find()` method in the +the :phpmethod:`find() ` method in the {+php-library+}. Some of the options to modify query results, such as ``skip``, ``sort``, and ``limit``, are settable directly as query builder methods and are described in the From f10f346dc4d0a0a3fcccda6591dc4f85310b8d78 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Tue, 25 Feb 2025 11:26:01 -0500 Subject: [PATCH 427/446] DOCSP-44554: add more aggregation examples (#3272) * DOCSP-44554: add more agg exs * import model fps * fix formatting * CI errors * language formatting * MW PR fixes 1 * JT small fix --- docs/fundamentals/aggregation-builder.txt | 196 +++++++++++--- .../aggregation/AggregationsBuilderTest.php | 244 +++++++++++++++++- .../fundamentals/aggregation/Inventory.php | 12 + .../fundamentals/aggregation/Order.php | 11 + .../fundamentals/aggregation/Sale.php | 11 + 5 files changed, 420 insertions(+), 54 deletions(-) create mode 100644 docs/includes/fundamentals/aggregation/Inventory.php create mode 100644 docs/includes/fundamentals/aggregation/Order.php create mode 100644 docs/includes/fundamentals/aggregation/Sale.php diff --git a/docs/fundamentals/aggregation-builder.txt b/docs/fundamentals/aggregation-builder.txt index 0dbcd3823..3169acfeb 100644 --- a/docs/fundamentals/aggregation-builder.txt +++ b/docs/fundamentals/aggregation-builder.txt @@ -39,6 +39,7 @@ aggregation builder to create the stages of an aggregation pipeline: - :ref:`laravel-add-aggregation-dependency` - :ref:`laravel-build-aggregation` +- :ref:`laravel-aggregation-examples` - :ref:`laravel-create-custom-operator-factory` .. tip:: @@ -71,12 +72,13 @@ includes the following line in the ``require`` object: .. _laravel-build-aggregation: -Create an Aggregation Pipeline ------------------------------- +Create Aggregation Stages +------------------------- To start an aggregation pipeline, call the ``Model::aggregate()`` method. -Then, chain the aggregation stage methods in the sequence you want them to -run. +Then, chain aggregation stage methods and specify the necessary +parameters for the stage. For example, you can call the ``sort()`` +operator method to build a ``$sort`` stage. The aggregation builder includes the following namespaces that you can import to build aggregation stages: @@ -88,17 +90,17 @@ to build aggregation stages: .. tip:: - To learn more about builder classes, see the `mongodb/mongodb-php-builder `__ + To learn more about builder classes, see the + :github:`mongodb/mongodb-php-builder ` GitHub repository. -This section features the following examples, which show how to use common -aggregation stages and combine stages to build an aggregation pipeline: +This section features the following examples that show how to use common +aggregation stages: - :ref:`laravel-aggregation-match-stage-example` - :ref:`laravel-aggregation-group-stage-example` - :ref:`laravel-aggregation-sort-stage-example` - :ref:`laravel-aggregation-project-stage-example` -- :ref:`laravel-aggregation-pipeline-example` To learn more about MongoDB aggregation operators, see :manual:`Aggregation Stages ` in @@ -112,10 +114,10 @@ by the ``User`` model. You can add the sample data by running the following ``insert()`` method: .. literalinclude:: /includes/fundamentals/aggregation/AggregationsBuilderTest.php - :language: php - :dedent: - :start-after: begin aggregation builder sample data - :end-before: end aggregation builder sample data + :language: php + :dedent: + :start-after: begin aggregation builder sample data + :end-before: end aggregation builder sample data .. _laravel-aggregation-match-stage-example: @@ -151,6 +153,7 @@ Click the :guilabel:`{+code-output-label+}` button to see the documents returned by running the code: .. io-code-block:: + :copyable: true .. input:: /includes/fundamentals/aggregation/AggregationsBuilderTest.php :language: php @@ -226,6 +229,7 @@ Click the :guilabel:`{+code-output-label+}` button to see the documents returned by running the code: .. io-code-block:: + :copyable: true .. input:: /includes/fundamentals/aggregation/AggregationsBuilderTest.php :language: php @@ -270,6 +274,7 @@ alphabetical order. Click the :guilabel:`{+code-output-label+}` button to see the documents returned by running the code: .. io-code-block:: + :copyable: true .. input:: /includes/fundamentals/aggregation/AggregationsBuilderTest.php :language: php @@ -370,6 +375,7 @@ Click the :guilabel:`{+code-output-label+}` button to see the data returned by running the code: .. io-code-block:: + :copyable: true .. input:: /includes/fundamentals/aggregation/AggregationsBuilderTest.php :language: php @@ -390,56 +396,166 @@ running the code: { "name": "Ellis Lee" } ] +.. _laravel-aggregation-examples: -.. _laravel-aggregation-pipeline-example: +Build Aggregation Pipelines +--------------------------- -Aggregation Pipeline Example -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +To build an aggregation pipeline, call the ``Model::aggregate()`` method, +then chain the aggregation stages in the sequence you want them to +run. The examples in this section are adapted from the {+server-docs-name+}. +Each example provides a link to the sample data that you can insert into +your database to test the aggregation operation. + +This section features the following examples, which show how to use common +aggregation stages: -This aggregation pipeline example chains multiple stages. Each stage runs -on the output retrieved from each preceding stage. In this example, the -stages perform the following operations sequentially: +- :ref:`laravel-aggregation-filter-group-example` +- :ref:`laravel-aggregation-unwind-example` +- :ref:`laravel-aggregation-lookup-example` -- Add the ``birth_year`` field to the documents and set the value to the year - extracted from the ``birthday`` field. -- Group the documents by the value of the ``occupation`` field and compute - the average value of ``birth_year`` for each group by using the - ``Accumulator::avg()`` function. Assign the result of the computation to - the ``birth_year_avg`` field. -- Sort the documents by the group key field in ascending order. -- Create the ``profession`` field from the value of the group key field, - include the ``birth_year_avg`` field, and omit the ``_id`` field. +.. _laravel-aggregation-filter-group-example: + +Filter and Group Example +~~~~~~~~~~~~~~~~~~~~~~~~ + +This example uses the sample data given in the :manual:`Calculate Count, +Sum, and Average ` +section of the ``$group`` stage reference in the {+server-docs-name+}. + +The following code example calculates the total sales amount, average +sales quantity, and sale count for each day in the year 2014. To do so, +it uses an aggregation pipeline that contains the following stages: + +1. :manual:`$match ` stage to + filter for documents that contain a ``date`` field in which the year is + 2014 + +#. :manual:`$group ` stage to + group the documents by date and calculate the total sales amount, + average sales quantity, and sale count for each group + +#. :manual:`$sort ` stage to + sort the results by the total sale amount for each group in descending + order Click the :guilabel:`{+code-output-label+}` button to see the data returned by running the code: .. io-code-block:: + :copyable: true .. input:: /includes/fundamentals/aggregation/AggregationsBuilderTest.php :language: php :dedent: - :start-after: begin pipeline example - :end-before: end pipeline example + :start-after: start-builder-match-group + :end-before: end-builder-match-group .. output:: :language: json :visible: false [ - { - "birth_year_avg": 1991.5, - "profession": "designer" - }, - { - "birth_year_avg": 1995.5, - "profession": "engineer" - } + { "_id": "2014-04-04", "totalSaleAmount": { "$numberDecimal": "200" }, "averageQuantity": 15, "count": 2 }, + { "_id": "2014-03-15", "totalSaleAmount": { "$numberDecimal": "50" }, "averageQuantity": 10, "count": 1 }, + { "_id": "2014-03-01", "totalSaleAmount": { "$numberDecimal": "40" }, "averageQuantity": 1.5, "count": 2 } + ] + +.. _laravel-aggregation-unwind-example: + +Unwind Embedded Arrays Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This example uses the sample data given in the :manual:`Unwind Embedded Arrays +` +section of the ``$unwind`` stage reference in the {+server-docs-name+}. + +The following code example groups sold items by their tags and +calculates the total sales amount for each tag. To do so, +it uses an aggregation pipeline that contains the following stages: + +1. :manual:`$unwind ` stage to + output a separate document for each element in the ``items`` array + +#. :manual:`$unwind ` stage to + output a separate document for each element in the ``items.tags`` arrays + +#. :manual:`$group ` stage to + group the documents by the tag value and calculate the total sales + amount of items that have each tag + +Click the :guilabel:`{+code-output-label+}` button to see the data returned by +running the code: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/fundamentals/aggregation/AggregationsBuilderTest.php + :start-after: start-builder-unwind + :end-before: end-builder-unwind + :language: php + :dedent: + + .. output:: + :language: json + :visible: false + + [ + { "_id": "school", "totalSalesAmount": { "$numberDecimal": "104.85" } }, + { "_id": "electronics", "totalSalesAmount": { "$numberDecimal": "800.00" } }, + { "_id": "writing", "totalSalesAmount": { "$numberDecimal": "60.00" } }, + { "_id": "office", "totalSalesAmount": { "$numberDecimal": "1019.60" } }, + { "_id": "stationary", "totalSalesAmount": { "$numberDecimal": "264.45" } } ] -.. note:: +.. _laravel-aggregation-lookup-example: + +Single Equality Join Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This example uses the sample data given in the :manual:`Perform a Single +Equality Join with $lookup +` +section of the ``$lookup`` stage reference in the {+server-docs-name+}. + +The following code example joins the documents from the ``orders`` +collection with the documents from the ``inventory`` collection by using +the ``item`` field from the ``orders`` collection and the ``sku`` field +from the ``inventory`` collection. - Since this pipeline omits the ``match()`` stage, the input for the initial - stage consists of all the documents in the collection. +To do so, the example uses an aggregation pipeline that contains a +:manual:`$lookup ` stage that +specifies the collection to retrieve data from and the local and +foreign field names. + +Click the :guilabel:`{+code-output-label+}` button to see the data returned by +running the code: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/fundamentals/aggregation/AggregationsBuilderTest.php + :start-after: start-builder-lookup + :end-before: end-builder-lookup + :language: php + :dedent: + + .. output:: + :language: json + :visible: false + + [ + { "_id": 1, "item": "almonds", "price": 12, "quantity": 2, "inventory_docs": [ + { "_id": 1, "sku": "almonds", "description": "product 1", "instock": 120 } + ] }, + { "_id": 2, "item": "pecans", "price": 20, "quantity": 1, "inventory_docs": [ + { "_id": 4, "sku": "pecans", "description": "product 4", "instock": 70 } + ] }, + { "_id": 3, "inventory_docs": [ + { "_id": 5, "sku": null, "description": "Incomplete" }, + { "_id": 6 } + ] } + ] .. _laravel-create-custom-operator-factory: diff --git a/docs/includes/fundamentals/aggregation/AggregationsBuilderTest.php b/docs/includes/fundamentals/aggregation/AggregationsBuilderTest.php index 4880ee75f..49f7d5c8f 100644 --- a/docs/includes/fundamentals/aggregation/AggregationsBuilderTest.php +++ b/docs/includes/fundamentals/aggregation/AggregationsBuilderTest.php @@ -4,7 +4,11 @@ namespace App\Http\Controllers; +use App\Models\Inventory; +use App\Models\Order; +use App\Models\Sale; use DateTimeImmutable; +use MongoDB\BSON\Decimal128; use MongoDB\BSON\UTCDateTime; use MongoDB\Builder\Accumulator; use MongoDB\Builder\Expression; @@ -18,6 +22,10 @@ class AggregationsBuilderTest extends TestCase { protected function setUp(): void { + require_once __DIR__ . '/Sale.php'; + require_once __DIR__ . '/Order.php'; + require_once __DIR__ . '/Inventory.php'; + parent::setUp(); User::truncate(); @@ -84,27 +92,235 @@ public function testAggregationBuilderProjectStage(): void $this->assertArrayNotHasKey('_id', $result->first()); } - public function testAggregationBuilderPipeline(): void + public function testAggregationBuilderMatchGroup(): void { - // begin pipeline example - $pipeline = User::aggregate() - ->addFields( - birth_year: Expression::year( - Expression::dateFieldPath('birthday'), - ), + Sale::truncate(); + + Sale::insert([ + [ + '_id' => 1, + 'item' => 'abc', + 'price' => new Decimal128('10'), + 'quantity' => 2, + 'date' => new UTCDateTime(new DateTimeImmutable('2014-03-01T08:00:00Z')), + ], + [ + '_id' => 2, + 'item' => 'jkl', + 'price' => new Decimal128('20'), + 'quantity' => 1, + 'date' => new UTCDateTime(new DateTimeImmutable('2014-03-01T09:00:00Z')), + ], + [ + '_id' => 3, + 'item' => 'xyz', + 'price' => new Decimal128('5'), + 'quantity' => 10, + 'date' => new UTCDateTime(new DateTimeImmutable('2014-03-15T09:00:00Z')), + ], + [ + '_id' => 4, + 'item' => 'xyz', + 'price' => new Decimal128('5'), + 'quantity' => 20, + 'date' => new UTCDateTime(new DateTimeImmutable('2014-04-04T11:21:39.736Z')), + ], + [ + '_id' => 5, + 'item' => 'abc', + 'price' => new Decimal128('10'), + 'quantity' => 10, + 'date' => new UTCDateTime(new DateTimeImmutable('2014-04-04T21:23:13.331Z')), + ], + [ + '_id' => 6, + 'item' => 'def', + 'price' => new Decimal128('7.5'), + 'quantity' => 5, + 'date' => new UTCDateTime(new DateTimeImmutable('2015-06-04T05:08:13Z')), + ], + [ + '_id' => 7, + 'item' => 'def', + 'price' => new Decimal128('7.5'), + 'quantity' => 10, + 'date' => new UTCDateTime(new DateTimeImmutable('2015-09-10T08:43:00Z')), + ], + [ + '_id' => 8, + 'item' => 'abc', + 'price' => new Decimal128('10'), + 'quantity' => 5, + 'date' => new UTCDateTime(new DateTimeImmutable('2016-02-06T20:20:13Z')), + ], + ]); + + // start-builder-match-group + $pipeline = Sale::aggregate() + ->match( + date: [ + Query::gte(new UTCDateTime(new DateTimeImmutable('2014-01-01'))), + Query::lt(new UTCDateTime(new DateTimeImmutable('2015-01-01'))), + ], ) ->group( - _id: Expression::fieldPath('occupation'), - birth_year_avg: Accumulator::avg(Expression::numberFieldPath('birth_year')), + _id: Expression::dateToString(Expression::dateFieldPath('date'), '%Y-%m-%d'), + totalSaleAmount: Accumulator::sum( + Expression::multiply( + Expression::numberFieldPath('price'), + Expression::numberFieldPath('quantity'), + ), + ), + averageQuantity: Accumulator::avg( + Expression::numberFieldPath('quantity'), + ), + count: Accumulator::sum(1), ) - ->sort(_id: Sort::Asc) - ->project(profession: Expression::fieldPath('_id'), birth_year_avg: 1, _id: 0); - // end pipeline example + ->sort( + totalSaleAmount: Sort::Desc, + ); + // end-builder-match-group $result = $pipeline->get(); - $this->assertEquals(2, $result->count()); - $this->assertNotNull($result->first()['birth_year_avg']); + $this->assertEquals(3, $result->count()); + $this->assertNotNull($result->first()['totalSaleAmount']); + } + + public function testAggregationBuilderUnwind(): void + { + Sale::truncate(); + + Sale::insert([ + [ + '_id' => '1', + 'items' => [ + [ + 'name' => 'pens', + 'tags' => ['writing', 'office', 'school', 'stationary'], + 'price' => new Decimal128('12.00'), + 'quantity' => 5, + ], + [ + 'name' => 'envelopes', + 'tags' => ['stationary', 'office'], + 'price' => new Decimal128('19.95'), + 'quantity' => 8, + ], + ], + ], + [ + '_id' => '2', + 'items' => [ + [ + 'name' => 'laptop', + 'tags' => ['office', 'electronics'], + 'price' => new Decimal128('800.00'), + 'quantity' => 1, + ], + [ + 'name' => 'notepad', + 'tags' => ['stationary', 'school'], + 'price' => new Decimal128('14.95'), + 'quantity' => 3, + ], + ], + ], + ]); + + // start-builder-unwind + $pipeline = Sale::aggregate() + ->unwind(Expression::arrayFieldPath('items')) + ->unwind(Expression::arrayFieldPath('items.tags')) + ->group( + _id: Expression::fieldPath('items.tags'), + totalSalesAmount: Accumulator::sum( + Expression::multiply( + Expression::numberFieldPath('items.price'), + Expression::numberFieldPath('items.quantity'), + ), + ), + ); + // end-builder-unwind + + $result = $pipeline->get(); + + $this->assertEquals(5, $result->count()); + $this->assertNotNull($result->first()['totalSalesAmount']); + } + + public function testAggregationBuilderLookup(): void + { + Order::truncate(); + Inventory::truncate(); + + Order::insert([ + [ + '_id' => 1, + 'item' => 'almonds', + 'price' => 12, + 'quantity' => 2, + ], + [ + '_id' => 2, + 'item' => 'pecans', + 'price' => 20, + 'quantity' => 1, + ], + [ + '_id' => 3, + ], + ]); + + Inventory::insert([ + [ + '_id' => 1, + 'sku' => 'almonds', + 'description' => 'product 1', + 'instock' => 120, + ], + [ + '_id' => 2, + 'sku' => 'bread', + 'description' => 'product 2', + 'instock' => 80, + ], + [ + '_id' => 3, + 'sku' => 'cashews', + 'description' => 'product 3', + 'instock' => 60, + ], + [ + '_id' => 4, + 'sku' => 'pecans', + 'description' => 'product 4', + 'instock' => 70, + ], + [ + '_id' => 5, + 'sku' => null, + 'description' => 'Incomplete', + ], + [ + '_id' => 6, + ], + ]); + + // start-builder-lookup + $pipeline = Order::aggregate() + ->lookup( + from: 'inventory', + localField: 'item', + foreignField: 'sku', + as: 'inventory_docs', + ); + // end-builder-lookup + + $result = $pipeline->get(); + + $this->assertEquals(3, $result->count()); + $this->assertNotNull($result->first()['item']); } // phpcs:disable Squiz.Commenting.FunctionComment.WrongStyle diff --git a/docs/includes/fundamentals/aggregation/Inventory.php b/docs/includes/fundamentals/aggregation/Inventory.php new file mode 100644 index 000000000..e1cdc7be1 --- /dev/null +++ b/docs/includes/fundamentals/aggregation/Inventory.php @@ -0,0 +1,12 @@ + Date: Wed, 26 Feb 2025 16:42:08 +0100 Subject: [PATCH 428/446] PHPORM-278 Introduce `Connection::getDatabase()` and `getClient` (#3289) Deprecate getMongoDB and get MongoClient Replace selectDatabase with getDatabase --- src/Concerns/ManagesTransactions.php | 11 ++++--- src/Connection.php | 42 ++++++++++++++++++++----- src/MongoDBServiceProvider.php | 8 ++--- src/Schema/Blueprint.php | 2 +- src/Schema/Builder.php | 14 ++++----- tests/ConnectionTest.php | 47 +++++++++++++++++++++++++--- 6 files changed, 96 insertions(+), 28 deletions(-) diff --git a/src/Concerns/ManagesTransactions.php b/src/Concerns/ManagesTransactions.php index ac3c1c6f7..6403cc45d 100644 --- a/src/Concerns/ManagesTransactions.php +++ b/src/Concerns/ManagesTransactions.php @@ -12,15 +12,18 @@ use function MongoDB\with_transaction; -/** @see https://docs.mongodb.com/manual/core/transactions/ */ +/** + * @internal + * + * @see https://docs.mongodb.com/manual/core/transactions/ + */ trait ManagesTransactions { protected ?Session $session = null; protected $transactions = 0; - /** @return Client */ - abstract public function getMongoClient(); + abstract public function getClient(): ?Client; public function getSession(): ?Session { @@ -30,7 +33,7 @@ public function getSession(): ?Session private function getSessionOrCreate(): Session { if ($this->session === null) { - $this->session = $this->getMongoClient()->startSession(); + $this->session = $this->getClient()->startSession(); } return $this->session; diff --git a/src/Connection.php b/src/Connection.php index 592e500e5..980750093 100644 --- a/src/Connection.php +++ b/src/Connection.php @@ -22,8 +22,11 @@ use function implode; use function is_array; use function preg_match; +use function sprintf; use function str_contains; +use function trigger_error; +use const E_USER_DEPRECATED; use const FILTER_FLAG_IPV6; use const FILTER_VALIDATE_IP; @@ -65,9 +68,10 @@ public function __construct(array $config) // Create the connection $this->connection = $this->createConnection($dsn, $config, $options); + $this->database = $this->getDefaultDatabaseName($dsn, $config); // Select database - $this->db = $this->connection->selectDatabase($this->getDefaultDatabaseName($dsn, $config)); + $this->db = $this->connection->getDatabase($this->database); $this->tablePrefix = $config['prefix'] ?? ''; @@ -114,29 +118,53 @@ public function getSchemaBuilder() /** * Get the MongoDB database object. * + * @deprecated since mongodb/laravel-mongodb:5.2, use getDatabase() instead + * * @return Database */ public function getMongoDB() { + trigger_error(sprintf('Since mongodb/laravel-mongodb:5.2, Method "%s()" is deprecated, use "getDatabase()" instead.', __FUNCTION__), E_USER_DEPRECATED); + + return $this->db; + } + + /** + * Get the MongoDB database object. + * + * @param string|null $name Name of the database, if not provided the default database will be returned. + * + * @return Database + */ + public function getDatabase(?string $name = null): Database + { + if ($name && $name !== $this->database) { + return $this->connection->getDatabase($name); + } + return $this->db; } /** - * return MongoDB object. + * Return MongoDB object. + * + * @deprecated since mongodb/laravel-mongodb:5.2, use getClient() instead * * @return Client */ public function getMongoClient() { - return $this->connection; + trigger_error(sprintf('Since mongodb/laravel-mongodb:5.2, method "%s()" is deprecated, use "getClient()" instead.', __FUNCTION__), E_USER_DEPRECATED); + + return $this->getClient(); } /** - * {@inheritDoc} + * Get the MongoDB client. */ - public function getDatabaseName() + public function getClient(): ?Client { - return $this->getMongoDB()->getDatabaseName(); + return $this->connection; } public function enableQueryLog() @@ -233,7 +261,7 @@ protected function createConnection(string $dsn, array $config, array $options): */ public function ping(): void { - $this->getMongoClient()->getManager()->selectServer(new ReadPreference(ReadPreference::PRIMARY_PREFERRED)); + $this->getClient()->getManager()->selectServer(new ReadPreference(ReadPreference::PRIMARY_PREFERRED)); } /** @inheritdoc */ diff --git a/src/MongoDBServiceProvider.php b/src/MongoDBServiceProvider.php index dc9caf082..349abadc7 100644 --- a/src/MongoDBServiceProvider.php +++ b/src/MongoDBServiceProvider.php @@ -67,7 +67,7 @@ public function register() assert($connection instanceof Connection, new InvalidArgumentException(sprintf('The database connection "%s" used for the session does not use the "mongodb" driver.', $connectionName))); return new MongoDbSessionHandler( - $connection->getMongoClient(), + $connection->getClient(), $app->config->get('session.options', []) + [ 'database' => $connection->getDatabaseName(), 'collection' => $app->config->get('session.table') ?: 'sessions', @@ -132,8 +132,8 @@ private function registerFlysystemAdapter(): void throw new InvalidArgumentException(sprintf('The database connection "%s" does not use the "mongodb" driver.', $config['connection'] ?? $app['config']['database.default'])); } - $bucket = $connection->getMongoClient() - ->selectDatabase($config['database'] ?? $connection->getDatabaseName()) + $bucket = $connection->getClient() + ->getDatabase($config['database'] ?? $connection->getDatabaseName()) ->selectGridFSBucket(['bucketName' => $config['bucket'] ?? 'fs', 'disableMD5' => true]); } @@ -171,7 +171,7 @@ private function registerScoutEngine(): void assert($connection instanceof Connection, new InvalidArgumentException(sprintf('The connection "%s" is not a MongoDB connection.', $connectionName))); - return new ScoutEngine($connection->getMongoDB(), $softDelete, $indexDefinitions); + return new ScoutEngine($connection->getDatabase(), $softDelete, $indexDefinitions); }); return $engineManager; diff --git a/src/Schema/Blueprint.php b/src/Schema/Blueprint.php index e3d7a230b..a525a9cee 100644 --- a/src/Schema/Blueprint.php +++ b/src/Schema/Blueprint.php @@ -251,7 +251,7 @@ public function create($options = []) { $collection = $this->collection->getCollectionName(); - $db = $this->connection->getMongoDB(); + $db = $this->connection->getDatabase(); // Ensure the collection is created. $db->createCollection($collection, $options); diff --git a/src/Schema/Builder.php b/src/Schema/Builder.php index fe806f0e5..4af15f1f9 100644 --- a/src/Schema/Builder.php +++ b/src/Schema/Builder.php @@ -76,7 +76,7 @@ public function hasColumns($table, array $columns): bool */ public function hasCollection($name) { - $db = $this->connection->getMongoDB(); + $db = $this->connection->getDatabase(); $collections = iterator_to_array($db->listCollections([ 'filter' => ['name' => $name], @@ -139,7 +139,7 @@ public function dropAllTables() public function getTables() { - $db = $this->connection->getMongoDB(); + $db = $this->connection->getDatabase(); $collections = []; foreach ($db->listCollectionNames() as $collectionName) { @@ -167,7 +167,7 @@ public function getTables() public function getTableListing() { - $collections = iterator_to_array($this->connection->getMongoDB()->listCollectionNames()); + $collections = iterator_to_array($this->connection->getDatabase()->listCollectionNames()); sort($collections); @@ -176,7 +176,7 @@ public function getTableListing() public function getColumns($table) { - $stats = $this->connection->getMongoDB()->selectCollection($table)->aggregate([ + $stats = $this->connection->getDatabase()->selectCollection($table)->aggregate([ // Sample 1,000 documents to get a representative sample of the collection ['$sample' => ['size' => 1_000]], // Convert each document to an array of fields @@ -229,7 +229,7 @@ public function getColumns($table) public function getIndexes($table) { - $collection = $this->connection->getMongoDB()->selectCollection($table); + $collection = $this->connection->getDatabase()->selectCollection($table); assert($collection instanceof Collection); $indexList = []; @@ -301,7 +301,7 @@ protected function createBlueprint($table, ?Closure $callback = null) */ public function getCollection($name) { - $db = $this->connection->getMongoDB(); + $db = $this->connection->getDatabase(); $collections = iterator_to_array($db->listCollections([ 'filter' => ['name' => $name], @@ -318,7 +318,7 @@ public function getCollection($name) protected function getAllCollections() { $collections = []; - foreach ($this->connection->getMongoDB()->listCollections() as $collection) { + foreach ($this->connection->getDatabase()->listCollections() as $collection) { $collections[] = $collection->getName(); } diff --git a/tests/ConnectionTest.php b/tests/ConnectionTest.php index 1efd17be0..ba5e09804 100644 --- a/tests/ConnectionTest.php +++ b/tests/ConnectionTest.php @@ -48,15 +48,15 @@ public function testDisconnectAndCreateNewConnection() { $connection = DB::connection('mongodb'); $this->assertInstanceOf(Connection::class, $connection); - $client = $connection->getMongoClient(); + $client = $connection->getClient(); $this->assertInstanceOf(Client::class, $client); $connection->disconnect(); - $client = $connection->getMongoClient(); + $client = $connection->getClient(); $this->assertNull($client); DB::purge('mongodb'); $connection = DB::connection('mongodb'); $this->assertInstanceOf(Connection::class, $connection); - $client = $connection->getMongoClient(); + $client = $connection->getClient(); $this->assertInstanceOf(Client::class, $client); } @@ -64,7 +64,7 @@ public function testDb() { $connection = DB::connection('mongodb'); $this->assertInstanceOf(Database::class, $connection->getMongoDB()); - $this->assertInstanceOf(Client::class, $connection->getMongoClient()); + $this->assertInstanceOf(Client::class, $connection->getClient()); } public static function dataConnectionConfig(): Generator @@ -196,7 +196,7 @@ public static function dataConnectionConfig(): Generator public function testConnectionConfig(string $expectedUri, string $expectedDatabaseName, array $config): void { $connection = new Connection($config); - $client = $connection->getMongoClient(); + $client = $connection->getClient(); $this->assertSame($expectedUri, (string) $client); $this->assertSame($expectedDatabaseName, $connection->getMongoDB()->getDatabaseName()); @@ -204,6 +204,43 @@ public function testConnectionConfig(string $expectedUri, string $expectedDataba $this->assertSame('foo', $connection->table('foo')->raw()->getCollectionName()); } + public function testLegacyGetMongoClient(): void + { + $connection = DB::connection('mongodb'); + $expected = $connection->getClient(); + + $this->assertSame($expected, $connection->getMongoClient()); + } + + public function testLegacyGetMongoDB(): void + { + $connection = DB::connection('mongodb'); + $expected = $connection->getDatabase(); + + $this->assertSame($expected, $connection->getMongoDB()); + } + + public function testGetDatabase(): void + { + $connection = DB::connection('mongodb'); + $defaultName = env('MONGODB_DATABASE', 'unittest'); + $database = $connection->getDatabase(); + + $this->assertInstanceOf(Database::class, $database); + $this->assertSame($defaultName, $database->getDatabaseName()); + $this->assertSame($database, $connection->getDatabase($defaultName), 'Same instance for the default database'); + } + + public function testGetOtherDatabase(): void + { + $connection = DB::connection('mongodb'); + $name = 'other_random_database'; + $database = $connection->getDatabase($name); + + $this->assertInstanceOf(Database::class, $database); + $this->assertSame($name, $database->getDatabaseName($name)); + } + public function testConnectionWithoutConfiguredDatabase(): void { $this->expectException(InvalidArgumentException::class); From 5f877df763cdbd2a3aeed04954f3c85fa0692c7f Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Thu, 27 Feb 2025 11:37:52 -0500 Subject: [PATCH 429/446] Rename Connection::getMongoDB to getDatabase --- docs/database-collection.txt | 2 +- docs/filesystems.txt | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/database-collection.txt b/docs/database-collection.txt index fb6573147..d42a0d52a 100644 --- a/docs/database-collection.txt +++ b/docs/database-collection.txt @@ -225,7 +225,7 @@ the collections in the database: .. code-block:: php - $collections = DB::connection('mongodb')->getMongoDB()->listCollections(); + $collections = DB::connection('mongodb')->getDatabase()->listCollections(); List Collection Fields ---------------------- diff --git a/docs/filesystems.txt b/docs/filesystems.txt index 725b799af..3ec7ee41f 100644 --- a/docs/filesystems.txt +++ b/docs/filesystems.txt @@ -94,7 +94,7 @@ In this case, the options ``connection`` and ``database`` are ignored: 'driver' => 'gridfs', 'bucket' => static function (Application $app): Bucket { return $app['db']->connection('mongodb') - ->getMongoDB() + ->getDatabase() ->selectGridFSBucket([ 'bucketName' => 'avatars', 'chunkSizeBytes' => 261120, @@ -150,7 +150,7 @@ if you need to work with revisions, as shown in the following code: // Create a bucket service from the MongoDB connection /** @var \MongoDB\GridFS\Bucket $bucket */ - $bucket = $app['db']->connection('mongodb')->getMongoDB()->selectGridFSBucket(); + $bucket = $app['db']->connection('mongodb')->getDatabase()->selectGridFSBucket(); // Download the last but one version of a file $bucket->openDownloadStreamByName('hello.txt', ['revision' => -2]) From 4891b5b16ad7f19e9565152b6d5e412f94c74600 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Thu, 27 Feb 2025 13:55:54 -0500 Subject: [PATCH 430/446] Jerome suggestion --- docs/database-collection.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/database-collection.txt b/docs/database-collection.txt index d42a0d52a..be081c97b 100644 --- a/docs/database-collection.txt +++ b/docs/database-collection.txt @@ -219,7 +219,7 @@ methods in your application: Example ``````` -The following example accesses a database connection, then calls the +The following example accesses the database of the connection, then calls the ``listCollections()`` query builder method to retrieve information about the collections in the database: From 28f22c8702fdcd111fa33b2914be52409d0c6468 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Fri, 28 Feb 2025 10:43:29 -0500 Subject: [PATCH 431/446] DOCSP-35945: read operations reorg (#3293) * DOCSP-35945: read operations reorg * skip * small fixes * small fixes * fixes - RM and moved a section --- docs/fundamentals/read-operations.txt | 636 +++--------------- .../read-operations/modify-results.txt | 227 +++++++ .../fundamentals/read-operations/retrieve.txt | 304 +++++++++ .../read-operations/search-text.txt | 157 +++++ docs/fundamentals/write-operations.txt | 3 +- .../before-you-get-started.rst | 15 + 6 files changed, 808 insertions(+), 534 deletions(-) create mode 100644 docs/fundamentals/read-operations/modify-results.txt create mode 100644 docs/fundamentals/read-operations/retrieve.txt create mode 100644 docs/fundamentals/read-operations/search-text.txt create mode 100644 docs/includes/fundamentals/read-operations/before-you-get-started.rst diff --git a/docs/fundamentals/read-operations.txt b/docs/fundamentals/read-operations.txt index d5605033b..303e53a3e 100644 --- a/docs/fundamentals/read-operations.txt +++ b/docs/fundamentals/read-operations.txt @@ -10,7 +10,13 @@ Read Operations :values: tutorial .. meta:: - :keywords: find one, find many, code example + :keywords: find one, find many, skip, limit, paginate, string, code example + +.. toctree:: + + Retrieve Data + Search Text + Modify Query Results .. contents:: On this page :local: @@ -21,588 +27,154 @@ Read Operations Overview -------- -In this guide, you can learn how to use {+odm-long+} to perform **find operations** -on your MongoDB collections. Find operations allow you to retrieve documents based on -criteria that you specify. - -This guide shows you how to perform the following tasks: - -- :ref:`laravel-retrieve-matching` -- :ref:`laravel-retrieve-all` -- :ref:`laravel-retrieve-text-search` -- :ref:`Modify Find Operation Behavior ` - -Before You Get Started ----------------------- - -To run the code examples in this guide, complete the :ref:`Quick Start ` -tutorial. This tutorial provides instructions on setting up a MongoDB Atlas instance with -sample data and creating the following files in your Laravel web application: - -- ``Movie.php`` file, which contains a ``Movie`` model to represent documents in the ``movies`` - collection -- ``MovieController.php`` file, which contains a ``show()`` function to run database operations -- ``browse_movies.blade.php`` file, which contains HTML code to display the results of database - operations - -The following sections describe how to edit the files in your Laravel application to run -the find operation code examples and view the expected output. - -.. _laravel-retrieve-matching: - -Retrieve Documents that Match a Query -------------------------------------- - -You can use Laravel's Eloquent object-relational mapper (ORM) to create models -that represent MongoDB collections and chain methods on them to specify -query criteria. - -To retrieve documents that match a set of criteria, call the ``where()`` -method on the collection's corresponding Eloquent model, then pass a query -filter to the method. - -A query filter specifies field value requirements and instructs the find -operation to return only documents that meet these requirements. - -You can use one of the following ``where()`` method calls to build a query: - -- ``where('', )`` builds a query that matches documents in - which the target field has the exact specified value - -- ``where('', '', )`` builds a query - that matches documents in which the target field's value meets the comparison - criteria - -To apply multiple sets of criteria to the find operation, you can chain a series -of ``where()`` methods together. - -After building your query by using the ``where()`` method, chain the ``get()`` -method to retrieve the query results. - -This example calls two ``where()`` methods on the ``Movie`` Eloquent model to -retrieve documents that meet the following criteria: - -- ``year`` field has a value of ``2010`` -- ``imdb.rating`` nested field has a value greater than ``8.5`` - -.. tabs:: - - .. tab:: Query Syntax - :tabid: query-syntax - - Use the following syntax to specify the query: - - .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php - :language: php - :dedent: - :start-after: start-query - :end-before: end-query - - .. tab:: Controller Method - :tabid: controller - - To see the query results in the ``browse_movies`` view, edit the ``show()`` function - in the ``MovieController.php`` file to resemble the following code: - - .. io-code-block:: - :copyable: true - - .. input:: - :language: php - - class MovieController - { - public function show() - { - $movies = Movie::where('year', 2010) - ->where('imdb.rating', '>', 8.5) - ->get(); - - return view('browse_movies', [ - 'movies' => $movies - ]); - } - } - - .. output:: - :language: none - :visible: false - - Title: Inception - Year: 2010 - Runtime: 148 - IMDB Rating: 8.8 - IMDB Votes: 1294646 - Plot: A thief who steals corporate secrets through use of dream-sharing - technology is given the inverse task of planting an idea into the mind of a CEO. - - Title: Senna - Year: 2010 - Runtime: 106 - IMDB Rating: 8.6 - IMDB Votes: 41904 - Plot: A documentary on Brazilian Formula One racing driver Ayrton Senna, who won the - F1 world championship three times before his death at age 34. - -To learn how to query by using the Laravel query builder instead of the -Eloquent ORM, see the :ref:`laravel-query-builder` page. - -Match Array Field Elements -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can specify a query filter to match array field elements when -retrieving documents. If your documents contain an array field, you can -match documents based on if the value contains all or some specified -array elements. - -You can use one of the following ``where()`` method calls to build a -query on an array field: +In this guide, you can see code templates of common +methods that you can use to read data from MongoDB by using +{+odm-long+}. -- ``where('', )`` builds a query that matches documents in - which the array field value is exactly the specified array - -- ``where('', 'in', )`` builds a query - that matches documents in which the array field value contains one or - more of the specified array elements - -After building your query by using the ``where()`` method, chain the ``get()`` -method to retrieve the query results. - -Select from the following :guilabel:`Exact Array Match` and -:guilabel:`Element Match` tabs to view the query syntax for each pattern: - -.. tabs:: - - .. tab:: Exact Array Match - :tabid: exact-array - - This example retrieves documents in which the ``countries`` array is - exactly ``['Indonesia', 'Canada']``: - - .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php - :language: php - :dedent: - :start-after: start-exact-array - :end-before: end-exact-array - - .. tab:: Element Match - :tabid: element-match - - This example retrieves documents in which the ``countries`` array - contains one of the values in the array ``['Canada', 'Egypt']``: - - .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php - :language: php - :dedent: - :start-after: start-elem-match - :end-before: end-elem-match - -To learn how to query array fields by using the Laravel query builder instead of the -Eloquent ORM, see the :ref:`laravel-query-builder-elemMatch` section in -the Query Builder guide. - -.. _laravel-retrieve-all: +.. tip:: -Retrieve All Documents in a Collection --------------------------------------- + To learn more about any of the methods included in this guide, + see the links provided in each section. -You can retrieve all documents in a collection by omitting the query filter. -To return the documents, call the ``get()`` method on an Eloquent model that -represents your collection. Alternatively, you can use the ``get()`` method's -alias ``all()`` to perform the same operation. +Find One +-------- -Use the following syntax to run a find operation that matches all documents: +The following code shows how to retrieve the first matching document +from a collection: .. code-block:: php - $movies = Movie::get(); - -.. warning:: - - The ``movies`` collection in the Atlas sample dataset contains a large amount of data. - Retrieving and displaying all documents in this collection might cause your web - application to time out. - - To avoid this issue, specify a document limit by using the ``take()`` method. For - more information about ``take()``, see the :ref:`laravel-modify-find` section of this - guide. - -.. _laravel-retrieve-text-search: - -Search Text Fields ------------------- + SampleModel::where('', '') + ->first(); -A text search retrieves documents that contain a **term** or a **phrase** in the -text-indexed fields. A term is a sequence of characters that excludes -whitespace characters. A phrase is a sequence of terms with any number -of whitespace characters. +To view a runnable example that finds one document, see the +:ref:`laravel-find-one-usage` usage example. -.. note:: +To learn more about retrieving documents and the ``first()`` method, see +the :ref:`laravel-fundamentals-read-retrieve` guide. - Before you can perform a text search, you must create a :manual:`text - index ` on - the text-valued field. To learn more about creating - indexes, see the :ref:`laravel-eloquent-indexes` section of the - Schema Builder guide. +Find Multiple +------------- -You can perform a text search by using the :manual:`$text -` operator followed -by the ``$search`` field in your query filter that you pass to the -``where()`` method. The ``$text`` operator performs a text search on the -text-indexed fields. The ``$search`` field specifies the text to search for. +The following code shows how to retrieve all documents that match a +query filter from a collection: -After building your query by using the ``where()`` method, chain the ``get()`` -method to retrieve the query results. - -This example calls the ``where()`` method on the ``Movie`` Eloquent model to -retrieve documents in which the ``plot`` field contains the phrase -``"love story"``. To perform this text search, the collection must have -a text index on the ``plot`` field. - -.. tabs:: - - .. tab:: Query Syntax - :tabid: query-syntax +.. code-block:: php - Use the following syntax to specify the query: + SampleModel::where('', '') + ->get(); - .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php - :language: php - :dedent: - :start-after: start-text - :end-before: end-text +To view a runnable example that finds documents, see the +:ref:`laravel-find-usage` usage example. - .. tab:: Controller Method - :tabid: controller +To learn more about retrieving documents, see the +:ref:`laravel-fundamentals-read-retrieve` guide. - To see the query results in the ``browse_movies`` view, edit the ``show()`` function - in the ``MovieController.php`` file to resemble the following code: +Return All Documents +-------------------- - .. io-code-block:: - :copyable: true +The following code shows how to retrieve all documents from a +collection: - .. input:: - :language: php +.. code-block:: php - class MovieController - { - public function show() - { - $movies = Movie::where('$text', ['$search' => '"love story"']) - ->get(); + SampleModel::get(); - return view('browse_movies', [ - 'movies' => $movies - ]); - } - } + // Or, use the all() method. + SampleModel::all(); - .. output:: - :language: none - :visible: false +To view a runnable example that finds documents, see the +:ref:`laravel-find-usage` usage example. - Title: Cafè de Flore - Year: 2011 - Runtime: 120 - IMDB Rating: 7.4 - IMDB Votes: 9663 - Plot: A love story between a man and woman ... +To learn more about retrieving documents, see the +:ref:`laravel-fundamentals-read-retrieve` guide. - Title: Paheli - Year: 2005 - Runtime: 140 - IMDB Rating: 6.7 - IMDB Votes: 8909 - Plot: A folk tale - supernatural love story about a ghost ... +Search Text +----------- - Title: Por un puèado de besos - Year: 2014 - Runtime: 98 - IMDB Rating: 6.1 - IMDB Votes: 223 - Plot: A girl. A boy. A love story ... - - ... - -A text search assigns a numerical :manual:`text score ` to indicate how closely -each result matches the string in your query filter. You can sort the -results by relevance by using the ``orderBy()`` method to sort on the -``textScore`` metadata field. You can access this metadata by using the -:manual:`$meta ` operator: - -.. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php - :language: php - :dedent: - :start-after: start-text-relevance - :end-before: end-text-relevance - :emphasize-lines: 2 +The following code shows how to perform a full-text search on a string +field in a collection's documents: -.. tip:: +.. code-block:: php - To learn more about the ``orderBy()`` method, see the - :ref:`laravel-sort` section of this guide. + SampleModel::where('$text', ['$search' => '']) + ->get(); -.. _laravel-modify-find: +To learn more about searching on text fields, see the +:ref:`laravel-retrieve-text-search` guide. -Modify Behavior +Count Documents --------------- -You can modify the results of a find operation by chaining more methods -to ``where()``. - -The following sections demonstrate how to modify the behavior of the ``where()`` -method: - -- :ref:`laravel-skip-limit` uses the ``skip()`` method to set the number of documents - to skip and the ``take()`` method to set the total number of documents to return -- :ref:`laravel-sort` uses the ``orderBy()`` method to return query - results in a specified order based on field values -- :ref:`laravel-retrieve-one` uses the ``first()`` method to return the first document - that matches the query filter - -.. _laravel-skip-limit: - -Skip and Limit Results -~~~~~~~~~~~~~~~~~~~~~~ - -This example queries for documents in which the ``year`` value is ``1999``. -The operation skips the first ``2`` matching documents and outputs a total of ``3`` -documents. - -.. tabs:: - - .. tab:: Query Syntax - :tabid: query-syntax - - Use the following syntax to specify the query: +The following code shows how to count documents in a collection: - .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php - :language: php - :dedent: - :start-after: start-skip-limit - :end-before: end-skip-limit - - .. tab:: Controller Method - :tabid: controller +.. code-block:: php - To see the query results in the ``browse_movies`` view, edit the ``show()`` function - in the ``MovieController.php`` file to resemble the following code: + SampleModel::count(); - .. io-code-block:: - :copyable: true - - .. input:: - :language: php - - class MovieController - { - public function show() - { - $movies = Movie::where('year', 1999) - ->skip(2) - ->take(3) - ->get(); - - return view('browse_movies', [ - 'movies' => $movies - ]); - } - } - - .. output:: - :language: none - :visible: false - - Title: Three Kings - Year: 1999 - Runtime: 114 - IMDB Rating: 7.2 - IMDB Votes: 130677 - Plot: In the aftermath of the Persian Gulf War, 4 soldiers set out to steal gold - that was stolen from Kuwait, but they discover people who desperately need their help. - - Title: Toy Story 2 - Year: 1999 - Runtime: 92 - IMDB Rating: 7.9 - IMDB Votes: 346655 - Plot: When Woody is stolen by a toy collector, Buzz and his friends vow to rescue him, - but Woody finds the idea of immortality in a museum tempting. - - Title: Beowulf - Year: 1999 - Runtime: 95 - IMDB Rating: 4 - IMDB Votes: 9296 - Plot: A sci-fi update of the famous 6th Century poem. In a besieged land, Beowulf must - battle against the hideous creature Grendel and his vengeance seeking mother. - -.. _laravel-sort: - -Sort Query Results -~~~~~~~~~~~~~~~~~~ - -To order query results based on the values of specified fields, use the ``where()`` method -followed by the ``orderBy()`` method. - -You can set an **ascending** or **descending** sort direction on -results. By default, the ``orderBy()`` method sets an ascending sort on -the supplied field name, but you can explicitly specify an ascending -sort by passing ``"asc"`` as the second parameter. To -specify a descending sort, pass ``"desc"`` as the second parameter. - -If your documents contain duplicate values in a specific field, you can -handle the tie by specifying more fields to sort on. This ensures consistent -results if the other fields contain unique values. - -This example queries for documents in which the value of the ``countries`` field contains -``"Indonesia"`` and orders results first by an ascending sort on the -``year`` field, then a descending sort on the ``title`` field. - -.. tabs:: - - .. tab:: Query Syntax - :tabid: query-syntax - - Use the following syntax to specify the query: - - .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php - :language: php - :dedent: - :start-after: start-sort - :end-before: end-sort - - .. tab:: Controller Method - :tabid: controller - - To see the query results in the ``browse_movies`` view, edit the ``show()`` function - in the ``MovieController.php`` file to resemble the following code: - - .. io-code-block:: - :copyable: true - - .. input:: - :language: php - - class MovieController - { - public function show() - { - $movies = Movie::where('countries', 'Indonesia') - ->orderBy('year') - ->orderBy('title', 'desc') - ->get(); - - return view('browse_movies', [ - 'movies' => $movies - ]); - } - } - - .. output:: - :language: none - :visible: false - - Title: Joni's Promise - Year: 2005 - Runtime: 83 - IMDB Rating: 7.6 - IMDB Votes: 702 - Plot: A film delivery man promises ... - - Title: Gie - Year: 2005 - Runtime: 147 - IMDB Rating: 7.5 - IMDB Votes: 470 - Plot: Soe Hok Gie is an activist who lived in the sixties ... - - Title: Requiem from Java - Year: 2006 - Runtime: 120 - IMDB Rating: 6.6 - IMDB Votes: 316 - Plot: Setyo (Martinus Miroto) and Siti (Artika Sari Dewi) - are young married couple ... - - ... + // You can also count documents that match a filter. + SampleModel::where('', '') + ->count(); -.. tip:: +To view a runnable example that counts documents, see the +:ref:`laravel-count-usage` usage example. - To learn more about sorting, see the following resources: +Retrieve Distinct Values +------------------------ - - :manual:`Natural order ` - in the {+server-docs-name+} glossary - - `Ordering, Grouping, Limit, and Offset `__ - in the Laravel documentation +The following code shows how to retrieve the distinct values of a +specified field: -.. _laravel-retrieve-one: - -Return the First Result -~~~~~~~~~~~~~~~~~~~~~~~ +.. code-block:: php -To retrieve the first document that matches a set of criteria, use the ``where()`` method -followed by the ``first()`` method. + SampleModel::select('') + ->distinct() + ->get(); -Chain the ``orderBy()`` method to ``first()`` to get consistent results when you query on a unique -value. If you omit the ``orderBy()`` method, MongoDB returns the matching documents according to -the documents' natural order, or as they appear in the collection. +To view a runnable example that returns distinct field values, see the +:ref:`laravel-distinct-usage` usage example. -This example queries for documents in which the value of the ``runtime`` field is -``30`` and returns the first matching document according to the value of the ``_id`` -field. +Skip Results +------------ -.. tabs:: +The following code shows how to skip a specified number of documents +returned from MongoDB: - .. tab:: Query Syntax - :tabid: query-syntax +.. code-block:: php - Use the following syntax to specify the query: + SampleModel::where('', '') + ->skip() + ->get(); - .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php - :language: php - :dedent: - :start-after: start-first - :end-before: end-first +To learn more about modifying how {+odm-long+} returns results, see the +:ref:`laravel-read-modify-results` guide. - .. tab:: Controller Method - :tabid: controller +Limit Results +------------- - To see the query results in the ``browse_movies`` view, edit the ``show()`` function - in the ``MovieController.php`` file to resemble the following code: +The following code shows how to return only a specified number of +documents from MongoDB: - .. io-code-block:: - :copyable: true +.. code-block:: php - .. input:: - :language: php + SampleModel::where('', '') + ->take() + ->get(); - class MovieController - { - public function show() - { - $movie = Movie::where('runtime', 30) - ->orderBy('_id') - ->first(); +To learn more about modifying how {+odm-long+} returns results, see the +:ref:`laravel-read-modify-results` guide. - return view('browse_movies', [ - 'movies' => $movie - ]); - } - } +Sort Results +------------ - .. output:: - :language: none - :visible: false +The following code shows how to set a sort order on results returned +from MongoDB: - Title: Statues also Die - Year: 1953 - Runtime: 30 - IMDB Rating: 7.6 - IMDB Votes: 620 - Plot: A documentary of black art. +.. code-block:: php -.. tip:: + SampleModel::where('field name', '') + ->orderBy('') + ->get(); - To learn more about the ``orderBy()`` method, see the - :ref:`laravel-sort` section of this guide. +To learn more about modifying how {+odm-long+} returns results, see the +:ref:`laravel-read-modify-results` guide. diff --git a/docs/fundamentals/read-operations/modify-results.txt b/docs/fundamentals/read-operations/modify-results.txt new file mode 100644 index 000000000..fd67422ae --- /dev/null +++ b/docs/fundamentals/read-operations/modify-results.txt @@ -0,0 +1,227 @@ +.. _laravel-modify-find: +.. _laravel-read-modify-results: + +==================== +Modify Query Results +==================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: filter, criteria, CRUD, code example + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to customize the way that {+odm-long+} +returns results from queries. You can modify the results of a find +operation by chaining more methods to the ``where()`` method. + +The following sections demonstrate how to modify the behavior of the +``where()`` method: + +- :ref:`laravel-skip-limit` uses the ``skip()`` method to set the number of documents + to skip and the ``take()`` method to set the total number of documents to return +- :ref:`laravel-sort` uses the ``orderBy()`` method to return query + results in a specified order based on field values + +To learn more about Eloquent models in the {+odm-short+}, see the +:ref:`laravel-eloquent-models` section. + +.. include:: /includes/fundamentals/read-operations/before-you-get-started.rst + +.. _laravel-skip-limit: + +Skip and Limit Results +---------------------- + +This example queries for documents in which the ``year`` value is ``1999``. +The operation skips the first ``2`` matching documents and outputs a total of ``3`` +documents. + +.. tabs:: + + .. tab:: Query Syntax + :tabid: query-syntax + + Use the following syntax to specify the query: + + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-skip-limit + :end-before: end-skip-limit + + .. tab:: Controller Method + :tabid: controller + + To see the query results in the ``browse_movies`` view, edit the ``show()`` function + in the ``MovieController.php`` file to resemble the following code: + + .. io-code-block:: + :copyable: true + + .. input:: + :language: php + + class MovieController + { + public function show() + { + $movies = Movie::where('year', 1999) + ->skip(2) + ->take(3) + ->get(); + + return view('browse_movies', [ + 'movies' => $movies + ]); + } + } + + .. output:: + :language: none + :visible: false + + Title: Three Kings + Year: 1999 + Runtime: 114 + IMDB Rating: 7.2 + IMDB Votes: 130677 + Plot: In the aftermath of the Persian Gulf War, 4 soldiers set out to steal gold + that was stolen from Kuwait, but they discover people who desperately need their help. + + Title: Toy Story 2 + Year: 1999 + Runtime: 92 + IMDB Rating: 7.9 + IMDB Votes: 346655 + Plot: When Woody is stolen by a toy collector, Buzz and his friends vow to rescue him, + but Woody finds the idea of immortality in a museum tempting. + + Title: Beowulf + Year: 1999 + Runtime: 95 + IMDB Rating: 4 + IMDB Votes: 9296 + Plot: A sci-fi update of the famous 6th Century poem. In a besieged land, Beowulf must + battle against the hideous creature Grendel and his vengeance seeking mother. + +.. _laravel-sort: + +Sort Query Results +------------------ + +To order query results based on the values of specified fields, use the ``where()`` method +followed by the ``orderBy()`` method. + +You can set an **ascending** or **descending** sort direction on +results. By default, the ``orderBy()`` method sets an ascending sort on +the supplied field name, but you can explicitly specify an ascending +sort by passing ``"asc"`` as the second parameter. To +specify a descending sort, pass ``"desc"`` as the second parameter. + +If your documents contain duplicate values in a specific field, you can +handle the tie by specifying more fields to sort on. This ensures consistent +results if the other fields contain unique values. + +This example queries for documents in which the value of the ``countries`` field contains +``"Indonesia"`` and orders results first by an ascending sort on the +``year`` field, then a descending sort on the ``title`` field. + +.. tabs:: + + .. tab:: Query Syntax + :tabid: query-syntax + + Use the following syntax to specify the query: + + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-sort + :end-before: end-sort + + .. tab:: Controller Method + :tabid: controller + + To see the query results in the ``browse_movies`` view, edit the ``show()`` function + in the ``MovieController.php`` file to resemble the following code: + + .. io-code-block:: + :copyable: true + + .. input:: + :language: php + + class MovieController + { + public function show() + { + $movies = Movie::where('countries', 'Indonesia') + ->orderBy('year') + ->orderBy('title', 'desc') + ->get(); + + return view('browse_movies', [ + 'movies' => $movies + ]); + } + } + + .. output:: + :language: none + :visible: false + + Title: Joni's Promise + Year: 2005 + Runtime: 83 + IMDB Rating: 7.6 + IMDB Votes: 702 + Plot: A film delivery man promises ... + + Title: Gie + Year: 2005 + Runtime: 147 + IMDB Rating: 7.5 + IMDB Votes: 470 + Plot: Soe Hok Gie is an activist who lived in the sixties ... + + Title: Requiem from Java + Year: 2006 + Runtime: 120 + IMDB Rating: 6.6 + IMDB Votes: 316 + Plot: Setyo (Martinus Miroto) and Siti (Artika Sari Dewi) + are young married couple ... + + ... + +.. tip:: + + To learn more about sorting, see the following resources: + + - :manual:`Natural order ` + in the {+server-docs-name+} glossary + - `Ordering, Grouping, Limit, and Offset `__ + in the Laravel documentation + +Additional Information +---------------------- + +To view runnable code examples that demonstrate how to perform find +operations by using the {+odm-short+}, see the following usage examples: + +- :ref:`laravel-find-one-usage` +- :ref:`laravel-find-usage` + +To learn how to retrieve data based on filter criteria, see the +:ref:`laravel-fundamentals-read-retrieve` guide. diff --git a/docs/fundamentals/read-operations/retrieve.txt b/docs/fundamentals/read-operations/retrieve.txt new file mode 100644 index 000000000..a4ca31091 --- /dev/null +++ b/docs/fundamentals/read-operations/retrieve.txt @@ -0,0 +1,304 @@ +.. _laravel-fundamentals-retrieve-documents: +.. _laravel-fundamentals-read-retrieve: + +============= +Retrieve Data +============= + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: filter, criteria, CRUD, code example + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to retrieve data from MongoDB +collections by using {+odm-long+}. This guide describes the Eloquent +model methods that you can use to retrieve data and provides examples +of different types of find operations. + +To learn more about Eloquent models in the {+odm-short+}, see the +:ref:`laravel-eloquent-models` section. + +.. include:: /includes/fundamentals/read-operations/before-you-get-started.rst + +.. _laravel-retrieve-matching: + +Retrieve Documents that Match a Query +------------------------------------- + +You can use Laravel's Eloquent object-relational mapper (ORM) to create models +that represent MongoDB collections and chain methods on them to specify +query criteria. + +To retrieve documents that match a set of criteria, call the ``where()`` +method on the collection's corresponding Eloquent model, then pass a query +filter to the method. + +.. tip:: Retrieve One Document + + The ``where()`` method retrieves all matching documents. To retrieve + the first matching document, you can chain the ``first()`` method. To + learn more and view an example, see the :ref:`laravel-retrieve-one` + section of this guide. + +A query filter specifies field value requirements and instructs the find +operation to return only documents that meet these requirements. + +You can use one of the following ``where()`` method calls to build a query: + +- ``where('', )`` builds a query that matches documents in + which the target field has the exact specified value + +- ``where('', '', )`` builds a query + that matches documents in which the target field's value meets the comparison + criteria + +To apply multiple sets of criteria to the find operation, you can chain a series +of ``where()`` methods together. + +After building your query by using the ``where()`` method, chain the ``get()`` +method to retrieve the query results. + +This example calls two ``where()`` methods on the ``Movie`` Eloquent model to +retrieve documents that meet the following criteria: + +- ``year`` field has a value of ``2010`` +- ``imdb.rating`` nested field has a value greater than ``8.5`` + +.. tabs:: + + .. tab:: Query Syntax + :tabid: query-syntax + + Use the following syntax to specify the query: + + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-query + :end-before: end-query + + .. tab:: Controller Method + :tabid: controller + + To see the query results in the ``browse_movies`` view, edit the ``show()`` function + in the ``MovieController.php`` file to resemble the following code: + + .. io-code-block:: + :copyable: true + + .. input:: + :language: php + + class MovieController + { + public function show() + { + $movies = Movie::where('year', 2010) + ->where('imdb.rating', '>', 8.5) + ->get(); + + return view('browse_movies', [ + 'movies' => $movies + ]); + } + } + + .. output:: + :language: none + :visible: false + + Title: Inception + Year: 2010 + Runtime: 148 + IMDB Rating: 8.8 + IMDB Votes: 1294646 + Plot: A thief who steals corporate secrets through use of dream-sharing + technology is given the inverse task of planting an idea into the mind of a CEO. + + Title: Senna + Year: 2010 + Runtime: 106 + IMDB Rating: 8.6 + IMDB Votes: 41904 + Plot: A documentary on Brazilian Formula One racing driver Ayrton Senna, who won the + F1 world championship three times before his death at age 34. + +To learn how to query by using the Laravel query builder instead of the +Eloquent ORM, see the :ref:`laravel-query-builder` page. + +Match Array Field Elements +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can specify a query filter to match array field elements when +retrieving documents. If your documents contain an array field, you can +match documents based on if the value contains all or some specified +array elements. + +You can use one of the following ``where()`` method calls to build a +query on an array field: + +- ``where('', )`` builds a query that matches documents in + which the array field value is exactly the specified array + +- ``where('', 'in', )`` builds a query + that matches documents in which the array field value contains one or + more of the specified array elements + +After building your query by using the ``where()`` method, chain the ``get()`` +method to retrieve the query results. + +Select from the following :guilabel:`Exact Array Match` and +:guilabel:`Element Match` tabs to view the query syntax for each pattern: + +.. tabs:: + + .. tab:: Exact Array Match + :tabid: exact-array + + This example retrieves documents in which the ``countries`` array is + exactly ``['Indonesia', 'Canada']``: + + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-exact-array + :end-before: end-exact-array + + .. tab:: Element Match + :tabid: element-match + + This example retrieves documents in which the ``countries`` array + contains one of the values in the array ``['Canada', 'Egypt']``: + + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-elem-match + :end-before: end-elem-match + +To learn how to query array fields by using the Laravel query builder instead of the +Eloquent ORM, see the :ref:`laravel-query-builder-elemMatch` section in +the Query Builder guide. + +.. _laravel-retrieve-one: + +Retrieve the First Result +------------------------- + +To retrieve the first document that matches a set of criteria, use the ``where()`` method +followed by the ``first()`` method. + +Chain the ``orderBy()`` method to ``first()`` to get consistent results when you query on a unique +value. If you omit the ``orderBy()`` method, MongoDB returns the matching documents according to +the documents' natural order, or as they appear in the collection. + +This example queries for documents in which the value of the ``runtime`` field is +``30`` and returns the first matching document according to the value of the ``_id`` +field. + +.. tabs:: + + .. tab:: Query Syntax + :tabid: query-syntax + + Use the following syntax to specify the query: + + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-first + :end-before: end-first + + .. tab:: Controller Method + :tabid: controller + + To see the query results in the ``browse_movies`` view, edit the ``show()`` function + in the ``MovieController.php`` file to resemble the following code: + + .. io-code-block:: + :copyable: true + + .. input:: + :language: php + + class MovieController + { + public function show() + { + $movie = Movie::where('runtime', 30) + ->orderBy('_id') + ->first(); + + return view('browse_movies', [ + 'movies' => $movie + ]); + } + } + + .. output:: + :language: none + :visible: false + + Title: Statues also Die + Year: 1953 + Runtime: 30 + IMDB Rating: 7.6 + IMDB Votes: 620 + Plot: A documentary of black art. + +.. tip:: + + To learn more about the ``orderBy()`` method, see the + :ref:`laravel-sort` section of the Modify Query Results guide. + +.. _laravel-retrieve-all: + +Retrieve All Documents in a Collection +-------------------------------------- + +You can retrieve all documents in a collection by omitting the query filter. +To return the documents, call the ``get()`` method on an Eloquent model that +represents your collection. Alternatively, you can use the ``get()`` method's +alias ``all()`` to perform the same operation. + +Use the following syntax to run a find operation that matches all documents: + +.. code-block:: php + + $movies = Movie::get(); + +.. warning:: + + The ``movies`` collection in the Atlas sample dataset contains a large amount of data. + Retrieving and displaying all documents in this collection might cause your web + application to time out. + + To avoid this issue, specify a document limit by using the ``take()`` method. For + more information about ``take()``, see the :ref:`laravel-modify-find` + section of the Modify Query Output guide. + +Additional Information +---------------------- + +To view runnable code examples that demonstrate how to perform find +operations by using the {+odm-short+}, see the following usage examples: + +- :ref:`laravel-find-one-usage` +- :ref:`laravel-find-usage` + +To learn how to insert data into MongoDB, see the +:ref:`laravel-fundamentals-write-ops` guide. + +To learn how to modify the way that the {+odm-short+} returns results, +see the :ref:`laravel-read-modify-results` guide. diff --git a/docs/fundamentals/read-operations/search-text.txt b/docs/fundamentals/read-operations/search-text.txt new file mode 100644 index 000000000..4b465e737 --- /dev/null +++ b/docs/fundamentals/read-operations/search-text.txt @@ -0,0 +1,157 @@ +.. _laravel-fundamentals-search-text: +.. _laravel-retrieve-text-search: + +=========== +Search Text +=========== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: filter, string, CRUD, code example + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to run a **text search** by using +{+odm-long+}. + +You can use a text search to retrieve documents that contain a term or a +phrase in a specified field. A term is a sequence of characters that +excludes whitespace characters. A phrase is a sequence of terms with any +number of whitespace characters. + +This guide describes the Eloquent model methods that you can use to +search text and provides examples. To learn more about Eloquent models +in the {+odm-short+}, see the :ref:`laravel-eloquent-models` section. + +.. include:: /includes/fundamentals/read-operations/before-you-get-started.rst + +Search Text Fields +------------------ + +Before you can perform a text search, you must create a :manual:`text +index ` on +the text-valued field. To learn more about creating +indexes, see the :ref:`laravel-eloquent-indexes` section of the +Schema Builder guide. + +You can perform a text search by using the :manual:`$text +` operator followed +by the ``$search`` field in your query filter that you pass to the +``where()`` method. The ``$text`` operator performs a text search on the +text-indexed fields. The ``$search`` field specifies the text to search for. + +After building your query by using the ``where()`` method, chain the ``get()`` +method to retrieve the query results. + +This example calls the ``where()`` method on the ``Movie`` Eloquent model to +retrieve documents in which the ``plot`` field contains the phrase +``"love story"``. To perform this text search, the collection must have +a text index on the ``plot`` field. + +.. tabs:: + + .. tab:: Query Syntax + :tabid: query-syntax + + Use the following syntax to specify the query: + + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-text + :end-before: end-text + + .. tab:: Controller Method + :tabid: controller + + To see the query results in the ``browse_movies`` view, edit the ``show()`` function + in the ``MovieController.php`` file to resemble the following code: + + .. io-code-block:: + :copyable: true + + .. input:: + :language: php + + class MovieController + { + public function show() + { + $movies = Movie::where('$text', ['$search' => '"love story"']) + ->get(); + + return view('browse_movies', [ + 'movies' => $movies + ]); + } + } + + .. output:: + :language: none + :visible: false + + Title: Cafè de Flore + Year: 2011 + Runtime: 120 + IMDB Rating: 7.4 + IMDB Votes: 9663 + Plot: A love story between a man and woman ... + + Title: Paheli + Year: 2005 + Runtime: 140 + IMDB Rating: 6.7 + IMDB Votes: 8909 + Plot: A folk tale - supernatural love story about a ghost ... + + Title: Por un puèado de besos + Year: 2014 + Runtime: 98 + IMDB Rating: 6.1 + IMDB Votes: 223 + Plot: A girl. A boy. A love story ... + + ... + +Search Score +------------ + +A text search assigns a numerical :manual:`text score ` to indicate how closely +each result matches the string in your query filter. You can sort the +results by relevance by using the ``orderBy()`` method to sort on the +``textScore`` metadata field. You can access this metadata by using the +:manual:`$meta ` operator: + +.. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-text-relevance + :end-before: end-text-relevance + :emphasize-lines: 2 + +.. tip:: + + To learn more about the ``orderBy()`` method, see the + :ref:`laravel-sort` section of the Modify Query Output guide. + +Additional Information +---------------------- + +To view runnable code examples that demonstrate how to perform find +operations by using the {+odm-short+}, see the following usage examples: + +- :ref:`laravel-find-one-usage` +- :ref:`laravel-find-usage` + +To learn how to retrieve data based on filter criteria, see the +:ref:`laravel-fundamentals-read-retrieve` guide. diff --git a/docs/fundamentals/write-operations.txt b/docs/fundamentals/write-operations.txt index 0a4d8a6ca..1b2f163be 100644 --- a/docs/fundamentals/write-operations.txt +++ b/docs/fundamentals/write-operations.txt @@ -133,8 +133,7 @@ matching document doesn't exist: ['upsert' => true], ); - /* Or, use the upsert() method. */ - + // Or, use the upsert() method. SampleModel::upsert( [], '', diff --git a/docs/includes/fundamentals/read-operations/before-you-get-started.rst b/docs/includes/fundamentals/read-operations/before-you-get-started.rst new file mode 100644 index 000000000..9555856fc --- /dev/null +++ b/docs/includes/fundamentals/read-operations/before-you-get-started.rst @@ -0,0 +1,15 @@ +Before You Get Started +---------------------- + +To run the code examples in this guide, complete the :ref:`Quick Start ` +tutorial. This tutorial provides instructions on setting up a MongoDB Atlas instance with +sample data and creating the following files in your Laravel web application: + +- ``Movie.php`` file, which contains a ``Movie`` model to represent documents in the ``movies`` + collection +- ``MovieController.php`` file, which contains a ``show()`` function to run database operations +- ``browse_movies.blade.php`` file, which contains HTML code to display the results of database + operations + +The following sections describe how to edit the files in your Laravel application to run +the find operation code examples and view the expected output. From d93a9c2d6406d4b58682100537617f79a53a1f5d Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 28 Feb 2025 11:01:09 -0500 Subject: [PATCH 432/446] link fic --- docs/fundamentals/read-operations/read-pref.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/fundamentals/read-operations/read-pref.txt b/docs/fundamentals/read-operations/read-pref.txt index b3081a1c5..075c74380 100644 --- a/docs/fundamentals/read-operations/read-pref.txt +++ b/docs/fundamentals/read-operations/read-pref.txt @@ -137,5 +137,5 @@ Additional Information To learn how to retrieve data based on filter criteria, see the :ref:`laravel-fundamentals-read-retrieve` guide. -To learn how to retrieve data based on filter criteria, see the -:ref:`laravel-fundamentals-read-retrieve` guide. +To learn how to modify the way that the {+odm-short+} returns results, +see the :ref:`laravel-read-modify-results` guide. From e373350f436596402a2b51cd7a8fe68fdd2df848 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Sat, 1 Mar 2025 23:34:32 +0100 Subject: [PATCH 433/446] PHPORM-289 Support Laravel 12 (#3283) --- .github/workflows/build-ci-atlas.yml | 1 + .github/workflows/build-ci.yml | 7 ++- composer.json | 14 +++--- phpstan-baseline.neon | 10 ++++ src/Connection.php | 6 ++- src/Schema/Blueprint.php | 29 +++--------- src/Schema/BlueprintLaravelCompatibility.php | 50 ++++++++++++++++++++ src/Schema/Builder.php | 37 +++++++++++++-- tests/Query/BuilderTest.php | 2 +- tests/RelationsTest.php | 1 + tests/SchemaTest.php | 26 ++++++++++ 11 files changed, 142 insertions(+), 41 deletions(-) create mode 100644 src/Schema/BlueprintLaravelCompatibility.php diff --git a/.github/workflows/build-ci-atlas.yml b/.github/workflows/build-ci-atlas.yml index 7a4ebd03f..30b4b06b1 100644 --- a/.github/workflows/build-ci-atlas.yml +++ b/.github/workflows/build-ci-atlas.yml @@ -20,6 +20,7 @@ jobs: - "8.4" laravel: - "11.*" + - "12.*" steps: - uses: "actions/checkout@v4" diff --git a/.github/workflows/build-ci.yml b/.github/workflows/build-ci.yml index d16a5885f..659c316d3 100644 --- a/.github/workflows/build-ci.yml +++ b/.github/workflows/build-ci.yml @@ -28,19 +28,18 @@ jobs: laravel: - "10.*" - "11.*" + - "12.*" include: - php: "8.1" laravel: "10.*" mongodb: "5.0" mode: "low-deps" os: "ubuntu-latest" - - php: "8.4" - laravel: "11.*" - mongodb: "7.0" - os: "ubuntu-latest" exclude: - php: "8.1" laravel: "11.*" + - php: "8.1" + laravel: "12.*" steps: - uses: "actions/checkout@v4" diff --git a/composer.json b/composer.json index 2855a9546..64006a47b 100644 --- a/composer.json +++ b/composer.json @@ -25,11 +25,11 @@ "php": "^8.1", "ext-mongodb": "^1.15", "composer-runtime-api": "^2.0.0", - "illuminate/cache": "^10.36|^11", - "illuminate/container": "^10.0|^11", - "illuminate/database": "^10.30|^11", - "illuminate/events": "^10.0|^11", - "illuminate/support": "^10.0|^11", + "illuminate/cache": "^10.36|^11|^12", + "illuminate/container": "^10.0|^11|^12", + "illuminate/database": "^10.30|^11|^12", + "illuminate/events": "^10.0|^11|^12", + "illuminate/support": "^10.0|^11|^12", "mongodb/mongodb": "^1.21", "symfony/http-foundation": "^6.4|^7" }, @@ -38,8 +38,8 @@ "league/flysystem-gridfs": "^3.28", "league/flysystem-read-only": "^3.0", "phpunit/phpunit": "^10.3|^11.5.3", - "orchestra/testbench": "^8.0|^9.0", - "mockery/mockery": "^1.4.4@stable", + "orchestra/testbench": "^8.0|^9.0|^10.0", + "mockery/mockery": "^1.4.4", "doctrine/coding-standard": "12.0.x-dev", "spatie/laravel-query-builder": "^5.6|^6", "phpstan/phpstan": "^1.10", diff --git a/phpstan-baseline.neon b/phpstan-baseline.neon index 67fdd4154..ba1f3b7aa 100644 --- a/phpstan-baseline.neon +++ b/phpstan-baseline.neon @@ -1,5 +1,15 @@ parameters: ignoreErrors: + - + message: "#^Class MongoDB\\\\Laravel\\\\Query\\\\Grammar does not have a constructor and must be instantiated without any parameters\\.$#" + count: 1 + path: src/Connection.php + + - + message: "#^Class MongoDB\\\\Laravel\\\\Schema\\\\Grammar does not have a constructor and must be instantiated without any parameters\\.$#" + count: 1 + path: src/Connection.php + - message: "#^Access to an undefined property Illuminate\\\\Container\\\\Container\\:\\:\\$config\\.$#" count: 3 diff --git a/src/Connection.php b/src/Connection.php index 980750093..4dd04120d 100644 --- a/src/Connection.php +++ b/src/Connection.php @@ -355,13 +355,15 @@ protected function getDefaultPostProcessor() /** @inheritdoc */ protected function getDefaultQueryGrammar() { - return new Query\Grammar(); + // Argument added in Laravel 12 + return new Query\Grammar($this); } /** @inheritdoc */ protected function getDefaultSchemaGrammar() { - return new Schema\Grammar(); + // Argument added in Laravel 12 + return new Schema\Grammar($this); } /** diff --git a/src/Schema/Blueprint.php b/src/Schema/Blueprint.php index a525a9cee..1197bfde1 100644 --- a/src/Schema/Blueprint.php +++ b/src/Schema/Blueprint.php @@ -4,9 +4,9 @@ namespace MongoDB\Laravel\Schema; -use Illuminate\Database\Connection; -use Illuminate\Database\Schema\Blueprint as SchemaBlueprint; +use Illuminate\Database\Schema\Blueprint as BaseBlueprint; use MongoDB\Collection; +use MongoDB\Laravel\Connection; use function array_flip; use function implode; @@ -16,17 +16,14 @@ use function is_string; use function key; -class Blueprint extends SchemaBlueprint +/** @property Connection $connection */ +class Blueprint extends BaseBlueprint { - /** - * The MongoConnection object for this blueprint. - * - * @var Connection - */ - protected $connection; + // Import $connection property and constructor for Laravel 12 compatibility + use BlueprintLaravelCompatibility; /** - * The Collection object for this blueprint. + * The MongoDB collection object for this blueprint. * * @var Collection */ @@ -39,18 +36,6 @@ class Blueprint extends SchemaBlueprint */ protected $columns = []; - /** - * Create a new schema blueprint. - */ - public function __construct(Connection $connection, string $collection) - { - parent::__construct($collection); - - $this->connection = $connection; - - $this->collection = $this->connection->getCollection($collection); - } - /** @inheritdoc */ public function index($columns = null, $name = null, $algorithm = null, $options = []) { diff --git a/src/Schema/BlueprintLaravelCompatibility.php b/src/Schema/BlueprintLaravelCompatibility.php new file mode 100644 index 000000000..bf288eae8 --- /dev/null +++ b/src/Schema/BlueprintLaravelCompatibility.php @@ -0,0 +1,50 @@ +connection = $connection; + $this->collection = $connection->getCollection($collection); + } + } +} else { + /** @internal For compatibility with Laravel 12+ */ + trait BlueprintLaravelCompatibility + { + public function __construct(Connection $connection, string $collection, ?Closure $callback = null) + { + parent::__construct($connection, $collection, $callback); + + $this->collection = $connection->getCollection($collection); + } + } +} diff --git a/src/Schema/Builder.php b/src/Schema/Builder.php index 4af15f1f9..ef450745a 100644 --- a/src/Schema/Builder.php +++ b/src/Schema/Builder.php @@ -7,6 +7,7 @@ use Closure; use MongoDB\Collection; use MongoDB\Driver\Exception\ServerException; +use MongoDB\Laravel\Connection; use MongoDB\Model\CollectionInfo; use MongoDB\Model\IndexInfo; @@ -16,11 +17,14 @@ use function array_keys; use function array_map; use function array_merge; +use function array_values; use function assert; use function count; use function current; use function implode; use function in_array; +use function is_array; +use function is_string; use function iterator_to_array; use function sort; use function sprintf; @@ -28,6 +32,7 @@ use function substr; use function usort; +/** @property Connection $connection */ class Builder extends \Illuminate\Database\Schema\Builder { /** @@ -137,9 +142,10 @@ public function dropAllTables() } } - public function getTables() + /** @param string|null $schema Database name */ + public function getTables($schema = null) { - $db = $this->connection->getDatabase(); + $db = $this->connection->getDatabase($schema); $collections = []; foreach ($db->listCollectionNames() as $collectionName) { @@ -150,7 +156,8 @@ public function getTables() $collections[] = [ 'name' => $collectionName, - 'schema' => null, + 'schema' => $db->getDatabaseName(), + 'schema_qualified_name' => $db->getDatabaseName() . '.' . $collectionName, 'size' => $stats[0]?->storageStats?->totalSize ?? null, 'comment' => null, 'collation' => null, @@ -165,9 +172,29 @@ public function getTables() return $collections; } - public function getTableListing() + /** + * @param string|null $schema + * @param bool $schemaQualified If a schema is provided, prefix the collection names with the schema name + * + * @return array + */ + public function getTableListing($schema = null, $schemaQualified = false) { - $collections = iterator_to_array($this->connection->getDatabase()->listCollectionNames()); + $collections = []; + + if ($schema === null || is_string($schema)) { + $collections[$schema ?? 0] = iterator_to_array($this->connection->getDatabase($schema)->listCollectionNames()); + } elseif (is_array($schema)) { + foreach ($schema as $db) { + $collections[$db] = iterator_to_array($this->connection->getDatabase($db)->listCollectionNames()); + } + } + + if ($schema && $schemaQualified) { + $collections = array_map(fn ($db, $collections) => array_map(static fn ($collection) => $db . '.' . $collection, $collections), array_keys($collections), $collections); + } + + $collections = array_merge(...array_values($collections)); sort($collections); diff --git a/tests/Query/BuilderTest.php b/tests/Query/BuilderTest.php index 2cc0c5764..20b5a12fb 100644 --- a/tests/Query/BuilderTest.php +++ b/tests/Query/BuilderTest.php @@ -1605,7 +1605,7 @@ private static function getBuilder(): Builder $connection = m::mock(Connection::class); $processor = m::mock(Processor::class); $connection->shouldReceive('getSession')->andReturn(null); - $connection->shouldReceive('getQueryGrammar')->andReturn(new Grammar()); + $connection->shouldReceive('getQueryGrammar')->andReturn(new Grammar($connection)); return new Builder($connection, null, $processor); } diff --git a/tests/RelationsTest.php b/tests/RelationsTest.php index a55c8c0e0..643e00e6a 100644 --- a/tests/RelationsTest.php +++ b/tests/RelationsTest.php @@ -35,6 +35,7 @@ public function tearDown(): void Photo::truncate(); Label::truncate(); Skill::truncate(); + Soft::truncate(); parent::tearDown(); } diff --git a/tests/SchemaTest.php b/tests/SchemaTest.php index e2f4f7b7e..8e91a2f66 100644 --- a/tests/SchemaTest.php +++ b/tests/SchemaTest.php @@ -395,6 +395,7 @@ public function testGetTables() { DB::connection('mongodb')->table('newcollection')->insert(['test' => 'value']); DB::connection('mongodb')->table('newcollection_two')->insert(['test' => 'value']); + $dbName = DB::connection('mongodb')->getDatabaseName(); $tables = Schema::getTables(); $this->assertIsArray($tables); @@ -403,9 +404,13 @@ public function testGetTables() foreach ($tables as $table) { $this->assertArrayHasKey('name', $table); $this->assertArrayHasKey('size', $table); + $this->assertArrayHasKey('schema', $table); + $this->assertArrayHasKey('schema_qualified_name', $table); if ($table['name'] === 'newcollection') { $this->assertEquals(8192, $table['size']); + $this->assertEquals($dbName, $table['schema']); + $this->assertEquals($dbName . '.newcollection', $table['schema_qualified_name']); $found = true; } } @@ -428,6 +433,27 @@ public function testGetTableListing() $this->assertContains('newcollection_two', $tables); } + public function testGetTableListingBySchema() + { + DB::connection('mongodb')->table('newcollection')->insert(['test' => 'value']); + DB::connection('mongodb')->table('newcollection_two')->insert(['test' => 'value']); + $dbName = DB::connection('mongodb')->getDatabaseName(); + + $tables = Schema::getTableListing([$dbName, 'database__that_does_not_exists'], schemaQualified: true); + + $this->assertIsArray($tables); + $this->assertGreaterThanOrEqual(2, count($tables)); + $this->assertContains($dbName . '.newcollection', $tables); + $this->assertContains($dbName . '.newcollection_two', $tables); + + $tables = Schema::getTableListing([$dbName, 'database__that_does_not_exists'], schemaQualified: false); + + $this->assertIsArray($tables); + $this->assertGreaterThanOrEqual(2, count($tables)); + $this->assertContains('newcollection', $tables); + $this->assertContains('newcollection_two', $tables); + } + public function testGetColumns() { $collection = DB::connection('mongodb')->table('newcollection'); From c97005e9ea29e9084ec597121c8b064af61a6e9a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 3 Mar 2025 15:02:55 +0100 Subject: [PATCH 434/446] Remove suggestion of archived package mongodb/builder (#3296) Now part of the mongodb/mongodb package --- composer.json | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/composer.json b/composer.json index 64006a47b..a6f5470aa 100644 --- a/composer.json +++ b/composer.json @@ -23,7 +23,7 @@ "license": "MIT", "require": { "php": "^8.1", - "ext-mongodb": "^1.15", + "ext-mongodb": "^1.21", "composer-runtime-api": "^2.0.0", "illuminate/cache": "^10.36|^11|^12", "illuminate/container": "^10.0|^11|^12", @@ -49,8 +49,7 @@ "illuminate/bus": "< 10.37.2" }, "suggest": { - "league/flysystem-gridfs": "Filesystem storage in MongoDB with GridFS", - "mongodb/builder": "Provides a fluent aggregation builder for MongoDB pipelines" + "league/flysystem-gridfs": "Filesystem storage in MongoDB with GridFS" }, "minimum-stability": "dev", "prefer-stable": true, From 824e2fc1f3c34b48724e091ac87029b7b4e2bba6 Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Tue, 4 Mar 2025 14:51:10 +0100 Subject: [PATCH 435/446] Fix releasing from development branch (#3299) --- .github/workflows/release.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 4afbe78f1..bc60a79cc 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -32,7 +32,7 @@ jobs: run: | echo RELEASE_VERSION=${{ inputs.version }} >> $GITHUB_ENV echo RELEASE_BRANCH=$(echo ${{ inputs.version }} | cut -d '.' -f-2) >> $GITHUB_ENV - echo DEV_BRANCH=$(echo ${{ inputs.version }} | cut -d '.' - f-1).x >> $GITHUB_ENV + echo DEV_BRANCH=$(echo ${{ inputs.version }} | cut -d '.' -f-1).x >> $GITHUB_ENV - name: "Ensure release tag does not already exist" run: | From 3d8d0954925873020e08873b4540ceeb8f80996f Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Tue, 4 Mar 2025 09:48:48 -0500 Subject: [PATCH 436/446] DOCSP-48028: v5.2 release (#3297) * DOCSP-48028: v5.2 release * wip * wip * add keyword --- docs/compatibility.txt | 8 ++++++- docs/filesystems.txt | 4 ++-- docs/fundamentals/aggregation-builder.txt | 22 ------------------- .../framework-compatibility-laravel.rst | 10 +++++++++ docs/query-builder.txt | 2 +- docs/quick-start.txt | 2 +- docs/quick-start/download-and-install.txt | 2 +- docs/user-authentication.txt | 5 +++-- 8 files changed, 25 insertions(+), 30 deletions(-) diff --git a/docs/compatibility.txt b/docs/compatibility.txt index fd3e2da02..9ee891e20 100644 --- a/docs/compatibility.txt +++ b/docs/compatibility.txt @@ -15,7 +15,7 @@ Compatibility :class: singlecol .. meta:: - :keywords: laravel 9, laravel 10, laravel 11, 4.0, 4.1, 4.2, 5.0, 5.1 + :keywords: laravel 9, laravel 10, laravel 11, laravel 12, 4.0, 4.1, 4.2, 5.0, 5.1, 5.2 Laravel Compatibility --------------------- @@ -28,3 +28,9 @@ the {+odm-short+} that you can use together. To find compatibility information for unmaintained versions of the {+odm-short+}, see `Laravel Version Compatibility <{+mongodb-laravel-gh+}/blob/3.9/README.md#installation>`__ on GitHub. + +PHP Driver Compatibility +------------------------ + +To use {+odm-long+} v5.2 or later, you must install v1.21 of the +{+php-library+} and {+php-extension+}. diff --git a/docs/filesystems.txt b/docs/filesystems.txt index 3ec7ee41f..c62853f58 100644 --- a/docs/filesystems.txt +++ b/docs/filesystems.txt @@ -79,7 +79,7 @@ You can configure the following settings in ``config/filesystems.php``: * - ``throw`` - If ``true``, exceptions are thrown when an operation cannot be performed. If ``false``, - operations return ``true`` on success and ``false`` on error. Defaults to ``false``. + operations return ``true`` on success and ``false`` on error. Defaults to ``false``. You can also use a factory or a service name to create an instance of ``MongoDB\GridFS\Bucket``. In this case, the options ``connection`` and ``database`` are ignored: @@ -133,7 +133,7 @@ metadata, including the file name and a unique ObjectId. If multiple documents share the same file name, they are considered "revisions" and further distinguished by creation timestamps. -The Laravel MongoDB integration uses the GridFS Flysystem adapter. It interacts +{+odm-long+} uses the GridFS Flysystem adapter. It interacts with file revisions in the following ways: - Reading a file reads the last revision of this file name diff --git a/docs/fundamentals/aggregation-builder.txt b/docs/fundamentals/aggregation-builder.txt index 3169acfeb..9ae31f0c1 100644 --- a/docs/fundamentals/aggregation-builder.txt +++ b/docs/fundamentals/aggregation-builder.txt @@ -37,7 +37,6 @@ The {+odm-long+} aggregation builder lets you build aggregation stages and aggregation pipelines. The following sections show examples of how to use the aggregation builder to create the stages of an aggregation pipeline: -- :ref:`laravel-add-aggregation-dependency` - :ref:`laravel-build-aggregation` - :ref:`laravel-aggregation-examples` - :ref:`laravel-create-custom-operator-factory` @@ -49,27 +48,6 @@ aggregation builder to create the stages of an aggregation pipeline: aggregation builder, see :ref:`laravel-query-builder-aggregations` in the Query Builder guide. -.. _laravel-add-aggregation-dependency: - -Add the Aggregation Builder Dependency --------------------------------------- - -The aggregation builder is part of the {+agg-builder-package-name+} package. -You must add this package as a dependency to your project to use it. Run the -following command to add the aggregation builder dependency to your -application: - -.. code-block:: bash - - composer require {+agg-builder-package-name+}:{+agg-builder-version+} - -When the installation completes, verify that the ``composer.json`` file -includes the following line in the ``require`` object: - -.. code-block:: json - - "{+agg-builder-package-name+}": "{+agg-builder-version+}", - .. _laravel-build-aggregation: Create Aggregation Stages diff --git a/docs/includes/framework-compatibility-laravel.rst b/docs/includes/framework-compatibility-laravel.rst index 16c405e21..c642a6763 100644 --- a/docs/includes/framework-compatibility-laravel.rst +++ b/docs/includes/framework-compatibility-laravel.rst @@ -3,21 +3,31 @@ :stub-columns: 1 * - {+odm-long+} Version + - Laravel 12.x - Laravel 11.x - Laravel 10.x - Laravel 9.x + * - 5.2 + - ✓ + - ✓ + - ✓ + - + * - 4.2 to 5.1 + - - ✓ - ✓ - * - 4.1 + - - - ✓ - * - 4.0 + - - - ✓ - diff --git a/docs/query-builder.txt b/docs/query-builder.txt index 76a0d144a..c641323dc 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -227,7 +227,7 @@ value greater than ``8.5`` and a ``year`` value of less than .. tip:: - For compatibility with Laravel, Laravel MongoDB v5.1 supports both arrow + For compatibility with Laravel, {+odm-long+} v5.1 supports both arrow (``->``) and dot (``.``) notation to access nested fields in a query filter. The preceding example uses dot notation to query the ``imdb.rating`` nested field, which is the recommended syntax. diff --git a/docs/quick-start.txt b/docs/quick-start.txt index 1d188ad84..83b0c3937 100644 --- a/docs/quick-start.txt +++ b/docs/quick-start.txt @@ -47,7 +47,7 @@ read and write operations on the data. MongoDB University Learning Byte. If you prefer to connect to MongoDB by using the {+php-library+} without - Laravel, see `Connecting to MongoDB `__ + Laravel, see `Connect to MongoDB `__ in the {+php-library+} documentation. The {+odm-short+} extends the Laravel Eloquent and Query Builder syntax to diff --git a/docs/quick-start/download-and-install.txt b/docs/quick-start/download-and-install.txt index 696861a43..293425791 100644 --- a/docs/quick-start/download-and-install.txt +++ b/docs/quick-start/download-and-install.txt @@ -31,7 +31,7 @@ to a Laravel web application. .. tip:: As an alternative to the following installation steps, you can use Laravel Herd - to install MongoDB and configure a Laravel MongoDB development environment. For + to install MongoDB and configure a development environment for {+odm-long+}. For more information about using Laravel Herd with MongoDB, see the following resources: - `Installing MongoDB via Herd Pro diff --git a/docs/user-authentication.txt b/docs/user-authentication.txt index 88b0da603..63e883d13 100644 --- a/docs/user-authentication.txt +++ b/docs/user-authentication.txt @@ -224,7 +224,7 @@ to the ``guards`` array: ], ], -Use Laravel Passport with Laravel MongoDB +Use Laravel Passport with {+odm-long+} ````````````````````````````````````````` After installing Laravel Passport, you must enable Passport compatibility with MongoDB by @@ -300,4 +300,5 @@ Additional Information To learn more about user authentication, see `Authentication `__ in the Laravel documentation. -To learn more about Eloquent models, see the :ref:`laravel-eloquent-model-class` guide. \ No newline at end of file +To learn more about Eloquent models, see the +:ref:`laravel-eloquent-model-class` guide. From f06d944955fed946fdf94f0a6f01fa48142b1357 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Tue, 4 Mar 2025 10:56:29 -0500 Subject: [PATCH 437/446] Merges the read operation reorganization into 5.2 (#3301) * DOCSP-35945: read operations reorg (#3293) * DOCSP-35945: read operations reorg * skip * small fixes * small fixes * fixes - RM and moved a section * link fic * Fix releasing from development branch (#3299) --------- Co-authored-by: MongoDB PHP Bot <162451593+mongodb-php-bot@users.noreply.github.com> Co-authored-by: Andreas Braun --- .github/workflows/release.yml | 2 +- docs/fundamentals/read-operations.txt | 749 +++--------------- .../read-operations/modify-results.txt | 227 ++++++ .../read-operations/read-pref.txt | 141 ++++ .../fundamentals/read-operations/retrieve.txt | 304 +++++++ .../read-operations/search-text.txt | 157 ++++ docs/fundamentals/write-operations.txt | 3 +- .../before-you-get-started.rst | 15 + 8 files changed, 960 insertions(+), 638 deletions(-) create mode 100644 docs/fundamentals/read-operations/modify-results.txt create mode 100644 docs/fundamentals/read-operations/read-pref.txt create mode 100644 docs/fundamentals/read-operations/retrieve.txt create mode 100644 docs/fundamentals/read-operations/search-text.txt create mode 100644 docs/includes/fundamentals/read-operations/before-you-get-started.rst diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 4afbe78f1..bc60a79cc 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -32,7 +32,7 @@ jobs: run: | echo RELEASE_VERSION=${{ inputs.version }} >> $GITHUB_ENV echo RELEASE_BRANCH=$(echo ${{ inputs.version }} | cut -d '.' -f-2) >> $GITHUB_ENV - echo DEV_BRANCH=$(echo ${{ inputs.version }} | cut -d '.' - f-1).x >> $GITHUB_ENV + echo DEV_BRANCH=$(echo ${{ inputs.version }} | cut -d '.' -f-1).x >> $GITHUB_ENV - name: "Ensure release tag does not already exist" run: | diff --git a/docs/fundamentals/read-operations.txt b/docs/fundamentals/read-operations.txt index f3b02c5ec..367e2d38d 100644 --- a/docs/fundamentals/read-operations.txt +++ b/docs/fundamentals/read-operations.txt @@ -10,7 +10,14 @@ Read Operations :values: tutorial .. meta:: - :keywords: find one, find many, code example + :keywords: find one, find many, skip, limit, paginate, string, code example + +.. toctree:: + + Retrieve Data + Search Text + Modify Query Results + Set Read Preference .. contents:: On this page :local: @@ -21,697 +28,169 @@ Read Operations Overview -------- -In this guide, you can learn how to use {+odm-long+} to perform **find operations** -on your MongoDB collections. Find operations allow you to retrieve documents based on -criteria that you specify. - -This guide shows you how to perform the following tasks: - -- :ref:`laravel-retrieve-matching` -- :ref:`laravel-retrieve-all` -- :ref:`laravel-retrieve-text-search` -- :ref:`Modify Find Operation Behavior ` - -Before You Get Started ----------------------- - -To run the code examples in this guide, complete the :ref:`Quick Start ` -tutorial. This tutorial provides instructions on setting up a MongoDB Atlas instance with -sample data and creating the following files in your Laravel web application: - -- ``Movie.php`` file, which contains a ``Movie`` model to represent documents in the ``movies`` - collection -- ``MovieController.php`` file, which contains a ``show()`` function to run database operations -- ``browse_movies.blade.php`` file, which contains HTML code to display the results of database - operations - -The following sections describe how to edit the files in your Laravel application to run -the find operation code examples and view the expected output. - -.. _laravel-retrieve-matching: - -Retrieve Documents that Match a Query -------------------------------------- - -You can use Laravel's Eloquent object-relational mapper (ORM) to create models -that represent MongoDB collections and chain methods on them to specify -query criteria. - -To retrieve documents that match a set of criteria, call the ``where()`` -method on the collection's corresponding Eloquent model, then pass a query -filter to the method. - -A query filter specifies field value requirements and instructs the find -operation to return only documents that meet these requirements. - -You can use one of the following ``where()`` method calls to build a query: - -- ``where('', )`` builds a query that matches documents in - which the target field has the exact specified value - -- ``where('', '', )`` builds a query - that matches documents in which the target field's value meets the comparison - criteria - -To apply multiple sets of criteria to the find operation, you can chain a series -of ``where()`` methods together. - -After building your query by using the ``where()`` method, chain the ``get()`` -method to retrieve the query results. - -This example calls two ``where()`` methods on the ``Movie`` Eloquent model to -retrieve documents that meet the following criteria: - -- ``year`` field has a value of ``2010`` -- ``imdb.rating`` nested field has a value greater than ``8.5`` - -.. tabs:: - - .. tab:: Query Syntax - :tabid: query-syntax - - Use the following syntax to specify the query: - - .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php - :language: php - :dedent: - :start-after: start-query - :end-before: end-query - - .. tab:: Controller Method - :tabid: controller - - To see the query results in the ``browse_movies`` view, edit the ``show()`` function - in the ``MovieController.php`` file to resemble the following code: - - .. io-code-block:: - :copyable: true - - .. input:: - :language: php - - class MovieController - { - public function show() - { - $movies = Movie::where('year', 2010) - ->where('imdb.rating', '>', 8.5) - ->get(); - - return view('browse_movies', [ - 'movies' => $movies - ]); - } - } - - .. output:: - :language: none - :visible: false - - Title: Inception - Year: 2010 - Runtime: 148 - IMDB Rating: 8.8 - IMDB Votes: 1294646 - Plot: A thief who steals corporate secrets through use of dream-sharing - technology is given the inverse task of planting an idea into the mind of a CEO. - - Title: Senna - Year: 2010 - Runtime: 106 - IMDB Rating: 8.6 - IMDB Votes: 41904 - Plot: A documentary on Brazilian Formula One racing driver Ayrton Senna, who won the - F1 world championship three times before his death at age 34. - -To learn how to query by using the Laravel query builder instead of the -Eloquent ORM, see the :ref:`laravel-query-builder` page. - -Match Array Field Elements -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can specify a query filter to match array field elements when -retrieving documents. If your documents contain an array field, you can -match documents based on if the value contains all or some specified -array elements. - -You can use one of the following ``where()`` method calls to build a -query on an array field: - -- ``where('', )`` builds a query that matches documents in - which the array field value is exactly the specified array +In this guide, you can see code templates of common +methods that you can use to read data from MongoDB by using +{+odm-long+}. -- ``where('', 'in', )`` builds a query - that matches documents in which the array field value contains one or - more of the specified array elements - -After building your query by using the ``where()`` method, chain the ``get()`` -method to retrieve the query results. - -Select from the following :guilabel:`Exact Array Match` and -:guilabel:`Element Match` tabs to view the query syntax for each pattern: - -.. tabs:: - - .. tab:: Exact Array Match - :tabid: exact-array - - This example retrieves documents in which the ``countries`` array is - exactly ``['Indonesia', 'Canada']``: - - .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php - :language: php - :dedent: - :start-after: start-exact-array - :end-before: end-exact-array - - .. tab:: Element Match - :tabid: element-match - - This example retrieves documents in which the ``countries`` array - contains one of the values in the array ``['Canada', 'Egypt']``: - - .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php - :language: php - :dedent: - :start-after: start-elem-match - :end-before: end-elem-match - -To learn how to query array fields by using the Laravel query builder instead of the -Eloquent ORM, see the :ref:`laravel-query-builder-elemMatch` section in -the Query Builder guide. - -.. _laravel-retrieve-all: +.. tip:: -Retrieve All Documents in a Collection --------------------------------------- + To learn more about any of the methods included in this guide, + see the links provided in each section. -You can retrieve all documents in a collection by omitting the query filter. -To return the documents, call the ``get()`` method on an Eloquent model that -represents your collection. Alternatively, you can use the ``get()`` method's -alias ``all()`` to perform the same operation. +Find One +-------- -Use the following syntax to run a find operation that matches all documents: +The following code shows how to retrieve the first matching document +from a collection: .. code-block:: php - $movies = Movie::get(); - -.. warning:: - - The ``movies`` collection in the Atlas sample dataset contains a large amount of data. - Retrieving and displaying all documents in this collection might cause your web - application to time out. - - To avoid this issue, specify a document limit by using the ``take()`` method. For - more information about ``take()``, see the :ref:`laravel-modify-find` section of this - guide. - -.. _laravel-retrieve-text-search: - -Search Text Fields ------------------- - -A text search retrieves documents that contain a **term** or a **phrase** in the -text-indexed fields. A term is a sequence of characters that excludes -whitespace characters. A phrase is a sequence of terms with any number -of whitespace characters. + SampleModel::where('', '') + ->first(); -.. note:: +To view a runnable example that finds one document, see the +:ref:`laravel-find-one-usage` usage example. - Before you can perform a text search, you must create a :manual:`text - index ` on - the text-valued field. To learn more about creating - indexes, see the :ref:`laravel-eloquent-indexes` section of the - Schema Builder guide. +To learn more about retrieving documents and the ``first()`` method, see +the :ref:`laravel-fundamentals-read-retrieve` guide. -You can perform a text search by using the :manual:`$text -` operator followed -by the ``$search`` field in your query filter that you pass to the -``where()`` method. The ``$text`` operator performs a text search on the -text-indexed fields. The ``$search`` field specifies the text to search for. +Find Multiple +------------- -After building your query by using the ``where()`` method, chain the ``get()`` -method to retrieve the query results. +The following code shows how to retrieve all documents that match a +query filter from a collection: -This example calls the ``where()`` method on the ``Movie`` Eloquent model to -retrieve documents in which the ``plot`` field contains the phrase -``"love story"``. To perform this text search, the collection must have -a text index on the ``plot`` field. - -.. tabs:: - - .. tab:: Query Syntax - :tabid: query-syntax +.. code-block:: php - Use the following syntax to specify the query: + SampleModel::where('', '') + ->get(); - .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php - :language: php - :dedent: - :start-after: start-text - :end-before: end-text +To view a runnable example that finds documents, see the +:ref:`laravel-find-usage` usage example. - .. tab:: Controller Method - :tabid: controller +To learn more about retrieving documents, see the +:ref:`laravel-fundamentals-read-retrieve` guide. - To see the query results in the ``browse_movies`` view, edit the ``show()`` function - in the ``MovieController.php`` file to resemble the following code: +Return All Documents +-------------------- - .. io-code-block:: - :copyable: true +The following code shows how to retrieve all documents from a +collection: - .. input:: - :language: php +.. code-block:: php - class MovieController - { - public function show() - { - $movies = Movie::where('$text', ['$search' => '"love story"']) - ->get(); + SampleModel::get(); - return view('browse_movies', [ - 'movies' => $movies - ]); - } - } + // Or, use the all() method. + SampleModel::all(); - .. output:: - :language: none - :visible: false +To view a runnable example that finds documents, see the +:ref:`laravel-find-usage` usage example. - Title: Cafè de Flore - Year: 2011 - Runtime: 120 - IMDB Rating: 7.4 - IMDB Votes: 9663 - Plot: A love story between a man and woman ... +To learn more about retrieving documents, see the +:ref:`laravel-fundamentals-read-retrieve` guide. - Title: Paheli - Year: 2005 - Runtime: 140 - IMDB Rating: 6.7 - IMDB Votes: 8909 - Plot: A folk tale - supernatural love story about a ghost ... +Search Text +----------- - Title: Por un puèado de besos - Year: 2014 - Runtime: 98 - IMDB Rating: 6.1 - IMDB Votes: 223 - Plot: A girl. A boy. A love story ... - - ... - -A text search assigns a numerical :manual:`text score ` to indicate how closely -each result matches the string in your query filter. You can sort the -results by relevance by using the ``orderBy()`` method to sort on the -``textScore`` metadata field. You can access this metadata by using the -:manual:`$meta ` operator: - -.. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php - :language: php - :dedent: - :start-after: start-text-relevance - :end-before: end-text-relevance - :emphasize-lines: 2 +The following code shows how to perform a full-text search on a string +field in a collection's documents: -.. tip:: +.. code-block:: php - To learn more about the ``orderBy()`` method, see the - :ref:`laravel-sort` section of this guide. + SampleModel::where('$text', ['$search' => '']) + ->get(); -.. _laravel-modify-find: +To learn more about searching on text fields, see the +:ref:`laravel-retrieve-text-search` guide. -Modify Behavior +Count Documents --------------- -You can modify the results of a find operation by chaining more methods -to ``where()``. - -The following sections demonstrate how to modify the behavior of the ``where()`` -method: - -- :ref:`laravel-skip-limit` uses the ``skip()`` method to set the number of documents - to skip and the ``take()`` method to set the total number of documents to return -- :ref:`laravel-sort` uses the ``orderBy()`` method to return query - results in a specified order based on field values -- :ref:`laravel-retrieve-one` uses the ``first()`` method to return the first document - that matches the query filter -- :ref:`laravel-read-pref` uses the ``readPreference()`` method to direct the query - to specific replica set members - -.. _laravel-skip-limit: - -Skip and Limit Results -~~~~~~~~~~~~~~~~~~~~~~ - -This example queries for documents in which the ``year`` value is ``1999``. -The operation skips the first ``2`` matching documents and outputs a total of ``3`` -documents. - -.. tabs:: - - .. tab:: Query Syntax - :tabid: query-syntax - - Use the following syntax to specify the query: - - .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php - :language: php - :dedent: - :start-after: start-skip-limit - :end-before: end-skip-limit - - .. tab:: Controller Method - :tabid: controller +The following code shows how to count documents in a collection: - To see the query results in the ``browse_movies`` view, edit the ``show()`` function - in the ``MovieController.php`` file to resemble the following code: - - .. io-code-block:: - :copyable: true - - .. input:: - :language: php - - class MovieController - { - public function show() - { - $movies = Movie::where('year', 1999) - ->skip(2) - ->take(3) - ->get(); - - return view('browse_movies', [ - 'movies' => $movies - ]); - } - } - - .. output:: - :language: none - :visible: false - - Title: Three Kings - Year: 1999 - Runtime: 114 - IMDB Rating: 7.2 - IMDB Votes: 130677 - Plot: In the aftermath of the Persian Gulf War, 4 soldiers set out to steal gold - that was stolen from Kuwait, but they discover people who desperately need their help. - - Title: Toy Story 2 - Year: 1999 - Runtime: 92 - IMDB Rating: 7.9 - IMDB Votes: 346655 - Plot: When Woody is stolen by a toy collector, Buzz and his friends vow to rescue him, - but Woody finds the idea of immortality in a museum tempting. - - Title: Beowulf - Year: 1999 - Runtime: 95 - IMDB Rating: 4 - IMDB Votes: 9296 - Plot: A sci-fi update of the famous 6th Century poem. In a besieged land, Beowulf must - battle against the hideous creature Grendel and his vengeance seeking mother. - -.. _laravel-sort: - -Sort Query Results -~~~~~~~~~~~~~~~~~~ - -To order query results based on the values of specified fields, use the ``where()`` method -followed by the ``orderBy()`` method. - -You can set an **ascending** or **descending** sort direction on -results. By default, the ``orderBy()`` method sets an ascending sort on -the supplied field name, but you can explicitly specify an ascending -sort by passing ``"asc"`` as the second parameter. To -specify a descending sort, pass ``"desc"`` as the second parameter. - -If your documents contain duplicate values in a specific field, you can -handle the tie by specifying more fields to sort on. This ensures consistent -results if the other fields contain unique values. - -This example queries for documents in which the value of the ``countries`` field contains -``"Indonesia"`` and orders results first by an ascending sort on the -``year`` field, then a descending sort on the ``title`` field. - -.. tabs:: - - .. tab:: Query Syntax - :tabid: query-syntax - - Use the following syntax to specify the query: - - .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php - :language: php - :dedent: - :start-after: start-sort - :end-before: end-sort - - .. tab:: Controller Method - :tabid: controller - - To see the query results in the ``browse_movies`` view, edit the ``show()`` function - in the ``MovieController.php`` file to resemble the following code: - - .. io-code-block:: - :copyable: true - - .. input:: - :language: php - - class MovieController - { - public function show() - { - $movies = Movie::where('countries', 'Indonesia') - ->orderBy('year') - ->orderBy('title', 'desc') - ->get(); - - return view('browse_movies', [ - 'movies' => $movies - ]); - } - } - - .. output:: - :language: none - :visible: false - - Title: Joni's Promise - Year: 2005 - Runtime: 83 - IMDB Rating: 7.6 - IMDB Votes: 702 - Plot: A film delivery man promises ... - - Title: Gie - Year: 2005 - Runtime: 147 - IMDB Rating: 7.5 - IMDB Votes: 470 - Plot: Soe Hok Gie is an activist who lived in the sixties ... - - Title: Requiem from Java - Year: 2006 - Runtime: 120 - IMDB Rating: 6.6 - IMDB Votes: 316 - Plot: Setyo (Martinus Miroto) and Siti (Artika Sari Dewi) - are young married couple ... - - ... +.. code-block:: php -.. tip:: + SampleModel::count(); - To learn more about sorting, see the following resources: + // You can also count documents that match a filter. + SampleModel::where('', '') + ->count(); - - :manual:`Natural order ` - in the {+server-docs-name+} glossary - - `Ordering, Grouping, Limit, and Offset `__ - in the Laravel documentation +To view a runnable example that counts documents, see the +:ref:`laravel-count-usage` usage example. -.. _laravel-retrieve-one: +Retrieve Distinct Values +------------------------ -Return the First Result -~~~~~~~~~~~~~~~~~~~~~~~ +The following code shows how to retrieve the distinct values of a +specified field: -To retrieve the first document that matches a set of criteria, use the ``where()`` method -followed by the ``first()`` method. +.. code-block:: php -Chain the ``orderBy()`` method to ``first()`` to get consistent results when you query on a unique -value. If you omit the ``orderBy()`` method, MongoDB returns the matching documents according to -the documents' natural order, or as they appear in the collection. + SampleModel::select('') + ->distinct() + ->get(); -This example queries for documents in which the value of the ``runtime`` field is -``30`` and returns the first matching document according to the value of the ``_id`` -field. +To view a runnable example that returns distinct field values, see the +:ref:`laravel-distinct-usage` usage example. -.. tabs:: +Skip Results +------------ - .. tab:: Query Syntax - :tabid: query-syntax +The following code shows how to skip a specified number of documents +returned from MongoDB: - Use the following syntax to specify the query: +.. code-block:: php - .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php - :language: php - :dedent: - :start-after: start-first - :end-before: end-first + SampleModel::where('', '') + ->skip() + ->get(); - .. tab:: Controller Method - :tabid: controller +To learn more about modifying how {+odm-long+} returns results, see the +:ref:`laravel-read-modify-results` guide. - To see the query results in the ``browse_movies`` view, edit the ``show()`` function - in the ``MovieController.php`` file to resemble the following code: +Limit Results +------------- - .. io-code-block:: - :copyable: true +The following code shows how to return only a specified number of +documents from MongoDB: - .. input:: - :language: php +.. code-block:: php - class MovieController - { - public function show() - { - $movie = Movie::where('runtime', 30) - ->orderBy('_id') - ->first(); + SampleModel::where('', '') + ->take() + ->get(); - return view('browse_movies', [ - 'movies' => $movie - ]); - } - } +To learn more about modifying how {+odm-long+} returns results, see the +:ref:`laravel-read-modify-results` guide. - .. output:: - :language: none - :visible: false +Sort Results +------------ - Title: Statues also Die - Year: 1953 - Runtime: 30 - IMDB Rating: 7.6 - IMDB Votes: 620 - Plot: A documentary of black art. +The following code shows how to set a sort order on results returned +from MongoDB: -.. tip:: +.. code-block:: php - To learn more about the ``orderBy()`` method, see the - :ref:`laravel-sort` section of this guide. + SampleModel::where('field name', '') + ->orderBy('') + ->get(); -.. _laravel-read-pref: +To learn more about modifying how {+odm-long+} returns results, see the +:ref:`laravel-read-modify-results` guide. Set a Read Preference -~~~~~~~~~~~~~~~~~~~~~ +--------------------- -To specify which replica set members receive your read operations, -set a read preference by using the ``readPreference()`` method. +The following code shows how to set a read preference when performing a +find operation: -The ``readPreference()`` method accepts the following parameters: - -- ``mode``: *(Required)* A string value specifying the read preference - mode. - -- ``tagSets``: *(Optional)* An array value specifying key-value tags that correspond to - certain replica set members. - -- ``options``: *(Optional)* An array value specifying additional read preference options. +.. code-block:: php -.. tip:: + SampleModel::where('field name', '') + ->readPreference(ReadPreference::SECONDARY_PREFERRED) + ->get(); - To view a full list of available read preference modes and options, see - :php:`MongoDB\Driver\ReadPreference::__construct ` - in the MongoDB PHP extension documentation. - -The following example queries for documents in which the value of the ``title`` -field is ``"Carrie"`` and sets the read preference to ``ReadPreference::SECONDARY_PREFERRED``. -As a result, the query retrieves the results from secondary replica set -members or the primary member if no secondaries are available: - -.. tabs:: - - .. tab:: Query Syntax - :tabid: query-syntax - - Use the following syntax to specify the query: - - .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php - :language: php - :dedent: - :start-after: start-read-pref - :end-before: end-read-pref - - .. tab:: Controller Method - :tabid: controller - - To see the query results in the ``browse_movies`` view, edit the ``show()`` function - in the ``MovieController.php`` file to resemble the following code: - - .. io-code-block:: - :copyable: true - - .. input:: - :language: php - - class MovieController - { - public function show() - { - $movies = Movie::where('title', 'Carrie') - ->readPreference(ReadPreference::SECONDARY_PREFERRED) - ->get(); - - return view('browse_movies', [ - 'movies' => $movies - ]); - } - } - - .. output:: - :language: none - :visible: false - - Title: Carrie - Year: 1952 - Runtime: 118 - IMDB Rating: 7.5 - IMDB Votes: 1458 - Plot: Carrie boards the train to Chicago with big ambitions. She gets a - job stitching shoes and her sister's husband takes almost all of her pay - for room and board. Then she injures a finger and ... - - Title: Carrie - Year: 1976 - Runtime: 98 - IMDB Rating: 7.4 - IMDB Votes: 115528 - Plot: A shy, outcast 17-year old girl is humiliated by her classmates for the - last time. - - Title: Carrie - Year: 2002 - Runtime: 132 - IMDB Rating: 5.5 - IMDB Votes: 7412 - Plot: Carrie White is a lonely and painfully shy teenage girl with telekinetic - powers who is slowly pushed to the edge of insanity by frequent bullying from - both her classmates and her domineering, religious mother. - - Title: Carrie - Year: 2013 - Runtime: 100 - IMDB Rating: 6 - IMDB Votes: 98171 - Plot: A reimagining of the classic horror tale about Carrie White, a shy girl - outcast by her peers and sheltered by her deeply religious mother, who unleashes - telekinetic terror on her small town after being pushed too far at her senior prom. +To learn more about read preferences, see the :ref:`laravel-read-pref` +guide. diff --git a/docs/fundamentals/read-operations/modify-results.txt b/docs/fundamentals/read-operations/modify-results.txt new file mode 100644 index 000000000..fd67422ae --- /dev/null +++ b/docs/fundamentals/read-operations/modify-results.txt @@ -0,0 +1,227 @@ +.. _laravel-modify-find: +.. _laravel-read-modify-results: + +==================== +Modify Query Results +==================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: filter, criteria, CRUD, code example + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to customize the way that {+odm-long+} +returns results from queries. You can modify the results of a find +operation by chaining more methods to the ``where()`` method. + +The following sections demonstrate how to modify the behavior of the +``where()`` method: + +- :ref:`laravel-skip-limit` uses the ``skip()`` method to set the number of documents + to skip and the ``take()`` method to set the total number of documents to return +- :ref:`laravel-sort` uses the ``orderBy()`` method to return query + results in a specified order based on field values + +To learn more about Eloquent models in the {+odm-short+}, see the +:ref:`laravel-eloquent-models` section. + +.. include:: /includes/fundamentals/read-operations/before-you-get-started.rst + +.. _laravel-skip-limit: + +Skip and Limit Results +---------------------- + +This example queries for documents in which the ``year`` value is ``1999``. +The operation skips the first ``2`` matching documents and outputs a total of ``3`` +documents. + +.. tabs:: + + .. tab:: Query Syntax + :tabid: query-syntax + + Use the following syntax to specify the query: + + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-skip-limit + :end-before: end-skip-limit + + .. tab:: Controller Method + :tabid: controller + + To see the query results in the ``browse_movies`` view, edit the ``show()`` function + in the ``MovieController.php`` file to resemble the following code: + + .. io-code-block:: + :copyable: true + + .. input:: + :language: php + + class MovieController + { + public function show() + { + $movies = Movie::where('year', 1999) + ->skip(2) + ->take(3) + ->get(); + + return view('browse_movies', [ + 'movies' => $movies + ]); + } + } + + .. output:: + :language: none + :visible: false + + Title: Three Kings + Year: 1999 + Runtime: 114 + IMDB Rating: 7.2 + IMDB Votes: 130677 + Plot: In the aftermath of the Persian Gulf War, 4 soldiers set out to steal gold + that was stolen from Kuwait, but they discover people who desperately need their help. + + Title: Toy Story 2 + Year: 1999 + Runtime: 92 + IMDB Rating: 7.9 + IMDB Votes: 346655 + Plot: When Woody is stolen by a toy collector, Buzz and his friends vow to rescue him, + but Woody finds the idea of immortality in a museum tempting. + + Title: Beowulf + Year: 1999 + Runtime: 95 + IMDB Rating: 4 + IMDB Votes: 9296 + Plot: A sci-fi update of the famous 6th Century poem. In a besieged land, Beowulf must + battle against the hideous creature Grendel and his vengeance seeking mother. + +.. _laravel-sort: + +Sort Query Results +------------------ + +To order query results based on the values of specified fields, use the ``where()`` method +followed by the ``orderBy()`` method. + +You can set an **ascending** or **descending** sort direction on +results. By default, the ``orderBy()`` method sets an ascending sort on +the supplied field name, but you can explicitly specify an ascending +sort by passing ``"asc"`` as the second parameter. To +specify a descending sort, pass ``"desc"`` as the second parameter. + +If your documents contain duplicate values in a specific field, you can +handle the tie by specifying more fields to sort on. This ensures consistent +results if the other fields contain unique values. + +This example queries for documents in which the value of the ``countries`` field contains +``"Indonesia"`` and orders results first by an ascending sort on the +``year`` field, then a descending sort on the ``title`` field. + +.. tabs:: + + .. tab:: Query Syntax + :tabid: query-syntax + + Use the following syntax to specify the query: + + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-sort + :end-before: end-sort + + .. tab:: Controller Method + :tabid: controller + + To see the query results in the ``browse_movies`` view, edit the ``show()`` function + in the ``MovieController.php`` file to resemble the following code: + + .. io-code-block:: + :copyable: true + + .. input:: + :language: php + + class MovieController + { + public function show() + { + $movies = Movie::where('countries', 'Indonesia') + ->orderBy('year') + ->orderBy('title', 'desc') + ->get(); + + return view('browse_movies', [ + 'movies' => $movies + ]); + } + } + + .. output:: + :language: none + :visible: false + + Title: Joni's Promise + Year: 2005 + Runtime: 83 + IMDB Rating: 7.6 + IMDB Votes: 702 + Plot: A film delivery man promises ... + + Title: Gie + Year: 2005 + Runtime: 147 + IMDB Rating: 7.5 + IMDB Votes: 470 + Plot: Soe Hok Gie is an activist who lived in the sixties ... + + Title: Requiem from Java + Year: 2006 + Runtime: 120 + IMDB Rating: 6.6 + IMDB Votes: 316 + Plot: Setyo (Martinus Miroto) and Siti (Artika Sari Dewi) + are young married couple ... + + ... + +.. tip:: + + To learn more about sorting, see the following resources: + + - :manual:`Natural order ` + in the {+server-docs-name+} glossary + - `Ordering, Grouping, Limit, and Offset `__ + in the Laravel documentation + +Additional Information +---------------------- + +To view runnable code examples that demonstrate how to perform find +operations by using the {+odm-short+}, see the following usage examples: + +- :ref:`laravel-find-one-usage` +- :ref:`laravel-find-usage` + +To learn how to retrieve data based on filter criteria, see the +:ref:`laravel-fundamentals-read-retrieve` guide. diff --git a/docs/fundamentals/read-operations/read-pref.txt b/docs/fundamentals/read-operations/read-pref.txt new file mode 100644 index 000000000..075c74380 --- /dev/null +++ b/docs/fundamentals/read-operations/read-pref.txt @@ -0,0 +1,141 @@ +.. _laravel-read-pref: + +===================== +Set a Read Preference +===================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: consistency, durability, CRUD, code example + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to set a read preference when +performing find operations with {+odm-long+}. + +.. include:: /includes/fundamentals/read-operations/before-you-get-started.rst + +Set a Read Preference +--------------------- + +To specify which replica set members receive your read operations, +set a read preference by using the ``readPreference()`` method. + +The ``readPreference()`` method accepts the following parameters: + +- ``mode``: *(Required)* A string value specifying the read preference + mode. + +- ``tagSets``: *(Optional)* An array value specifying key-value tags that correspond to + certain replica set members. + +- ``options``: *(Optional)* An array value specifying additional read preference options. + +.. tip:: + + To view a full list of available read preference modes and options, see + :php:`MongoDB\Driver\ReadPreference::__construct ` + in the MongoDB PHP extension documentation. + +The following example queries for documents in which the value of the ``title`` +field is ``"Carrie"`` and sets the read preference to ``ReadPreference::SECONDARY_PREFERRED``. +As a result, the query retrieves the results from secondary replica set +members or the primary member if no secondaries are available: + +.. tabs:: + + .. tab:: Query Syntax + :tabid: query-syntax + + Use the following syntax to specify the query: + + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-read-pref + :end-before: end-read-pref + + .. tab:: Controller Method + :tabid: controller + + To see the query results in the ``browse_movies`` view, edit the ``show()`` function + in the ``MovieController.php`` file to resemble the following code: + + .. io-code-block:: + :copyable: true + + .. input:: + :language: php + + class MovieController + { + public function show() + { + $movies = Movie::where('title', 'Carrie') + ->readPreference(ReadPreference::SECONDARY_PREFERRED) + ->get(); + + return view('browse_movies', [ + 'movies' => $movies + ]); + } + } + + .. output:: + :language: none + :visible: false + + Title: Carrie + Year: 1952 + Runtime: 118 + IMDB Rating: 7.5 + IMDB Votes: 1458 + Plot: Carrie boards the train to Chicago with big ambitions. She gets a + job stitching shoes and her sister's husband takes almost all of her pay + for room and board. Then she injures a finger and ... + + Title: Carrie + Year: 1976 + Runtime: 98 + IMDB Rating: 7.4 + IMDB Votes: 115528 + Plot: A shy, outcast 17-year old girl is humiliated by her classmates for the + last time. + + Title: Carrie + Year: 2002 + Runtime: 132 + IMDB Rating: 5.5 + IMDB Votes: 7412 + Plot: Carrie White is a lonely and painfully shy teenage girl with telekinetic + powers who is slowly pushed to the edge of insanity by frequent bullying from + both her classmates and her domineering, religious mother. + + Title: Carrie + Year: 2013 + Runtime: 100 + IMDB Rating: 6 + IMDB Votes: 98171 + Plot: A reimagining of the classic horror tale about Carrie White, a shy girl + outcast by her peers and sheltered by her deeply religious mother, who unleashes + telekinetic terror on her small town after being pushed too + far at her senior prom. + +Additional Information +---------------------- + +To learn how to retrieve data based on filter criteria, see the +:ref:`laravel-fundamentals-read-retrieve` guide. + +To learn how to modify the way that the {+odm-short+} returns results, +see the :ref:`laravel-read-modify-results` guide. diff --git a/docs/fundamentals/read-operations/retrieve.txt b/docs/fundamentals/read-operations/retrieve.txt new file mode 100644 index 000000000..a4ca31091 --- /dev/null +++ b/docs/fundamentals/read-operations/retrieve.txt @@ -0,0 +1,304 @@ +.. _laravel-fundamentals-retrieve-documents: +.. _laravel-fundamentals-read-retrieve: + +============= +Retrieve Data +============= + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: filter, criteria, CRUD, code example + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to retrieve data from MongoDB +collections by using {+odm-long+}. This guide describes the Eloquent +model methods that you can use to retrieve data and provides examples +of different types of find operations. + +To learn more about Eloquent models in the {+odm-short+}, see the +:ref:`laravel-eloquent-models` section. + +.. include:: /includes/fundamentals/read-operations/before-you-get-started.rst + +.. _laravel-retrieve-matching: + +Retrieve Documents that Match a Query +------------------------------------- + +You can use Laravel's Eloquent object-relational mapper (ORM) to create models +that represent MongoDB collections and chain methods on them to specify +query criteria. + +To retrieve documents that match a set of criteria, call the ``where()`` +method on the collection's corresponding Eloquent model, then pass a query +filter to the method. + +.. tip:: Retrieve One Document + + The ``where()`` method retrieves all matching documents. To retrieve + the first matching document, you can chain the ``first()`` method. To + learn more and view an example, see the :ref:`laravel-retrieve-one` + section of this guide. + +A query filter specifies field value requirements and instructs the find +operation to return only documents that meet these requirements. + +You can use one of the following ``where()`` method calls to build a query: + +- ``where('', )`` builds a query that matches documents in + which the target field has the exact specified value + +- ``where('', '', )`` builds a query + that matches documents in which the target field's value meets the comparison + criteria + +To apply multiple sets of criteria to the find operation, you can chain a series +of ``where()`` methods together. + +After building your query by using the ``where()`` method, chain the ``get()`` +method to retrieve the query results. + +This example calls two ``where()`` methods on the ``Movie`` Eloquent model to +retrieve documents that meet the following criteria: + +- ``year`` field has a value of ``2010`` +- ``imdb.rating`` nested field has a value greater than ``8.5`` + +.. tabs:: + + .. tab:: Query Syntax + :tabid: query-syntax + + Use the following syntax to specify the query: + + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-query + :end-before: end-query + + .. tab:: Controller Method + :tabid: controller + + To see the query results in the ``browse_movies`` view, edit the ``show()`` function + in the ``MovieController.php`` file to resemble the following code: + + .. io-code-block:: + :copyable: true + + .. input:: + :language: php + + class MovieController + { + public function show() + { + $movies = Movie::where('year', 2010) + ->where('imdb.rating', '>', 8.5) + ->get(); + + return view('browse_movies', [ + 'movies' => $movies + ]); + } + } + + .. output:: + :language: none + :visible: false + + Title: Inception + Year: 2010 + Runtime: 148 + IMDB Rating: 8.8 + IMDB Votes: 1294646 + Plot: A thief who steals corporate secrets through use of dream-sharing + technology is given the inverse task of planting an idea into the mind of a CEO. + + Title: Senna + Year: 2010 + Runtime: 106 + IMDB Rating: 8.6 + IMDB Votes: 41904 + Plot: A documentary on Brazilian Formula One racing driver Ayrton Senna, who won the + F1 world championship three times before his death at age 34. + +To learn how to query by using the Laravel query builder instead of the +Eloquent ORM, see the :ref:`laravel-query-builder` page. + +Match Array Field Elements +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can specify a query filter to match array field elements when +retrieving documents. If your documents contain an array field, you can +match documents based on if the value contains all or some specified +array elements. + +You can use one of the following ``where()`` method calls to build a +query on an array field: + +- ``where('', )`` builds a query that matches documents in + which the array field value is exactly the specified array + +- ``where('', 'in', )`` builds a query + that matches documents in which the array field value contains one or + more of the specified array elements + +After building your query by using the ``where()`` method, chain the ``get()`` +method to retrieve the query results. + +Select from the following :guilabel:`Exact Array Match` and +:guilabel:`Element Match` tabs to view the query syntax for each pattern: + +.. tabs:: + + .. tab:: Exact Array Match + :tabid: exact-array + + This example retrieves documents in which the ``countries`` array is + exactly ``['Indonesia', 'Canada']``: + + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-exact-array + :end-before: end-exact-array + + .. tab:: Element Match + :tabid: element-match + + This example retrieves documents in which the ``countries`` array + contains one of the values in the array ``['Canada', 'Egypt']``: + + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-elem-match + :end-before: end-elem-match + +To learn how to query array fields by using the Laravel query builder instead of the +Eloquent ORM, see the :ref:`laravel-query-builder-elemMatch` section in +the Query Builder guide. + +.. _laravel-retrieve-one: + +Retrieve the First Result +------------------------- + +To retrieve the first document that matches a set of criteria, use the ``where()`` method +followed by the ``first()`` method. + +Chain the ``orderBy()`` method to ``first()`` to get consistent results when you query on a unique +value. If you omit the ``orderBy()`` method, MongoDB returns the matching documents according to +the documents' natural order, or as they appear in the collection. + +This example queries for documents in which the value of the ``runtime`` field is +``30`` and returns the first matching document according to the value of the ``_id`` +field. + +.. tabs:: + + .. tab:: Query Syntax + :tabid: query-syntax + + Use the following syntax to specify the query: + + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-first + :end-before: end-first + + .. tab:: Controller Method + :tabid: controller + + To see the query results in the ``browse_movies`` view, edit the ``show()`` function + in the ``MovieController.php`` file to resemble the following code: + + .. io-code-block:: + :copyable: true + + .. input:: + :language: php + + class MovieController + { + public function show() + { + $movie = Movie::where('runtime', 30) + ->orderBy('_id') + ->first(); + + return view('browse_movies', [ + 'movies' => $movie + ]); + } + } + + .. output:: + :language: none + :visible: false + + Title: Statues also Die + Year: 1953 + Runtime: 30 + IMDB Rating: 7.6 + IMDB Votes: 620 + Plot: A documentary of black art. + +.. tip:: + + To learn more about the ``orderBy()`` method, see the + :ref:`laravel-sort` section of the Modify Query Results guide. + +.. _laravel-retrieve-all: + +Retrieve All Documents in a Collection +-------------------------------------- + +You can retrieve all documents in a collection by omitting the query filter. +To return the documents, call the ``get()`` method on an Eloquent model that +represents your collection. Alternatively, you can use the ``get()`` method's +alias ``all()`` to perform the same operation. + +Use the following syntax to run a find operation that matches all documents: + +.. code-block:: php + + $movies = Movie::get(); + +.. warning:: + + The ``movies`` collection in the Atlas sample dataset contains a large amount of data. + Retrieving and displaying all documents in this collection might cause your web + application to time out. + + To avoid this issue, specify a document limit by using the ``take()`` method. For + more information about ``take()``, see the :ref:`laravel-modify-find` + section of the Modify Query Output guide. + +Additional Information +---------------------- + +To view runnable code examples that demonstrate how to perform find +operations by using the {+odm-short+}, see the following usage examples: + +- :ref:`laravel-find-one-usage` +- :ref:`laravel-find-usage` + +To learn how to insert data into MongoDB, see the +:ref:`laravel-fundamentals-write-ops` guide. + +To learn how to modify the way that the {+odm-short+} returns results, +see the :ref:`laravel-read-modify-results` guide. diff --git a/docs/fundamentals/read-operations/search-text.txt b/docs/fundamentals/read-operations/search-text.txt new file mode 100644 index 000000000..4b465e737 --- /dev/null +++ b/docs/fundamentals/read-operations/search-text.txt @@ -0,0 +1,157 @@ +.. _laravel-fundamentals-search-text: +.. _laravel-retrieve-text-search: + +=========== +Search Text +=========== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: filter, string, CRUD, code example + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to run a **text search** by using +{+odm-long+}. + +You can use a text search to retrieve documents that contain a term or a +phrase in a specified field. A term is a sequence of characters that +excludes whitespace characters. A phrase is a sequence of terms with any +number of whitespace characters. + +This guide describes the Eloquent model methods that you can use to +search text and provides examples. To learn more about Eloquent models +in the {+odm-short+}, see the :ref:`laravel-eloquent-models` section. + +.. include:: /includes/fundamentals/read-operations/before-you-get-started.rst + +Search Text Fields +------------------ + +Before you can perform a text search, you must create a :manual:`text +index ` on +the text-valued field. To learn more about creating +indexes, see the :ref:`laravel-eloquent-indexes` section of the +Schema Builder guide. + +You can perform a text search by using the :manual:`$text +` operator followed +by the ``$search`` field in your query filter that you pass to the +``where()`` method. The ``$text`` operator performs a text search on the +text-indexed fields. The ``$search`` field specifies the text to search for. + +After building your query by using the ``where()`` method, chain the ``get()`` +method to retrieve the query results. + +This example calls the ``where()`` method on the ``Movie`` Eloquent model to +retrieve documents in which the ``plot`` field contains the phrase +``"love story"``. To perform this text search, the collection must have +a text index on the ``plot`` field. + +.. tabs:: + + .. tab:: Query Syntax + :tabid: query-syntax + + Use the following syntax to specify the query: + + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-text + :end-before: end-text + + .. tab:: Controller Method + :tabid: controller + + To see the query results in the ``browse_movies`` view, edit the ``show()`` function + in the ``MovieController.php`` file to resemble the following code: + + .. io-code-block:: + :copyable: true + + .. input:: + :language: php + + class MovieController + { + public function show() + { + $movies = Movie::where('$text', ['$search' => '"love story"']) + ->get(); + + return view('browse_movies', [ + 'movies' => $movies + ]); + } + } + + .. output:: + :language: none + :visible: false + + Title: Cafè de Flore + Year: 2011 + Runtime: 120 + IMDB Rating: 7.4 + IMDB Votes: 9663 + Plot: A love story between a man and woman ... + + Title: Paheli + Year: 2005 + Runtime: 140 + IMDB Rating: 6.7 + IMDB Votes: 8909 + Plot: A folk tale - supernatural love story about a ghost ... + + Title: Por un puèado de besos + Year: 2014 + Runtime: 98 + IMDB Rating: 6.1 + IMDB Votes: 223 + Plot: A girl. A boy. A love story ... + + ... + +Search Score +------------ + +A text search assigns a numerical :manual:`text score ` to indicate how closely +each result matches the string in your query filter. You can sort the +results by relevance by using the ``orderBy()`` method to sort on the +``textScore`` metadata field. You can access this metadata by using the +:manual:`$meta ` operator: + +.. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-text-relevance + :end-before: end-text-relevance + :emphasize-lines: 2 + +.. tip:: + + To learn more about the ``orderBy()`` method, see the + :ref:`laravel-sort` section of the Modify Query Output guide. + +Additional Information +---------------------- + +To view runnable code examples that demonstrate how to perform find +operations by using the {+odm-short+}, see the following usage examples: + +- :ref:`laravel-find-one-usage` +- :ref:`laravel-find-usage` + +To learn how to retrieve data based on filter criteria, see the +:ref:`laravel-fundamentals-read-retrieve` guide. diff --git a/docs/fundamentals/write-operations.txt b/docs/fundamentals/write-operations.txt index 0a4d8a6ca..1b2f163be 100644 --- a/docs/fundamentals/write-operations.txt +++ b/docs/fundamentals/write-operations.txt @@ -133,8 +133,7 @@ matching document doesn't exist: ['upsert' => true], ); - /* Or, use the upsert() method. */ - + // Or, use the upsert() method. SampleModel::upsert( [], '', diff --git a/docs/includes/fundamentals/read-operations/before-you-get-started.rst b/docs/includes/fundamentals/read-operations/before-you-get-started.rst new file mode 100644 index 000000000..9555856fc --- /dev/null +++ b/docs/includes/fundamentals/read-operations/before-you-get-started.rst @@ -0,0 +1,15 @@ +Before You Get Started +---------------------- + +To run the code examples in this guide, complete the :ref:`Quick Start ` +tutorial. This tutorial provides instructions on setting up a MongoDB Atlas instance with +sample data and creating the following files in your Laravel web application: + +- ``Movie.php`` file, which contains a ``Movie`` model to represent documents in the ``movies`` + collection +- ``MovieController.php`` file, which contains a ``show()`` function to run database operations +- ``browse_movies.blade.php`` file, which contains HTML code to display the results of database + operations + +The following sections describe how to edit the files in your Laravel application to run +the find operation code examples and view the expected output. From 937fb27f6e1c75f1e2fd5e3b1dd11f86f5bd1081 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Wed, 5 Mar 2025 09:44:34 -0500 Subject: [PATCH 438/446] DOCSP-46479: document Scout integration (#3261) * DOCSP-46479: document Scout integration * NR PR fixes 1 * fix spacing * fix spacing * fix spacing * fix spacing * NR PR fixes 2 * JT tech comment * fix spacing * JT tech review 1 * JT tech review 1 * custom index * link to atlas doc --- docs/index.txt | 2 + docs/scout.txt | 259 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 261 insertions(+) create mode 100644 docs/scout.txt diff --git a/docs/index.txt b/docs/index.txt index 2937968a7..1eb1d8657 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -22,6 +22,7 @@ Databases & Collections User Authentication Cache & Locks + Scout Integration HTTP Sessions Queues Transactions @@ -86,6 +87,7 @@ see the following content: - :ref:`laravel-aggregation-builder` - :ref:`laravel-user-authentication` - :ref:`laravel-cache` +- :ref:`laravel-scout` - :ref:`laravel-sessions` - :ref:`laravel-queues` - :ref:`laravel-transactions` diff --git a/docs/scout.txt b/docs/scout.txt new file mode 100644 index 000000000..8f409148b --- /dev/null +++ b/docs/scout.txt @@ -0,0 +1,259 @@ +.. _laravel-scout: + +=========================== +Full-Text Search with Scout +=========================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: php framework, odm, code example, text search, atlas + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to use the Laravel Scout feature in +your {+odm-long+} application. Scout enables you to implement full-text +search on your Eloquent models. To learn more, see `Laravel Scout +`__ in the +Laravel documentation. + +The Scout integration for {+odm-long+} provides the following +functionality: + +- Provides an abstraction to create :atlas:`Atlas Search indexes + ` from any MongoDB or SQL model. + + .. important:: Use Schema Builder to Create Search Indexes + + If your documents are already in MongoDB, create Search indexes + by using {+php-library+} or ``Schema`` builder methods to improve + search query performance. To learn more about creating Search + indexes, see the :ref:`laravel-as-index` section of the Atlas + Search guide. + +- Enables you to automatically replicate data from MongoDB into a + search engine such as `Meilisearch `__ + or `Algolia `__. You can use a MongoDB Eloquent + model as the source to import and index. To learn more about indexing + to a search engine, see the `Indexing + `__ + section of the Laravel Scout documentation. + +.. important:: Deployment Compatibility + + You can use Laravel Scout only when you connect to MongoDB Atlas + deployments. This feature is not available for self-managed + deployments. + +Scout for Atlas Search Tutorial +------------------------------- + +This tutorial demonstrates how to use Scout to compound and index +documents for MongoDB Atlas Search from Eloquent models (MongoDB or SQL). + +.. procedure:: + :style: connected + + .. step:: Install the Scout package + + Before you can use Scout in your application, run the following + command from your application's root directory to install the + ``laravel/scout`` package: + + .. code-block:: bash + + composer require laravel/scout + + .. step:: Add the Searchable trait to your model + + Add the ``Laravel\Scout\Searchable`` trait to an Eloquent model to make + it searchable. The following example adds this trait to the ``Movie`` + model, which represents documents in the ``sample_mflix.movies`` + collection: + + .. code-block:: php + :emphasize-lines: 6, 10 + + `__ + section of the Laravel Scout documentation. + + .. step:: Configure Scout in your application + + Ensure that your application is configured to use MongoDB as its + database connection. To learn how to configure MongoDB, see the + :ref:`laravel-quick-start-connect-to-mongodb` section of the Quick Start + guide. + + To configure Scout in your application, create a file named + ``scout.php`` in your application's ``config`` directory. Paste the + following code into the file to configure Scout: + + .. code-block:: php + :caption: config/scout.php + + env('SCOUT_DRIVER', 'mongodb'), + 'mongodb' => [ + 'connection' => env('SCOUT_MONGODB_CONNECTION', 'mongodb'), + ], + 'prefix' => env('SCOUT_PREFIX', 'scout_'), + ]; + + The preceding code specifies the following configuration: + + - Uses the value of the ``SCOUT_DRIVER`` environment variable as + the default search driver, or ``mongodb`` if the environment + variable is not set + + - Specifies ``scout_`` as the prefix for the collection name of the + searchable collection + + In the ``config/scout.php`` file, you can also specify a custom + Atlas Search index definition. To learn more, see the :ref:`custom + index definition example ` in the + following step. + + Set the following environment variable in your application's + ``.env`` file to select ``mongodb`` as the default search driver: + + .. code-block:: none + :caption: .env + + SCOUT_DRIVER=mongodb + + .. tip:: Queueing + + When using Scout, consider configuring a queue driver to reduce + response times for your application's web interface. To learn more, + see the `Queuing section + `__ + of the Laravel Scout documentation and the :ref:`laravel-queues` guide. + + .. step:: Create the Atlas Search index + + After you configure Scout and set your default search driver, you can + create your searchable collection and search index by running the + following command from your application's root directory: + + .. code-block:: bash + + php artisan scout:index 'App\Models\Movie' + + Because you set MongoDB as the default search driver, the preceding + command creates the search collection with an Atlas Search index in your + MongoDB database. The collection is named ``scout_movies``, based on the prefix + set in the preceding step. The Atlas Search index is named ``scout`` + and has the following configuration by default: + + .. code-block:: json + + { + "mappings": { + "dynamic": true + } + } + + .. _laravel-scout-custom-index: + + To customize the index definition, add the ``index-definitions`` + configuration to the ``mongodb`` entry in your + ``config/scout.php`` file. The following code demonstrates how to + specify a custom index definition to create on the + ``scout_movies`` collection: + + .. code-block:: php + + 'mongodb' => [ + 'connection' => env('SCOUT_MONGODB_CONNECTION', 'mongodb'), + 'index-definitions' => [ + 'scout_movies' => [ + 'mappings' => [ + 'dynamic' => false, + 'fields' => ['title' => ['type' => 'string']] + ] + ] + ] + ], ... + + To learn more about defining Atlas Search index definitions, see the + :atlas:`Define Field Mappings + ` guide in the Atlas + documentation. + + .. note:: + + MongoDB can take up to a minute to create and finalize + an Atlas Search index, so the ``scout:index`` command might not + return a success message immediately. + + .. step:: Import data into the searchable collection + + You can use Scout to replicate data from a source collection + modeled by your Eloquent model into a searchable collection. The + following command replicates and indexes data from the ``movies`` + collection into the ``scout_movies`` collection indexed in the + preceding step: + + .. code-block:: bash + + php artisan scout:import 'App\Models\Movie' + + The documents are automatically indexed for Atlas Search queries. + + .. tip:: Select Fields to Import + + You might not need all the fields from your source documents in your + searchable collection. Limiting the amount of data you replicate can improve + your application's speed and performance. + + You can select specific fields to import by defining the + ``toSearchableArray()`` method in your Eloquent model class. The + following code demonstrates how to define ``toSearchableArray()`` to + select only the ``plot`` and ``title`` fields for replication: + + .. code-block:: php + + class Movie extends Model + { + .... + public function toSearchableArray(): array + { + return [ + 'plot' => $this->plot, + 'title' => $this->title, + ]; + } + } + +After completing these steps, you can perform Atlas Search queries on the +``scout_movies`` collection in your {+odm-long+} application. To learn +how to perform full-text searches, see the :ref:`laravel-atlas-search` +guide. From 536327d0ef77d5fc3d8e421f5e8dd35e972daa45 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Wed, 5 Mar 2025 11:09:19 -0500 Subject: [PATCH 439/446] DOCSP-48018: laravel 12 feature compat (#3304) * DOCSP-48018: laravel 12 feature compat * small fixes * JT fix --- docs/eloquent-models/model-class.txt | 7 ++++--- docs/feature-compatibility.txt | 19 +++++++++++++------ 2 files changed, 17 insertions(+), 9 deletions(-) diff --git a/docs/eloquent-models/model-class.txt b/docs/eloquent-models/model-class.txt index a2a9861bc..6f686e88a 100644 --- a/docs/eloquent-models/model-class.txt +++ b/docs/eloquent-models/model-class.txt @@ -200,9 +200,10 @@ model attribute, stored in MongoDB as a :php:`MongoDB\\BSON\\UTCDateTime .. tip:: Casts in Laravel 11 - In Laravel 11, you can define a ``casts()`` method to specify data type conversions - instead of using the ``$casts`` attribute. The following code performs the same - conversion as the preceding example by using a ``casts()`` method: + Starting in Laravel 11, you can define a ``casts()`` method to + specify data type conversions instead of using the ``$casts`` + attribute. The following code performs the same conversion as the + preceding example by using a ``casts()`` method: .. code-block:: php diff --git a/docs/feature-compatibility.txt b/docs/feature-compatibility.txt index 57c8c7486..965be2ebb 100644 --- a/docs/feature-compatibility.txt +++ b/docs/feature-compatibility.txt @@ -21,7 +21,7 @@ Overview -------- This guide describes the Laravel features that are supported by -{+odm-long+}. This page discusses Laravel version 11.x feature +{+odm-long+}. This page discusses Laravel version 12.x feature availability in the {+odm-short+}. The following sections contain tables that describe whether individual @@ -32,6 +32,7 @@ Database Features .. list-table:: :header-rows: 1 + :widths: 40 60 * - Eloquent Feature - Availability @@ -63,6 +64,12 @@ Database Features * - Database Monitoring - *Unsupported* + * - Multi-database Support / Multiple Schemas + - *Unsupported* Laravel uses a dot separator (``.``) + between SQL schema and table names, but MongoDB allows ``.`` + characters within collection names, which might lead to + unexpected namespace parsing. + Query Features -------------- @@ -114,19 +121,19 @@ The following Eloquent methods are not supported in the {+odm-short+}: * - Unions - *Unsupported* - * - `Basic Where Clauses `__ + * - `Basic Where Clauses `__ - ✓ - * - `Additional Where Clauses `__ + * - `Additional Where Clauses `__ - ✓ * - Logical Grouping - ✓ - * - `Advanced Where Clauses `__ + * - `Advanced Where Clauses `__ - ✓ - * - `Subquery Where Clauses `__ + * - `Subquery Where Clauses `__ - *Unsupported* * - Ordering @@ -136,7 +143,7 @@ The following Eloquent methods are not supported in the {+odm-short+}: - *Unsupported* * - Grouping - - Partially supported, use :ref:`Aggregations `. + - Partially supported. Use :ref:`Aggregations `. * - Limit and Offset - ✓ From 89772e239af7d9d3f51d29816ace06a34ca260ef Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Thu, 6 Mar 2025 10:38:47 -0500 Subject: [PATCH 440/446] DOCSP-47950: Fix all operator section (#3308) * DOCSP-47950: Fix all operator section * review feedback --- docs/includes/query-builder/QueryBuilderTest.php | 2 +- docs/query-builder.txt | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index 574fe060f..3f7ea2274 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -351,7 +351,7 @@ public function testAll(): void { // begin query all $result = DB::table('movies') - ->where('movies', 'all', ['title', 'rated', 'imdb.rating']) + ->where('writers', 'all', ['Ben Affleck', 'Matt Damon']) ->get(); // end query all diff --git a/docs/query-builder.txt b/docs/query-builder.txt index c641323dc..68a9b2102 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -869,7 +869,8 @@ Contains All Fields Example The following example shows how to use the ``all`` query operator with the ``where()`` query builder method to match -documents that contain all the specified fields: +documents that have a ``writers`` array field containing all +the specified values: .. literalinclude:: /includes/query-builder/QueryBuilderTest.php :language: php From 4fd1b811d1b20eeaafde32f02c2501bf84b59d63 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Thu, 6 Mar 2025 16:17:17 -0500 Subject: [PATCH 441/446] Remove link to builder package/repo (#3312) --- docs/fundamentals/aggregation-builder.txt | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/fundamentals/aggregation-builder.txt b/docs/fundamentals/aggregation-builder.txt index 9ae31f0c1..47994ce9e 100644 --- a/docs/fundamentals/aggregation-builder.txt +++ b/docs/fundamentals/aggregation-builder.txt @@ -66,12 +66,6 @@ to build aggregation stages: - ``MongoDB\Builder\Query`` - ``MongoDB\Builder\Type`` -.. tip:: - - To learn more about builder classes, see the - :github:`mongodb/mongodb-php-builder ` - GitHub repository. - This section features the following examples that show how to use common aggregation stages: From 90ad73f7f93a0d86b7f0fa6c19653f1d666a746a Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 11 Mar 2025 09:17:12 +0100 Subject: [PATCH 442/446] Bump ramsey/composer-install from 3.0.0 to 3.1.0 (#3317) Bumps [ramsey/composer-install](https://github.com/ramsey/composer-install) from 3.0.0 to 3.1.0. - [Release notes](https://github.com/ramsey/composer-install/releases) - [Commits](https://github.com/ramsey/composer-install/compare/3.0.0...3.1.0) --- updated-dependencies: - dependency-name: ramsey/composer-install dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/coding-standards.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/coding-standards.yml b/.github/workflows/coding-standards.yml index 24d397294..1d7b89b2d 100644 --- a/.github/workflows/coding-standards.yml +++ b/.github/workflows/coding-standards.yml @@ -49,7 +49,7 @@ jobs: run: "php --ri mongodb" - name: "Install dependencies with Composer" - uses: "ramsey/composer-install@3.0.0" + uses: "ramsey/composer-install@3.1.0" with: composer-options: "--no-suggest" From b91a3c5f9afc49e54426e834256e91249feaeb8d Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Tue, 11 Mar 2025 09:35:38 -0400 Subject: [PATCH 443/446] fix line spacing in feature compat doc (#3315) --- docs/feature-compatibility.txt | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/feature-compatibility.txt b/docs/feature-compatibility.txt index 965be2ebb..c36d30812 100644 --- a/docs/feature-compatibility.txt +++ b/docs/feature-compatibility.txt @@ -65,10 +65,11 @@ Database Features - *Unsupported* * - Multi-database Support / Multiple Schemas - - *Unsupported* Laravel uses a dot separator (``.``) - between SQL schema and table names, but MongoDB allows ``.`` - characters within collection names, which might lead to - unexpected namespace parsing. + - | *Unsupported* + | Laravel uses a dot separator (``.``) + between SQL schema and table names, but MongoDB allows ``.`` + characters within collection names, which might lead to + unexpected namespace parsing. Query Features -------------- From 1265bb1e9d5904e585822eb79e2d4d98c8254ed7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 31 Mar 2025 10:39:05 +0200 Subject: [PATCH 444/446] PHPORM-306 Test with MongoDB Driver v2 (#3319) --- .github/workflows/build-ci-atlas.yml | 23 ++- .github/workflows/build-ci.yml | 25 ++- .github/workflows/coding-standards.yml | 2 +- .github/workflows/static-analysis.yml | 17 +- composer.json | 4 +- src/Eloquent/Builder.php | 4 +- tests/QueryBuilderTest.php | 6 +- tests/Scout/ScoutEngineTest.php | 230 +++++++++++++------------ 8 files changed, 189 insertions(+), 122 deletions(-) diff --git a/.github/workflows/build-ci-atlas.yml b/.github/workflows/build-ci-atlas.yml index 30b4b06b1..339f8fc38 100644 --- a/.github/workflows/build-ci-atlas.yml +++ b/.github/workflows/build-ci-atlas.yml @@ -4,11 +4,15 @@ on: push: pull_request: +env: + MONGODB_EXT_V1: mongodb-1.21.0 + MONGODB_EXT_V2: mongodb-mongodb/mongo-php-driver@v2.x + jobs: build: runs-on: "${{ matrix.os }}" - name: "PHP ${{ matrix.php }} Laravel ${{ matrix.laravel }} Atlas" + name: "PHP/${{ matrix.php }} Laravel/${{ matrix.laravel }} Driver/${{ matrix.driver }}" strategy: matrix: @@ -21,6 +25,13 @@ jobs: laravel: - "11.*" - "12.*" + driver: + - 1 + include: + - php: "8.4" + laravel: "12.*" + os: "ubuntu-latest" + driver: 2 steps: - uses: "actions/checkout@v4" @@ -39,11 +50,19 @@ jobs: run: | docker exec --tty mongodb mongosh --eval "db.runCommand({ serverStatus: 1 })" + - name: Setup cache environment + id: extcache + uses: shivammathur/cache-extensions@v1 + with: + php-version: ${{ matrix.php }} + extensions: ${{ matrix.driver == 1 && env.MONGODB_EXT_V1 || env.MONGODB_EXT_V2 }} + key: "extcache-v1" + - name: "Installing php" uses: "shivammathur/setup-php@v2" with: php-version: ${{ matrix.php }} - extensions: "curl,mbstring,xdebug" + extensions: "curl,mbstring,xdebug,${{ matrix.driver == 1 && env.MONGODB_EXT_V1 || env.MONGODB_EXT_V2 }}" coverage: "xdebug" tools: "composer" diff --git a/.github/workflows/build-ci.yml b/.github/workflows/build-ci.yml index 659c316d3..bc799c70e 100644 --- a/.github/workflows/build-ci.yml +++ b/.github/workflows/build-ci.yml @@ -4,11 +4,15 @@ on: push: pull_request: +env: + MONGODB_EXT_V1: mongodb-1.21.0 + MONGODB_EXT_V2: mongodb-mongodb/mongo-php-driver@v2.x + jobs: build: runs-on: "${{ matrix.os }}" - name: "PHP ${{ matrix.php }} Laravel ${{ matrix.laravel }} MongoDB ${{ matrix.mongodb }} ${{ matrix.mode }}" + name: "PHP/${{ matrix.php }} Laravel/${{ matrix.laravel }} Driver/${{ matrix.driver }} Server/${{ matrix.mongodb }} ${{ matrix.mode }}" strategy: matrix: @@ -29,12 +33,21 @@ jobs: - "10.*" - "11.*" - "12.*" + driver: + - 1 include: - php: "8.1" laravel: "10.*" mongodb: "5.0" mode: "low-deps" os: "ubuntu-latest" + driver: 1.x + driver_version: "1.21.0" + - php: "8.4" + laravel: "12.*" + mongodb: "8.0" + os: "ubuntu-latest" + driver: 2 exclude: - php: "8.1" laravel: "11.*" @@ -59,11 +72,19 @@ jobs: if [ "${{ matrix.mongodb }}" = "4.4" ]; then MONGOSH_BIN="mongo"; else MONGOSH_BIN="mongosh"; fi docker exec --tty mongodb $MONGOSH_BIN --eval "db.runCommand({ serverStatus: 1 })" + - name: Setup cache environment + id: extcache + uses: shivammathur/cache-extensions@v1 + with: + php-version: ${{ matrix.php }} + extensions: ${{ matrix.driver == 1 && env.MONGODB_EXT_V1 || env.MONGODB_EXT_V2 }} + key: "extcache-v1" + - name: "Installing php" uses: "shivammathur/setup-php@v2" with: php-version: ${{ matrix.php }} - extensions: "curl,mbstring,xdebug" + extensions: "curl,mbstring,xdebug,${{ matrix.driver == 1 && env.MONGODB_EXT_V1 || env.MONGODB_EXT_V2 }}" coverage: "xdebug" tools: "composer" diff --git a/.github/workflows/coding-standards.yml b/.github/workflows/coding-standards.yml index 24d397294..946e84971 100644 --- a/.github/workflows/coding-standards.yml +++ b/.github/workflows/coding-standards.yml @@ -5,7 +5,7 @@ on: pull_request: env: - PHP_VERSION: "8.2" + PHP_VERSION: "8.4" DRIVER_VERSION: "stable" jobs: diff --git a/.github/workflows/static-analysis.yml b/.github/workflows/static-analysis.yml index a66100d93..e0c907953 100644 --- a/.github/workflows/static-analysis.yml +++ b/.github/workflows/static-analysis.yml @@ -13,9 +13,12 @@ on: env: PHP_VERSION: "8.2" DRIVER_VERSION: "stable" + MONGODB_EXT_V1: mongodb-1.21.0 + MONGODB_EXT_V2: mongodb-mongodb/mongo-php-driver@v2.x jobs: phpstan: + name: "PHP/${{ matrix.php }} Driver/${{ matrix.driver }}" runs-on: "ubuntu-22.04" continue-on-error: true strategy: @@ -24,6 +27,10 @@ jobs: - '8.1' - '8.2' - '8.3' + - '8.4' + driver: + - 1 + - 2 steps: - name: Checkout uses: actions/checkout@v4 @@ -35,11 +42,19 @@ jobs: run: | echo CHECKED_OUT_SHA=$(git rev-parse HEAD) >> $GITHUB_ENV + - name: Setup cache environment + id: extcache + uses: shivammathur/cache-extensions@v1 + with: + php-version: ${{ matrix.php }} + extensions: ${{ matrix.driver == 1 && env.MONGODB_EXT_V1 || env.MONGODB_EXT_V2 }} + key: "extcache-v1" + - name: Setup PHP uses: shivammathur/setup-php@v2 with: php-version: ${{ matrix.php }} - extensions: curl, mbstring + extensions: "curl,mbstring,${{ matrix.driver == 1 && env.MONGODB_EXT_V1 || env.MONGODB_EXT_V2 }}" tools: composer:v2 coverage: none diff --git a/composer.json b/composer.json index a6f5470aa..2542b51bb 100644 --- a/composer.json +++ b/composer.json @@ -23,14 +23,14 @@ "license": "MIT", "require": { "php": "^8.1", - "ext-mongodb": "^1.21", + "ext-mongodb": "^1.21|^2", "composer-runtime-api": "^2.0.0", "illuminate/cache": "^10.36|^11|^12", "illuminate/container": "^10.0|^11|^12", "illuminate/database": "^10.30|^11|^12", "illuminate/events": "^10.0|^11|^12", "illuminate/support": "^10.0|^11|^12", - "mongodb/mongodb": "^1.21", + "mongodb/mongodb": "^1.21|^2", "symfony/http-foundation": "^6.4|^7" }, "require-dev": { diff --git a/src/Eloquent/Builder.php b/src/Eloquent/Builder.php index eedbe8712..f85570575 100644 --- a/src/Eloquent/Builder.php +++ b/src/Eloquent/Builder.php @@ -11,7 +11,7 @@ use MongoDB\Builder\Type\QueryInterface; use MongoDB\Builder\Type\SearchOperatorInterface; use MongoDB\Driver\CursorInterface; -use MongoDB\Driver\Exception\WriteException; +use MongoDB\Driver\Exception\BulkWriteException; use MongoDB\Laravel\Connection; use MongoDB\Laravel\Helpers\QueriesRelationships; use MongoDB\Laravel\Query\AggregationBuilder; @@ -285,7 +285,7 @@ public function createOrFirst(array $attributes = [], array $values = []) try { return $this->create(array_merge($attributes, $values)); - } catch (WriteException $e) { + } catch (BulkWriteException $e) { if ($e->getCode() === self::DUPLICATE_KEY_ERROR) { return $this->where($attributes)->first() ?? throw $e; } diff --git a/tests/QueryBuilderTest.php b/tests/QueryBuilderTest.php index 9592bbe7c..46beebab1 100644 --- a/tests/QueryBuilderTest.php +++ b/tests/QueryBuilderTest.php @@ -161,7 +161,7 @@ public function testFindWithTimeout() $id = DB::table('users')->insertGetId(['name' => 'John Doe']); $subscriber = new class implements CommandSubscriber { - public function commandStarted(CommandStartedEvent $event) + public function commandStarted(CommandStartedEvent $event): void { if ($event->getCommandName() !== 'find') { return; @@ -171,11 +171,11 @@ public function commandStarted(CommandStartedEvent $event) Assert::assertSame(1000, $event->getCommand()->maxTimeMS); } - public function commandFailed(CommandFailedEvent $event) + public function commandFailed(CommandFailedEvent $event): void { } - public function commandSucceeded(CommandSucceededEvent $event) + public function commandSucceeded(CommandSucceededEvent $event): void { } }; diff --git a/tests/Scout/ScoutEngineTest.php b/tests/Scout/ScoutEngineTest.php index 40d943ffb..7b254ec9c 100644 --- a/tests/Scout/ScoutEngineTest.php +++ b/tests/Scout/ScoutEngineTest.php @@ -11,13 +11,11 @@ use Laravel\Scout\Builder; use Laravel\Scout\Jobs\RemoveFromSearch; use LogicException; -use Mockery as m; use MongoDB\BSON\Document; use MongoDB\BSON\UTCDateTime; use MongoDB\Collection; use MongoDB\Database; use MongoDB\Driver\CursorInterface; -use MongoDB\Laravel\Eloquent\Model; use MongoDB\Laravel\Scout\ScoutEngine; use MongoDB\Laravel\Tests\Scout\Models\ScoutUser; use MongoDB\Laravel\Tests\Scout\Models\SearchableModel; @@ -36,7 +34,7 @@ class ScoutEngineTest extends TestCase public function testCreateIndexInvalidDefinition(): void { - $database = m::mock(Database::class); + $database = $this->createMock(Database::class); $engine = new ScoutEngine($database, false, ['collection_invalid' => ['foo' => 'bar']]); $this->expectException(LogicException::class); @@ -53,21 +51,22 @@ public function testCreateIndex(): void ], ]; - $database = m::mock(Database::class); - $collection = m::mock(Collection::class); - $database->shouldReceive('createCollection') - ->once() + $database = $this->createMock(Database::class); + $collection = $this->createMock(Collection::class); + $database->expects($this->once()) + ->method('createCollection') ->with($collectionName); - $database->shouldReceive('selectCollection') + $database->expects($this->once()) + ->method('selectCollection') ->with($collectionName) - ->andReturn($collection); - $collection->shouldReceive('createSearchIndex') - ->once() + ->willReturn($collection); + $collection->expects($this->once()) + ->method('createSearchIndex') ->with($expectedDefinition, ['name' => 'scout']); - $collection->shouldReceive('listSearchIndexes') - ->once() + $collection->expects($this->once()) + ->method('listSearchIndexes') ->with(['name' => 'scout', 'typeMap' => ['root' => 'bson']]) - ->andReturn(new ArrayIterator([Document::fromPHP(['name' => 'scout', 'status' => 'READY'])])); + ->willReturn(new ArrayIterator([Document::fromPHP(['name' => 'scout', 'status' => 'READY'])])); $engine = new ScoutEngine($database, false, []); $engine->createIndex($collectionName); @@ -90,21 +89,22 @@ public function testCreateIndexCustomDefinition(): void ], ]; - $database = m::mock(Database::class); - $collection = m::mock(Collection::class); - $database->shouldReceive('createCollection') - ->once() + $database = $this->createMock(Database::class); + $collection = $this->createMock(Collection::class); + $database->expects($this->once()) + ->method('createCollection') ->with($collectionName); - $database->shouldReceive('selectCollection') + $database->expects($this->once()) + ->method('selectCollection') ->with($collectionName) - ->andReturn($collection); - $collection->shouldReceive('createSearchIndex') - ->once() + ->willReturn($collection); + $collection->expects($this->once()) + ->method('createSearchIndex') ->with($expectedDefinition, ['name' => 'scout']); - $collection->shouldReceive('listSearchIndexes') - ->once() + $collection->expects($this->once()) + ->method('listSearchIndexes') ->with(['name' => 'scout', 'typeMap' => ['root' => 'bson']]) - ->andReturn(new ArrayIterator([Document::fromPHP(['name' => 'scout', 'status' => 'READY'])])); + ->willReturn(new ArrayIterator([Document::fromPHP(['name' => 'scout', 'status' => 'READY'])])); $engine = new ScoutEngine($database, false, [$collectionName => $expectedDefinition]); $engine->createIndex($collectionName); @@ -115,26 +115,28 @@ public function testCreateIndexCustomDefinition(): void public function testSearch(Closure $builder, array $expectedPipeline): void { $data = [['_id' => 'key_1', '__count' => 15], ['_id' => 'key_2', '__count' => 15]]; - $database = m::mock(Database::class); - $collection = m::mock(Collection::class); - $database->shouldReceive('selectCollection') + $database = $this->createMock(Database::class); + $collection = $this->createMock(Collection::class); + $database->expects($this->once()) + ->method('selectCollection') ->with('collection_searchable') - ->andReturn($collection); - $cursor = m::mock(CursorInterface::class); - $cursor->shouldReceive('setTypeMap')->once()->with(self::EXPECTED_TYPEMAP); - $cursor->shouldReceive('toArray')->once()->with()->andReturn($data); - - $collection->shouldReceive('getCollectionName') - ->zeroOrMoreTimes() - ->andReturn('collection_searchable'); - $collection->shouldReceive('aggregate') - ->once() - ->withArgs(function ($pipeline) use ($expectedPipeline) { - self::assertEquals($expectedPipeline, $pipeline); - - return true; - }) - ->andReturn($cursor); + ->willReturn($collection); + $cursor = $this->createMock(CursorInterface::class); + $cursor->expects($this->once()) + ->method('setTypeMap') + ->with(self::EXPECTED_TYPEMAP); + $cursor->expects($this->once()) + ->method('toArray') + ->with() + ->willReturn($data); + + $collection->expects($this->any()) + ->method('getCollectionName') + ->willReturn('collection_searchable'); + $collection->expects($this->once()) + ->method('aggregate') + ->with($expectedPipeline) + ->willReturn($cursor); $engine = new ScoutEngine($database, softDelete: false); $result = $engine->search($builder()); @@ -414,15 +416,15 @@ public function testPaginate() $perPage = 5; $page = 3; - $database = m::mock(Database::class); - $collection = m::mock(Collection::class); - $cursor = m::mock(CursorInterface::class); - $database->shouldReceive('selectCollection') + $database = $this->createMock(Database::class); + $collection = $this->createMock(Collection::class); + $cursor = $this->createMock(CursorInterface::class); + $database->method('selectCollection') ->with('collection_searchable') - ->andReturn($collection); - $collection->shouldReceive('aggregate') - ->once() - ->withArgs(function (...$args) { + ->willReturn($collection); + $collection->expects($this->once()) + ->method('aggregate') + ->willReturnCallback(function (...$args) use ($cursor) { self::assertSame([ [ '$search' => [ @@ -468,14 +470,11 @@ public function testPaginate() ], ], $args[0]); - return true; - }) - ->andReturn($cursor); - $cursor->shouldReceive('setTypeMap')->once()->with(self::EXPECTED_TYPEMAP); - $cursor->shouldReceive('toArray') - ->once() - ->with() - ->andReturn([['_id' => 'key_1', '__count' => 17], ['_id' => 'key_2', '__count' => 17]]); + return $cursor; + }); + $cursor->expects($this->once())->method('setTypeMap')->with(self::EXPECTED_TYPEMAP); + $cursor->expects($this->once())->method('toArray')->with() + ->willReturn([['_id' => 'key_1', '__count' => 17], ['_id' => 'key_2', '__count' => 17]]); $engine = new ScoutEngine($database, softDelete: false); $builder = new Builder(new SearchableModel(), 'mustang'); @@ -485,20 +484,27 @@ public function testPaginate() public function testMapMethodRespectsOrder() { - $database = m::mock(Database::class); + $database = $this->createMock(Database::class); + $query = $this->createMock(Builder::class); $engine = new ScoutEngine($database, false); - $model = m::mock(Model::class); - $model->shouldReceive(['getScoutKeyName' => 'id']); - $model->shouldReceive('queryScoutModelsByIds->get') - ->andReturn(LaravelCollection::make([ + $model = $this->createMock(SearchableModel::class); + $model->expects($this->any()) + ->method('getScoutKeyName') + ->willReturn('id'); + $model->expects($this->once()) + ->method('queryScoutModelsByIds') + ->willReturn($query); + $query->expects($this->once()) + ->method('get') + ->willReturn(LaravelCollection::make([ new ScoutUser(['id' => 1]), new ScoutUser(['id' => 2]), new ScoutUser(['id' => 3]), new ScoutUser(['id' => 4]), ])); - $builder = m::mock(Builder::class); + $builder = $this->createMock(Builder::class); $results = $engine->map($builder, [ ['_id' => 1, '__count' => 4], @@ -518,21 +524,27 @@ public function testMapMethodRespectsOrder() public function testLazyMapMethodRespectsOrder() { - $lazy = false; - $database = m::mock(Database::class); + $database = $this->createMock(Database::class); + $query = $this->createMock(Builder::class); $engine = new ScoutEngine($database, false); - $model = m::mock(Model::class); - $model->shouldReceive(['getScoutKeyName' => 'id']); - $model->shouldReceive('queryScoutModelsByIds->cursor') - ->andReturn(LazyCollection::make([ + $model = $this->createMock(SearchableModel::class); + $model->expects($this->any()) + ->method('getScoutKeyName') + ->willReturn('id'); + $model->expects($this->once()) + ->method('queryScoutModelsByIds') + ->willReturn($query); + $query->expects($this->once()) + ->method('cursor') + ->willReturn(LazyCollection::make([ new ScoutUser(['id' => 1]), new ScoutUser(['id' => 2]), new ScoutUser(['id' => 3]), new ScoutUser(['id' => 4]), ])); - $builder = m::mock(Builder::class); + $builder = $this->createMock(Builder::class); $results = $engine->lazyMap($builder, [ ['_id' => 1, '__count' => 4], @@ -553,13 +565,14 @@ public function testLazyMapMethodRespectsOrder() public function testUpdate(): void { $date = new DateTimeImmutable('2000-01-02 03:04:05'); - $database = m::mock(Database::class); - $collection = m::mock(Collection::class); - $database->shouldReceive('selectCollection') + $database = $this->createMock(Database::class); + $collection = $this->createMock(Collection::class); + $database->expects($this->once()) + ->method('selectCollection') ->with('collection_indexable') - ->andReturn($collection); - $collection->shouldReceive('bulkWrite') - ->once() + ->willReturn($collection); + $collection->expects($this->once()) + ->method('bulkWrite') ->with([ [ 'updateOne' => [ @@ -592,26 +605,23 @@ public function testUpdate(): void public function testUpdateWithSoftDelete(): void { $date = new DateTimeImmutable('2000-01-02 03:04:05'); - $database = m::mock(Database::class); - $collection = m::mock(Collection::class); - $database->shouldReceive('selectCollection') + $database = $this->createMock(Database::class); + $collection = $this->createMock(Collection::class); + $database->expects($this->once()) + ->method('selectCollection') ->with('collection_indexable') - ->andReturn($collection); - $collection->shouldReceive('bulkWrite') - ->once() - ->withArgs(function ($pipeline) { - $this->assertSame([ - [ - 'updateOne' => [ - ['_id' => 'key_1'], - ['$set' => ['id' => 1, '__soft_deleted' => false]], - ['upsert' => true], - ], + ->willReturn($collection); + $collection->expects($this->once()) + ->method('bulkWrite') + ->with([ + [ + 'updateOne' => [ + ['_id' => 'key_1'], + ['$set' => ['id' => 1, '__soft_deleted' => false]], + ['upsert' => true], ], - ], $pipeline); - - return true; - }); + ], + ]); $model = new SearchableModel(['id' => 1]); $model->delete(); @@ -622,13 +632,14 @@ public function testUpdateWithSoftDelete(): void public function testDelete(): void { - $database = m::mock(Database::class); - $collection = m::mock(Collection::class); - $database->shouldReceive('selectCollection') + $database = $this->createMock(Database::class); + $collection = $this->createMock(Collection::class); + $database->expects($this->once()) + ->method('selectCollection') ->with('collection_indexable') - ->andReturn($collection); - $collection->shouldReceive('deleteMany') - ->once() + ->willReturn($collection); + $collection->expects($this->once()) + ->method('deleteMany') ->with(['_id' => ['$in' => ['key_1', 'key_2']]]); $engine = new ScoutEngine($database, softDelete: false); @@ -646,13 +657,14 @@ public function testDeleteWithRemoveableScoutCollection(): void $job = unserialize(serialize($job)); - $database = m::mock(Database::class); - $collection = m::mock(Collection::class); - $database->shouldReceive('selectCollection') + $database = $this->createMock(Database::class); + $collection = $this->createMock(Collection::class); + $database->expects($this->once()) + ->method('selectCollection') ->with('collection_indexable') - ->andReturn($collection); - $collection->shouldReceive('deleteMany') - ->once() + ->willReturn($collection); + $collection->expects($this->once()) + ->method('deleteMany') ->with(['_id' => ['$in' => ['key_5']]]); $engine = new ScoutEngine($database, softDelete: false); From 583200745cd698ad03ae0025aa928f84c64fc6e8 Mon Sep 17 00:00:00 2001 From: Ivan Todorovic Date: Tue, 1 Apr 2025 13:36:48 +0200 Subject: [PATCH 445/446] Remove manual dirty _id check when updating a model (#3329) --- src/Query/Builder.php | 7 ------- tests/Ticket/GH3326Test.php | 42 +++++++++++++++++++++++++++++++++++++ 2 files changed, 42 insertions(+), 7 deletions(-) create mode 100644 tests/Ticket/GH3326Test.php diff --git a/src/Query/Builder.php b/src/Query/Builder.php index f613b6467..5c873380b 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -783,13 +783,6 @@ public function update(array $values, array $options = []) unset($values[$key]); } - // Since "id" is an alias for "_id", we prevent updating it - foreach ($values as $fields) { - if (array_key_exists('id', $fields)) { - throw new InvalidArgumentException('Cannot update "id" field.'); - } - } - return $this->performUpdate($values, $options); } diff --git a/tests/Ticket/GH3326Test.php b/tests/Ticket/GH3326Test.php new file mode 100644 index 000000000..d3f339acc --- /dev/null +++ b/tests/Ticket/GH3326Test.php @@ -0,0 +1,42 @@ +foo = 'bar'; + $model->save(); + + $fresh = $model->fresh(); + + $this->assertEquals('bar', $fresh->foo); + $this->assertEquals('written-in-created', $fresh->extra); + } +} + +class GH3326Model extends Model +{ + protected $connection = 'mongodb'; + protected $collection = 'test_gh3326'; + protected $guarded = []; + + protected static function booted(): void + { + static::created(function ($model) { + $model->extra = 'written-in-created'; + $model->saveQuietly(); + }); + } +} From 3aa95bec5b7e7cbf9d43b208e9dc1460895b9062 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Thu, 3 Apr 2025 15:28:18 -0400 Subject: [PATCH 446/446] DOCSP-48956: replace tutorial link (#3333) --- docs/quick-start.txt | 5 ----- docs/quick-start/next-steps.txt | 10 +++++++++- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/quick-start.txt b/docs/quick-start.txt index 83b0c3937..ebfcb7348 100644 --- a/docs/quick-start.txt +++ b/docs/quick-start.txt @@ -41,11 +41,6 @@ read and write operations on the data. `How to Build a Laravel + MongoDB Back End Service `__ MongoDB Developer Center tutorial. - You can learn how to set up a local Laravel development environment - and perform CRUD operations by viewing the - :mdbu-course:`Getting Started with Laravel and MongoDB ` - MongoDB University Learning Byte. - If you prefer to connect to MongoDB by using the {+php-library+} without Laravel, see `Connect to MongoDB `__ in the {+php-library+} documentation. diff --git a/docs/quick-start/next-steps.txt b/docs/quick-start/next-steps.txt index 1a7f45c6e..2853777fb 100644 --- a/docs/quick-start/next-steps.txt +++ b/docs/quick-start/next-steps.txt @@ -21,6 +21,15 @@ You can download the web application project by cloning the `laravel-quickstart `__ GitHub repository. +.. tip:: Build a Full Stack Application + + Learn how to build a full stack application that uses {+odm-long+} by + following along with the `Full Stack Instagram Clone with Laravel and + MongoDB `__ tutorial on YouTube. + +Further Learning +---------------- + Learn more about {+odm-long+} features from the following resources: - :ref:`laravel-fundamentals-connection`: learn how to configure your MongoDB @@ -34,4 +43,3 @@ Learn more about {+odm-long+} features from the following resources: - :ref:`laravel-query-builder`: use the query builder to specify MongoDB queries and aggregations. -