From eb0d6e70d3919571609f09cfa9b420e8bb3778d6 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 2 Oct 2024 09:59:32 -0400 Subject: [PATCH 01/30] use sharedincludes in compat page --- source/compatibility.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/compatibility.txt b/source/compatibility.txt index acca9855..94812c3b 100644 --- a/source/compatibility.txt +++ b/source/compatibility.txt @@ -29,7 +29,7 @@ The first column lists the version of the library and extension. .. sharedinclude:: dbx/compatibility-table-legend.rst -.. include:: /includes/mongodb-compatibility-table-php.rst +.. sharedinclude:: dbx/mongodb-compatibility-table-php.rst For more information on how to read the compatibility tables, see our guide on :ref:`MongoDB Compatibility Tables `. @@ -42,7 +42,7 @@ of the {+php-library+} and extension that you can use with a specific version of The first column lists the version of the library and extension. -.. include:: /includes/language-compatibility-table-php.rst +.. sharedinclude:: dbx/language-compatibility-table-php.rst For more information on how to read the compatibility tables, see our guide on :ref:`MongoDB Compatibility Tables `. From 2a75b9c76740f0efdcbe13c1f11fe73bb6ba40b2 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 2 Oct 2024 10:00:20 -0400 Subject: [PATCH 02/30] add source constants for versions --- snooty.toml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/snooty.toml b/snooty.toml index aa728e0c..c0d688f0 100644 --- a/snooty.toml +++ b/snooty.toml @@ -39,6 +39,8 @@ php-library = "MongoDB PHP Library" [constants] php-library = "MongoDB PHP Library" +version = "1.20" +full-version = "{+version+}.0" extension-short = "PHP extension" mdb-server = "MongoDB Server" stable-api = "Stable API" From d5a0d208b9c0c68a7946bd3bebed22d5ffa82799 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 2 Oct 2024 10:03:46 -0400 Subject: [PATCH 03/30] delete files for old build system (cherry picked from commit 55daa82e88b36ff861f16745819d01df06a61012) --- .github/workflows/check-autobuilder.yml | 13 --- Makefile | 94 ------------------ conf-sitemap.xml | 26 ----- config/build_conf.yaml | 36 ------- config/htaccess.yaml | 31 ------ config/integration.yaml | 19 ---- config/intersphinx.yaml | 9 -- config/push.yaml | 2 - config/robots.yaml | 4 - config/sphinx.yaml | 30 ------ config/sphinx_local.yaml | 17 ---- phpcs.xml | 126 ------------------------ psalm-baseline.xml | 57 ----------- psalm.xml | 37 ------- source/pretty.js | 4 - 15 files changed, 505 deletions(-) delete mode 100644 .github/workflows/check-autobuilder.yml delete mode 100644 Makefile delete mode 100644 conf-sitemap.xml delete mode 100644 config/build_conf.yaml delete mode 100644 config/htaccess.yaml delete mode 100644 config/integration.yaml delete mode 100644 config/intersphinx.yaml delete mode 100644 config/push.yaml delete mode 100644 config/robots.yaml delete mode 100644 config/sphinx.yaml delete mode 100644 config/sphinx_local.yaml delete mode 100644 phpcs.xml delete mode 100644 psalm-baseline.xml delete mode 100644 psalm.xml delete mode 100644 source/pretty.js diff --git a/.github/workflows/check-autobuilder.yml b/.github/workflows/check-autobuilder.yml deleted file mode 100644 index 8495db96..00000000 --- a/.github/workflows/check-autobuilder.yml +++ /dev/null @@ -1,13 +0,0 @@ -name: Check Autobuilder for Errors - -on: - pull_request: - paths: - - "source/**" - -jobs: - check: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: cbush/snooty-autobuilder-check@main diff --git a/Makefile b/Makefile deleted file mode 100644 index f70ffb5a..00000000 --- a/Makefile +++ /dev/null @@ -1,94 +0,0 @@ -GIT_BRANCH=$(shell git rev-parse --abbrev-ref HEAD) -USER=$(shell whoami) -STAGING_URL="https://docs-mongodborg-staging.corp.mongodb.com" -PRODUCTION_URL="https://docs.mongodb.com" -STAGING_BUCKET=docs-mongodb-org-prd-staging -PRODUCTION_BUCKET=docs-mongodb-org-prd -PROJECT=php-library -PREFIX=php-library -DOTCOM_STAGING_URL="https://mongodbcom-cdn.website.staging.corp.mongodb.com" -DOTCOM_STAGING_BUCKET=docs-mongodb-org-dotcomstg -DOTCOM_PRODUCTION_URL="https://mongodb.com" -DOTCOM_PRODUCTION_BUCKET=docs-mongodb-org-dotcomprd -DOTCOM_PREFIX=docs/php-library -DOTCOM_STGPREFIX=docs/php-library -SEARCH_INDEX_BUCKET=docs-search-indexes-test - - -# Parse our published-branches configuration file to get the name of -# the current "stable" branch. This is weird and dumb, yes. -STABLE_BRANCH=`grep 'manual' build/docs-tools/data/${PROJECT}-published-branches.yaml | cut -d ':' -f 2 | grep -Eo '[0-9a-z.]+'` - -.PHONY: help publish stage deploy deploy-search-index - -help: ## Show this help message - @grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}' - @echo - @echo 'Variables' - @printf " \033[36m%-18s\033[0m %s\n" 'ARGS' 'Arguments to pass to mut-publish' - -html: - giza make html - -publish: ## Build docs locally -# !!! DOES NOT PUT STUFF ONTO THE INTERNET !!! -# Builds the artifacts that you will deploy with other targets. -# Also builds an HTML rendering for local viewing. -# -# If master branch, giza creates any symlinks needed per integrations.yaml -# If master, giza creates any redirects per build_conf.yaml / htaccess.yaml - - # get the latest for mongo-php-libray/docs git submodule: - git submodule update --remote --init - # create the source/ directory if it doesn't exist - mkdir -p source/ - # rsync the docs source from the submodule to the source/ directory: - rsync -a --delete mongo-php-library/docs/ source/ - # build the publish artefacts using giza: - giza make publish - if [ ${GIT_BRANCH} = master ]; then mut-redirects config/redirects -o build/public/.htaccess; fi - -stage: ## Host online for review -# !!! DEPLOY HTML TO STAGING WEBSITE !!! -# Deploys the HTML from the build/ directory to the STAGING_BUCKET. -# -# mut-publish -# build/${GIT_BRANCH}/html directory from which to grab the HTML to deploy to the STAGING_BUCKET -# STAGING_BUCKET Amazon s3 bucket used for the staging site -# --prefix=${PROJECT} ${PROJECT} is the folder in the staging bucket in which to place the HTML -# --stage indicates that mut-publish should publish to the staging bucket (not the prod bucket) -# if ${ARGS}, then additonal arguments - - mut-publish build/${GIT_BRANCH}/html ${DOTCOM_STAGING_BUCKET} --prefix=${DOTCOM_STGPREFIX} --stage ${ARGS} - @echo "Hosted at ${DOTCOM_STAGING_URL}/${DOTCOM_STGPREFIX}/${USER}/${GIT_BRANCH}/index.html" - - - -deploy: publish ## Deploy to the production bucket -# !!! DEPLOY BUILD ARTIFACTS TO PRODUCTION !!! -# Deploys the build artifacts from the build/public directory to the PRODUCTION_BUCKET, -# first doing a 'dry run' that lists all of the files that will be uploaded/deleted/etc. -# and then asks you to press a key to perform the procedure. -# -# deploy: publish the :publish indicates that the publish target must happen before the deploy -# mut-publish -# build/public directory from which to grab the build artifacts to deploy to the PRODUCTION_BUCKET -# PRODUCTION_BUCKET Amazon s3 bucket that holds the production docs -# --prefix=${PROJECT} ${PROJECT} is the folder in the prod. bucket in which to place the artifacts -# --deploy indicates that mut-publish should publish to the production bucket (not the staging bucket) -# --verbose prints out a detail of what files are being uploaded/deleted/etc. -# --dry-run instructs mut-publish to do everything *except* actually put stuff on the internet. -# if ${ARGS}, then additonal arguments - mut-publish build/public ${DOTCOM_PRODUCTION_BUCKET} --prefix=${DOTCOM_PREFIX} --deploy ${ARGS} - @echo "Hosted at ${DOTCOM_PRODUCTION_URL}/${DOTCOM_PREFIX}/${GIT_BRANCH}" - - $(MAKE) deploy-search-index - -deploy-search-index: ## Update the search index for this branch - @echo "Building search index" - if [ ${STABLE_BRANCH} = ${GIT_BRANCH} ]; then \ - mut-index upload build/public/${GIT_BRANCH} -o docs-php-library-${GIT_BRANCH}.json -u ${PRODUCTION_URL}/${PROJECT}/${GIT_BRANCH} -b ${SEARCH_INDEX_BUCKET} -p search-indexes/prd -g -s; \ - else \ - mut-index upload build/public/${GIT_BRANCH} -o docs-php-library-${GIT_BRANCH}.json -u ${PRODUCTION_URL}/${PROJECT}/${GIT_BRANCH} -b ${SEARCH_INDEX_BUCKET} -p search-indexes/prd -s; \ - fi - diff --git a/conf-sitemap.xml b/conf-sitemap.xml deleted file mode 100644 index 231be19b..00000000 --- a/conf-sitemap.xml +++ /dev/null @@ -1,26 +0,0 @@ - - - - - - - - - - - - - - - - - - diff --git a/config/build_conf.yaml b/config/build_conf.yaml deleted file mode 100644 index ecb0f5fe..00000000 --- a/config/build_conf.yaml +++ /dev/null @@ -1,36 +0,0 @@ -git: - repo: mongodb/docs-php-library - remote: - upstream: 'mongodb/docs-php-library' - tools: 'mongodb/docs-tools' -project: - name: 'php-library' - tag: 'php-library' - url: 'http://docs.mongodb.com/php-library' - title: "PHP Library Manual" - branched: true -version: - release: 'upcoming' - branch: 'master' -system: - runstate: - serial_sphinx: publish - files: - - 'intersphinx.yaml' - - 'integration.yaml' - - 'sphinx_local.yaml' - - 'push.yaml' - - htaccess: ['htaccess.yaml'] -assets: - - branch: master - path: build/docs-tools - repository: https://github.com/mongodb/docs-tools.git -paths: - output: 'build' - source: 'source' - includes: 'source/includes' - images: 'source/images' - tools: 'bin' - buildsystem: 'build/docs-tools' - builddata: 'config' -... diff --git a/config/htaccess.yaml b/config/htaccess.yaml deleted file mode 100644 index 7d53298b..00000000 --- a/config/htaccess.yaml +++ /dev/null @@ -1,31 +0,0 @@ -# Each YAML document has the following schema: -# -# from: "the path to the redirected URL" -# to: "the path to the new location for the resource" -# type: "currently this script only supports 'redirect', and -# ignores all documents with another type." -# code: "the HTTP redirect code. Raises exception if not 301, 302, 303." -# outputs: "a list of branches/paths as follows:" -# -# - 'all': generates redirects for all published branches, but *not* 'manual'. But giza will take care of manual as part of integration.yaml logic in redirects.py -# -# - '': generates redirects for a specific branch. -# -# - 'before-': generates redirects for all branches that -# reflect releases previous to the specified branch. (Inclusive.) -# -# - 'after-': generates redirects for all branches that -# reflect releases after the specified branch. (Non-inclusive.) -# -# All paths are relative to the ``source/`` directory. -# -######################################################################## -### Giza requires this file, even if no redirects -### More as a safety -- in case, we remove redirects during deploys -from: '/' -to: '/current' -type: 'redirect' -code: 301 -outputs: - - {'/php-library': 'https://docs.mongodb.com/php-library'} -... diff --git a/config/integration.yaml b/config/integration.yaml deleted file mode 100644 index af8d28b1..00000000 --- a/config/integration.yaml +++ /dev/null @@ -1,19 +0,0 @@ -fr: - inherit: base -es: - inherit: base -ja: - inherit: base -zh: - inherit: base -it: - inherit: base -base: - targets: - - html - - dirhtml - doc-root: - - 'sitemap.xml' - - '.htaccess' - branch-root: [] -... diff --git a/config/intersphinx.yaml b/config/intersphinx.yaml deleted file mode 100644 index ad466abb..00000000 --- a/config/intersphinx.yaml +++ /dev/null @@ -1,9 +0,0 @@ -# Weirdly, giza wants a non-empty list of two or more, so we have to include extraneous/unused one --hence the python -name: python -url: https://docs.python.org/2/ -path: python2.inv ---- -name: mongodb -url: https://www.mongodb.com/docs/manual/ -path: mongodb.inv -... \ No newline at end of file diff --git a/config/push.yaml b/config/push.yaml deleted file mode 100644 index 97e1964d..00000000 --- a/config/push.yaml +++ /dev/null @@ -1,2 +0,0 @@ -### Apparently, giza requires this file, even if empty -### Must include ref to this file in the build_conf.yaml \ No newline at end of file diff --git a/config/robots.yaml b/config/robots.yaml deleted file mode 100644 index 24a5cbfc..00000000 --- a/config/robots.yaml +++ /dev/null @@ -1,4 +0,0 @@ -file: '/meta/google-compute-engine' -branches: - - 'php-library' -... diff --git a/config/sphinx.yaml b/config/sphinx.yaml deleted file mode 100644 index abca75b8..00000000 --- a/config/sphinx.yaml +++ /dev/null @@ -1,30 +0,0 @@ -# The items in the ``builders`` list are the name of Sphinx builders -# supported by ``sphinx-build``. -# -# The ``prerequsites`` list stores all targets that must build before -# sphinx can begin. -# -# The ``generated-source`` list stores all the targets that generate rst. - -prerequisites: - - setup - - intersphinx - - generate-source -generated-source: - - tables - - api - - toc - - intersphinx - - images -### --- #### -web-base: - tags: - - web -### --- #### -dirhtml: - builder: dirhtml - inherit: web-base -html: - builder: html - inherit: web-base -... diff --git a/config/sphinx_local.yaml b/config/sphinx_local.yaml deleted file mode 100644 index 860bc049..00000000 --- a/config/sphinx_local.yaml +++ /dev/null @@ -1,17 +0,0 @@ -project: 'php-library-manual' -master_doc: 'index' -paths: - static: ['source/.static'] -theme: - name: 'php-library' - project: 'docs-php-library' - sitename: 'MongoDB PHP Library Documentation' - repo: 'docs-php-library' - jira: 'DOCS' - google_analytics: 'UA-7301842-8' - nav_excluded: - - / -sidebars: - '**': - - 'pagenav.html' -... diff --git a/phpcs.xml b/phpcs.xml deleted file mode 100644 index b7a82547..00000000 --- a/phpcs.xml +++ /dev/null @@ -1,126 +0,0 @@ - - - - - - - - - - - - source/examples - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - tests - - - tests - - - tests - - - - - - - - src - - - - - - - - /src/GridFS/StreamWrapper - /tests/DocumentationExamplesTest.php - /tests/GridFS/UnusableStream.php - /tests/SpecTests/ClientSideEncryption/Prose* - - - /examples - /tests/PHPUnit/ConstraintTrait.php - - - /examples - - - /tests/SpecTests/ClientSideEncryption/Prose* - - diff --git a/psalm-baseline.xml b/psalm-baseline.xml deleted file mode 100644 index 19357242..00000000 --- a/psalm-baseline.xml +++ /dev/null @@ -1,57 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/psalm.xml b/psalm.xml deleted file mode 100644 index dc1d7d11..00000000 --- a/psalm.xml +++ /dev/null @@ -1,37 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - diff --git a/source/pretty.js b/source/pretty.js deleted file mode 100644 index cd0aa1e1..00000000 --- a/source/pretty.js +++ /dev/null @@ -1,4 +0,0 @@ -$(document).ready(function() { - $('pre code').parent().addClass('prettyprint well'); - prettyPrint(); -}); From b7125f9d86a82a67c1fc0e6f0f2903d24a2149a7 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 2 Oct 2024 10:51:53 -0400 Subject: [PATCH 04/30] adds more info to v1.20 whats new (cherry picked from commit 302bcd51d3a2c13382384b99be1016628285c473) --- source/tutorial.txt | 11 ----------- source/whats-new.txt | 28 ++++++++++++++++++++++++++++ 2 files changed, 28 insertions(+), 11 deletions(-) diff --git a/source/tutorial.txt b/source/tutorial.txt index 3102405c..915f75d7 100644 --- a/source/tutorial.txt +++ b/source/tutorial.txt @@ -7,19 +7,8 @@ Tutorials .. toctree:: - /tutorial/connecting /tutorial/server-selection - /data-formats/crud - /data-formats/codecs /tutorial/collation /tutorial/commands - /tutorial/custom-types - /tutorial/decimal128 /tutorial/encryption - /tutorial/gridfs - /tutorial/indexes - /tutorial/tailable-cursor - /tutorial/example-data /tutorial/aws-lambda - /tutorial/modeling-bson-data - /tutorial/stable-api diff --git a/source/whats-new.txt b/source/whats-new.txt index 49bc54c3..e31ddc67 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -22,6 +22,8 @@ following versions of the {+php-library+}: * :ref:`Version 1.20 ` +* :ref:`Version 1.19 ` + * :ref:`Version 1.18 ` * :ref:`Version 1.17 ` @@ -42,6 +44,32 @@ What's New in 1.20 - Adds support for {+mdb-server+} v8.0. +- Adds support for Queryable Encryption (QE) range queries. To use this + feature, your app must connect to {+mdb-server+} 8.0 or later. For + more information about QE range queries, see :manual:`Queryable + Encryption ` in the {+mdb-server+} manual. + +- When a sharded cluster operation is unsuccessful, the library avoids + selecting the same ``mongos`` server for operation retry attempts if other + ``mongos`` servers are available. + +- When you create a KMIP data key, you can now specify the ``delegated`` + option. If this option is set to ``true``, the KMIP provider performs + encryption and decryption of the data key locally, ensuring that the + encryption key never leaves the KMIP server. + +For more information about the changes in this version, see the +:github:`v1.20 release notes +` on GitHub. + +.. _php-lib-version-1.19: + +What's New in 1.19 +------------------ + +This release of the {+library-short+} contains no significant changes +and was added to keep version parity with the {+extension-short+}. + .. _php-lib-version-1.18: What's New in 1.18 From a04544f45a4d57f4d5309546acf632663bc6a789 Mon Sep 17 00:00:00 2001 From: Jordan Smith Date: Thu, 3 Oct 2024 07:44:49 -0700 Subject: [PATCH 05/30] Fix compatibility table (cherry picked from commit 4fba22facb3ac558f0b2addd71abdd7422415151) --- source/includes/language-compatibility-table-php.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/includes/language-compatibility-table-php.rst b/source/includes/language-compatibility-table-php.rst index c50e52b3..27c84620 100644 --- a/source/includes/language-compatibility-table-php.rst +++ b/source/includes/language-compatibility-table-php.rst @@ -27,7 +27,7 @@ - ✓ - ✓ - ✓ - - + - ✓ - * - ext + lib 1.16 From 1f72f82776916ad10a766f17008c26d4401e4d4f Mon Sep 17 00:00:00 2001 From: Elyse Foreman Date: Mon, 21 Oct 2024 10:58:48 -0400 Subject: [PATCH 06/30] (DOCSP-44298) Removed EOL'd v1.16 and earlier. (#165) (#166) --- source/whats-new.txt | 43 +------------------------------------------ 1 file changed, 1 insertion(+), 42 deletions(-) diff --git a/source/whats-new.txt b/source/whats-new.txt index e31ddc67..63eb44f6 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -28,10 +28,6 @@ following versions of the {+php-library+}: * :ref:`Version 1.17 ` -* :ref:`Version 1.16 ` - -* :ref:`Version 1.15 ` - .. _php-lib-version-1.20: What's New in 1.20 @@ -118,41 +114,4 @@ What's New in 1.17 7.2 and 7.3 has been removed and the library now requires PHP 7.4 or newer. To learn more about this release, see the `v1.17 Release Notes -`__ on GitHub. - -.. _php-lib-version-1.16: - -What's New in 1.16 ------------------- - -- Introduces support for :v7.0:`MongoDB 7.0 `. - -- Introduces :phpmethod:`MongoDB\Database::createEncryptedCollection()`. - This method automatically creates data encryption keys when creating a new - encrypted collection. - -- Upgrades the ``mongodb`` extension requirement to 1.16.0. - -To learn more about this release, see the `v1.16 Release Notes -`__ on GitHub. - -.. _php-lib-version-1.15: - -What's New in 1.15 ------------------- - -- Adds new ``examples/`` and ``tools/`` directories to the library repository, - which contain code snippets and scripts that may prove useful when writing - or debugging applications. These directories are intended to - supplement the library's existing documentation and will be added to over time. - -- Adds various backwards compatible typing improvements throughout the - library. Downstream impact for these changes are discussed in - `UPGRADE-1.15.md `__. - -- Integrates `Psalm `__ for static analysis. - -- Upgrades the ``mongodb`` extension requirement to 1.15.0. - -To learn more about this release, see the `v1.15 Release Notes -`__ on GitHub. +`__ on GitHub. \ No newline at end of file From f76e0c01b3e42afe436848f72e77ea70d63daeaf Mon Sep 17 00:00:00 2001 From: lindseymoore <71525840+lindseymoore@users.noreply.github.com> Date: Thu, 7 Nov 2024 18:02:58 -0500 Subject: [PATCH 07/30] DOCSP-44903 Shorten TOC Labels (#176) * DOCSP-44903 Shorten TOC Labels * rest of pages * angle brackets * fixes * internal review * updates based on Mike's PR * review comments and consistency (cherry picked from commit b9fda162ecdbb9aa04a44cb2bb5ff3b594352afb) --- source/connect.txt | 10 +++++----- source/data-formats.txt | 9 ++++----- source/databases-collections.txt | 2 +- source/get-started.txt | 10 +++++----- source/index.txt | 30 ++++++++++++++--------------- source/indexes.txt | 10 +++++----- source/monitoring.txt | 2 +- source/read.txt | 16 +++++++-------- source/reference.txt | 16 +++++++-------- source/reference/result-classes.txt | 2 +- source/security.txt | 4 ++-- source/write.txt | 14 +++++++------- 12 files changed, 62 insertions(+), 63 deletions(-) diff --git a/source/connect.txt b/source/connect.txt index 7bbdce1e..d45f506b 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -22,11 +22,11 @@ Connect to MongoDB :titlesonly: :maxdepth: 1 - /connect/client - /connect/connection-options - /connect/connection-targets - /connect/tls - /connect/stable-api + Create a Client + Specify Connection Options + Choose a Connection Target + Configure TLS + Stable API Overview -------- diff --git a/source/data-formats.txt b/source/data-formats.txt index ca4e482a..550c2d64 100644 --- a/source/data-formats.txt +++ b/source/data-formats.txt @@ -21,11 +21,10 @@ Specialized Data Formats :titlesonly: :maxdepth: 1 - /data-formats/custom-types - /data-formats/codecs - /data-formats/decimal128 - /data-formats/modeling-bson-data - + Custom Data Types + Codecs + Decimal128 + BSON Overview -------- diff --git a/source/databases-collections.txt b/source/databases-collections.txt index 43e2786f..98d09bfe 100644 --- a/source/databases-collections.txt +++ b/source/databases-collections.txt @@ -21,7 +21,7 @@ Databases and Collections :titlesonly: :maxdepth: 1 - /databases-collections/time-series + Time Series Overview -------- diff --git a/source/get-started.txt b/source/get-started.txt index d9a61995..9cfd031c 100644 --- a/source/get-started.txt +++ b/source/get-started.txt @@ -20,11 +20,11 @@ Get Started with the PHP Library .. toctree:: - /get-started/download-and-install/ - /get-started/create-a-deployment/ - /get-started/create-a-connection-string/ - /get-started/connect-to-mongodb/ - /get-started/next-steps/ + Download & Install + Create a Deployment + Create a Connection String + Connect to MongoDB + Next Steps Overview -------- diff --git a/source/index.txt b/source/index.txt index 5627d911..d1df02fa 100644 --- a/source/index.txt +++ b/source/index.txt @@ -11,22 +11,22 @@ MongoDB PHP Library :titlesonly: Get Started - /connect - /databases-collections - /read - /write - /read-write-pref - /run-command - /aggregation - /indexes - /monitoring - /security - /data-formats - /compatibility - /whats-new - /upgrade + Connect to MongoDB + Databases & Collections + Read Data + Write Data + CRUD Operations & Replica Sets + Run a Database Command + Data Aggregation + Indexes + Monitor Your Application + Security + Specialized Data Formats + Compatibility + What's New + Upgrade FAQ - /reference + API Documentation Overview -------- diff --git a/source/indexes.txt b/source/indexes.txt index 2e6d5ccf..29afd6ed 100644 --- a/source/indexes.txt +++ b/source/indexes.txt @@ -22,11 +22,11 @@ Optimize Queries by Using Indexes :titlesonly: :maxdepth: 1 - /indexes/index-mgmt - /indexes/single-field-index - /indexes/compound-index - /indexes/multikey-index - /indexes/atlas-search-index + Index Management + Single Field Indexes + Compound Indexes + Multikey Indexes + Atlas Search Overview -------- diff --git a/source/monitoring.txt b/source/monitoring.txt index 5322004f..43d15f27 100644 --- a/source/monitoring.txt +++ b/source/monitoring.txt @@ -7,7 +7,7 @@ Monitor Your Application .. toctree:: :caption: Monitoring categories - /monitoring/cluster-monitoring + Cluster Monitoring .. /monitoring/command-monitoring .. /monitoring/connection-monitoring diff --git a/source/read.txt b/source/read.txt index 1e01ef17..1f7c9296 100644 --- a/source/read.txt +++ b/source/read.txt @@ -22,14 +22,14 @@ Read Data from MongoDB :titlesonly: :maxdepth: 1 - /read/retrieve - /read/project - /read/cursor - /read/count - /read/specify-documents-to-return - /read/specify-a-query - /read/distinct - /read/change-streams + Retrieve Data + Specify Fields to Return + Access Data from a Cursor + Count Documents + Specify Documents to Return + Specify a Query + Distinct Field Values + Monitor Changes Overview -------- diff --git a/source/reference.txt b/source/reference.txt index 2dd51527..04f9e5ab 100644 --- a/source/reference.txt +++ b/source/reference.txt @@ -7,11 +7,11 @@ API Documentation .. toctree:: :titlesonly: - /reference/bson - /reference/class/MongoDBClient - /reference/class/MongoDBDatabase - /reference/class/MongoDBCollection - /reference/class/MongoDBGridFSBucket - /reference/result-classes - /reference/functions - /reference/exception-classes + BSON + MongoDB\Client + MongoDB\Database + MongoDB\Collection + MongoDB\GridFS\Bucket + Result Classes + Functions + Exception Classes diff --git a/source/reference/result-classes.txt b/source/reference/result-classes.txt index b59f480c..97c47025 100644 --- a/source/reference/result-classes.txt +++ b/source/reference/result-classes.txt @@ -19,4 +19,4 @@ Result Classes DatabaseInfo Class DatabaseInfoIterator Class IndexInfo Class - IndexInfoIterator Class \ No newline at end of file + IndexInfoIterator Class diff --git a/source/security.txt b/source/security.txt index 8c8e236b..249ae009 100644 --- a/source/security.txt +++ b/source/security.txt @@ -22,8 +22,8 @@ Secure Your Data :titlesonly: :maxdepth: 1 - /security/authentication - /security/in-use-encryption + Authentication + Encryption Overview -------- diff --git a/source/write.txt b/source/write.txt index 8d9d16ca..3114e42f 100644 --- a/source/write.txt +++ b/source/write.txt @@ -22,13 +22,13 @@ Write Data to MongoDB :titlesonly: :maxdepth: 1 - /write/update - /write/insert - /write/delete - /write/replace - /write/bulk-write - /write/transaction - /write/gridfs + Update + Insert + Delete + Replace + Bulk Write Operations + Transactions + Store Large Files Overview -------- From 8c7e3afa933e924fff3943e35a5c8729d413a5e8 Mon Sep 17 00:00:00 2001 From: Jeremy Mikola Date: Mon, 11 Nov 2024 09:56:56 -0500 Subject: [PATCH 08/30] PHPLIB-1278: FAQ entry on connection persistence --- source/faq.txt | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/source/faq.txt b/source/faq.txt index 5e333636..13455a6e 100644 --- a/source/faq.txt +++ b/source/faq.txt @@ -101,6 +101,64 @@ for the correct environment. The aforementioned ``detect-extension`` script can also be used to determine the appropriate DLL for your PHP environment. + +Connection Handling and Persistence +----------------------------------- + +Connections to the MongoDB deployment are handled entirely by libmongoc and the +:php:`mongodb extension `. When a :phpclass:`MongoDB\Client` is +constructed, the |php-library| creates a +:php:`MongoDB\Driver\Manager ` using the +same connection string and options. The extension also uses those constructor +arguments to derive a hash key for persistent libmongoc clients. If a libmongoc +client was previously persisted with a key, it will be reused; otherwise, a new +libmongoc client will be created and persisted for the lifetime of the PHP +worker process. This process is described in more detail in the +:php:`extension documentation `. + +Each libmongoc client maintains its own connections to the MongoDB deployment +and a view of its topology. When a persistent libmongoc client is reused, the +PHP driver is able to avoid the overhead of establishing new connections and +rediscovering the topology. This approach generally improves performance and is +therefore the driver's default behavior. + +Persistent libmongoc clients are not destroyed until the PHP worker process +terminates. This means that connections to a MongoDB deployment may remain open +long after a ``MongoDB\Driver\Manager`` object goes out of scope. While this is +typically not an issue for applications that connect to one MongoDB deployment, +it could be problematic in some situations. Consider the following cases: + +- PHP-FPM is configured with ``pm.max_requests=0`` (i.e. workers never respawn) + and a PHP application is deployed many times with small changes to its MongoDB + connection string and/or options. This could lead to an accumulation of + libmongoc client objects within each worker process. +- An application occasionally connects to a separate MongoDB deployment in some + backend component where request latency is not paramount. + +In the first case, restarting PHP-FPM as part of the application deployment +would allow the application to relinquish any unused libmongoc clients and still +utilize a persistent client for the latest connection string. + +The second case warrants a different solution. Specifying ``true`` for the +``disableClientPersistence`` driver option will instruct the PHP driver to +create a new libmongoc client and ensure it is destroyed when the corresponding +``MongoDB\Driver\Manager`` goes out of scope. + +.. code-block:: php + + true], + ); + +The ``disableClientPersistence`` driver option should be used sparingly, as +opting out of client persistence means that additional time will be required to +establish connections to the MongoDB deployment and discover its topology. + + Server Selection Failures ------------------------- From edc759aef83d8a5d71a20bc92a69cb030a582c06 Mon Sep 17 00:00:00 2001 From: Jeremy Mikola Date: Mon, 11 Nov 2024 10:09:53 -0500 Subject: [PATCH 09/30] Address vale lint checks on word usage --- source/faq.txt | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/source/faq.txt b/source/faq.txt index 13455a6e..b9f7b3be 100644 --- a/source/faq.txt +++ b/source/faq.txt @@ -118,30 +118,30 @@ worker process. This process is described in more detail in the Each libmongoc client maintains its own connections to the MongoDB deployment and a view of its topology. When a persistent libmongoc client is reused, the -PHP driver is able to avoid the overhead of establishing new connections and +PHP driver can avoid the overhead of establishing new connections and rediscovering the topology. This approach generally improves performance and is therefore the driver's default behavior. -Persistent libmongoc clients are not destroyed until the PHP worker process +Persistent libmongoc clients are not freed until the PHP worker process terminates. This means that connections to a MongoDB deployment may remain open long after a ``MongoDB\Driver\Manager`` object goes out of scope. While this is typically not an issue for applications that connect to one MongoDB deployment, it could be problematic in some situations. Consider the following cases: -- PHP-FPM is configured with ``pm.max_requests=0`` (i.e. workers never respawn) - and a PHP application is deployed many times with small changes to its MongoDB - connection string and/or options. This could lead to an accumulation of - libmongoc client objects within each worker process. +- PHP-FPM is configured with ``pm.max_requests=0`` (workers never respawn) and a + PHP application is deployed many times with small changes to its MongoDB + connection string or options. This could lead to an accumulation of libmongoc + client objects within each worker process. - An application occasionally connects to a separate MongoDB deployment in some backend component where request latency is not paramount. In the first case, restarting PHP-FPM as part of the application deployment -would allow the application to relinquish any unused libmongoc clients and still -utilize a persistent client for the latest connection string. +allows the application to relinquish any unused libmongoc clients and still use +a persistent client for the latest connection string. The second case warrants a different solution. Specifying ``true`` for the ``disableClientPersistence`` driver option will instruct the PHP driver to -create a new libmongoc client and ensure it is destroyed when the corresponding +create a new libmongoc client and ensure it is freed when the corresponding ``MongoDB\Driver\Manager`` goes out of scope. .. code-block:: php @@ -154,9 +154,9 @@ create a new libmongoc client and ensure it is destroyed when the corresponding driverOptions: ['disableClientPersistence' => true], ); -The ``disableClientPersistence`` driver option should be used sparingly, as -opting out of client persistence means that additional time will be required to -establish connections to the MongoDB deployment and discover its topology. +Use the ``disableClientPersistence`` driver option sparingly, as opting out of +client persistence will require more time to establish connections to the +MongoDB deployment and discover its topology. Server Selection Failures From da7b1e4bf9a95b118fbff9bc0b340f7a7f46959d Mon Sep 17 00:00:00 2001 From: rustagir Date: Mon, 11 Nov 2024 11:50:20 -0500 Subject: [PATCH 10/30] Docs edits --- source/faq.txt | 70 +++++++++++++++++++++++++++----------------------- 1 file changed, 38 insertions(+), 32 deletions(-) diff --git a/source/faq.txt b/source/faq.txt index b9f7b3be..a1e6a655 100644 --- a/source/faq.txt +++ b/source/faq.txt @@ -101,50 +101,56 @@ for the correct environment. The aforementioned ``detect-extension`` script can also be used to determine the appropriate DLL for your PHP environment. - Connection Handling and Persistence ----------------------------------- -Connections to the MongoDB deployment are handled entirely by libmongoc and the -:php:`mongodb extension `. When a :phpclass:`MongoDB\Client` is -constructed, the |php-library| creates a -:php:`MongoDB\Driver\Manager ` using the +Connections to the MongoDB deployment are handled by the ``libmongoc`` +library and the :php:`{+extension-short+} `. When you construct +a :phpclass:`MongoDB\Client` instance, the {+library-short+} creates a +:php:`MongoDB\Driver\Manager ` instance by using the same connection string and options. The extension also uses those constructor -arguments to derive a hash key for persistent libmongoc clients. If a libmongoc -client was previously persisted with a key, it will be reused; otherwise, a new -libmongoc client will be created and persisted for the lifetime of the PHP -worker process. This process is described in more detail in the -:php:`extension documentation `. - -Each libmongoc client maintains its own connections to the MongoDB deployment -and a view of its topology. When a persistent libmongoc client is reused, the -PHP driver can avoid the overhead of establishing new connections and +arguments to derive a hash key for persistent ``libmongoc`` clients. If +you previously persisted a ``libmongoc`` client by using a key, it is +reused. Otherwise, a new ``libmongoc`` client is created and persisted +for the lifetime of the PHP worker process. You can learn more about +this process in the :php:`{+extension-short+} documentation +`. + +Each ``libmongoc`` client maintains its own connections to the MongoDB deployment +and a view of its topology. When you reuse a persistent ``libmongoc`` client, the +{+library-short+} can avoid the overhead of establishing new connections and rediscovering the topology. This approach generally improves performance and is -therefore the driver's default behavior. +the driver's default behavior. -Persistent libmongoc clients are not freed until the PHP worker process -terminates. This means that connections to a MongoDB deployment may remain open -long after a ``MongoDB\Driver\Manager`` object goes out of scope. While this is +Persistent ``libmongoc`` clients are not freed until the PHP worker process +ends. This means that connections to a MongoDB deployment might remain open +after a ``MongoDB\Driver\Manager`` object goes out of scope. While this is typically not an issue for applications that connect to one MongoDB deployment, -it could be problematic in some situations. Consider the following cases: +it might be problematic in some situations, which are described in the +following list: -- PHP-FPM is configured with ``pm.max_requests=0`` (workers never respawn) and a +- PHP-FPM is configured with ``pm.max_requests=0``, so that workers never respawn, and a PHP application is deployed many times with small changes to its MongoDB - connection string or options. This could lead to an accumulation of libmongoc - client objects within each worker process. -- An application occasionally connects to a separate MongoDB deployment in some - backend component where request latency is not paramount. + connection string or options. This could lead to an accumulation of ``libmongoc`` + client objects in each worker process. + +- An application occasionally connects to a separate MongoDB deployment in a + backend component where request latency is not the most important aspect. In the first case, restarting PHP-FPM as part of the application deployment -allows the application to relinquish any unused libmongoc clients and still use +allows the application to release any unused ``libmongoc`` clients and still use a persistent client for the latest connection string. -The second case warrants a different solution. Specifying ``true`` for the -``disableClientPersistence`` driver option will instruct the PHP driver to -create a new libmongoc client and ensure it is freed when the corresponding +The second case requires a different solution. Specifying ``true`` for the +``disableClientPersistence`` driver option instructs the {+library-short+} to +create a new ``libmongoc`` client and ensure it is freed when the corresponding ``MongoDB\Driver\Manager`` goes out of scope. +The following code demonstrates how to set the +``disableClientPersistence`` option to ``true`` when creating a client: + .. code-block:: php + :emphasize-lines: 6 true], ); -Use the ``disableClientPersistence`` driver option sparingly, as opting out of -client persistence will require more time to establish connections to the -MongoDB deployment and discover its topology. - +Use the ``disableClientPersistence`` driver option after careful +consideration, because opting out of client persistence requires more +time to establish connections to the MongoDB deployment and discover its +topology. Server Selection Failures ------------------------- From 02755ef3ea9400d1643b0827b5daae0bc9176094 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Mon, 2 Dec 2024 09:46:57 -0500 Subject: [PATCH 11/30] Merge pull request #181 from mcmorisi/DRIVERS-2658-hint DOCSP-45139: Add Hint option for Distinct operation --- source/read/distinct.txt | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/source/read/distinct.txt b/source/read/distinct.txt index 31d88bd5..8a71ca01 100644 --- a/source/read/distinct.txt +++ b/source/read/distinct.txt @@ -138,6 +138,10 @@ options you can set to customize the operation: - | The read preference to use for the operation. To learn more, see :manual:`Read Preference ` in the Server manual. | **Type**: ``MongoDB\Driver\ReadPreference`` + + * - ``hint`` + - | The index to use for the operation. + | **Type**: ``string|object`` The following example retrieves the distinct values of the ``name`` field for all documents that have a ``borough`` field value of ``'Bronx'`` and a From ad72d35909ba50e31ae9df8bf6fcea36d4b2b11a Mon Sep 17 00:00:00 2001 From: Sarah Simpers <82042374+sarahsimpers@users.noreply.github.com> Date: Tue, 3 Dec 2024 11:37:25 -0500 Subject: [PATCH 12/30] (DOCSP-45749) Denests last phase 1 nested components (#182) * (DOCSP-45749) Denests last phase 1 nested components * Update build --- .../method/MongoDBDatabase-createCollection.txt | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/source/reference/method/MongoDBDatabase-createCollection.txt b/source/reference/method/MongoDBDatabase-createCollection.txt index 23c4e51f..11b62e23 100644 --- a/source/reference/method/MongoDBDatabase-createCollection.txt +++ b/source/reference/method/MongoDBDatabase-createCollection.txt @@ -64,9 +64,8 @@ Parameters - Specify ``false`` to disable the automatic creation of an index on the ``_id`` field. - .. important:: - - For replica sets, do not set ``autoIndexId`` to ``false``. + :gold:`IMPORTANT:` For replica sets, do not set + ``autoIndexId`` to ``false``. .. deprecated:: 1.4 This option has been deprecated since MongoDB 3.2. As of MongoDB @@ -242,10 +241,8 @@ Parameters - Determines whether to ``error`` on invalid documents or just ``warn`` about the violations but allow invalid documents to be inserted. - .. important:: - - Validation of documents only applies to those documents as - determined by the ``validationLevel``. + :gold:`IMPORTANT:` Validation of documents only applies to + those documents as determined by the ``validationLevel``. .. list-table:: :header-rows: 1 From 6c7246348e0cfd7c79e34f16707cc808cf122717 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Mon, 9 Dec 2024 13:29:04 -0500 Subject: [PATCH 13/30] DOCSP-45100: Delete and rename by name (#187) * DOCSP-45100: Delete and rename by name * edits * JM feedback (cherry picked from commit 343f3392376d36c2311408efb89d8fff9af0cf16) --- source/includes/write/gridfs.php | 18 ++++++++--- source/write/gridfs.txt | 55 +++++++++++++++++++++----------- 2 files changed, 50 insertions(+), 23 deletions(-) diff --git a/source/includes/write/gridfs.php b/source/includes/write/gridfs.php index bb94ce63..104a90cf 100644 --- a/source/includes/write/gridfs.php +++ b/source/includes/write/gridfs.php @@ -81,11 +81,21 @@ function toJSON(object $document): string // end-download-to-stream // Renames a file from the GridFS bucket with the specified ObjectId -// start-rename-files +// start-rename-files-id $bucket->rename(new ObjectId('66e0a5487c880f844c0a32b1'), 'new_file_name'); -// end-rename-files +// end-rename-files-id + +// Renames files from the GridFS bucket with the specified filename +// start-rename-files-name +$bucket->renameByName('my_file', 'new_file_name'); +// end-rename-files-name // Deletes a file from the GridFS bucket with the specified ObjectId -// start-delete-files +// start-delete-files-id $bucket->delete(new ObjectId('66e0a5487c880f844c0a32b1')); -// end-delete-files +// end-delete-files-id + +// Deletes a file and its revisions from the GridFS bucket by name +// start-delete-files-name +$bucket->deleteByName('my_file'); +// end-delete-files-name diff --git a/source/write/gridfs.txt b/source/write/gridfs.txt index 3415dc8f..0ceb287e 100644 --- a/source/write/gridfs.txt +++ b/source/write/gridfs.txt @@ -375,48 +375,65 @@ Rename Files ------------ Use the ``MongoDB\GridFS\Bucket::rename()`` method to update the name of -a GridFS file in your bucket. You must specify the file to rename by its -``_id`` field rather than its file name. +a GridFS file in your bucket. Pass the following parameters to the ``rename()`` +method: + +- ``_id`` value of the file you want to rename +- New file name The following example shows how to update the ``filename`` field to -``'new_file_name'`` by referencing a document's ``_id`` field: +``'new_file_name'`` by referencing a file's ``_id`` value: .. literalinclude:: /includes/write/gridfs.php :language: php :dedent: - :start-after: start-rename-files - :end-before: end-rename-files + :start-after: start-rename-files-id + :end-before: end-rename-files-id + +Alternatively, you can use the ``MongoDB\GridFS\Bucket::renameByName()`` +method to rename a GridFS file and all its file revisions. Pass the +following parameters to the ``renameByName()`` method: -.. note:: File Revisions +- ``filename`` value you want to change +- New file name - The ``rename()`` method supports updating the name of only one file at - a time. If you want to rename each file revision, or files with different upload - times that share the same file name, collect the ``_id`` values of each revision. - Then, pass each value in separate calls to the ``rename()`` method. +The following example renames all files that have a ``filename`` value +of ``'my_file'``: + +.. literalinclude:: /includes/write/gridfs.php + :language: php + :dedent: + :start-after: start-rename-files-name + :end-before: end-rename-files-name .. _gridfs-delete-files: Delete Files ------------ -Use the ``MongoDB\GridFS\Bucket::delete()`` method to remove a file's collection +Use the ``MongoDB\GridFS\Bucket::delete()`` method to remove a GridFS file's collection document and associated chunks from your bucket. This effectively deletes the file. -You must specify the file by its ``_id`` field rather than its file name. +Pass the ``_id`` value of the file you want to delete as a parameter to the +``delete()`` method. The following example shows you how to delete a file by referencing its ``_id`` field: .. literalinclude:: /includes/write/gridfs.php :language: php :dedent: - :start-after: start-delete-files - :end-before: end-delete-files + :start-after: start-delete-files-id + :end-before: end-delete-files-id -.. note:: File Revisions +Alternatively, you can use the ``MongoDB\GridFS\Bucket::deleteByName()`` method +to delete a GridFS file and all its file revisions. Pass the ``filename`` value of the +file you want to delete as a parameter to the ``deleteByName()`` method, as shown +in the following code: - The ``delete()`` method supports deleting only one file at a time. If - you want to delete each file revision, or files with different upload - times that share the same file name, collect the ``_id`` values of each revision. - Then, pass each value in separate calls to the ``delete()`` method. +.. literalinclude:: /includes/write/gridfs.php + :language: php + :dedent: + :start-after: start-delete-files-name + :end-before: end-delete-files-name API Documentation ----------------- From 7c13ef66acc93367d22a8be8dfe37082c5765ceb Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 4 Feb 2025 11:05:19 -0500 Subject: [PATCH 14/30] bring master changes into v1.21 --- .../method/MongoDBCollection-distinct.txt | 402 +++++++++--------- 1 file changed, 204 insertions(+), 198 deletions(-) diff --git a/source/reference/method/MongoDBCollection-distinct.txt b/source/reference/method/MongoDBCollection-distinct.txt index f8bcd4b0..9a055cd2 100644 --- a/source/reference/method/MongoDBCollection-distinct.txt +++ b/source/reference/method/MongoDBCollection-distinct.txt @@ -19,11 +19,11 @@ Definition .. code-block:: php - function distinct( - string $fieldName, - array|object $filter = [], - array $options = [] - ): mixed[] + function distinct( + string $fieldName, + array|object $filter = [], + array $options = [] + ): mixed[] Parameters ---------- @@ -39,50 +39,56 @@ Parameters An array specifying the desired options. .. list-table:: - :header-rows: 1 - :widths: 20 20 80 + :header-rows: 1 + :widths: 20 20 80 - * - Name - - Type - - Description + * - Name + - Type + - Description - * - collation - - array|object - - .. include:: /includes/extracts/collection-option-collation.rst + * - collation + - array|object + - .. include:: /includes/extracts/collection-option-collation.rst - * - comment - - mixed - - .. include:: /includes/extracts/common-option-comment.rst + * - comment + - mixed + - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-4.4.rst - .. versionadded:: 1.13 + .. versionadded:: 1.13 - * - maxTimeMS - - integer - - .. include:: /includes/extracts/common-option-maxTimeMS.rst + * - hint + - string|object + - .. include:: /includes/extracts/common-option-hint.rst - * - readConcern - - :php:`MongoDB\Driver\ReadConcern ` - - .. include:: /includes/extracts/collection-option-readConcern.rst + .. versionadded:: 1.21 - .. include:: /includes/extracts/common-option-readConcern-transaction.rst + * - maxTimeMS + - integer + - .. include:: /includes/extracts/common-option-maxTimeMS.rst - * - readPreference - - :php:`MongoDB\Driver\ReadPreference ` - - .. include:: /includes/extracts/collection-option-readPreference.rst + * - readConcern + - :php:`MongoDB\Driver\ReadConcern ` + - .. include:: /includes/extracts/collection-option-readConcern.rst - * - session - - :php:`MongoDB\Driver\Session ` - - .. include:: /includes/extracts/common-option-session.rst + .. include:: /includes/extracts/common-option-readConcern-transaction.rst - .. versionadded:: 1.3 + * - readPreference + - :php:`MongoDB\Driver\ReadPreference ` + - .. include:: /includes/extracts/collection-option-readPreference.rst - * - typeMap - - array - - .. include:: /includes/extracts/collection-option-typeMap.rst + * - session + - :php:`MongoDB\Driver\Session ` + - .. include:: /includes/extracts/common-option-session.rst - .. versionadded:: 1.5 + .. versionadded:: 1.3 + + * - typeMap + - array + - .. include:: /includes/extracts/collection-option-typeMap.rst + + .. versionadded:: 1.5 Return Values ------------- @@ -126,18 +132,18 @@ The output would then resemble: .. code-block:: none array(6) { - [0]=> - string(5) "Bronx" - [1]=> - string(8) "Brooklyn" - [2]=> - string(9) "Manhattan" - [3]=> - string(7) "Missing" - [4]=> - string(6) "Queens" - [5]=> - string(13) "Staten Island" + [0]=> + string(5) "Bronx" + [1]=> + string(8) "Brooklyn" + [2]=> + string(9) "Manhattan" + [3]=> + string(7) "Missing" + [4]=> + string(6) "Queens" + [5]=> + string(13) "Staten Island" } Return Distinct Values Using a Filter @@ -162,156 +168,156 @@ The output would then resemble: .. code-block:: none array(75) { - [0]=> - string(6) "Afghan" - [1]=> - string(7) "African" - [2]=> - string(9) "American " - [3]=> - string(8) "Armenian" - [4]=> - string(5) "Asian" - [5]=> - string(10) "Australian" - [6]=> - string(15) "Bagels/Pretzels" - [7]=> - string(6) "Bakery" - [8]=> - string(11) "Bangladeshi" - [9]=> - string(8) "Barbecue" - [10]=> - string(55) "Bottled beverages, including water, sodas, juices, etc." - [11]=> - string(9) "Brazilian" - [12]=> - string(4) "Cafe" - [13]=> - string(16) "Café/Coffee/Tea" - [14]=> - string(5) "Cajun" - [15]=> - string(9) "Caribbean" - [16]=> - string(7) "Chicken" - [17]=> - string(7) "Chinese" - [18]=> - string(13) "Chinese/Cuban" - [19]=> - string(16) "Chinese/Japanese" - [20]=> - string(11) "Continental" - [21]=> - string(6) "Creole" - [22]=> - string(5) "Czech" - [23]=> - string(12) "Delicatessen" - [24]=> - string(6) "Donuts" - [25]=> - string(16) "Eastern European" - [26]=> - string(8) "Egyptian" - [27]=> - string(7) "English" - [28]=> - string(8) "Filipino" - [29]=> - string(6) "French" - [30]=> - string(17) "Fruits/Vegetables" - [31]=> - string(6) "German" - [32]=> - string(5) "Greek" - [33]=> - string(10) "Hamburgers" - [34]=> - string(16) "Hotdogs/Pretzels" - [35]=> - string(31) "Ice Cream, Gelato, Yogurt, Ices" - [36]=> - string(6) "Indian" - [37]=> - string(10) "Indonesian" - [38]=> - string(5) "Irish" - [39]=> - string(7) "Italian" - [40]=> - string(8) "Japanese" - [41]=> - string(13) "Jewish/Kosher" - [42]=> - string(30) "Juice, Smoothies, Fruit Salads" - [43]=> - string(6) "Korean" - [44]=> - string(64) "Latin (Cuban, Dominican, Puerto Rican, South & Central American)" - [45]=> - string(13) "Mediterranean" - [46]=> - string(7) "Mexican" - [47]=> - string(14) "Middle Eastern" - [48]=> - string(8) "Moroccan" - [49]=> - string(25) "Not Listed/Not Applicable" - [50]=> - string(18) "Nuts/Confectionary" - [51]=> - string(5) "Other" - [52]=> - string(9) "Pakistani" - [53]=> - string(16) "Pancakes/Waffles" - [54]=> - string(8) "Peruvian" - [55]=> - string(5) "Pizza" - [56]=> - string(13) "Pizza/Italian" - [57]=> - string(6) "Polish" - [58]=> - string(10) "Portuguese" - [59]=> - string(7) "Russian" - [60]=> - string(6) "Salads" - [61]=> - string(10) "Sandwiches" - [62]=> - string(30) "Sandwiches/Salads/Mixed Buffet" - [63]=> - string(7) "Seafood" - [64]=> - string(9) "Soul Food" - [65]=> - string(18) "Soups & Sandwiches" - [66]=> - string(12) "Southwestern" - [67]=> - string(7) "Spanish" - [68]=> - string(5) "Steak" - [69]=> - string(5) "Tapas" - [70]=> - string(7) "Tex-Mex" - [71]=> - string(4) "Thai" - [72]=> - string(7) "Turkish" - [73]=> - string(10) "Vegetarian" - [74]=> - string(29) "Vietnamese/Cambodian/Malaysia" + [0]=> + string(6) "Afghan" + [1]=> + string(7) "African" + [2]=> + string(9) "American " + [3]=> + string(8) "Armenian" + [4]=> + string(5) "Asian" + [5]=> + string(10) "Australian" + [6]=> + string(15) "Bagels/Pretzels" + [7]=> + string(6) "Bakery" + [8]=> + string(11) "Bangladeshi" + [9]=> + string(8) "Barbecue" + [10]=> + string(55) "Bottled beverages, including water, sodas, juices, etc." + [11]=> + string(9) "Brazilian" + [12]=> + string(4) "Cafe" + [13]=> + string(16) "Café/Coffee/Tea" + [14]=> + string(5) "Cajun" + [15]=> + string(9) "Caribbean" + [16]=> + string(7) "Chicken" + [17]=> + string(7) "Chinese" + [18]=> + string(13) "Chinese/Cuban" + [19]=> + string(16) "Chinese/Japanese" + [20]=> + string(11) "Continental" + [21]=> + string(6) "Creole" + [22]=> + string(5) "Czech" + [23]=> + string(12) "Delicatessen" + [24]=> + string(6) "Donuts" + [25]=> + string(16) "Eastern European" + [26]=> + string(8) "Egyptian" + [27]=> + string(7) "English" + [28]=> + string(8) "Filipino" + [29]=> + string(6) "French" + [30]=> + string(17) "Fruits/Vegetables" + [31]=> + string(6) "German" + [32]=> + string(5) "Greek" + [33]=> + string(10) "Hamburgers" + [34]=> + string(16) "Hotdogs/Pretzels" + [35]=> + string(31) "Ice Cream, Gelato, Yogurt, Ices" + [36]=> + string(6) "Indian" + [37]=> + string(10) "Indonesian" + [38]=> + string(5) "Irish" + [39]=> + string(7) "Italian" + [40]=> + string(8) "Japanese" + [41]=> + string(13) "Jewish/Kosher" + [42]=> + string(30) "Juice, Smoothies, Fruit Salads" + [43]=> + string(6) "Korean" + [44]=> + string(64) "Latin (Cuban, Dominican, Puerto Rican, South & Central American)" + [45]=> + string(13) "Mediterranean" + [46]=> + string(7) "Mexican" + [47]=> + string(14) "Middle Eastern" + [48]=> + string(8) "Moroccan" + [49]=> + string(25) "Not Listed/Not Applicable" + [50]=> + string(18) "Nuts/Confectionary" + [51]=> + string(5) "Other" + [52]=> + string(9) "Pakistani" + [53]=> + string(16) "Pancakes/Waffles" + [54]=> + string(8) "Peruvian" + [55]=> + string(5) "Pizza" + [56]=> + string(13) "Pizza/Italian" + [57]=> + string(6) "Polish" + [58]=> + string(10) "Portuguese" + [59]=> + string(7) "Russian" + [60]=> + string(6) "Salads" + [61]=> + string(10) "Sandwiches" + [62]=> + string(30) "Sandwiches/Salads/Mixed Buffet" + [63]=> + string(7) "Seafood" + [64]=> + string(9) "Soul Food" + [65]=> + string(18) "Soups & Sandwiches" + [66]=> + string(12) "Southwestern" + [67]=> + string(7) "Spanish" + [68]=> + string(5) "Steak" + [69]=> + string(5) "Tapas" + [70]=> + string(7) "Tex-Mex" + [71]=> + string(4) "Thai" + [72]=> + string(7) "Turkish" + [73]=> + string(10) "Vegetarian" + [74]=> + string(29) "Vietnamese/Cambodian/Malaysia" } See Also From 033cd67925dd980aa690d06b64ae2fa3fb3d06f4 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 4 Feb 2025 11:48:40 -0500 Subject: [PATCH 15/30] DOCSP-44644: db/coll accessor methods --- source/reference/class/MongoDBClient.txt | 6 +- source/reference/class/MongoDBCollection.txt | 2 +- source/reference/class/MongoDBDatabase.txt | 6 +- .../method/MongoDBClient-getCollection.txt | 126 ++++++++++++++++++ .../method/MongoDBClient-getDatabase.txt | 114 ++++++++++++++++ .../method/MongoDBClient-selectCollection.txt | 8 +- .../method/MongoDBClient-selectDatabase.txt | 8 +- .../method/MongoDBDatabase-getCollection.txt | 122 +++++++++++++++++ .../MongoDBDatabase-selectCollection.txt | 8 +- source/whats-new.txt | 21 +++ 10 files changed, 403 insertions(+), 18 deletions(-) create mode 100644 source/reference/method/MongoDBClient-getCollection.txt create mode 100644 source/reference/method/MongoDBClient-getDatabase.txt create mode 100644 source/reference/method/MongoDBDatabase-getCollection.txt diff --git a/source/reference/class/MongoDBClient.txt b/source/reference/class/MongoDBClient.txt index 25cf7a18..27125c62 100644 --- a/source/reference/class/MongoDBClient.txt +++ b/source/reference/class/MongoDBClient.txt @@ -2,8 +2,6 @@ MongoDB\\Client Class ===================== -.. default-domain:: mongodb - .. contents:: On this page :local: :backlinks: none @@ -33,6 +31,8 @@ Methods addSubscriber() createClientEncryption() dropDatabase() + getCollection() + getDatabase() getManager() getReadConcern() getReadPreference() @@ -51,6 +51,8 @@ Methods - :phpmethod:`MongoDB\Client::addSubscriber()` - :phpmethod:`MongoDB\Client::createClientEncryption()` - :phpmethod:`MongoDB\Client::dropDatabase()` +- :phpmethod:`MongoDB\Client::getCollection()` +- :phpmethod:`MongoDB\Client::getDatabase()` - :phpmethod:`MongoDB\Client::getManager()` - :phpmethod:`MongoDB\Client::getReadConcern()` - :phpmethod:`MongoDB\Client::getReadPreference()` diff --git a/source/reference/class/MongoDBCollection.txt b/source/reference/class/MongoDBCollection.txt index 462ac4d9..257a3ac5 100644 --- a/source/reference/class/MongoDBCollection.txt +++ b/source/reference/class/MongoDBCollection.txt @@ -22,7 +22,7 @@ Definition :php:`MongoDB\Driver\Manager ` class or select a collection from the library's :phpclass:`MongoDB\Client` or :phpclass:`MongoDB\Database` classes. A collection may also be cloned from - an existing :phpclass:`MongoDB\Collection` object via the + an existing :phpclass:`MongoDB\Collection` object by using the :phpmethod:`withOptions() ` method. :phpclass:`MongoDB\Collection` supports the :php:`readConcern diff --git a/source/reference/class/MongoDBDatabase.txt b/source/reference/class/MongoDBDatabase.txt index d733616f..2e8e6fa8 100644 --- a/source/reference/class/MongoDBDatabase.txt +++ b/source/reference/class/MongoDBDatabase.txt @@ -2,8 +2,6 @@ MongoDB\\Database Class ======================= -.. default-domain:: mongodb - .. contents:: On this page :local: :backlinks: none @@ -22,7 +20,7 @@ Definition :php:`MongoDB\Driver\Manager ` class or select a database from the library's :phpclass:`MongoDB\Client` class. A database may also be cloned from an existing :phpclass:`MongoDB\Database` - object via the :phpmethod:`withOptions() ` + object by using the :phpmethod:`withOptions() ` method. :phpclass:`MongoDB\Database` supports the :php:`readConcern @@ -51,6 +49,7 @@ Methods createEncryptedCollection() drop() dropCollection() + getCollection() getDatabaseName() getManager() getReadConcern() @@ -75,6 +74,7 @@ Methods - :phpmethod:`MongoDB\Database::drop()` - :phpmethod:`MongoDB\Database::dropCollection()` - :phpmethod:`MongoDB\Database::getDatabaseName()` +- :phpmethod:`MongoDB\Database::getCollection()` - :phpmethod:`MongoDB\Database::getManager()` - :phpmethod:`MongoDB\Database::getReadConcern()` - :phpmethod:`MongoDB\Database::getReadPreference()` diff --git a/source/reference/method/MongoDBClient-getCollection.txt b/source/reference/method/MongoDBClient-getCollection.txt new file mode 100644 index 00000000..6a3c48c4 --- /dev/null +++ b/source/reference/method/MongoDBClient-getCollection.txt @@ -0,0 +1,126 @@ +================================ +MongoDB\\Client::getCollection() +================================ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Definition +---------- + +.. phpmethod:: MongoDB\Client::getCollection() + + Gets access to a collection on the server. This method is an alias for + :phpmethod:`MongoDB\Client::selectCollection()` and will replace it in + a future release. + + .. code-block:: php + + function getCollection( + string $databaseName, + string $collectionName, + array $options = [] + ): MongoDB\Collection + +Parameters +---------- + +``$databaseName`` : string + The name of the database containing the collection to access. + +``$collectionName`` : string + The name of the collection to access. + +``$options`` : array + An array specifying the desired options. + + .. list-table:: + :header-rows: 1 + :widths: 20 20 80 + + * - Name + - Type + - Description + + * - codec + - MongoDB\\Codec\\DocumentCodec + - The default :doc:`codec ` to use for collection + operations. + + .. versionadded:: 1.17 + + * - readConcern + - :php:`MongoDB\Driver\ReadConcern ` + - The default read concern to use for collection operations. Defaults to + the client's read concern. + + * - readPreference + - :php:`MongoDB\Driver\ReadPreference ` + - The default read preference to use for collection operations. Defaults + to the client's read preference. + + * - typeMap + - array + - The default type map to use for collection operations. Defaults to the + client's type map. + + * - writeConcern + - :php:`MongoDB\Driver\WriteConcern ` + - The default write concern to use for collection operations. Defaults to + the client's write concern. + +Return Values +------------- + +A :phpclass:`MongoDB\Collection` object. + +Errors/Exceptions +----------------- + +.. include:: /includes/extracts/error-invalidargumentexception.rst + +Behavior +-------- + +The selected collection inherits options such as read preference and type +mapping from the :phpclass:`Client ` object. Options may be +overridden by using the ``$options`` parameter. + +Example +------- + +The following example gets access to the ``users`` collection in the ``test`` database: + +.. code-block:: php + + getCollection('test', 'users'); + +The following example gets access to the ``users`` collection in the ``test`` database +with a custom read preference: + +.. code-block:: php + + getCollection( + 'test', + 'users', + [ + 'readPreference' => new MongoDB\Driver\ReadPreference('primaryPreferred'), + ] + ); + +See Also +-------- + +- :phpmethod:`MongoDB\Collection::__construct()` +- :phpmethod:`MongoDB\Database::getCollection()` \ No newline at end of file diff --git a/source/reference/method/MongoDBClient-getDatabase.txt b/source/reference/method/MongoDBClient-getDatabase.txt new file mode 100644 index 00000000..9cf5ab1b --- /dev/null +++ b/source/reference/method/MongoDBClient-getDatabase.txt @@ -0,0 +1,114 @@ +============================== +MongoDB\\Client::getDatabase() +============================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Definition +---------- + +.. phpmethod:: MongoDB\Client::getDatabase() + + Gets access to a database on the server. This method is an alias for + :phpmethod:`MongoDB\Client::selectDatabase()` and will replace it in + a future release. + + .. code-block:: php + + function getDatabase( + string $databaseName, + array $options = [] + ): MongoDB\Database + +Parameters +---------- + +``$databaseName`` : string + The name of the database to access. + +``$options`` : array + An array specifying the desired options. + + .. list-table:: + :header-rows: 1 + :widths: 20 20 80 + + * - Name + - Type + - Description + + * - readConcern + - :php:`MongoDB\Driver\ReadConcern ` + - The default read concern to use for database operations. Defaults to + the client's read concern. + + * - readPreference + - :php:`MongoDB\Driver\ReadPreference ` + - The default read preference to use for database operations. Defaults to + the client's read preference. + + * - typeMap + - array + - The default type map to use for database operations. Defaults to the + client's type map. + + * - writeConcern + - :php:`MongoDB\Driver\WriteConcern ` + - The default write concern to use for database operations. Defaults to + the client's write concern. + +Return Values +------------- + +A :phpclass:`MongoDB\Database` object. + +Errors/Exceptions +----------------- + +.. include:: /includes/extracts/error-invalidargumentexception.rst + +Behavior +-------- + +The selected database inherits options such as read preference and type mapping +from the :phpclass:`Client ` object. Options may be overridden +by using the ``$options`` parameter. + +Example +------- + +The following example gets access to the ``test`` database: + +.. code-block:: php + + getDatabase('test'); + +The following examples gets access to the ``test`` database with a custom read +preference: + +.. code-block:: php + + getDatabase( + 'test', + [ + 'readPreference' => new MongoDB\Driver\ReadPreference('primaryPreferred'), + ] + ); + +See Also +-------- + +- :phpmethod:`MongoDB\Client::__get()` +- :phpmethod:`MongoDB\Database::__construct()` \ No newline at end of file diff --git a/source/reference/method/MongoDBClient-selectCollection.txt b/source/reference/method/MongoDBClient-selectCollection.txt index b45b83dd..0ca80161 100644 --- a/source/reference/method/MongoDBClient-selectCollection.txt +++ b/source/reference/method/MongoDBClient-selectCollection.txt @@ -2,8 +2,6 @@ MongoDB\\Client::selectCollection() =================================== -.. default-domain:: mongodb - .. contents:: On this page :local: :backlinks: none @@ -15,7 +13,9 @@ Definition .. phpmethod:: MongoDB\Client::selectCollection() - Selects a collection on the server. + Selects a collection on the server. This method is aliased by + :phpmethod:`MongoDB\Client::getCollection()` and will be replaced by + it in a future release. .. code-block:: php @@ -87,7 +87,7 @@ Behavior The selected collection inherits options such as read preference and type mapping from the :phpclass:`Client ` object. Options may be -overridden via the ``$options`` parameter. +overridden by using the ``$options`` parameter. Example ------- diff --git a/source/reference/method/MongoDBClient-selectDatabase.txt b/source/reference/method/MongoDBClient-selectDatabase.txt index 33c7ec32..0c1913de 100644 --- a/source/reference/method/MongoDBClient-selectDatabase.txt +++ b/source/reference/method/MongoDBClient-selectDatabase.txt @@ -2,8 +2,6 @@ MongoDB\\Client::selectDatabase() ================================= -.. default-domain:: mongodb - .. contents:: On this page :local: :backlinks: none @@ -15,7 +13,9 @@ Definition .. phpmethod:: MongoDB\Client::selectDatabase() - Selects a database on the server. + Selects a database on the server. This method is aliased by + :phpmethod:`MongoDB\Client::getDatabase()` and will be replaced by + it in a future release. .. code-block:: php @@ -76,7 +76,7 @@ Behavior The selected database inherits options such as read preference and type mapping from the :phpclass:`Client ` object. Options may be overridden -via the ``$options`` parameter. +by using the ``$options`` parameter. Example ------- diff --git a/source/reference/method/MongoDBDatabase-getCollection.txt b/source/reference/method/MongoDBDatabase-getCollection.txt new file mode 100644 index 00000000..1255c300 --- /dev/null +++ b/source/reference/method/MongoDBDatabase-getCollection.txt @@ -0,0 +1,122 @@ +===================================== +MongoDB\\Database::getCollection() +===================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Definition +---------- + +.. phpmethod:: MongoDB\Database::getCollection() + + Gets access to a collection within the database. This method is an alias for + :phpmethod:`MongoDB\Database::selectCollection()` and will replace it in + a future release. + + .. code-block:: php + + function getCollection( + string $collectionName, + array $options = [] + ): MongoDB\Collection + +Parameters +---------- + +``$collectionName`` : string + The name of the collection to access. + +``$options`` : array + An array specifying the desired options. + + .. list-table:: + :header-rows: 1 + :widths: 20 20 80 + + * - Name + - Type + - Description + + * - codec + - MongoDB\\Codec\\DocumentCodec + - The default :doc:`codec ` to use for collection + operations. + + .. versionadded:: 1.17 + + * - readConcern + - :php:`MongoDB\Driver\ReadConcern ` + - The default read concern to use for collection operations. Defaults to + the database's read concern. + + * - readPreference + - :php:`MongoDB\Driver\ReadPreference ` + - The default read preference to use for collection operations. Defaults + to the database's read preference. + + * - typeMap + - array + - The default type map to use for collection operations. Defaults to the + database's type map. + + * - writeConcern + - :php:`MongoDB\Driver\WriteConcern ` + - The default write concern to use for collection operations. Defaults to + the database's write concern. + +Return Values +------------- + +A :phpclass:`MongoDB\Collection` object. + +Errors/Exceptions +----------------- + +.. include:: /includes/extracts/error-invalidargumentexception.rst + +Behavior +-------- + +The selected collection inherits options such as read preference and type +mapping from the :phpclass:`Database ` object. Options may be +overridden by using the ``$options`` parameter. + +Example +------- + +The following example gets access to the ``users`` collection in the ``test`` database: + +.. code-block:: php + + test; + + $collection = $db->getCollection('users'); + +The following example gets access to the ``users`` collection in the ``test`` +database with a custom read preference: + +.. code-block:: php + + test; + + $users = $db->getCollection( + 'users', + [ + 'readPreference' => new MongoDB\Driver\ReadPreference('primaryPreferred'), + ] + ); + +See Also +-------- + +- :phpmethod:`MongoDB\Database::__get()` +- :phpmethod:`MongoDB\Client::getCollection()` +- :phpmethod:`MongoDB\Collection::__construct()` diff --git a/source/reference/method/MongoDBDatabase-selectCollection.txt b/source/reference/method/MongoDBDatabase-selectCollection.txt index 237e38cf..f27fb8a7 100644 --- a/source/reference/method/MongoDBDatabase-selectCollection.txt +++ b/source/reference/method/MongoDBDatabase-selectCollection.txt @@ -2,8 +2,6 @@ MongoDB\\Database::selectCollection() ===================================== -.. default-domain:: mongodb - .. contents:: On this page :local: :backlinks: none @@ -15,7 +13,9 @@ Definition .. phpmethod:: MongoDB\Database::selectCollection() - Selects a collection within the database. + Selects a collection within the database. This method is aliased by + :phpmethod:`MongoDB\Database::getCollection()` and will be replaced by + it in a future release. .. code-block:: php @@ -83,7 +83,7 @@ Behavior The selected collection inherits options such as read preference and type mapping from the :phpclass:`Database ` object. Options may be -overridden via the ``$options`` parameter. +overridden by using the ``$options`` parameter. Example ------- diff --git a/source/whats-new.txt b/source/whats-new.txt index 63eb44f6..af355a54 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -20,6 +20,8 @@ What's New Learn about new features, improvements, and fixes introduced in the following versions of the {+php-library+}: +* :ref:`Version 1.21 ` + * :ref:`Version 1.20 ` * :ref:`Version 1.19 ` @@ -28,6 +30,25 @@ following versions of the {+php-library+}: * :ref:`Version 1.17 ` +.. _php-lib-version-1.21: + +What's New in 1.21 +------------------ + +The {+library-short+} v1.21 release includes the following features, +improvements, and fixes: + +- Adds the following methods: + + - :phpmethod:`MongoDB\Client::getDatabase()`: alias for :phpmethod:`MongoDB\Client::selectDatabase()` + - :phpmethod:`MongoDB\Database::getCollection()`: alias for :phpmethod:`MongoDB\Database::selectCollection()` + - :phpmethod:`MongoDB\Database::getCollection()`: alias for :phpmethod:`MongoDB\Database::selectCollection()` + + The ``Client::selectCollection()``, ``Client::selectDatabase()``, and + ``Database::selectCollection()`` methods will be deprecated and + replaced by these new methods in a future driver release, so consider + changing the usages in your application. + .. _php-lib-version-1.20: What's New in 1.20 From a35bd9f67e8aa8b4b9134efc1314a0b3c8c4d603 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 4 Feb 2025 11:53:38 -0500 Subject: [PATCH 16/30] vale action dependency --- .github/workflows/vale-tdbx.yml | 65 +++++++++++++++++---------------- 1 file changed, 34 insertions(+), 31 deletions(-) diff --git a/.github/workflows/vale-tdbx.yml b/.github/workflows/vale-tdbx.yml index ca2a7348..44374e3d 100644 --- a/.github/workflows/vale-tdbx.yml +++ b/.github/workflows/vale-tdbx.yml @@ -1,39 +1,42 @@ name: vale-checks on: - pull_request: - paths: - - "source/**" + pull_request: + paths: + - "source/**" jobs: - vale: - name: TDBX Vale rules - runs-on: ubuntu-latest - steps: - - name: checkout - uses: actions/checkout@v4 + vale: + name: TDBX Vale rules + runs-on: ubuntu-latest + steps: + - name: checkout + uses: actions/checkout@v4 - - id: files - uses: masesgroup/retrieve-changed-files@v2 - with: - format: 'csv' + - name: Install docutils + run: sudo apt-get install -y docutils - - name: checkout-latest-rules - uses: actions/checkout@v4 - with: - repository: mongodb/mongodb-vale-action - path: './tdbx-vale-rules' - token: ${{secrets.GITHUB_TOKEN}} + - id: files + uses: masesgroup/retrieve-changed-files@v2 + with: + format: 'csv' - - name: move-files-for-vale-action - run: | - cp tdbx-vale-rules/.vale.ini .vale.ini - mkdir -p .github/styles/ - cp -rf tdbx-vale-rules/.github/styles/ .github/ + - name: checkout-latest-rules + uses: actions/checkout@v4 + with: + repository: mongodb/mongodb-vale-action + path: './tdbx-vale-rules' + token: ${{secrets.GITHUB_TOKEN}} - - name: run-vale - uses: errata-ai/vale-action@reviewdog - with: - reporter: github-pr-check - files: ${{steps.files.outputs.added_modified}} - fail_on_error: true - token: ${{secrets.GITHUB_TOKEN}} + - name: move-files-for-vale-action + run: | + cp tdbx-vale-rules/.vale.ini .vale.ini + mkdir -p .github/styles/ + cp -rf tdbx-vale-rules/.github/styles/ .github/ + + - name: run-vale + uses: errata-ai/vale-action@reviewdog + with: + reporter: github-pr-check + files: ${{steps.files.outputs.added_modified}} + fail_on_error: true + token: ${{secrets.GITHUB_TOKEN}} From 45b9fca53d0e4b2ba426fcb2ef2473c798534229 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 4 Feb 2025 11:55:26 -0500 Subject: [PATCH 17/30] vale action dependency --- .github/workflows/vale-tdbx.yml | 62 ++++++++++++++++----------------- 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/.github/workflows/vale-tdbx.yml b/.github/workflows/vale-tdbx.yml index 44374e3d..29a13db3 100644 --- a/.github/workflows/vale-tdbx.yml +++ b/.github/workflows/vale-tdbx.yml @@ -1,42 +1,42 @@ name: vale-checks on: - pull_request: - paths: - - "source/**" + pull_request: + paths: + - "source/**" jobs: - vale: - name: TDBX Vale rules - runs-on: ubuntu-latest - steps: - - name: checkout - uses: actions/checkout@v4 + vale: + name: TDBX Vale rules + runs-on: ubuntu-latest + steps: + - name: checkout + uses: actions/checkout@v4 - name: Install docutils run: sudo apt-get install -y docutils - - id: files - uses: masesgroup/retrieve-changed-files@v2 - with: - format: 'csv' + - id: files + uses: masesgroup/retrieve-changed-files@v2 + with: + format: "csv" - - name: checkout-latest-rules - uses: actions/checkout@v4 - with: - repository: mongodb/mongodb-vale-action - path: './tdbx-vale-rules' - token: ${{secrets.GITHUB_TOKEN}} + - name: checkout-latest-rules + uses: actions/checkout@v4 + with: + repository: mongodb/mongodb-vale-action + path: "./tdbx-vale-rules" + token: ${{secrets.GITHUB_TOKEN}} - - name: move-files-for-vale-action - run: | - cp tdbx-vale-rules/.vale.ini .vale.ini - mkdir -p .github/styles/ - cp -rf tdbx-vale-rules/.github/styles/ .github/ + - name: move-files-for-vale-action + run: | + cp tdbx-vale-rules/.vale.ini .vale.ini + mkdir -p .github/styles/ + cp -rf tdbx-vale-rules/.github/styles/ .github/ - - name: run-vale - uses: errata-ai/vale-action@reviewdog - with: - reporter: github-pr-check - files: ${{steps.files.outputs.added_modified}} - fail_on_error: true - token: ${{secrets.GITHUB_TOKEN}} + - name: run-vale + uses: errata-ai/vale-action@reviewdog + with: + reporter: github-pr-check + files: ${{steps.files.outputs.added_modified}} + fail_on_error: true + token: ${{secrets.GITHUB_TOKEN}} From ddff76632c07580e253e857b704fcc70f92dce5e Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Fri, 7 Feb 2025 14:09:50 -0500 Subject: [PATCH 18/30] DOCSP-45100: GridFS methods api docs (#196) * DOCSP-45100: GridFS methods api docs * edits * RR feedback * JT feedback (cherry picked from commit 1442347c1875be03b71d13e2f5ef77c43b1cb4c0) --- .../reference/class/MongoDBGridFSBucket.txt | 4 ++ .../MongoDBGridFSBucket-deleteByName.txt | 50 +++++++++++++++ .../MongoDBGridFSBucket-renameByName.txt | 62 +++++++++++++++++++ source/write/gridfs.txt | 4 +- 4 files changed, 119 insertions(+), 1 deletion(-) create mode 100644 source/reference/method/MongoDBGridFSBucket-deleteByName.txt create mode 100644 source/reference/method/MongoDBGridFSBucket-renameByName.txt diff --git a/source/reference/class/MongoDBGridFSBucket.txt b/source/reference/class/MongoDBGridFSBucket.txt index c3e3e6e6..1ef2db8b 100644 --- a/source/reference/class/MongoDBGridFSBucket.txt +++ b/source/reference/class/MongoDBGridFSBucket.txt @@ -36,6 +36,7 @@ Methods __construct() delete() + deleteByName() downloadToStream() downloadToStreamByName() drop() @@ -57,10 +58,12 @@ Methods openUploadStream() registerGlobalStreamWrapperAlias() rename() + renameByName() uploadFromStream() - :phpmethod:`MongoDB\GridFS\Bucket::__construct()` - :phpmethod:`MongoDB\GridFS\Bucket::delete()` +- :phpmethod:`MongoDB\GridFS\Bucket::deleteByName()` - :phpmethod:`MongoDB\GridFS\Bucket::downloadToStream()` - :phpmethod:`MongoDB\GridFS\Bucket::drop()` - :phpmethod:`MongoDB\GridFS\Bucket::find()` @@ -81,4 +84,5 @@ Methods - :phpmethod:`MongoDB\GridFS\Bucket::openUploadStream()` - :phpmethod:`MongoDB\GridFS\Bucket::registerGlobalStreamWrapperAlias()` - :phpmethod:`MongoDB\GridFS\Bucket::rename()` +- :phpmethod:`MongoDB\GridFS\Bucket::renameByName()` - :phpmethod:`MongoDB\GridFS\Bucket::uploadFromStream()` diff --git a/source/reference/method/MongoDBGridFSBucket-deleteByName.txt b/source/reference/method/MongoDBGridFSBucket-deleteByName.txt new file mode 100644 index 00000000..70fcb5a1 --- /dev/null +++ b/source/reference/method/MongoDBGridFSBucket-deleteByName.txt @@ -0,0 +1,50 @@ +======================================= +MongoDB\\GridFS\\Bucket::deleteByName() +======================================= + + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Definition +---------- + +.. phpmethod:: MongoDB\GridFS\Bucket::deleteByName() + + Deletes a file and all its revisions from the GridFS bucket. + + .. code-block:: php + + function deleteByName(string $filename): void + +Parameters +---------- + +``$filename`` : string + The ``filename`` of the files to delete. + +Errors/Exceptions +----------------- + +.. include:: /includes/extracts/error-gridfs-filenotfoundexception.rst +.. include:: /includes/extracts/error-driver-runtimeexception.rst + +Examples +-------- + +.. code-block:: php + + test->selectGridFSBucket(); + + $stream = fopen('php://temp', 'w+b'); + fwrite($stream, "foobar"); + rewind($stream); + + $bucket->uploadFromStream('filename', $stream); + + $bucket->deleteByName('filename'); \ No newline at end of file diff --git a/source/reference/method/MongoDBGridFSBucket-renameByName.txt b/source/reference/method/MongoDBGridFSBucket-renameByName.txt new file mode 100644 index 00000000..ef351c27 --- /dev/null +++ b/source/reference/method/MongoDBGridFSBucket-renameByName.txt @@ -0,0 +1,62 @@ +======================================= +MongoDB\\GridFS\\Bucket::renameByName() +======================================= + + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Definition +---------- + +.. phpmethod:: MongoDB\GridFS\Bucket::renameByName() + + Sets a new ``filename`` value for a GridFS file and any of its + revisions. + + .. code-block:: php + + function renameByName(string $filename, string $newFilename): void + +Parameters +---------- + +``$filename`` : string + The ``filename`` of the files to rename. + +``$newFilename`` : string + The new ``filename`` value. + +Errors/Exceptions +----------------- + +.. include:: /includes/extracts/error-gridfs-filenotfoundexception.rst +.. include:: /includes/extracts/error-driver-runtimeexception.rst + +Examples +-------- + +.. code-block:: php + + test->selectGridFSBucket(); + + $stream = fopen('php://temp', 'w+b'); + fwrite($stream, "foobar"); + rewind($stream); + + $bucket->uploadFromStream('a', $stream); + + $bucket->renameByName('a', 'b'); + + var_dump(stream_get_contents($bucket->openDownloadStreamByName('b'))); + +The output would then resemble: + +.. code-block:: none + + string(6) "foobar" diff --git a/source/write/gridfs.txt b/source/write/gridfs.txt index 0ceb287e..fd53b346 100644 --- a/source/write/gridfs.txt +++ b/source/write/gridfs.txt @@ -449,4 +449,6 @@ see the following API documentation: - :phpmethod:`MongoDB\GridFS\Bucket::openDownloadStream()` - :phpmethod:`MongoDB\GridFS\Bucket::downloadToStream()` - :phpmethod:`MongoDB\GridFS\Bucket::rename()` -- :phpmethod:`MongoDB\GridFS\Bucket::delete()` \ No newline at end of file +- :phpmethod:`MongoDB\GridFS\Bucket::renameByName()` +- :phpmethod:`MongoDB\GridFS\Bucket::delete()` +- :phpmethod:`MongoDB\GridFS\Bucket::deleteByName()` \ No newline at end of file From 586c4ddc90cb78564c2d273c6b8bf19ec89f45b2 Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 7 Feb 2025 14:51:48 -0500 Subject: [PATCH 19/30] DOCSP-43365: type specification for createSearchIndex(es) (cherry picked from commit e09b124d7dbabc011a35825b2ed1bd8267970b1d) --- source/includes/extracts-note.yaml | 2 +- source/includes/indexes/indexes.php | 58 +++++++++------ source/indexes/atlas-search-index.txt | 71 ++++++++++++------- .../MongoDBCollection-createIndexes.txt | 2 - .../MongoDBCollection-createSearchIndex.txt | 50 +++++++------ .../MongoDBCollection-createSearchIndexes.txt | 10 ++- 6 files changed, 115 insertions(+), 78 deletions(-) diff --git a/source/includes/extracts-note.yaml b/source/includes/extracts-note.yaml index 6225fafb..f607a286 100644 --- a/source/includes/extracts-note.yaml +++ b/source/includes/extracts-note.yaml @@ -20,7 +20,7 @@ content: | --- ref: note-atlas-search-async content: | - Atlas Search indexes are managed asynchronously. After creating or updating an + Atlas Search and Vector Search indexes are managed asynchronously. After creating or updating an index, you can periodically execute :phpmethod:`MongoDB\Collection::listSearchIndexes()` and check the ``queryable`` :manual:`output field ` diff --git a/source/includes/indexes/indexes.php b/source/includes/indexes/indexes.php index 3b293fb1..f286125f 100644 --- a/source/includes/indexes/indexes.php +++ b/source/includes/indexes/indexes.php @@ -57,36 +57,48 @@ // end-index-array-query // start-create-search-index -$indexName = $collection->createSearchIndex( +$searchIndexName = $collection->createSearchIndex( ['mappings' => ['dynamic' => true]], ['name' => 'mySearchIdx'] ); // end-create-search-index -// start-create-search-indexes -$indexNames = $collection->createSearchIndexes( +// start-create-vector-index +$vectorSearchIndexName = $collection->createSearchIndex( [ - [ - 'name' => 'SearchIdx_dynamic', - 'definition' => ['mappings' => ['dynamic' => true]], - ], - [ - 'name' => 'SearchIdx_simple', - 'definition' => [ - 'mappings' => [ - 'dynamic' => false, - 'fields' => [ - 'title' => [ - 'type' => 'string', - 'analyzer' => 'lucene.simple' - ] - ] - ] - ], - ], - ] + 'fields' => [[ + 'type' => 'vector', + 'path' => 'plot_embedding', + 'numDimensions' => 1536, + 'similarity' => 'dotProduct' + ]] + ], + ['name' => 'myVSidx', 'type' => 'vectorSearch'] +); +// end-create-vector-index + +// start-create-multiple-indexes +$indexNames = $collection->createSearchIndexes( + [ + [ + 'name' => 'SearchIdx', + 'definition' => ['mappings' => ['dynamic' => true]], + ], + [ + 'name' => 'VSidx', + 'type' => 'vectorSearch', + 'definition' => [ + 'fields' => [[ + 'type' => 'vector', + 'path' => 'plot_embedding', + 'numDimensions' => 1536, + 'similarity' => 'dotProduct' + ]] + ], + ], + ] ); -// end-create-search-indexes +// end-create-multiple-indexes // start-list-search-indexes foreach ($collection->listSearchIndexes() as $indexInfo) { diff --git a/source/indexes/atlas-search-index.txt b/source/indexes/atlas-search-index.txt index eb8762aa..225bb44e 100644 --- a/source/indexes/atlas-search-index.txt +++ b/source/indexes/atlas-search-index.txt @@ -20,16 +20,19 @@ Atlas Search Indexes Overview -------- -The MongoDB Atlas Search feature enables you to perform full-text -searches on collections hosted on Atlas. Before you can perform Atlas -Search queries, you must create indexes that specify which -fields to index and how they are indexed. +In this guide, you can learn how to programmatically manage your Atlas +Search and Atlas Vector Search indexes by using the {+library-short+}. -To learn more about Atlas Search, see the :atlas:`Atlas Search Overview -`. +The Atlas Search feature enables you to perform full-text searches on +collections hosted on MongoDB Atlas. To learn more about Atlas Search, +see the :atlas:`Atlas Search Overview `. + +Atlas Vector Search enables you to perform semantic searches on vector +embeddings stored in MongoDB Atlas. To learn more about Atlas Vector Search, +see the :atlas:`Atlas Vector Search Overview `. You can use the following methods on a ``MongoDB\Collection`` instance -to manage your Atlas Search indexes: +to manage your Atlas Search and Vector Search indexes: - ``MongoDB\Collection::createSearchIndex()`` - ``MongoDB\Collection::createSearchIndexes()`` @@ -37,15 +40,16 @@ to manage your Atlas Search indexes: - ``MongoDB\Collection::updateSearchIndex()`` - ``MongoDB\Collection::dropSearchIndex()`` -.. note:: Atlas Search Index Management is Asynchronous +.. note:: Search and Vector Search Index Management is Asynchronous - The {+php-library+} manages Atlas Search indexes asynchronously. The - library methods described in the following sections return the server - response immediately, but the changes to your Search indexes take - place in the background and might not complete until some time later. + The {+php-library+} manages Atlas Search and Vector Search indexes + asynchronously. The library methods described in the following + sections return the server response immediately, but the changes to + your Search indexes take place in the background and might not + complete until some time later. The following sections provide code examples that demonstrate how to use -each Atlas Search index management method. +each of the preceding methods. .. _php-atlas-search-index-create: @@ -53,8 +57,9 @@ Create a Search Index --------------------- You can use the ``createSearchIndex()`` method to create a single Atlas -Search index on a collection, or the ``createSearchIndexes()`` method to -create multiple indexes simultaneously. +Search or Vector Search index on a collection, or the +``createSearchIndexes()`` method to create multiple indexes +simultaneously. The following code example shows how to create a single Atlas Search index: @@ -64,17 +69,30 @@ index: :start-after: start-create-search-index :end-before: end-create-search-index -The following code example shows how to create multiple Atlas Search -indexes: +The following code example shows how to create a single Atlas Vector +Search index: + +.. literalinclude:: /includes/indexes/indexes.php + :language: php + :start-after: start-create-vector-index + :end-before: end-create-vector-index + +The following code example shows how to create Search and +Vector Search indexes in one call: .. literalinclude:: /includes/indexes/indexes.php :language: php - :start-after: start-create-search-indexes - :end-before: end-create-search-indexes + :start-after: start-create-multiple-indexes + :end-before: end-create-multiple-indexes + +After you create Atlas Search or Atlas Vector Search indexes, you can +perform the corresponding query types on your documents. -After you create a Search index, you can perform Atlas Search queries on -your collection. To learn more, see :atlas:`Create and Run Atlas Search -Queries ` in the Atlas documentation. +.. + TODO uncomment when https://github.com/mongodb/docs-php-library/pull/197 is merged + To learn more, see the following guides: + - :ref:`php-atlas-search` + - :ref:`php-vector-search` .. _php-atlas-search-index-list: @@ -82,7 +100,7 @@ List Search Indexes ------------------- You can use the ``listSearchIndexes()`` method to return an array of the -Atlas Search indexes on a collection: +Atlas Search and Vector Search indexes on a collection: .. literalinclude:: /includes/indexes/indexes.php :language: php @@ -96,9 +114,8 @@ Update a Search Index --------------------- You can use the ``updateSearchIndex()`` -method to update an Atlas Search index. You can use this method to -change the name of a Search index or change the configuration of the -index. +method to update an Atlas Search or Vector Search index. You can use this method to +change the name or configuration of an existing index. The following code shows how to update a search index to use a simple analyzer on the ``title`` field: @@ -115,7 +132,7 @@ Delete a Search Index --------------------- You can use the ``dropSearchIndex()`` method to remove an Atlas Search -index from a collection. +or Vector Search index from a collection. The following code shows how to delete the Atlas Search index named ``mySearchIdx``: diff --git a/source/reference/method/MongoDBCollection-createIndexes.txt b/source/reference/method/MongoDBCollection-createIndexes.txt index 4357a9f7..802643e9 100644 --- a/source/reference/method/MongoDBCollection-createIndexes.txt +++ b/source/reference/method/MongoDBCollection-createIndexes.txt @@ -2,8 +2,6 @@ MongoDB\\Collection::createIndexes() ==================================== -.. default-domain:: mongodb - .. contents:: On this page :local: :backlinks: none diff --git a/source/reference/method/MongoDBCollection-createSearchIndex.txt b/source/reference/method/MongoDBCollection-createSearchIndex.txt index ae85f97f..3a5c94c3 100644 --- a/source/reference/method/MongoDBCollection-createSearchIndex.txt +++ b/source/reference/method/MongoDBCollection-createSearchIndex.txt @@ -4,8 +4,6 @@ MongoDB\\Collection::createSearchIndex() .. versionadded:: 1.17 -.. default-domain:: mongodb - .. contents:: On this page :local: :backlinks: none @@ -17,14 +15,14 @@ Definition .. phpmethod:: MongoDB\Collection::createSearchIndex() - Create an Atlas Search index for the collection. + Create an Atlas Search or Vector Search index for the collection. .. code-block:: php - function createSearchIndex( - array|object $definition, - array $options = [] - ): string + function createSearchIndex( + array|object $definition, + array $options = [] + ): string .. include:: /includes/extracts/note-atlas-search-requirement.rst @@ -39,28 +37,33 @@ Parameters An array specifying the desired options. .. list-table:: - :header-rows: 1 - :widths: 20 20 80 + :header-rows: 1 + :widths: 20 20 80 - * - Name - - Type - - Description + * - Name + - Type + - Description - * - comment - - mixed - - .. include:: /includes/extracts/common-option-comment.rst + * - comment + - mixed + - .. include:: /includes/extracts/common-option-comment.rst - * - name - - string - - Name of the search index to create. + * - name + - string + - | Name of the search index to create. + | You cannot create multiple indexes with the same name on a single + collection. If you do not specify a name, the index is named ``default``. - You cannot create multiple indexes with the same name on a single - collection. If you do not specify a name, the index is named "default". + * - type + - string + - Type of index to create. Accepted values are ``'search'`` and + ``'vectorSearch'``. If you omit this option, the default + value is ``'search'`` and the method creates an Atlas Search index. Return Values ------------- -The name of the created Atlas Search index as a string. +The name of the created Atlas Search or Vector Search index as a string. Errors/Exceptions ----------------- @@ -92,8 +95,8 @@ to index all document fields containing $collection = (new MongoDB\Client)->selectCollection('test', 'articles'); $indexName = $collection->createSearchIndex( - ['mappings' => ['dynamic' => true]], - ['name' => 'test-search-index'] + ['mappings' => ['dynamic' => true]], + ['name' => 'test-search-index'] ); var_dump($indexName); @@ -111,6 +114,7 @@ See Also - :phpmethod:`MongoDB\Collection::dropSearchIndex()` - :phpmethod:`MongoDB\Collection::listSearchIndexes()` - :phpmethod:`MongoDB\Collection::updateSearchIndex()` +- :ref:`php-atlas-search-index` guide - :manual:`createSearchIndexes ` command reference in the MongoDB manual - `Atlas Search `__ documentation in the MongoDB Manual diff --git a/source/reference/method/MongoDBCollection-createSearchIndexes.txt b/source/reference/method/MongoDBCollection-createSearchIndexes.txt index 85d27d84..abf77d39 100644 --- a/source/reference/method/MongoDBCollection-createSearchIndexes.txt +++ b/source/reference/method/MongoDBCollection-createSearchIndexes.txt @@ -17,7 +17,7 @@ Definition .. phpmethod:: MongoDB\Collection::createSearchIndexes() - Create one or more Atlas Search indexes for the collection. + Create one or more Atlas Search or Vector Search indexes for the collection. .. code-block:: php @@ -42,6 +42,10 @@ Parameters create. You cannot create multiple indexes with the same name on a single collection. If you do not specify a name, the index is named "default". + An optional ``type`` string field specifies the type of search index to + create. Accepted values are ``'search'`` and ``'vectorSearch'``. If + you do not specify a type, the method creates an Atlas Search index. + ``$options`` : array An array specifying the desired options. @@ -60,7 +64,8 @@ Parameters Return Values ------------- -The names of the created Atlas Search indexes as an array of strings. +The names of the created Atlas Search and Vector Search indexes as an +array of strings. Errors/Exceptions ----------------- @@ -118,6 +123,7 @@ See Also - :phpmethod:`MongoDB\Collection::dropSearchIndex()` - :phpmethod:`MongoDB\Collection::listSearchIndexes()` - :phpmethod:`MongoDB\Collection::updateSearchIndex()` +- :ref:`php-atlas-search-index` guide - :manual:`createSearchIndexes ` command reference in the MongoDB manual - `Atlas Search `__ documentation in the MongoDB Manual From 3a0a2514075ae74324ec9b25e68a10012cf71d60 Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 7 Feb 2025 14:55:06 -0500 Subject: [PATCH 20/30] indentation fix (cherry picked from commit cd6a5867e086bec78443a09780e2ec7ce4193391) --- .../MongoDBCollection-createSearchIndex.txt | 48 +++++++++---------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/source/reference/method/MongoDBCollection-createSearchIndex.txt b/source/reference/method/MongoDBCollection-createSearchIndex.txt index 3a5c94c3..a74d0b0a 100644 --- a/source/reference/method/MongoDBCollection-createSearchIndex.txt +++ b/source/reference/method/MongoDBCollection-createSearchIndex.txt @@ -19,10 +19,10 @@ Definition .. code-block:: php - function createSearchIndex( - array|object $definition, - array $options = [] - ): string + function createSearchIndex( + array|object $definition, + array $options = [] + ): string .. include:: /includes/extracts/note-atlas-search-requirement.rst @@ -37,28 +37,28 @@ Parameters An array specifying the desired options. .. list-table:: - :header-rows: 1 - :widths: 20 20 80 + :header-rows: 1 + :widths: 20 20 80 - * - Name - - Type - - Description + * - Name + - Type + - Description - * - comment - - mixed - - .. include:: /includes/extracts/common-option-comment.rst + * - comment + - mixed + - .. include:: /includes/extracts/common-option-comment.rst - * - name - - string - - | Name of the search index to create. - | You cannot create multiple indexes with the same name on a single - collection. If you do not specify a name, the index is named ``default``. + * - name + - string + - | Name of the search index to create. + | You cannot create multiple indexes with the same name on a single + collection. If you do not specify a name, the index is named ``default``. - * - type - - string - - Type of index to create. Accepted values are ``'search'`` and - ``'vectorSearch'``. If you omit this option, the default - value is ``'search'`` and the method creates an Atlas Search index. + * - type + - string + - Type of index to create. Accepted values are ``'search'`` and + ``'vectorSearch'``. If you omit this option, the default + value is ``'search'`` and the method creates an Atlas Search index. Return Values ------------- @@ -95,8 +95,8 @@ to index all document fields containing $collection = (new MongoDB\Client)->selectCollection('test', 'articles'); $indexName = $collection->createSearchIndex( - ['mappings' => ['dynamic' => true]], - ['name' => 'test-search-index'] + ['mappings' => ['dynamic' => true]], + ['name' => 'test-search-index'] ); var_dump($indexName); From c4e06a34e43f4b379da6ffa1612d9e1683c143c6 Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 7 Feb 2025 14:58:03 -0500 Subject: [PATCH 21/30] indentation fix (cherry picked from commit 3b3ec37c252c1169cbbbfe677f27726c18bb14c4) --- source/includes/indexes/indexes.php | 36 ++++++++++++++--------------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/source/includes/indexes/indexes.php b/source/includes/indexes/indexes.php index f286125f..f7947e02 100644 --- a/source/includes/indexes/indexes.php +++ b/source/includes/indexes/indexes.php @@ -79,24 +79,24 @@ // start-create-multiple-indexes $indexNames = $collection->createSearchIndexes( - [ - [ - 'name' => 'SearchIdx', - 'definition' => ['mappings' => ['dynamic' => true]], - ], - [ - 'name' => 'VSidx', - 'type' => 'vectorSearch', - 'definition' => [ - 'fields' => [[ - 'type' => 'vector', - 'path' => 'plot_embedding', - 'numDimensions' => 1536, - 'similarity' => 'dotProduct' - ]] - ], - ], - ] + [ + [ + 'name' => 'SearchIdx', + 'definition' => ['mappings' => ['dynamic' => true]], + ], + [ + 'name' => 'VSidx', + 'type' => 'vectorSearch', + 'definition' => [ + 'fields' => [[ + 'type' => 'vector', + 'path' => 'plot_embedding', + 'numDimensions' => 1536, + 'similarity' => 'dotProduct' + ]] + ], + ], + ] ); // end-create-multiple-indexes From d080be4cc6f62ed1ce56b63f253b76cfc7afdb6d Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 7 Feb 2025 15:01:53 -0500 Subject: [PATCH 22/30] add whats new entry (cherry picked from commit f8210307193c1a7c994e5519d576bb175288559d) --- source/whats-new.txt | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/source/whats-new.txt b/source/whats-new.txt index af355a54..f9fd94e1 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -75,6 +75,13 @@ What's New in 1.20 encryption and decryption of the data key locally, ensuring that the encryption key never leaves the KMIP server. +- Adds the ``type`` option in Search index specifications for + the :phpmethod:`MongoDB\Collection::createIndex()` and + :phpmethod:`MongoDB\Collection::createSearchIndexes()` methods. This + change allows you to create Atlas Vector Search indexes + programmatically. To learn more and view examples, see the + :ref:`php-atlas-search-index` guide. + For more information about the changes in this version, see the :github:`v1.20 release notes ` on GitHub. @@ -135,4 +142,5 @@ What's New in 1.17 7.2 and 7.3 has been removed and the library now requires PHP 7.4 or newer. To learn more about this release, see the `v1.17 Release Notes -`__ on GitHub. \ No newline at end of file +`__ on +GitHub. From 150d78d6009e9609a12eb1658f585cbd943ba6d5 Mon Sep 17 00:00:00 2001 From: rustagir Date: Mon, 10 Feb 2025 09:33:01 -0500 Subject: [PATCH 23/30] SA PR fixes 1 (cherry picked from commit 7d9bfe879947431e4212b411a3d0846f1cca8c9d) --- source/indexes.txt | 5 +++-- source/indexes/atlas-search-index.txt | 4 ++-- .../reference/method/MongoDBCollection-createSearchIndex.txt | 3 ++- .../method/MongoDBCollection-createSearchIndexes.txt | 3 ++- 4 files changed, 9 insertions(+), 6 deletions(-) diff --git a/source/indexes.txt b/source/indexes.txt index 29afd6ed..dfe80727 100644 --- a/source/indexes.txt +++ b/source/indexes.txt @@ -229,9 +229,10 @@ Atlas Search Index Management ----------------------------- The following sections contain code examples that describe how to manage -:atlas:`Atlas Search indexes `. +:atlas:`Atlas Search ` and :atlas:`Vector +Search ` indexes. -.. note:: Atlas Search Index Management is Asynchronous +.. note:: Atlas Search and Vector Search Index Management is Asynchronous The {+php-library+} manages Atlas Search indexes asynchronously. The library methods described in the following sections return the server diff --git a/source/indexes/atlas-search-index.txt b/source/indexes/atlas-search-index.txt index 225bb44e..c3d8fce4 100644 --- a/source/indexes/atlas-search-index.txt +++ b/source/indexes/atlas-search-index.txt @@ -40,7 +40,7 @@ to manage your Atlas Search and Vector Search indexes: - ``MongoDB\Collection::updateSearchIndex()`` - ``MongoDB\Collection::dropSearchIndex()`` -.. note:: Search and Vector Search Index Management is Asynchronous +.. note:: Atlas Search and Vector Search Index Management is Asynchronous The {+php-library+} manages Atlas Search and Vector Search indexes asynchronously. The library methods described in the following @@ -77,7 +77,7 @@ Search index: :start-after: start-create-vector-index :end-before: end-create-vector-index -The following code example shows how to create Search and +The following code example shows how to create Atlas Search and Vector Search indexes in one call: .. literalinclude:: /includes/indexes/indexes.php diff --git a/source/reference/method/MongoDBCollection-createSearchIndex.txt b/source/reference/method/MongoDBCollection-createSearchIndex.txt index a74d0b0a..c7c7b894 100644 --- a/source/reference/method/MongoDBCollection-createSearchIndex.txt +++ b/source/reference/method/MongoDBCollection-createSearchIndex.txt @@ -52,7 +52,8 @@ Parameters - string - | Name of the search index to create. | You cannot create multiple indexes with the same name on a single - collection. If you do not specify a name, the index is named ``default``. + collection. If you do not specify a name, the default index + name is ``default``. * - type - string diff --git a/source/reference/method/MongoDBCollection-createSearchIndexes.txt b/source/reference/method/MongoDBCollection-createSearchIndexes.txt index abf77d39..b9a78aa2 100644 --- a/source/reference/method/MongoDBCollection-createSearchIndexes.txt +++ b/source/reference/method/MongoDBCollection-createSearchIndexes.txt @@ -40,7 +40,8 @@ Parameters An optional ``name`` string field specifies the name of the search index to create. You cannot create multiple indexes with the same name on a single - collection. If you do not specify a name, the index is named "default". + collection. If you do not specify a name, the default index name is + ``default``. An optional ``type`` string field specifies the type of search index to create. Accepted values are ``'search'`` and ``'vectorSearch'``. If From 263bead1c0c60ce8e0c0de44257d61c6a80fbf7a Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Mon, 10 Feb 2025 11:06:55 -0500 Subject: [PATCH 24/30] DOCSP-43457: builderEncoder option (#200) * DOCSP-43457: builderEncoder option * fix * fix type * go back * codec * JT feedback (cherry picked from commit e1ed0563e2c67fea27bb192abecc0f54f1a8fef1) --- source/reference/method/MongoDBClient__construct.txt | 7 +++++++ source/reference/method/MongoDBCollection-bulkWrite.txt | 7 +++++++ source/reference/method/MongoDBCollection__construct.txt | 7 +++++++ source/reference/method/MongoDBDatabase__construct.txt | 7 +++++++ 4 files changed, 28 insertions(+) diff --git a/source/reference/method/MongoDBClient__construct.txt b/source/reference/method/MongoDBClient__construct.txt index 3d8ad586..2edf8f3b 100644 --- a/source/reference/method/MongoDBClient__construct.txt +++ b/source/reference/method/MongoDBClient__construct.txt @@ -125,6 +125,13 @@ Parameters 'root' => 'MongoDB\Model\BSONDocument', ] + * - builderEncoder + - MongoDB\\Codec\\Encoder + - Encoder to use for query and aggregation builders. If not set, this option + defaults to a new instance of the ``MongoDB\Builder\BuilderEncoder`` class. + + .. versionadded:: 1.21 + * - allow_invalid_hostname - boolean - Disables hostname validation if ``true``. Defaults to ``false``. diff --git a/source/reference/method/MongoDBCollection-bulkWrite.txt b/source/reference/method/MongoDBCollection-bulkWrite.txt index 1f273e76..ef942927 100644 --- a/source/reference/method/MongoDBCollection-bulkWrite.txt +++ b/source/reference/method/MongoDBCollection-bulkWrite.txt @@ -65,6 +65,13 @@ Parameters - Type - Description + * - builderEncoder + - MongoDB\\Codec\\Encoder + - Encoder to use for query and aggregation builders. If not set, this option + defaults to a new instance of the ``MongoDB\Builder\BuilderEncoder`` class. + + .. versionadded:: 1.21 + * - bypassDocumentValidation - boolean - If ``true``, allows the write operation to circumvent document level diff --git a/source/reference/method/MongoDBCollection__construct.txt b/source/reference/method/MongoDBCollection__construct.txt index c9ee112d..b1940dff 100644 --- a/source/reference/method/MongoDBCollection__construct.txt +++ b/source/reference/method/MongoDBCollection__construct.txt @@ -49,6 +49,13 @@ Definition - Type - Description + * - builderEncoder + - MongoDB\\Codec\\Encoder + - Encoder to use for query and aggregation builders. If not set, this option + defaults to a new instance of the ``MongoDB\Builder\BuilderEncoder`` class. + + .. versionadded:: 1.21 + * - codec - MongoDB\\Codec\\DocumentCodec - The default :doc:`codec ` to use for collection diff --git a/source/reference/method/MongoDBDatabase__construct.txt b/source/reference/method/MongoDBDatabase__construct.txt index f25e6c4b..f40aa5a8 100644 --- a/source/reference/method/MongoDBDatabase__construct.txt +++ b/source/reference/method/MongoDBDatabase__construct.txt @@ -46,6 +46,13 @@ Parameters - Type - Description + * - builderEncoder + - MongoDB\\Codec\\Encoder + - Encoder to use for query and aggregation builders. If not set, this option + defaults to a new instance of the ``MongoDB\Builder\BuilderEncoder`` class. + + .. versionadded:: 1.21 + * - readConcern - :php:`MongoDB\Driver\ReadConcern ` - The default read concern to use for database operations. Defaults to From 1543f93934f51766a2b312dad40400efaf9767db Mon Sep 17 00:00:00 2001 From: lindseymoore <71525840+lindseymoore@users.noreply.github.com> Date: Mon, 10 Feb 2025 11:54:56 -0500 Subject: [PATCH 25/30] DOCSP-44237 flags Option deprecation on v2.21 (#201) * DOCSP-44237 flags Option deprecation on v2.21 * add what's new note * Rea review comments --- .../reference/method/MongoDBDatabase-createCollection.txt | 6 ++++++ source/whats-new.txt | 3 +++ 2 files changed, 9 insertions(+) diff --git a/source/reference/method/MongoDBDatabase-createCollection.txt b/source/reference/method/MongoDBDatabase-createCollection.txt index 11b62e23..2fbd0572 100644 --- a/source/reference/method/MongoDBDatabase-createCollection.txt +++ b/source/reference/method/MongoDBDatabase-createCollection.txt @@ -152,6 +152,12 @@ Parameters :manual:`db.createCollection() ` for more information. + *Deprecated*: This option is deprecated and will be removed in + the v2.0 {+library-short+} release. To learn more about upgrading + from the MMAPv1 storage engine to Wired Tiger, see the + :manual:`Change a Self-Managed Standalone to WiredTiger ` + guide in the Server manual. + * - indexOptionDefaults - array|object - Allows users to specify a default configuration for indexes when diff --git a/source/whats-new.txt b/source/whats-new.txt index f9fd94e1..5731697e 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -49,6 +49,9 @@ improvements, and fixes: replaced by these new methods in a future driver release, so consider changing the usages in your application. +- Deprecates the ``flags`` option, used for the deprecated MMAPv1 storage engine. + This option will be removed in {+library-short+} v2.0. + .. _php-lib-version-1.20: What's New in 1.20 From 3daba831c63254494a30546bbf4230cc2d3bad8e Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Tue, 11 Feb 2025 09:02:25 -0500 Subject: [PATCH 26/30] DOCSP-45770: atlas search queries (#197) * DOCSP-45770: atlas search queries * fix indentation * fix indentation * fix indentation * fix indentation * snooty landing page * snooty landing page * indentation fix * netlify trigger * whats new * RM PR fixes 1 * comments * small fix * JT tech review 1 * indentation fix * fix * small fixes * small fixes * remov Pipeline type --- snooty.toml | 1 + source/aggregation.txt | 27 +- source/aggregation/atlas-search.txt | 256 ++++++++++++++++++ source/aggregation/vector-search.txt | 217 +++++++++++++++ .../{ => aggregation}/aggregation.php | 0 source/includes/aggregation/atlas-search.php | 145 ++++++++++ source/includes/aggregation/vector-search.php | 104 +++++++ source/whats-new.txt | 6 + 8 files changed, 747 insertions(+), 9 deletions(-) create mode 100644 source/aggregation/atlas-search.txt create mode 100644 source/aggregation/vector-search.txt rename source/includes/{ => aggregation}/aggregation.php (100%) create mode 100644 source/includes/aggregation/atlas-search.php create mode 100644 source/includes/aggregation/vector-search.php diff --git a/snooty.toml b/snooty.toml index c0d688f0..f8b6d380 100644 --- a/snooty.toml +++ b/snooty.toml @@ -30,6 +30,7 @@ toc_landing_pages = [ "/security", "/data-formats", "/upgrade", + "/aggregation" ] sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/" diff --git a/source/aggregation.txt b/source/aggregation.txt index 96e7f63e..527a9626 100644 --- a/source/aggregation.txt +++ b/source/aggregation.txt @@ -18,12 +18,12 @@ Transform Your Data with Aggregation :depth: 2 :class: singlecol -.. TODO: - .. toctree:: - :titlesonly: - :maxdepth: 1 +.. toctree:: + :titlesonly: + :maxdepth: 1 - /aggregation/aggregation-tutorials + Atlas Search + Atlas Vector Search Overview -------- @@ -88,7 +88,7 @@ Aggregation Example ------------------- .. note:: - + The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants`` database from the :atlas:`Atlas sample datasets `. To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the :atlas:`Get Started with Atlas @@ -110,7 +110,7 @@ of New York. To do so, it uses an aggregation pipeline that contains the followi .. io-code-block:: :copyable: - .. input:: /includes/aggregation.php + .. input:: /includes/aggregation/aggregation.php :start-after: start-match-group :end-before: end-match-group :language: php @@ -146,13 +146,13 @@ from the preceding :ref:`php-aggregation-example`: .. io-code-block:: :copyable: - .. input:: /includes/aggregation.php + .. input:: /includes/aggregation/aggregation.php :start-after: start-explain :end-before: end-explain :language: php :dedent: - .. output:: + .. output:: :visible: false {"explainVersion":"2","queryPlanner":{"namespace":"sample_restaurants.restaurants", @@ -188,6 +188,15 @@ pages in the {+mdb-server+} manual: :manual:`Explain Output ` and :manual:`Query Plans `. +Atlas Search and Vector Search +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can perform full-text searches by using the Atlas Search feature. To +learn more, see the :ref:`php-atlas-search` guide. + +You can perform similarity searches on vector embeddings by using the +Atlas Vector Search feature. To learn more, see the :ref:`php-vector-search` guide. + .. TODO: Aggregation Tutorials ~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/aggregation/atlas-search.txt b/source/aggregation/atlas-search.txt new file mode 100644 index 00000000..d47ac750 --- /dev/null +++ b/source/aggregation/atlas-search.txt @@ -0,0 +1,256 @@ +.. _php-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. The {+library-short+} allows you to +perform Atlas Search queries by using the :ref:`Aggregation Builder API +`. + +.. 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:`Atlas Search Overview +`. The Atlas Search implementation +for the {+library-short+} 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:: Atlas Vector Search + + To perform searches on vector embeddings in MongoDB, you can use the + Atlas Vector Search API. To learn about this feature, see + the :ref:`php-vector-search` guide. + +Atlas Search Index +~~~~~~~~~~~~~~~~~~ + +Before you can perform Atlas Search queries, you must create an Atlas +Search index on your collection. To learn more about creating this index +type, see the :ref:`php-atlas-search-index` guide. + +Search Aggregation Stage +------------------------ + +Import the following classes into your application to perform Atlas +Search queries by using the Aggregation Builder: + +.. literalinclude:: /includes/aggregation/atlas-search.php + :language: php + :dedent: + :start-after: start-imports + :end-before: end-imports + +To create a ``$search`` stage in your aggregation pipeline, perform the +following actions: + +1. Create an array to store the pipeline stages + +#. Call the ``Stage::search()`` method to create the Atlas Search stage + +#. Within the body of the ``search()`` method, use methods from the + ``Search`` builder class to construct your Search query criteria + +The following code demonstrates the template for constructing basic Atlas Search +queries: + +.. code-block:: php + + $pipeline = [ + Stage::search( + /* Atlas Search query specifications + Search::compound(...) */ + ), + ]; + +Atlas Search Query Examples +--------------------------- + +In this section, you can learn how to perform different types of Atlas +Search queries by using the Aggregation Builder. The examples in this +section use sample data from the ``sample_restaurants.restaurants`` +collection. + +Compound Query with Filter +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use the ``Search::compound()`` method to combine two or more operators +into a single query. This method takes named arguments for your clauses, +such as ``must`` and ``filter``. In each clause, use the +``Search::text()`` method to specify the strings to look for when +performing the full-text search. + +This example performs an Atlas Search query that has the following +specifications: + +- Includes a ``must`` clause to search the ``name`` field for the string + ``"kitchen"`` +- Includes a ``should`` clause to highly rank documents in which the + ``cuisine`` field includes ``"american"`` +- Includes a ``filter`` field to include only documents in which the + ``borough`` value is ``"Queens"`` in the results + +.. io-code-block:: + :copyable: true + + .. input:: /includes/aggregation/atlas-search.php + :language: php + :dedent: + :start-after: start-compound-search-query + :end-before: end-compound-search-query + + .. output:: + :language: json + :visible: false + + {"_id":...,"borough":"Queens","cuisine":"American","name":"Kitchen Door"} + {"_id":...,"borough":"Queens","cuisine":"American","name":"Cc Kitchen"} + {"_id":...,"borough":"Queens","cuisine":"American","name":"Suite Kitchen"} + // Results truncated + +Autocomplete Query +~~~~~~~~~~~~~~~~~~ + +The {+library-short+} provides the ``Search::autocomplete()`` method to run +autocomplete searches on documents in your collections. + +To learn more about this type of Atlas Search query, see the +:atlas:`autocomplete ` reference in the +Atlas documentation. + +.. note:: + + Your Atlas Search index must be configured for autocomplete queries. + To learn more, see :atlas:`How to Index Fields for Autocompletion + ` in the Atlas + documentation. + +The following code performs an Atlas Search autocomplete query for the +string ``"Lucy"`` on the ``name`` field: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/aggregation/atlas-search.php + :language: php + :dedent: + :start-after: start-autocomplete-search-query + :end-before: end-autocomplete-search-query + + .. output:: + :language: json + :visible: false + + {"name":"Juicy Lucy"} + {"name":"Lucy'S Vietnamese Kitchen"} + {"name":"Lucy'S Cantina Royale"} + // Results Truncated + +You can also pass the following optional parameters to the ``autocomplete()`` +method to customize the query: + +.. list-table:: + :header-rows: 1 + + * - Optional Parameter + - Description + - Default Value + + * - ``fuzzy`` + - Enables fuzzy search and fuzzy search options + - ``false`` + + * - ``tokenOrder`` + - 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. + +Search Options +-------------- + +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. diff --git a/source/aggregation/vector-search.txt b/source/aggregation/vector-search.txt new file mode 100644 index 00000000..b9ca56dc --- /dev/null +++ b/source/aggregation/vector-search.txt @@ -0,0 +1,217 @@ +.. _php-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. The {+library-short+} allows you to +perform Atlas Vector Search queries by using the :ref:`Aggregation Builder API +`. + +.. 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 Vector Search, see the :atlas:`Atlas Vector +Search Overview `. The +Atlas Vector Search implementation for the {+library-short+} 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:: Atlas Search + + To perform advanced full-text search on your documents, you can use the + Atlas Search API. To learn about this feature, see the + :ref:`php-atlas-search` guide. + +Atlas Vector Search Index +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Before you can perform Atlas Vector Search queries, you must create an +Atlas Vector Search index on your collection. To learn more about +creating this index type, see the :ref:`php-atlas-search-index` guide. + +Vector Search Aggregation Stage +------------------------------- + +Import the following classes into your application to perform Atlas +Search queries by using the Aggregation Builder: + +.. literalinclude:: /includes/aggregation/vector-search.php + :language: php + :dedent: + :start-after: start-imports + :end-before: end-imports + +To create a ``$vectorSearch`` stage in your aggregation pipeline, perform the +following actions: + +1. Create an array to store the pipeline stages + +#. Call the ``Stage::vectorSearch()`` method to create the Atlas Vector + Search stage + +#. Within the body of the ``vectorSearch()`` method, specify the + criteria for your vector query + +The following code demonstrates the template for constructing basic Atlas Search +queries: + +.. code-block:: php + + $pipeline = [ + Stage::vectorSearch( + /* Atlas Vector Search query specifications + index: '', + path: '', ...*/ + ), + ]; + +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`` + - ``array`` or ``string`` + - Field that stores vector embeddings + + * - ``queryVector`` + - ``array`` + - Vector representation of your query + + * - ``limit`` + - ``int`` + - Number of results to return + +Atlas Search Query Examples +--------------------------- + +In this section, you can learn how to perform Atlas Vector +Search queries by using the Aggregation Builder. The examples in this +section use sample data from the ``sample_mflix.embedded_movies`` +collection. + +.. note:: Query Vector Length + + For demonstrative purposes, the examples in this section use + sample query vectors that contain very few elements, compared to + the query vector you might use in a runnable application. To view an + example that contains the full-length query vector, see the + :atlas:`Atlas Vector Search Quick Start ` + and select :guilabel:`PHP` from the :guilabel:`Select your language` dropdown in the upper-right + corner of the page. + +Basic Vector Search Query +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following code performs an Atlas Vector Search query on the +``plot_embedding`` vector field: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/aggregation/vector-search.php + :language: php + :dedent: + :start-after: start-basic-query + :end-before: end-basic-query + + .. output:: + :language: json + :visible: false + + {"title":"Thrill Seekers"} + {"title":"About Time"} + {"title":"Timecop"} + // Results truncated + +Vector Search Score +~~~~~~~~~~~~~~~~~~~ + +The following code performs the same query as in the preceding example, +but outputs only the ``title`` field and ``vectorSearchScore`` meta +field, which describes how well the document matches the query vector: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/aggregation/vector-search.php + :language: php + :dedent: + :start-after: start-score-query + :end-before: end-score-query + + .. output:: + :language: json + :visible: false + + {"title":"Thrill Seekers","score":0.927734375} + {"title":"About Time","score":0.925750732421875} + {"title":"Timecop","score":0.9241180419921875} + // Results truncated + +Vector Search Options +--------------------- + +You can use the ``vectorSearch()`` method to perform many types of Atlas +Vector 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`` + +To learn more about these parameters, see the :atlas:`Fields +` section of the +``$vectorSearch`` operator reference in the Atlas documentation. diff --git a/source/includes/aggregation.php b/source/includes/aggregation/aggregation.php similarity index 100% rename from source/includes/aggregation.php rename to source/includes/aggregation/aggregation.php diff --git a/source/includes/aggregation/atlas-search.php b/source/includes/aggregation/atlas-search.php new file mode 100644 index 00000000..80f165f2 --- /dev/null +++ b/source/includes/aggregation/atlas-search.php @@ -0,0 +1,145 @@ +sample_restaurants->restaurants; + +define('WAIT_TIMEOUT_SEC', 300); + +echo "\nCreating the Atlas Search index.\n"; +$collection->createSearchIndex( + ['mappings' => ['dynamic' => true]], +); + +// Waits for the index to be queryable +wait(function () use ($collection) { + echo '.'; + foreach ($collection->listSearchIndexes() as $index) { + if ($index->name === 'default') { + return $index->queryable; + } + } + + return false; +}); + +echo "\n"; + +// start-compound-search-query +$pipeline = [ + Stage::search( + Search::compound( + must: [ + Search::text( + query: 'kitchen', + path: 'name', + ), + ], + should: [ + Search::text( + query: 'american', + path: 'cuisine', + ), + ], + filter: [ + Search::text( + query: 'Queens', + path: 'borough', + ), + ], + ), + ), + Stage::project( + borough: 1, + cuisine: 1, + name: 1 + ), + Stage::limit(3) +]; + +$cursor = $collection->aggregate($pipeline); + +foreach ($cursor as $doc) { + echo json_encode($doc), PHP_EOL; +} +// end-compound-search-query + +echo "\nUpdating the Atlas Search index for autocomplete.\n"; +$collection->updateSearchIndex( + 'default', + ['mappings' => [ + "dynamic" => false, + "fields" => [ + "name" => [ + ["type" => "stringFacet"], + ["type" => "string"], + [ + "foldDiacritics" => false, + "maxGrams" => 7, + "minGrams" => 3, + "tokenization" => "edgeGram", + "type" => "autocomplete" + ], + ] + ] + ]] +); + +// Waits for the index to be updated. +wait(function () use ($collection) { + echo '.'; + foreach ($collection->listSearchIndexes() as $index) { + if ($index->name === 'default') { + return $index->latestDefinition->mappings->fields->name[2]['type'] === 'autocomplete' + && $index->status === 'READY'; + } + } + + return false; +}); + +echo "\n"; + +// start-autocomplete-search-query +$pipeline = [ + Stage::search( + Search::autocomplete( + query: 'Lucy', + path: 'name', + ), + ), + Stage::limit(3), + Stage::project(_id: 0, name: 1), +]; + +$cursor = $collection->aggregate($pipeline); + +foreach ($cursor as $doc) { + echo json_encode($doc), PHP_EOL; +} +// end-autocomplete-search-query + +/** + * This function waits until the callback returns true or the timeout is reached. + */ +function wait(Closure $callback): void +{ + $timeout = hrtime()[0] + WAIT_TIMEOUT_SEC; + while (hrtime()[0] < $timeout) { + if ($callback()) { + return; + } + + sleep(5); + } + + throw new RuntimeException('Time out'); +} diff --git a/source/includes/aggregation/vector-search.php b/source/includes/aggregation/vector-search.php new file mode 100644 index 00000000..c8e0c924 --- /dev/null +++ b/source/includes/aggregation/vector-search.php @@ -0,0 +1,104 @@ +sample_mflix->embedded_movies; + +define('WAIT_TIMEOUT_SEC', 300); + +echo "\nCreating the Atlas Vector Search index.\n"; +$collection->createSearchIndex( + [ + 'fields' => [[ + 'type' => 'vector', + 'path' => 'plot_embedding', + 'numDimensions' => 1536, + 'similarity' => 'dotProduct', + 'quantization' => 'scalar' + ]] + ], + ['name' => 'vector', 'type' => 'vectorSearch'], +); + +// Wait for the index to be queryable. +wait(function () use ($collection) { + echo '.'; + foreach ($collection->listSearchIndexes() as $index) { + if ($index->name === 'vector') { + return $index->queryable; + } + } + + return false; +}); + +echo "\n"; + +// start-basic-query +$pipeline = [ + Stage::vectorSearch( + index: 'vector', + path: 'plot_embedding', + queryVector: [-0.0016261312, -0.028070757, -0.011342932], + numCandidates: 150, + limit: 5, + ), + Stage::project( + _id: 0, + title: 1, + ), +]; + +$cursor = $collection->aggregate($pipeline); + +foreach ($cursor as $doc) { + echo json_encode($doc), PHP_EOL; +} +// end-basic-query + +// start-score-query +$pipeline = [ + Stage::vectorSearch( + index: 'vector', + path: 'plot_embedding', + queryVector: [-0.0016261312, -0.028070757, -0.011342932], + numCandidates: 150, + limit: 5, + ), + Stage::project( + _id: 0, + title: 1, + score: ['$meta' => 'vectorSearchScore'], + ), +]; + +$cursor = $collection->aggregate($pipeline); + +foreach ($cursor as $doc) { + echo json_encode($doc), PHP_EOL; +} +// end-score-query + +/** + * This function waits until the callback returns true or the timeout is reached. + */ +function wait(Closure $callback): void +{ + $timeout = hrtime()[0] + WAIT_TIMEOUT_SEC; + while (hrtime()[0] < $timeout) { + if ($callback()) { + return; + } + + sleep(5); + } + + throw new RuntimeException('Time out'); +} diff --git a/source/whats-new.txt b/source/whats-new.txt index 5731697e..62b87004 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -49,6 +49,12 @@ improvements, and fixes: replaced by these new methods in a future driver release, so consider changing the usages in your application. +- Adds named arguments for the ``SearchStage``, ``VectorSearchStage``, + and ``SearchMetaStage`` builder classes. This change + allows you to write Atlas Search and Atlas Vector Search queries in a + more type-safe and organized way. To learn more, see the + :ref:`php-atlas-search` and :ref:`php-vector-search` guides. + - Deprecates the ``flags`` option, used for the deprecated MMAPv1 storage engine. This option will be removed in {+library-short+} v2.0. From d2c1afbde8093d08fde35d0fd889f4102c934998 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Thu, 13 Feb 2025 14:16:57 -0500 Subject: [PATCH 27/30] DOCSP-45878: Transactions parallelism note (#204) (cherry picked from commit ba91a37d3e0df7a16b2365f71ddba06bb27cc3fe) --- source/write/transaction.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/write/transaction.txt b/source/write/transaction.txt index 342be0e4..5a929cc0 100644 --- a/source/write/transaction.txt +++ b/source/write/transaction.txt @@ -161,6 +161,8 @@ completes the following actions: Successfully performed transaction! Summary: SAVINGS +1000 CHECKING -1000 +.. sharedinclude:: dbx/transactions-parallelism.rst + Additional Information ---------------------- From bc9c0e295cad6a0203721d7dffdc0ba6b2e7173d Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Thu, 13 Feb 2025 15:48:36 -0500 Subject: [PATCH 28/30] DOCSP-43919: aggregation builder (#203) * DOCSP-43919: aggregation builder * indentation fix * remov Pipeline type * LM PR fixes 1 * fp fixes * todo fixes * small fixes * JM tech review 1 --- .github/workflows/coding-standards.yml | 4 +- .github/workflows/static-analysis.yml | 4 +- snooty.toml | 1 + source/aggregation.txt | 228 ++++++++++++++++++-- source/aggregation/atlas-search.txt | 9 +- source/aggregation/vector-search.txt | 9 +- source/includes/aggregation/aggregation.php | 83 ++++++- source/indexes/atlas-search-index.txt | 10 +- source/whats-new.txt | 5 + 9 files changed, 305 insertions(+), 48 deletions(-) diff --git a/.github/workflows/coding-standards.yml b/.github/workflows/coding-standards.yml index 30012e46..18961eb7 100644 --- a/.github/workflows/coding-standards.yml +++ b/.github/workflows/coding-standards.yml @@ -8,9 +8,7 @@ on: env: PHP_VERSION: "8.2" - # TODO: change to "stable" once 1.20.0 is released - # DRIVER_VERSION: "stable" - DRIVER_VERSION: "mongodb/mongo-php-driver@master" + DRIVER_VERSION: "stable" jobs: phpcs: diff --git a/.github/workflows/static-analysis.yml b/.github/workflows/static-analysis.yml index ef58d7c5..3a655b5f 100644 --- a/.github/workflows/static-analysis.yml +++ b/.github/workflows/static-analysis.yml @@ -14,9 +14,7 @@ on: env: PHP_VERSION: "8.2" - # TODO: change to "stable" once 1.20.0 is released - # DRIVER_VERSION: "stable" - DRIVER_VERSION: "mongodb/mongo-php-driver@master" + DRIVER_VERSION: "stable" jobs: psalm: diff --git a/snooty.toml b/snooty.toml index f8b6d380..2d2e7384 100644 --- a/snooty.toml +++ b/snooty.toml @@ -41,6 +41,7 @@ php-library = "MongoDB PHP Library" [constants] php-library = "MongoDB PHP Library" version = "1.20" +source-gh-branch = "v1.x" full-version = "{+version+}.0" extension-short = "PHP extension" mdb-server = "MongoDB Server" diff --git a/source/aggregation.txt b/source/aggregation.txt index 527a9626..2ec29c8f 100644 --- a/source/aggregation.txt +++ b/source/aggregation.txt @@ -47,8 +47,8 @@ The **aggregation pipeline** is the assembly line, **aggregation stages** are th assembly stations, and **operator expressions** are the specialized tools. -Aggregation Versus Find Operations -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Compare Aggregation and Find Operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can use find operations to perform the following actions: @@ -72,6 +72,7 @@ Consider the following limitations when performing aggregation operations: - Returned documents cannot violate the :manual:`BSON document size limit ` of 16 megabytes. + - Pipeline stages have a memory limit of 100 megabytes by default. You can exceed this limit by creating an options array that sets the ``allowDiskUse`` option to ``true`` and passing the array to the ``MongoDB\Collection::aggregate()`` method. @@ -82,37 +83,63 @@ Consider the following limitations when performing aggregation operations: ` stage has a strict memory limit of 100 megabytes and ignores the ``allowDiskUse`` option. -.. _php-aggregation-example: +Aggregation APIs +---------------- -Aggregation Example -------------------- +The {+library-short+} provides the following APIs to create aggregation +pipelines: + +- :ref:`php-aggregation-array-api`: Create aggregation pipelines by + passing arrays that specify the aggregation stages. +- :ref:`php-aggregation-builder-api`: Create aggregation pipelines by + using factory methods to make your application more type-safe and debuggable. + +The following sections describe each API and provide examples for +creating aggregation pipelines. -.. note:: +.. _php-aggregation-array-api: - The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants`` - database from the :atlas:`Atlas sample datasets `. To learn how to create a - free MongoDB Atlas cluster and load the sample datasets, see the :atlas:`Get Started with Atlas - ` guide. +Array API +--------- -To perform an aggregation, pass an array containing the pipeline stages to -the ``MongoDB\Collection::aggregate()`` method. +To perform an aggregation, pass an array containing the pipeline stages +as BSON documents to the ``MongoDB\Collection::aggregate()`` method, as +shown in the following code: + +.. code-block:: php + + $pipeline = [ + ['' => ], + ['' => ], + ... + ]; + + $cursor = $collection->aggregate($pipeline); + +The examples in this section use the ``restaurants`` collection in the ``sample_restaurants`` +database from the :atlas:`Atlas sample datasets `. To learn how to create a +free MongoDB Atlas cluster and load the sample datasets, see the :atlas:`Get Started with Atlas +` guide. + +Filter and Group Example +~~~~~~~~~~~~~~~~~~~~~~~~ The following code example produces a count of the number of bakeries in each borough of New York. To do so, it uses an aggregation pipeline that contains the following stages: -- :manual:`$match ` stage to filter for documents - in which the ``cuisine`` field contains the value ``'Bakery'`` +1. :manual:`$match ` stage to filter for documents + in which the ``cuisine`` field contains the value ``'Bakery'`` -- :manual:`$group ` stage to group the matching - documents by the ``borough`` field, accumulating a count of documents for each distinct - value +#. :manual:`$group ` stage to group the matching + documents by the ``borough`` field, accumulating a count of documents for each distinct + value .. io-code-block:: :copyable: .. input:: /includes/aggregation/aggregation.php - :start-after: start-match-group - :end-before: end-match-group + :start-after: start-array-match-group + :end-before: end-array-match-group :language: php :dedent: @@ -141,14 +168,14 @@ and pass the database, collection, and pipeline stages as parameters. Then, pass ``MongoDB\Operation\Aggregate`` object to the ``MongoDB\Collection::explain()`` method. The following example instructs MongoDB to explain the aggregation operation -from the preceding :ref:`php-aggregation-example`: +from the preceding section: .. io-code-block:: :copyable: .. input:: /includes/aggregation/aggregation.php - :start-after: start-explain - :end-before: end-explain + :start-after: start-array-explain + :end-before: end-array-explain :language: php :dedent: @@ -161,6 +188,158 @@ from the preceding :ref:`php-aggregation-example`: "maxIndexedAndSolutionsReached":false,"maxScansToExplodeReached":false,"winningPlan":{ ... } +.. _php-aggregation-builder-api: + +Aggregation Builder +------------------- + +To create an aggregation pipeline by using the Aggregation Builder, +perform the following actions: + +1. Create an array to store the pipeline stages. + +#. For each stage, call the a factory method from the + ``Stage`` that shares the same name as your desired aggregation + stage. For example, to create an ``$unwind`` stage, call the + ``Stage::unwind()`` method. + +#. Within the body of the ``Stage`` method, use methods from other + builder classes such as ``Query``, ``Expression``, or ``Accumulator`` + to express your aggregation specifications. + +The following code demonstrates the template for constructing +aggregation pipelines: + +.. code-block:: php + + $pipeline = [ + Stage::( + + ), + Stage::( + + ), + ... + ]; + + $cursor = $collection->aggregate($pipeline); + +The examples in this section are adapted from the {+mdb-server+} manual. +Each example provides a link to the sample data that you can insert into +your database to test the aggregation operation. + +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 manual. + +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 + +.. io-code-block:: + :copyable: + + .. input:: /includes/aggregation/aggregation.php + :start-after: start-builder-match-group + :end-before: end-builder-match-group + :language: php + :dedent: + + .. output:: + :visible: false + + {"_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} + +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 manual. + +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 + +.. io-code-block:: + :copyable: + + .. input:: /includes/aggregation/aggregation.php + :start-after: start-builder-unwind + :end-before: end-builder-unwind + :language: php + :dedent: + + .. output:: + :visible: false + + {"_id":"office","totalSalesAmount":{"$numberDecimal":"1019.60"}} + {"_id":"school","totalSalesAmount":{"$numberDecimal":"104.85"}} + {"_id":"stationary","totalSalesAmount":{"$numberDecimal":"264.45"}} + {"_id":"electronics","totalSalesAmount":{"$numberDecimal":"800.00"}} + {"_id":"writing","totalSalesAmount":{"$numberDecimal":"60.00"}} + +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 manual. + +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. + +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. + +.. io-code-block:: + :copyable: + + .. input:: /includes/aggregation/aggregation.php + :start-after: start-builder-lookup + :end-before: end-builder-lookup + :language: php + :dedent: + + .. output:: + :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}]} + Additional Information ---------------------- @@ -169,6 +348,11 @@ pipelines, see `Complex Aggregation Pipelines with Vanilla PHP and MongoDB `__ in the MongoDB Developer Center. +To view more examples of aggregation pipelines built by using the Aggregation +Builder, see the :github:`Stage class test suite +` in the +{+library-short+} source code on GitHub. + MongoDB Server Manual ~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/aggregation/atlas-search.txt b/source/aggregation/atlas-search.txt index d47ac750..8846459f 100644 --- a/source/aggregation/atlas-search.txt +++ b/source/aggregation/atlas-search.txt @@ -22,8 +22,7 @@ Overview In this guide, you can learn how to perform searches on your documents by using the Atlas Search feature. The {+library-short+} allows you to -perform Atlas Search queries by using the :ref:`Aggregation Builder API -`. +perform Atlas Search queries by using the :ref:`php-aggregation-builder-api`. .. note:: Deployment Compatibility @@ -66,12 +65,12 @@ Search queries by using the Aggregation Builder: To create a ``$search`` stage in your aggregation pipeline, perform the following actions: -1. Create an array to store the pipeline stages +1. Create an array to store the pipeline stages. -#. Call the ``Stage::search()`` method to create the Atlas Search stage +#. Call the ``Stage::search()`` method to create the Atlas Search stage. #. Within the body of the ``search()`` method, use methods from the - ``Search`` builder class to construct your Search query criteria + ``Search`` builder class to construct your Search query criteria. The following code demonstrates the template for constructing basic Atlas Search queries: diff --git a/source/aggregation/vector-search.txt b/source/aggregation/vector-search.txt index b9ca56dc..c1396ac7 100644 --- a/source/aggregation/vector-search.txt +++ b/source/aggregation/vector-search.txt @@ -22,8 +22,7 @@ Overview In this guide, you can learn how to perform searches on your documents by using the Atlas Vector Search feature. The {+library-short+} allows you to -perform Atlas Vector Search queries by using the :ref:`Aggregation Builder API -`. +perform Atlas Vector Search queries by using the :ref:`php-aggregation-builder-api`. .. note:: Deployment Compatibility @@ -67,13 +66,13 @@ Search queries by using the Aggregation Builder: To create a ``$vectorSearch`` stage in your aggregation pipeline, perform the following actions: -1. Create an array to store the pipeline stages +1. Create an array to store the pipeline stages. #. Call the ``Stage::vectorSearch()`` method to create the Atlas Vector - Search stage + Search stage. #. Within the body of the ``vectorSearch()`` method, specify the - criteria for your vector query + criteria for your vector query. The following code demonstrates the template for constructing basic Atlas Search queries: diff --git a/source/includes/aggregation/aggregation.php b/source/includes/aggregation/aggregation.php index e8b1a7f9..5aa56684 100644 --- a/source/includes/aggregation/aggregation.php +++ b/source/includes/aggregation/aggregation.php @@ -1,4 +1,5 @@ ['cuisine' => 'Bakery']], ['$group' => ['_id' => '$borough', 'count' => ['$sum' => 1]]], @@ -19,10 +20,10 @@ foreach ($cursor as $doc) { echo json_encode($doc), PHP_EOL; } -// end-match-group +// end-array-match-group // Performs the same aggregation operation as above but asks MongoDB to explain it -// start-explain +// start-array-explain $pipeline = [ ['$match' => ['cuisine' => 'Bakery']], ['$group' => ['_id' => '$borough', 'count' => ['$sum' => 1]]], @@ -36,5 +37,79 @@ $result = $collection->explain($aggregate); echo json_encode($result), PHP_EOL; -// end-explain +// end-array-explain + +// start-builder-match-group +$pipeline = [ + MongoDB\Builder\Stage::match( + date: [ + MongoDB\Builder\Query::gte(new MongoDB\BSON\UTCDateTime(new DateTimeImmutable('2014-01-01'))), + MongoDB\Builder\Query::lt(new MongoDB\BSON\UTCDateTime(new DateTimeImmutable('2015-01-01'))), + ], + ), + MongoDB\Builder\Stage::group( + _id: MongoDB\Builder\Expression::dateToString(MongoDB\Builder\Expression::dateFieldPath('date'), '%Y-%m-%d'), + totalSaleAmount: MongoDB\Builder\Accumulator::sum( + MongoDB\Builder\Expression::multiply( + MongoDB\Builder\Expression::numberFieldPath('price'), + MongoDB\Builder\Expression::numberFieldPath('quantity'), + ), + ), + averageQuantity: MongoDB\Builder\Accumulator::avg( + MongoDB\Builder\Expression::numberFieldPath('quantity'), + ), + count: MongoDB\Builder\Accumulator::sum(1), + ), + MongoDB\Builder\Stage::sort( + totalSaleAmount: MongoDB\Builder\Type\Sort::Desc, + ), +]; + +$cursor = $collection->aggregate($pipeline); + +foreach ($cursor as $doc) { + echo json_encode($doc), PHP_EOL; +} +// end-builder-match-group + +// start-builder-unwind +$pipeline = [ + MongoDB\Builder\Stage::unwind(MongoDB\Builder\Expression::arrayFieldPath('items')), + MongoDB\Builder\Stage::unwind(MongoDB\Builder\Expression::arrayFieldPath('items.tags')), + MongoDB\Builder\Stage::group( + _id: MongoDB\Builder\Expression::fieldPath('items.tags'), + totalSalesAmount: MongoDB\Builder\Accumulator::sum( + MongoDB\Builder\Expression::multiply( + MongoDB\Builder\Expression::numberFieldPath('items.price'), + MongoDB\Builder\Expression::numberFieldPath('items.quantity'), + ), + ), + ), +]; + +$cursor = $collection->aggregate($pipeline); + +foreach ($cursor as $doc) { + echo json_encode($doc), PHP_EOL; +} +// end-builder-unwind + +$collection = $client->db->orders; + +// start-builder-lookup +$pipeline = [ + MongoDB\Builder\Stage::lookup( + from: 'inventory', + localField: 'item', + foreignField: 'sku', + as: 'inventory_docs', + ), +]; + +/* Performs the aggregation on the orders collection */ +$cursor = $collection->aggregate($pipeline); +foreach ($cursor as $doc) { + echo json_encode($doc), PHP_EOL; +} +// end-builder-lookup diff --git a/source/indexes/atlas-search-index.txt b/source/indexes/atlas-search-index.txt index c3d8fce4..8b6a1c50 100644 --- a/source/indexes/atlas-search-index.txt +++ b/source/indexes/atlas-search-index.txt @@ -86,13 +86,11 @@ Vector Search indexes in one call: :end-before: end-create-multiple-indexes After you create Atlas Search or Atlas Vector Search indexes, you can -perform the corresponding query types on your documents. +perform the corresponding query types on your documents. To learn more, +see the following guides: -.. - TODO uncomment when https://github.com/mongodb/docs-php-library/pull/197 is merged - To learn more, see the following guides: - - :ref:`php-atlas-search` - - :ref:`php-vector-search` +- :ref:`php-atlas-search` guide +- :ref:`php-vector-search` guide .. _php-atlas-search-index-list: diff --git a/source/whats-new.txt b/source/whats-new.txt index 62b87004..ab6a7a9e 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -38,6 +38,11 @@ What's New in 1.21 The {+library-short+} v1.21 release includes the following features, improvements, and fixes: +- Introduces the Aggregation Builder, an API to build aggregation + pipelines in a more type-safe way. To learn more and + view examples, see the :ref:`php-aggregation-builder-api` section of + the Aggregation guide. + - Adds the following methods: - :phpmethod:`MongoDB\Client::getDatabase()`: alias for :phpmethod:`MongoDB\Client::selectDatabase()` From 5250d436284460afc293ee668d6521b7cf09e4b1 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Thu, 13 Feb 2025 15:53:01 -0500 Subject: [PATCH 29/30] DOCSP-46127: Update manual link (#205) * DOCSP-46127: Update manual link * MW feedback (cherry picked from commit bf6ac8a943b3548ef608c5247c05356d8781c77f) --- snooty.toml | 1 - source/security/authentication.txt | 5 ++--- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/snooty.toml b/snooty.toml index 2d2e7384..a15ae3ae 100644 --- a/snooty.toml +++ b/snooty.toml @@ -49,7 +49,6 @@ stable-api = "Stable API" library-short = "PHP library" driver-short = "{+library-short+}" api = "https://www.mongodb.com/docs/php-library/current/reference" -php-manual = "https://www.php.net/manual/en" string-data-type = "``string``" bool-data-type = "``bool``" int-data-type = "``int``" diff --git a/source/security/authentication.txt b/source/security/authentication.txt index e03e9856..f4be9f13 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -384,7 +384,6 @@ API Documentation To learn more about the ``MongoDB\Client`` class, see :phpclass:`MongoDB\Client` in the library API documentation. -To view a full list of URI options that you can pass to a ``MongoDB\Client``, see -`MongoDB\\Driver\\Manager::__construct() Parameters -<{+php-manual+}/mongodb-driver-manager.construct.php#refsect1-mongodb-driver-manager.construct-parameters>`__ +To view a full list of URI options that you can pass to a ``MongoDB\Client``, see the +:php:`MongoDB\Driver\Manager::__construct parameters ` in the extension API documentation. \ No newline at end of file From e729a2e97b4ff1172efd9634c107e32f1320fa05 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Thu, 20 Feb 2025 09:36:56 -0500 Subject: [PATCH 30/30] DOCSP-47690: aws lambda tutorial (#207) * DOCSP-47690: aws lambda tutorial * fixes * fixes * fixes * MM PR fixes 1 * remove section * RB small fix (cherry picked from commit 8ed8ddee3dacc48e75ce6acd97c32ad36a6f473b) --- source/aws-lambda.txt | 173 ++++++++++++++++++ .../aws-lambda/composer.json | 0 .../aws-lambda/index.php | 0 .../aws-lambda/serverless.yml | 0 source/index.txt | 9 +- source/tutorial/aws-lambda.txt | 153 ---------------- 6 files changed, 181 insertions(+), 154 deletions(-) create mode 100644 source/aws-lambda.txt rename source/{examples => includes}/aws-lambda/composer.json (100%) rename source/{examples => includes}/aws-lambda/index.php (100%) rename source/{examples => includes}/aws-lambda/serverless.yml (100%) delete mode 100644 source/tutorial/aws-lambda.txt diff --git a/source/aws-lambda.txt b/source/aws-lambda.txt new file mode 100644 index 00000000..54236adc --- /dev/null +++ b/source/aws-lambda.txt @@ -0,0 +1,173 @@ +.. _php-aws-lambda: + +================================== +Deploy to AWS Lambda by Using Bref +================================== + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :keywords: serverless, deployment, code example, live + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to use `Bref +`__ to deploy serverless PHP applications to AWS +Lambda. This guide demonstrates how to deploy a PHP application built by +using the {+library-short+} and connect to an Atlas cluster by using AWS +IAM authentication. + +Before You Get Started +---------------------- + +Before you can deploy to AWS Lambda by using Bref, you must set up the +following components: + +- AWS account and access keys +- `Serverless Framework `__ + +The `Setup `__ tutorial in the Bref +documentation describes how to prepare these components. + +Install Dependencies +-------------------- + +Bref uses `Lambda layers +`__ to +provide the PHP runtime. The ``bref`` layer integrates Bref into your +application and is compiled with PHP and a few other extensions. You can +install the other necessary extensions, such as ``mongodb``, in other layers. + +The following commands create a new project directory and install the +MongoDB and Bref dependencies: + +.. code-block:: bash + + mkdir bref-mongodb-app && cd bref-mongodb-app + composer init + composer require bref/bref bref/extra-php-extensions mongodb/mongodb + +Then, initialize the serverless configuration by using the ``bref`` +command: + +.. code-block:: bash + + vendor/bin/bref init + +After the commands complete, your project contains the following files: + +- ``composer.json``: Lists PHP dependencies installed in the ``vendor`` directory +- ``index.php``: Defines a sample webpage +- ``serverless.yml``: Configures the deployment + +Add the MongoDB Extension to Your Configuration +----------------------------------------------- + +After you initialize the project, you can add the ``mongodb`` extension. +Locate the ``Serverless config`` name in the list of extensions provided +by the :github:`bref/extra-php-extension ` +package. Add it to the ``layers`` of the function in the ``serverless.yaml`` +file, as shown in the following code: + +.. code-block:: yaml + + plugins: + - ./vendor/bref/bref + - ./vendor/bref/extra-php-extensions # Adds the extra Serverless plugin + + functions: + api: + handler: index.php + runtime: php-83-fpm + layers: + - ${bref-extra:mongodb-php-81} # Adds the MongoDB layer + +Customize the Sample Application +-------------------------------- + +Create a web page that list planets from the Atlas :atlas:`sample data +` by replacing the contents of ``index.php`` with the +following code: + +.. literalinclude:: /includes/aws-lambda/index.php + :language: php + +.. tip:: Find Operations + + The preceding code uses the :phpmethod:`MongoDB\Collection::find()` + method to retrieve documents. To learn more about this method, see the + :ref:`php-retrieve` guide. + +Set AWS Credentials +------------------- + +Atlas supports passwordless authentication when using AWS credentials. +In any Lambda function, AWS sets environment variables that contain the +access token and secret token for the role assigned to deploy the function. + +The following steps demonstrate how to set the role in your Atlas +cluster: + +1. Open the Lambda function in the AWS console. +#. Navigate to :guilabel:`Configuration > Permission`, then copy the + :guilabel:`Role name`. +#. Add this role to your Atlas cluster in the :guilabel:`Database + Access` section. Select the :guilabel:`AWS IAM` authentication method + and set the built-in role ``Read and write any database``. + +To learn how to set up unified AWS access, see :atlas:`Set Up Unified +AWS Access ` in the Atlas documentation. + +After you configure the permissions, the Lambda function is allowed to access +your Atlas cluster. Next, configure your application to use the Atlas endpoint. + +Access to Atlas clusters is also restricted by IP address. Since the +range of IP addresses that comes from AWS is very wide, you can allow +access from everywhere. To learn how to allow universal access, see +:atlas:`Configure IP Access List Entries ` in +the Atlas documentation. + +.. note:: + + Using Virtual Private Cloud (VPC) Peering is recommended to isolate + your Atlas cluster from the internet. This requires the Lambda + function to be deployed in the AWS VPC. To learn more, see + :atlas:`Set Up a Network Peering Connection ` + in the Atlas documentation. + +Next, copy your connection string and remove the ``:`` section, as your credentials are read from environment variables. + +In your project's ``serverless.yml`` file, set the +``MONGODB_URI`` environment variable to your connection string: + +.. code-block:: yaml + + provider: + environment: + MONGODB_URI: "" + +To learn more about using the ``MONGODB-AWS`` authentication mechanism, +see the :ref:`MONGODB-AWS ` section of the +Authentication Mechanisms guide. + +Deploy Your Application +----------------------- + +Finally, deploy the application: + +.. code-block:: bash + + serverless deploy + +After deployment completes, you can access the URL and see the +list of planets from your collection. diff --git a/source/examples/aws-lambda/composer.json b/source/includes/aws-lambda/composer.json similarity index 100% rename from source/examples/aws-lambda/composer.json rename to source/includes/aws-lambda/composer.json diff --git a/source/examples/aws-lambda/index.php b/source/includes/aws-lambda/index.php similarity index 100% rename from source/examples/aws-lambda/index.php rename to source/includes/aws-lambda/index.php diff --git a/source/examples/aws-lambda/serverless.yml b/source/includes/aws-lambda/serverless.yml similarity index 100% rename from source/examples/aws-lambda/serverless.yml rename to source/includes/aws-lambda/serverless.yml diff --git a/source/index.txt b/source/index.txt index d1df02fa..3274f5db 100644 --- a/source/index.txt +++ b/source/index.txt @@ -22,6 +22,7 @@ MongoDB PHP Library Monitor Your Application Security Specialized Data Formats + Deploy to AWS Lambda Compatibility What's New Upgrade @@ -111,6 +112,12 @@ Specialized Data Formats Learn how to work with specialized data formats and custom types in the :ref:`php-data-formats` section. +Deploy to AWS Lambda +-------------------- + +Learn how to deploy a PHP application on AWS Lambda by using Bref in the +:ref:`php-aws-lambda` section. + Compatibility ------------- @@ -134,4 +141,4 @@ FAQ --- See answers to commonly asked questions about the {+library-short+} in the -the :ref:`php-faq` section. \ No newline at end of file +the :ref:`php-faq` section. diff --git a/source/tutorial/aws-lambda.txt b/source/tutorial/aws-lambda.txt deleted file mode 100644 index cb27689f..00000000 --- a/source/tutorial/aws-lambda.txt +++ /dev/null @@ -1,153 +0,0 @@ -:orphan: - -============================== -Deploy to AWS Lambda with Bref -============================== - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -Overview --------- - -`Bref `__ lets you deploy serverless PHP applications on AWS Lambda. -In this tutorial, you will deploy a simple PHP application with the MongoDB PHP extension, -and connect to an Atlas cluster using AWS IAM authentication. - -Prerequisites --------------- - -To deploy to AWS Lambda by using Bref, you must have the following components set up: - -- AWS account with access keys -- Serverless Framework - -To learn how to set these up, follow the `Setup tutorial `__ -in the Bref official documentation. - -Install the MongoDB extension ------------------------------ - -Bref uses Lambda layers to provide the PHP runtime. The ``bref`` layer is compiled -with PHP and a few extensions. Other extensions, like ``mongodb``, are available -in additional layers. - -Start by creating a new directory for your project and install the required MongoDB -and Bref dependencies. - -.. code-block:: none - - $ mkdir bref-mongodb-app && cd bref-mongodb-app - $ composer init - $ composer require bref/bref bref/extra-php-extensions mongodb/mongodb - -Then initialize the serverless configuration using the ``bref`` command. - -.. code-block:: none - - $ vendor/bin/bref init - - -After this series of commands, you should have this files: - -- ``composer.json`` for PHP dependencies installed in the ``vendor`` directory -- ``index.php`` a sample webpage -- ``serverless.yml`` for the configuration of the deployment - -To validate your setup, try deploying this default application. This outputs -a URL that renders a webpage with the Bref logo: - -.. code-block:: none - - $ serverless deploy - - -Now that you have initialized the project, you will add the ``mongodb`` extension. -Locate the "Serverless config" name in the list of extensions provided by -`bref/extra-php-extension `__. -Add it to the ``layers`` of the function in ``serverless.yaml``, this file -will look like this: - -.. code-block:: yaml - - plugins: - - ./vendor/bref/bref - - ./vendor/bref/extra-php-extensions - - functions: - api: - handler: index.php - runtime: php-83-fpm - layers: - - ${bref-extra:mongodb-php-83} - - - -Let's use the MongoDB driver with a web page that list planets from the Atlas -`sample dataset `__. -Replace the contents of ``index.php`` with the following: - -.. literalinclude:: /examples/aws-lambda/index.php - :language: php - - -Redeploy the application with the new ``index.php``: - -.. code-block:: none - - $ serverless deploy - - -The application will display an error message because the ``MONGODB_URI`` -environment variable has not yet been set. We'll look at how to set this -variable in the next section. - -AWS Credentials ---------------- - -Atlas supports passwordless authentication with AWS credentials. In any Lambda function, -AWS sets environment variables that contains the access token and secret token with -the role assigned to deployed function. - -1. Open the Lambda function in the AWS console -2. In :guilabel:`Configuration > Permission`, copy the :guilabel:`Role name` -3. Add this role to your Atlas cluster with the built-in Role: "Read and write any database" - -To learn how to set up unified AWS access, see `Set Up Unified AWS Access -`__ -in the MongoDB Atlas documentation. - -Now that the permissions have been configured, the Lambda function is allowed to access -your Atlas cluster. You can configure your application with the Atlas endpoint. - -Access to Atlas clusters is also restricted by IP address. Since the range of IP that comes -from AWS is very wide, you can `allow access from everywhere -`__. - -.. note:: - - Using VPC Peering is recommended in order to isolate your Atlas cluster from Internet. - This requires the Lambda function to be deployed in this AWS VPC. - -Find the connection URI in the Atlas UI :guilabel:`Atlas > Deployment > Database > Connect`. -Select :guilabel:`3. AWS IAM`. -Remove the ``:`` part from the URI, the credentials -will be read from environment variables. - -Update the ``serverless.yml`` file to pass the environment variable ``MONGODB_URI``. - -.. code-block:: yaml - - provider: - environment: - MONGODB_URI: "mongodb+srv://cluster0.example.mongodb.net/?authSource=%24external&authMechanism=MONGODB-AWS&retryWrites=true&w=majority" - -Finally, deploy with the new configuration. After deployment completes, you can -access the function URL and see the list of planets from your Atlas cluster. - -.. code-block:: none - - $ serverless deploy