PHP Documentation (English)

When creating or migrating textual entities related to specific extensions (replacing the old language-snippets.ent format), follow these naming and structural conventions:

• Naming: Prefix all entity names with ext..
• File Location: Place entities in doc-en/reference/$extension/entities.ent.
• Organization: Keep entities sorted by name, with one empty line separating each entity.
• Large Entities: If an entity is too large or complex for a shared file, create an individual file at doc-en/entities/name.$extension.$entname.xml. The content must be a well-balanced XML fragment. DTD entity names are allowed, but XML declarations are not.
• Namespaces: Define XML namespaces in the root <entities> element only. Do not use namespaces within individual <entity> child elements.

To build the documentation locally, ensure you have Docker installed. You can use the provided Makefile to automate the build process.

By default, the build process will use doc-base or phd repositories if they are located in directories adjacent to this one.

To view the results:

1. Run make to build the documentation.
2. Open the output/php-chunked-xhtml/ directory in your web browser.

To build the web version of the documentation, use make php. The output will be located in output/php-web.

# Rebuild the documentation
make

# Force rebuild of the Docker image
make -B build

# Build the web version
make php

To rename existing entities to the new ext. prefixed format without breaking existing references immediately, you can create temporary aliases. This allows you to transition names gradually.

It is recommended to place these aliases in doc-en/entities/entities-remove.ent to minimize redundant work in translation files, though they can also be placed in the extension's entity file.

<entity name="old.name">&new.name;</entity>

An extension entity file should use the DocBook namespace and include the translate="yes" attribute on the root element. Entities should follow the ext.$extension.$entity-name naming pattern.

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!--
    See `manual.xml` for XML namespaces defaults.
    Keep the lines under 79 columns, to make the process of manual
    translation easier, and to avoid wrap-around in some other contexts.
-->
<entities xmlns       = "http://docbook.org/ns/docbook"
          xmlns:xlink = "http://www.w3.org/1999/xlink"
          translate   = "yes">

<entity name="ext.$extention.$entity-name">
 <simpara>
  Text.
 </simpara>
</entity>

</entities>

The PHP documentation is translated into multiple languages. Each language has its own dedicated repository:

• Brazilian Portuguese: doc-pt_br
• Chinese (Simplified): doc-zh
• English: doc-en (this repository)
• French: doc-fr
• German: doc-de
• Italian: doc-it
• Japanese: doc-ja
• Polish: doc-pl
• Romanian: doc-ro
• Russian: doc-ru
• Spanish: doc-es
• Turkish: doc-tr
• Ukrainian: doc-uk

To restrict the amount of time a specific command can run on the server, include the maxTimeMS option directly within the document array passed to the MongoDB\Driver\Command constructor, rather than in the commandOptions parameter.

<?php

$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
$command = new MongoDB\Driver\Command(
    array(
        "distinct" => "beer",
        "key" => "beer_name",
        "maxTimeMS" => 10,
    )
);

try {
    $cursor = $manager->executeCommand("beerdb", $command);
    $response = $cursor->toArray()[0];
} catch(MongoDB\Driver\Exception\Exception $e) {
    echo $e->getMessage(), "\n";
    exit;
}
var_dump($response);

The constructor for MongoDB\Driver\Command accepts the following parameters:

document (required)

An array or object representing the complete command document that will be sent to the MongoDB server.

commandOptions (optional)

An array or null used to specify options related to the execution of the command and the resulting MongoDB\Driver\Cursor.

Note: Do not use commandOptions to specify options described in the MongoDB manual (e.g., maxTimeMS). Use the document parameter for those. Only use commandOptions for the specific driver options listed below.

// Signature:
public final function __construct(
    array|object $document,
    array|null $commandOptions = null
)

The commandOptions parameter in the MongoDB\Driver\Command constructor supports the following driver-specific option:

// Example of using commandOptions
$command = new MongoDB\Driver\Command($document, ['maxAwaitTimeMS' => 1000]);