Merge branch 'php-standardization' into docsp-41962-stable-api

Author: mongoKart

.github/workflows/check-autobuilder.yml

@@ -0,0 +1,8 @@
+# ensures that we always use the latest version of the script
+if [ -f build-site.sh ]; then
+  rm build-site.sh
+fi 
+
+
+curl https://raw.githubusercontent.com/mongodb/docs-worker-pool/netlify-poc/scripts/build-site.sh -o build-site.sh 
+sh build-site.sh

build.sh

@@ -0,0 +1,9 @@
+[[integrations]]
+name = "snooty-cache-plugin"
+
+# Production context: all deploys from the Production branch
+# set in your site’s Branches settings in the UI will inherit
+# these settings.
+[build]
+publish = "snooty/public"
+command = ". ./build.sh"

netlify.toml

@@ -1,7 +1,11 @@
 name = "php-library"
 title = "PHP Library Manual"
 
-intersphinx = ["https://www.mongodb.com/docs/manual/objects.inv"]
+intersphinx = [
+    "https://www.mongodb.com/docs/manual/objects.inv",
+    "https://www.mongodb.com/docs/drivers/objects.inv",
+    "https://www.mongodb.com/docs/atlas/objects.inv",
+]
 
 toc_landing_pages = [
     "/reference/class/MongoDBClient",
@@ -18,16 +22,24 @@ toc_landing_pages = [
     "/reference/class/MongoDBModelDatabaseInfo",
     "/reference/class/MongoDBModelIndexInfo",
     "/get-started",
+    "/databases-collections",
+    "/write",
+    "/indexes",
+    "/security"
+    "/data-formats"
 ]
 
+sharedinclude_root =  "https://raw.githubusercontent.com/10gen/docs-shared/main/"
+
 [substitutions]
 php-library = "MongoDB PHP Library"
 
 [constants]
-
 php-library = "MongoDB PHP Library"
 driver-short = "PHP library"
 extension-short = "PHP extension"
 mdb-server = "MongoDB Server"
 stable-api = "Stable API"
+library-short = "PHP library"
 api = "https://www.mongodb.com/docs/php-library/current/reference"
+php-manual = "https://www.php.net/manual/en"

snooty.toml

@@ -0,0 +1,205 @@
+.. _php-aggregation:
+
+====================================
+Transform Your Data with Aggregation
+====================================
+
+.. facet::
+   :name: genre
+   :values: reference
+ 
+.. meta::
+   :keywords: code example, transform, computed, pipeline
+   :description: Learn how to use the PHP library to perform aggregation operations.
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. TODO:
+ .. toctree::
+    :titlesonly:
+    :maxdepth: 1
+
+    /aggregation/aggregation-tutorials
+
+Overview
+--------
+
+In this guide, you can learn how to use the {+php-library+} to perform
+**aggregation operations**.
+
+Aggregation operations process data in your MongoDB collections and
+return computed results. The MongoDB Aggregation framework, which is
+part of the Query API, is modeled on the concept of data processing
+pipelines. Documents enter a pipeline that contains one or more stages,
+and this pipeline transforms the documents into an aggregated result.
+
+An aggregation operation is similar to a car factory. A car factory has
+an assembly line, which contains assembly stations with specialized
+tools to do specific jobs, like drills and welders. Raw parts enter the
+factory, and then the assembly line transforms and assembles them into a
+finished product.
+
+The **aggregation pipeline** is the assembly line, **aggregation stages** are the
+assembly stations, and **operator expressions** are the
+specialized tools.
+
+Aggregation Versus Find Operations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can use find operations to perform the following actions:
+
+- Select which documents to return
+- Select which fields to return
+- Sort the results
+
+You can use aggregation operations to perform the following actions:
+
+- Run find operations
+- Rename fields
+- Calculate fields
+- Summarize data
+- Group values
+
+Limitations
+~~~~~~~~~~~
+
+Consider the following limitations when performing aggregation operations:
+
+- Returned documents cannot violate the
+  :manual:`BSON document size limit </reference/limits/#mongodb-limit-BSON-Document-Size>`
+  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.
+
+  .. important:: $graphLookup Exception
+
+     The :manual:`$graphLookup
+     </reference/operator/aggregation/graphLookup/>` stage has a strict
+     memory limit of 100 megabytes and ignores the ``allowDiskUse`` option.
+
+.. _php-aggregation-example:
+
+Aggregation Example
+-------------------
+
+.. note::
+  
+   The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants``
+   database from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
+   free MongoDB Atlas cluster and load the sample datasets, see the :atlas:`Get Started with Atlas
+   </getting-started>` guide.
+
+To perform an aggregation, pass an array containing the pipeline stages to
+the ``MongoDB\Collection::aggregate()`` method.
+
+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 </reference/operator/aggregation/match/>` stage to filter for documents
+  in which the ``cuisine`` field contains the value ``'Bakery'``
+
+- :manual:`$group </reference/operator/aggregation/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.php
+      :start-after: start-match-group
+      :end-before: end-match-group
+      :language: php
+      :dedent:
+
+   .. output:: 
+      :visible: false
+
+      {"_id":"Brooklyn","count":173}
+      {"_id":"Queens","count":204}
+      {"_id":"Bronx","count":71}
+      {"_id":"Staten Island","count":20}
+      {"_id":"Missing","count":2}
+      {"_id":"Manhattan","count":221}
+
+Explain an Aggregation
+~~~~~~~~~~~~~~~~~~~~~~
+
+To view information about how MongoDB executes your operation, you can
+instruct the MongoDB query planner to **explain** it. When MongoDB explains
+an operation, it returns **execution plans** and performance statistics.
+An execution plan is a potential way in which MongoDB can complete an operation.
+When you instruct MongoDB to explain an operation, it returns both the
+plan MongoDB executed and any rejected execution plans.
+
+To explain an aggregation operation, construct a ``MongoDB\Operation\Aggregate`` object
+and pass the database, collection, and pipeline stages as parameters. Then, pass the
+``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`:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/aggregation.php
+      :start-after: start-explain
+      :end-before: end-explain
+      :language: php
+      :dedent:
+
+   .. output:: 
+      :visible: false
+
+      {"explainVersion":"2","queryPlanner":{"namespace":"sample_restaurants.restaurants",
+      "indexFilterSet":false,"parsedQuery":{"cuisine":{"$eq":"Bakery"}},"queryHash":"865F14C3",
+      "planCacheKey":"D56D6F10","optimizedPipeline":true,"maxIndexedOrSolutionsReached":false,
+      "maxIndexedAndSolutionsReached":false,"maxScansToExplodeReached":false,"winningPlan":{
+      ... }
+
+Additional Information
+----------------------
+
+To view a tutorial that uses the {+php-library+} to create complex aggregation
+pipelines, see `Complex Aggregation Pipelines with Vanilla PHP and MongoDB 
+<https://www.mongodb.com/developer/products/mongodb/aggregations-php-mongodb/>`__
+in the MongoDB Developer Center.
+
+MongoDB Server Manual
+~~~~~~~~~~~~~~~~~~~~~
+
+To learn more about the topics discussed in this guide, see the following
+pages in the {+mdb-server+} manual:
+
+- To view a full list of expression operators, see :manual:`Aggregation
+  Operators </reference/operator/aggregation/>`.
+
+- To learn about assembling an aggregation pipeline and to view examples, see
+  :manual:`Aggregation Pipeline </core/aggregation-pipeline/>`.
+
+- To learn more about creating pipeline stages, see :manual:`Aggregation
+  Stages </reference/operator/aggregation-pipeline/>`.
+
+- To learn more about explaining MongoDB operations, see
+  :manual:`Explain Output </reference/explain-results/>` and
+  :manual:`Query Plans </core/query-plans/>`.
+
+.. TODO:
+ Aggregation Tutorials
+ ~~~~~~~~~~~~~~~~~~~~~
+
+.. To view step-by-step explanations of common aggregation tasks, see
+.. :ref:`php-aggregation-tutorials-landing`.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about the methods discussed in this guide, see the
+following API documentation:
+
+- `MongoDB\\Collection::aggregate() <{+api+}/method/MongoDBCollection-aggregate/>`__
+- `MongoDB\\Collection::explain() <{+api+}/method/MongoDBCollection-explain/>`__

source/aggregation.txt

@@ -0,0 +1,62 @@
+.. _php-compatibility:
+
+=============
+Compatibility
+=============
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: backwards compatibility, versions, upgrade
+
+MongoDB Compatibility
+---------------------
+
+The following compatibility table specifies the recommended version or versions
+of the {+php-library+} and extension that you can use with a specific version of MongoDB.
+
+The first column lists the version of the library and extension.
+
+.. sharedinclude:: dbx/lifecycle-schedule-callout.rst
+
+.. sharedinclude:: dbx/compatibility-table-legend.rst
+
+.. include:: /includes/mongodb-compatibility-table-php.rst
+
+For more information on how to read the compatibility tables, see our guide on
+:ref:`MongoDB Compatibility Tables <about-driver-compatibility>`.
+
+Language Compatibility
+----------------------
+
+The following compatibility table specifies the recommended version or versions
+of the {+php-library+} and extension that you can use with a specific version of PHP.
+
+The first column lists the version of the library and extension.
+
+.. include:: /includes/language-compatibility-table-php.rst
+
+For more information on how to read the compatibility tables, see our guide on
+:ref:`MongoDB Compatibility Tables <about-driver-compatibility>`.
+
+How to Get Help
+---------------
+
+If you have questions about compatibility, visit the following resources for further guidance:
+
+- Ask questions on our :community-forum:`MongoDB Community Forums <>`.
+- Visit our :technical-support:`Support Channels </>`.
+- File an issue or feature request in our issue tracker, JIRA, under one of the
+  following projects:
+
+  - `PHPC - Extension <https://jira.mongodb.org/projects/PHPC/summary>`_
+  
+  - `PHPLIB - Library <https://jira.mongodb.org/projects/PHPLIB/summary>`_

source/compatibility.txt

@@ -22,13 +22,13 @@ Overview
 
 To connect to a MongoDB deployment, you must create the following items:
 
-- **Connection URI**, also known as a *connection string*, which tells the {+driver-short+}
+- **Connection URI**, also known as a *connection string*, which tells the {+library-short+}
   which MongoDB deployment to connect to.
 - **MongoDB\\Client** object, which creates the connection to the MongoDB deployment
   and lets you perform operations on it.
 
 You can also set options within either or both of these components to
-customize the way that the {+driver-short+} behaves
+customize the way that the {+library-short+} behaves
 while connected to MongoDB.
 
 This guide describes the components of a connection string and shows how to
@@ -99,7 +99,7 @@ deployment on port ``27017`` of ``localhost``:
 API Documentation
 -----------------
 
-To learn more about creating a ``MongoDB\Client`` object in the {+driver-short+},
+To learn more about creating a ``MongoDB\Client`` object in the {+library-short+},
 see the following API documentation:
 
 - :ref:`MongoDB\Client <php-api-mongodbclient>`