diff --git a/source/index.txt b/source/index.txt index 53398b22..ae4981e5 100644 --- a/source/index.txt +++ b/source/index.txt @@ -23,7 +23,7 @@ MongoDB PHP Library Run a Database Command Data Aggregation Indexes - Monitor Your Application + Monitor Your Application Security Specialized Data Formats Deploy to AWS Lambda diff --git a/source/monitoring.txt b/source/logging-monitoring.txt similarity index 89% rename from source/monitoring.txt rename to source/logging-monitoring.txt index 43d15f27..a249bd1a 100644 --- a/source/monitoring.txt +++ b/source/logging-monitoring.txt @@ -7,7 +7,7 @@ Monitor Your Application .. toctree:: :caption: Monitoring categories - Cluster Monitoring + Cluster Monitoring .. /monitoring/command-monitoring .. /monitoring/connection-monitoring diff --git a/source/monitoring/cluster-monitoring.txt b/source/logging-monitoring/cluster-monitoring.txt similarity index 100% rename from source/monitoring/cluster-monitoring.txt rename to source/logging-monitoring/cluster-monitoring.txt diff --git a/source/tutorial/commands.txt b/source/tutorial/commands.txt deleted file mode 100644 index 4305e07a..00000000 --- a/source/tutorial/commands.txt +++ /dev/null @@ -1,154 +0,0 @@ -:orphan: - -========================= -Execute Database Commands -========================= - -.. meta:: - :description: Learn to execute database commands with the MongoDB PHP Library, including handling single and multiple result documents and setting custom read preferences. - - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -Overview --------- - -The |php-library| provides helper methods across the :phpclass:`Client -`, :phpclass:`Database `, and -:phpclass:`Collection ` classes for common -:manual:`database commands `. In addition, the -:phpmethod:`MongoDB\Database::command()` method may be used to run database -commands that do not have a helper method. - -The :phpmethod:`MongoDB\Database::command()` method always returns a -:php:`MongoDB\Driver\Cursor ` object, since it must -support execution of commands that return single result documents *and* multiple -results via a command cursor. - -Commands That Return a Single Result Document ---------------------------------------------- - -Most database commands return a single result document, which can be obtained by -converting the returned cursor to an array and accessing its first element. The -following example executes a :manual:`ping ` command -and prints its result document: - -.. code-block:: php - - test; - - $cursor = $database->command(['ping' => 1]); - - var_dump($cursor->toArray()[0]); - -The output would resemble: - -.. code-block:: none - - object(MongoDB\Model\BSONDocument)#11 (1) { - ["storage":"ArrayObject":private]=> - array(1) { - ["ok"]=> - float(1) - } - } - -Commands That Yield Multiple Results ------------------------------------- - -Some database commands return a cursor with multiple results. The following -example executes :manual:`listCollections `, -which returns a cursor containing a result document for each collection in the -``test`` database, and iterates through the results using a ``foreach`` loop. -Note that this example is illustrative; applications would generally use -:phpmethod:`MongoDB\Database::listCollections()` in practice. - -.. code-block:: php - - test; - - $cursor = $database->command(['listCollections' => 1]); - - foreach ($cursor as $collection) { - echo $collection['name'], "\n"; - } - -The output might resemble the following: - -.. code-block:: none - - persons - posts - zips - -.. note:: - - At the *protocol* level, commands that yield multiple results via a cursor - will return a single result document with the essential ingredients for - constructing the cursor (i.e. the cursor's ID, namespace, and an optional - first batch of results). If the :php:`MongoDB\Driver\Manager::executeCommand() - ` method in the extension detects - such a response, it will construct an iterable command cursor and return it - instead of the raw result document. If necessary, raw result documents can - still be observed using :php:`command monitoring - `. - -Specifying a Custom Read Preference ------------------------------------ - -Write commands, such as :manual:`createUser `, -can only be executed on a writable server (e.g. primary replica set -member). Command helper methods in the |php-library|, such as -:phpmethod:`MongoDB\Database::drop()`, know to apply their own :term:`read -preference` if necessary. However, the :phpmethod:`MongoDB\Database::command()` -method is a generic method and defaults to the read preference of the Database -object on which it is invoked. When necessary, the ``readPreference`` option may -be used to override the default read preference. - -The following example connects to a cluster and specifies ``secondaryPreferred`` -as the Client's default read preference. It then specifies a ``primary`` read -preference when executing the ``createUser`` command on the ``test`` database: - -.. code-block:: php - - 'secondaryPreferred'] - ); - - $client->test; - - $cursor = $db->command( - [ - 'createUser' => 'username', - 'pwd' => 'password', - 'roles' => ['readWrite'], - ], - [ - 'readPreference' => new MongoDB\Driver\ReadPreference('primary'), - ] - ); - - var_dump($cursor->toArray()[0]); - -The output would then resemble: - -.. code-block:: none - - object(MongoDB\Model\BSONDocument)#8 (1) { - ["storage":"ArrayObject":private]=> - array(1) { - ["ok"]=> - float(1) - } - } diff --git a/source/tutorial/encryption.txt b/source/tutorial/encryption.txt deleted file mode 100644 index 70b99df3..00000000 --- a/source/tutorial/encryption.txt +++ /dev/null @@ -1,274 +0,0 @@ -:orphan: - -================= -In-Use Encryption -================= - -.. meta:: - :description: Learn how to implement in-use encryption in PHP projects with the MongoDB PHP Library, including managing encryption keys and configuring client-side field level encryption. - - -.. contents:: On this page - :local: - :backlinks: none - :depth: 3 - :class: singlecol - - -Dependencies ------------- - -To get started using in-use encryption in your project, the -:php:`extension ` will need to be compiled with -`libmongocrypt `_ (enabled by -default). - -Additionally, either ``crypt_shared`` or ``mongocryptd`` are required in order to -use *automatic* client-side encryption. Neither is required for *explicit* -encryption. - -``crypt_shared`` -~~~~~~~~~~~~~~~~ - -The :manual:`Automatic Encryption Shared Library ` -(``crypt_shared``) provides the same functionality as ``mongocryptd``, but does not -require you to spawn another process to perform automatic encryption. - -By default, the extension attempts to load ``crypt_shared`` from the system -path(s) and uses it automatically if found. To load ``crypt_shared`` from -another location, use the ``cryptSharedLibPath`` auto encryption -:php:`driver option ` -when constructing a client. If the extension cannot load ``crypt_shared`` it -will attempt to fallback to using ``mongocryptd`` by default. The -``cryptSharedLibRequired`` option may be used to always require ``crypt_shared`` -and fail if it cannot be loaded. - -For detailed installation instructions see the MongoDB documentation for the -:manual:`Automatic Encryption Shared Library `. - -``mongocryptd`` -~~~~~~~~~~~~~~~ - -The ``mongocryptd`` binary is an alternative requirement for automatic client-side -encryption and is included as a component in the -:manual:`MongoDB Enterprise Server package `. -For detailed installation instructions see the -:manual:`MongoDB documentation on mongocryptd `. - -``mongocryptd`` performs the following: - -- Parses the automatic encryption rules specified in the client configuration. - If the ``schemaMap`` auto encryption driver option contains invalid syntax, - ``mongocryptd`` returns an error. - -- Uses the specified automatic encryption rules to mark fields in read and write - operations for encryption. - -- Rejects read/write operations that may return unexpected or incorrect results - when applied to an encrypted field. For supported and unsupported operations, - see :manual:`Supported Operations for Automatic Encryption `. - -A client configured with auto encryption will automatically spawn the -``mongocryptd`` process from the application's ``PATH``. Applications can control -the spawning behavior via various auto encryption -:php:`driver options `. - -``mongocryptd`` is only responsible for supporting automatic client-side encryption -and does not itself perform any encryption or decryption. - -Managing Encryption Keys ------------------------- - -.. seealso:: :manual:`Encryption Key Management ` in the MongoDB manual - -Creating an Encryption Key -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. note:: - - The following examples use a local master key. While this is suitable for - development, a production application should use a supported cloud provider - (e.g. AWS KMS). The master key is used to encrypt locally stored data keys - and thus it is very important that you keep this key secure. - -To create an encryption key, create a -:php:`MongoDB\Driver\ClientEncryption ` -instance with encryption options and use the -:php:`createDataKey() ` -method. The method will return the key ID which can be used to reference the key -later. You can also pass multiple :ref:`alternate names ` for this key -and reference the key by these names instead of the key ID. - -Creating a new data encryption key would typically be done on initial -deployment, but depending on your use case you may want to use more than one -encryption key (e.g. user-specific encryption keys) or create them dynamically. - -.. literalinclude:: /examples/encryption/create_data_key.php - :language: php - -.. _alt_name: - -Referencing Encryption Keys by an Alternative Name -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To reference keys in your application, you can use the ``keyAltName`` -attribute specified when creating the key. The following example creates an -encryption key with an alternative name, which could be done when deploying the -application. The script then encrypts data by referencing the key by its -alternative name using the ``keyAltName`` option instead of ``keyId``. - -.. note:: - - Prior to adding a new key alternate name, you must create a partial, unique - index on the ``keyAltNames`` field. Client-Side Field Level Encryption - depends on server-enforced uniqueness of key alternate names. - -.. literalinclude:: /examples/encryption/key_alt_name.php - :language: php - - -Client-Side Field Level Encryption ----------------------------------- - -Introduced in MongoDB 4.2, -:manual:`Client-Side Field Level Encryption ` allows an -application to encrypt specific data fields in addition to pre-existing MongoDB -encryption features such as -:manual:`Encryption at Rest ` and -:manual:`TLS/SSL (Transport Encryption) `. - -With field level encryption, applications can encrypt fields in documents prior -to transmitting data over the wire to the server. Client-side field level -encryption supports workloads where applications must guarantee that -unauthorized parties, including server administrators, cannot read the encrypted -data. - - -Automatic Client-Side Field Level Encryption -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. note:: - - Automatic client-side field level encryption requires MongoDB 4.2+ Enterprise - or a MongoDB 4.2+ Atlas cluster. - -Automatic client-side field level encryption is enabled by creating a client and -specifying the ``autoEncryption`` -:php:`driver option `. -The following examples demonstrate how to setup automatic client-side field -level encryption and use a -:php:`MongoDB\Driver\ClientEncryption ` -object to create a new encryption key. - - -.. _server-side: - -Server-Side Field Level Encryption Enforcement -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The MongoDB 4.2+ server supports using schema validation to enforce encryption -of specific fields in a collection. This schema validation will prevent an -application from inserting unencrypted values for any fields marked with the -:manual:`"encrypt" schema keyword `. - -The following example sets up a collection with automatic encryption using a -``$jsonSchema`` validator and -:manual:`Encryption Schema syntax `. -Data in the ``encryptedField`` field is automatically encrypted on insertion and -decrypted when reading on the client side. - -.. literalinclude:: /examples/encryption/csfle-automatic_encryption-server_side_schema.php - :language: php - - -Providing Local Automatic Encryption Rules -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The following example uses the ``schemaMap`` auto encryption driver option to -define encrypted fields using a -:manual:`strict subset of the JSON schema syntax `. - -Using ``schemaMap`` in conjunction with a :ref:`server-side schema ` -provides more security than relying entirely on a schema obtained from the -server. It protects against a malicious server advertising a false schema, which -could trick the client into sending unencrypted data that should be encrypted. - -.. note:: - - Only :manual:`Encryption Schema syntax ` - can be used with the ``schemaMap`` option. Do not specify document validation - keywords in the automatic encryption rules. To define document validation - rules, configure :manual:`schema validation `. - -.. literalinclude:: /examples/encryption/csfle-automatic_encryption-local_schema.php - :language: php - - -Explicit Encryption -~~~~~~~~~~~~~~~~~~~ - -Explicit encryption is a MongoDB community feature and does not use -``crypt_shared`` or ``mongocryptd``. Explicit encryption is provided by the -:php:`MongoDB\Driver\ClientEncryption ` class. - -.. literalinclude:: /examples/encryption/csfle-explicit_encryption.php - :language: php - - -Explicit Encryption with Automatic Decryption -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Although automatic encryption requires MongoDB 4.2+ enterprise or a MongoDB 4.2+ -Atlas cluster, automatic *decryption* is supported for all users. To configure -automatic decryption without automatic encryption set the -``bypassAutoEncryption`` auto encryption -:php:`driver option ` -when constructing a client. - -.. literalinclude:: /examples/encryption/csfle-explicit_encryption_automatic_decryption.php - :language: php - - -Queryable Encryption --------------------- - -Introduced in MongoDB 7.0, -:manual:`Queryable Encryption ` is another -form of in-use encryption. Data is encrypted client-side. Queryable Encryption -supports indexed encrypted fields, which are further processed server-side. - - -Automatic Queryable Encryption -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. note:: - - Automatic queryable encryption requires MongoDB 7.0+ Enterprise or a MongoDB - 7.0+ Atlas cluster. - -Automatic encryption in Queryable Encryption utilizes ``crypt_shared`` or -``mongocryptd`` to automatically encrypt and decrypt data client-side. The data -in the ``encryptedIndexed`` and ``encryptedUnindexed`` fields will be -automatically encrypted on insertion and decrypted when querying on the client -side. Additionally, it is possible to query on the ``encryptedIndexed`` field. - -.. literalinclude:: /examples/encryption/queryable_encryption-automatic.php - :language: php - - -Explicit Queryable Encryption -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. note:: - - Explicit queryable encryption requires MongoDB 7.0+. - -Explicit encryption in Queryable Encryption is performed using the -:php:`MongoDB\Driver\ClientEncryption::encrypt() ` -and :php:`decrypt() ` methods. Although -values must be explicitly encrypted (e.g. insertions, query criteria), automatic -*decryption* for queries is possible by configuring ``encryptedFields`` on the -collection, as demonstrated in the following example: - -.. literalinclude:: /examples/encryption/queryable_encryption-explicit.php - :language: php