DOCSP-41962 - Stable API

[mongoKart]

Adapted from the PyMongo page of the same name

Pull Request Info

PR Reviewing Guidelines

JIRA - https://jira.mongodb.org/browse/DOCSP-41962
Staging - https://preview-mongodbmongokart.gatsbyjs.io/php-library/docsp-41962-stable-api/connect/stable-api/

Self-Review Checklist

• Is this free of any warnings or errors in the RST?
• Did you run a spell-check?
• Did you run a grammar-check?
• Are all the links working?
• Are the facets and meta keywords accurate?

[norareidy]

LGTM with some suggestions

[jmikola]

I don't recall seeing multiple <?php tags in source files from @norareidy's previous PRs. This makes the file itself invalid, unless you intend to add a ?> above (probably between end-specify-v1 and start-stable-api-options since there's no reason to show ?> to a user (they won't use it in their files).

If these source files are ever meant to be executed for correctness (as we do for some existing sources in the PHPLIB docs before the docs team took over), that'd be even more reason to ensure the syntax within is valid.

[mongoKart]

i wasn't sure about these. the existing, un-standardized docs (e.g., hhttps://www.mongodb.com/docs/php-library/current/tutorial/gridfs/#uploading-files-with-writable-streamsere) include them in all code samples, so i assumed it was the preferred syntax.

these files will never be executed in toto, so i'm just going to remove these tags.

[jmikola]

the existing, un-standardized docs include them in all code samples

I think that was necessary for syntax highlighting. Note that most of those code blocks are embedded in the RST and weren't being included from a common file (nor do they get automated testing). Speaking just of the GridFS examples, I'll also note that those are all full scripts that can be executed on their own (each constructs a Client).

I think it makes sense to leave <?php at the top of each of your source files. I expect it is also required for the CI workflow to check coding standards.

[jmikola]

@alcaeus: I'm not sure what version of PHPLIB is being targeted here, but if we're bumping to PHP 8.1+ with version 1.20 I think this would be a good opportunity to use named arguments (available in PHP 8.0+) for the the booleans. Consider:

'serverApi' => new MongoDB\Driver\ServerApi('1', strict: true, deprecationErrors: true),

Ignore this suggestion if we need to remain compatible with earlier versions (back to PHP 7.4).

Also, my previous comment about a trailing comma after elements in multi-line arrays also applies here.

[alcaeus]

I think we can assume newer PHP versions, so using named arguments sounds like a great idea, especially for those boolean flags!

[mongoKart]

love it. helps a ton with readability.

FYI @rustagir and @norareidy

[netlify]

❌ Deploy Preview for docs-php-library failed. Why did it fail? →

Name	Link
🔨 Latest commit	4434310
🔍 Latest deploy log	https://app.netlify.com/sites/docs-php-library/deploys/66f469c2d4afbd000804dd4e

[mongoKart]

If I wanted to split this line into multiple, shorter lines, how would I do that?

[jmikola]

I think this would be readable:

$uri = "mongodb://<hostname>:<port>";

$serverApi = new MongoDB\Driver\ServerApi('1', strict: true, deprecationErrors: true);
$driverOptions = ['serverApi' => $serverApi];

$client = new MongoDB\Client($uri, [], $driverOptions);

I also think the previous example could benefit from an extra newline before $client = ....

---

If you want to break ServerApi across multiple lines, you can do something like:

$serverApi = new MongoDB\Driver\ServerApi(
    '1',
    strict: true,
    deprecationErrors: true,
);

PHP 8.0 allows trailing commas in parameter lists (consistent with what we'd do for multi-line arrays): https://php.watch/versions/8.0/trailing-comma-parameter-use-list

If that's too much wrapping, you could also do this:

$driverOptions = [
    'serverApi' => new MongoDB\Driver\ServerApi('1', strict: true, deprecationErrors: true),
];

That said, I don't think either of these are better than just assigning $serverApi on its own line as I did in the first suggestion.

[mongoKart]

thanks!

[jmikola]

I think this would be readable:

$uri = "mongodb://<hostname>:<port>";

$serverApi = new MongoDB\Driver\ServerApi('1', strict: true, deprecationErrors: true);
$driverOptions = ['serverApi' => $serverApi];

$client = new MongoDB\Client($uri, [], $driverOptions);

I also think the previous example could benefit from an extra newline before $client = ....

---

If you want to break ServerApi across multiple lines, you can do something like:

$serverApi = new MongoDB\Driver\ServerApi(
    '1',
    strict: true,
    deprecationErrors: true,
);

PHP 8.0 allows trailing commas in parameter lists (consistent with what we'd do for multi-line arrays): https://php.watch/versions/8.0/trailing-comma-parameter-use-list

If that's too much wrapping, you could also do this:

$driverOptions = [
    'serverApi' => new MongoDB\Driver\ServerApi('1', strict: true, deprecationErrors: true),
];

That said, I don't think either of these are better than just assigning $serverApi on its own line as I did in the first suggestion.