CONTRIBUTING.md
No OneTemporary
Actions

Authored By

Unknown

Size

12 KB

Referenced Files

None

Subscribers

None

CONTRIBUTING.md
View Options

	# Contributing to the PHP Driver for MongoDB

	## Building from Source

	Developers who would like to contribute to the driver will need to build it from
	source. The repository may be initialized with:

	```
	$ git clone https://github.com/mongodb/mongo-php-driver.git
	$ cd mongo-php-driver
	$ git submodule update --init
	```

	The following script may be used to build the driver:

	```
	#!/bin/sh

	phpize > /dev/null && \
	./configure --enable-mongodb-developer-flags > /dev/null && \
	make clean > /dev/null && make all > /dev/null && make install
	```

	To verify that the installation was successful, run the following command, which
	will report `phpinfo()` output for the extension:

	```
	$ php --ri mongodb
	```

	## Generating arginfo from stub files

	Arginfo structures are generated from stub files using the `gen_stub.php`
	file. Note that this requires `phpize` to be run for PHP 8.2 to make use
	of all features. After changing a stub file, run `./build/gen_stub.php`
	to regenerate the corresponding arginfo files and commit the results.

	## Generating function maps for static analysis tools

	PHPStan and Psalm use function maps to provide users with correct type analysis
	when using this extension. To generate the function map, run the
	`generate-function-map` make target. The generated map will be stored in
	`scripts/functionMap.php`.

	## Testing

	The driver includes a test suite that can be run with `make test`. To run a single
	test file, define the `TESTS` variable with the file path:

	```
	make test TESTS=tests/<path-to-test-file>.phpt
	```

	### File format

	The extension's test use the PHPT format from PHP internals. This format is
	documented in the following links:

	* [Introduction to PHPT Files](https://qa.php.net/write-test.php)
	* [PHPT - Test File Layout](https://qa.php.net/phpt_details.php)

	Generally, most tests will be based on the following template:

	```
	--TEST--
	Description of API or JIRA issue being tested
	--SKIPIF--
	<?php require __DIR__ . "/../utils/basic-skipif.inc"; ?>
	<?php /* One or more skip functions */ ?>
	--FILE--
	<?php
	require_once __DIR__ . "/../utils/basic.inc";

	// Test code

	?>
	===DONE===
	<?php exit(0); ?>
	--EXPECT--
	===DONE===
	```

	The `basic-skipif.inc` and `basic.inc` files contain utility functions for the
	`SKIPIF` and `FILE` sections, respectively. If those functions are not needed
	(e.g. skip logic only depends on checking the `PHP_INT_SIZE` constant), the test
	should not include the file. When it doubt, keep it simple.

	### Best Practices for `SKIPIF`

	The [`skipif.php`](tests/utils/skipif.php) file defines various helper functions
	for use within a test's [`SKIPIF`](https://qa.php.net/phpt_details.php#skipif_section)
	section. When multiple functions are used in a single `SKIPIF` section, they
	should be logically ordered:

	* Any PHP environment requirements should be checked first. For example, if a
	test requires a 64-bit architecture, start by checking `PHP_INT_SIZE` before
	anything else.
	* Any extension build requirements (e.g. `skip_if_not_libmongoc_crypto()`) or
	test environment requirements (e.g. `skip_if_auth()`) should then be checked.
	These functions only examine local information, such as `phpinfo()` output or
	the structure of the `URI` constant, and do not interact with a remote
	MongoDB server.
	* Any remote server requirements should then be checked. A general integration
	test that requires any type of remote server to be accessible might use
	`skip_if_not_live()` while a test requiring a replica set would prefer
	`skip_if_not_replica_set()`.
	* After requiring a remote server to be accessible (optionally with a specific
	type), you can enforce requirements about that server. This includes checking
	its server version, storage engine, availability of test commands, etc.
	* Finally, use `skip_if_not_clean()` if needed to ensure that the collection(s)
	under test are dropped before the test runs.

	As a rule of thumb, your `SKIPIF` logic should be written to allow the test to
	run in as many environments as possible. To paraphrase the
	[robustness principal](https://en.wikipedia.org/wiki/Robustness_principle):

	> Be conservative in what/how you test, and liberal in what environment you require

	Consider that a well-crafted `EXPECTF` section may allow a `SKIPIF` section to
	be less restrictive.

	### Environment Variables

	The test suite references the following environment variables:

	* `MONGODB_DATABASE`: Default database to use in tests. Defaults to `phongo`.
	* `MONGO_ORCHESTRATION_URI`: API endpoint for
	[Mongo Orchestration](https://github.com/10gen/mongo-orchestration). Defaults
	to `http://localhost:8889/v1`. This is only used by a few tests that start
	temporary servers, and those tests will be skipped if Mongo Orchestration is
	inaccessible.
	* `MONGODB_URI`: Connection string. Defaults to `mongodb://127.0.0.1/`, which
	assumes a MongoDB server is listening on localhost port 27017.
	* `SSL_DIR`: Path to directory containing certificate files. On Evergreen, this
	will be set to the
	[.evergreen/x509gen](https://github.com/mongodb-labs/drivers-evergreen-tools/tree/master/.evergreen/x509gen)
	directory within
	[drivers-evergreen-tools](https://github.com/mongodb-labs/drivers-evergreen-tools).
	If undefined or inaccessible, tests requiring certificates will be skipped.

	The following environment variable is used for [stable API testing](https://github.com/mongodb/specifications/blob/master/source/versioned-api/tests/README.rst):

	* `API_VERSION`: If defined, this value will be used to construct a
	[`MongoDB\Driver\ServerApi`](https://www.php.net/manual/en/mongodb-driver-serverapi.construct.php),
	which will then be specified as the `serverApi` driver option for
	[`MongoDB\Driver\Manager`](https://www.php.net/manual/en/class.mongodb-driver-manager.php)
	objects created by the test suite.

	The following environment variables are used for [CSFLE testing](https://github.com/mongodb/specifications/blob/master/source/client-side-encryption/tests/README.rst):

	* `CRYPT_SHARED_LIB_PATH`: If defined, this value will be used to set the
	`cryptSharedLibPath` autoEncryption driver option for
	[`MongoDB\Driver\Manager`](https://www.php.net/manual/en/class.mongodb-driver-manager.php)
	objects created by the test suite.

	### Mongo Orchestration

	[Mongo Orchestration](https://github.com/10gen/mongo-orchestration) is an HTTP
	server that provides a REST API for managing MongoDB servers and clusters.
	Evergreen CI and GitHub Actions use configurations provided by the
	[drivers-evergreen-tools](https://github.com/mongodb-labs/drivers-evergreen-tools)
	repository. These configurations are loaded by Mongo Orchestration, which then
	provides a connection string to assign to `MONGODB_URI` and run the test suite.
	Additionally, some tests start temporary servers and interact directly with
	Mongo Orchestration (via `MONGO_ORCHESTRATION_URI`).

	For local development, running Mongo Orchestration is not required and it is
	generally sufficient to test against a single-node replica set.

	## Updating libmongoc, libbson, and libmongocrypt

	The PHP driver can use either system libraries or bundled versions of
	libmongoc, libbson, and libmongocrypt. If a new version of either library is
	available, the submodule and build configuration will need to be updated to
	reflect the new sources and/or package version.

	### Resolving Submodule Conflicts When Merging Maintenance Branches

	When merging a maintenance branch up to master, it is quite possible for there
	to be a submodule conflict (and in related files). Resolving a merge conflict
	should never result in downgrading a submodule to an older version. Rather, the
	submodule should be conservatively advanced and satisfy any requirements for
	incoming changes from the maintenance branch.

	For example, the 1.14.2 release bumped libmongoc from 1.22.1 to 1.22.2. When
	merging v1.14 into master (1.15-dev), a conflict arose because the libmongoc
	submodule in master pointed to a 1.23-dev commit (before the 1.23.0 release).
	In this case, there were no particular requirements for incoming changes from
	the v1.14 branch and the libmongoc submodule was bumped to 1.23.0 even though
	a 1.23.1 tag also existed at the time. The bump to libmongoc 1.23.1 was left to
	another PHPC ticket in the 1.15.0 milestone, which actually depended on the
	libmongoc changes therein.

	### Updating bundled libraries

	The following steps are the same for libmongoc and libmongocrypt. When updating
	libmongocrypt, follow the same steps but replace `libmongoc` with
	`libmongocrypt`, retaining the same capitalization. The following examples
	always refer to libmongoc.

	#### Update submodule

	```shell
	cd src/libmongoc
	git fetch
	git checkout 1.20.0
	```

	During development, it may be necessary to temporarily point the submodule to a
	commit on the developer's fork. For instance, the developer may be working on a
	PHP driver feature that depends on unmerged or unreleased changes. In this case,
	the submodule path can be updated using the `git submodules set-url` command can
	be used to change the URL, and `git submodules set-branch` can be used to point
	the submodule to a development branch:

	```shell
	git submodules set-url src/libmongoc https://github.com/<owner>/<repo>.git
	git submodules set-branch -b <branch> src/libmongoc
	```

	#### Ensure version information is correct

	Various build processes and tools rely on the version files to infer version
	information. This file can be regenerated using Makefile targets:

	```shell
	make libmongoc-version-current
	```

	Alternatively, the `build/calc_release_version.py` script in the submodule can
	be executed directly.

	Note: If the submodule points to a non-release, non-master branch, the script
	may fail to correctly detect the version. This issue is being tracked in
	[CDRIVER-3315](https://jira.mongodb.org/browse/CDRIVER-3315) and can be safely ignored since this should only happen
	during development (any PHP driver release should point to a tagged submodule
	version).

	#### Update sources in build configurations

	The Autotools and Windows build configurations (`config.m4` and `config.w32`,
	respectively) define several variables (e.g. `PHP_MONGODB_MONGOC_SOURCES`) that
	collectively enumerate all of the sources within the submodules to include in a
	bundled build.

	These variables should each have a shell command in a preceding comment, which
	should be run to regenerate that particular list of source files. Each command
	may be run manually or `scripts/update-submodule-sources.php` may be used to
	update all variables. In the event that a new source directory is introduced,
	this directory will need to be manually added following prior art.

	#### Update package dependencies

	The Autotools configuration additionally includes some `pkg-config` commands for
	using libmongoc, libbson, and libmongocrypt as system libraries (in lieu of a
	bundled build). When bumping the bundled version, be sure to update the version
	check _and_ error message in the `pkg-config` blocks for the submodule being
	updated. When updating libmongoc, be sure to update both version checks for
	libmongoc and libbson.

	For example, the following lines might be updated for libmongoc:

	```
	if $PKG_CONFIG libmongoc-1.0 --atleast-version 1.20.0; then

	...

	AC_MSG_ERROR(system libmongoc must be upgraded to version >= 1.20.0)
	```

	#### Update tested versions in Evergreen configuration (libmongoc only)

	Evergreen tests against multiple versions of libmongoc. When updating to a newer
	libmongoc version, make sure to update the libmongoc build tasks in `.evergreen/config/templates/build/build-libmongoc.yml`
	and regenerate the build configuration. The template file contains additional
	information about the build tasks and where they are used. In general, we test
	against two additional versions of libmongoc:

	- The upcoming patch release of the current libmongoc minor version (e.g. the
	`r1.x` branch)
	- The upcoming minor release of libmongoc (e.g. the `master` branch)

	#### Update sources in PECL package generation script

	If a new version of a submodule introduces a new source directory, that may also
	require updating the glob patterns in the `bin/prep-release.php` script to
	ensure new source files will be included in any generated PECL package.

	#### Update SBOM file

	After updating dependencies, the SBOM file needs to be updated. There is a
	script to automate this process:

	```shell
	./scripts/update-sbom.sh
	```

	This script will generate a temporary purl file with our dependencies, then run
	the internal silkbomb tool to update the SBOM. Note that you need to have docker
	installed in order to run this.

	#### Test and commit your changes

	Verify that the upgrade was successful by ensuring that the driver can compile
	using both the bundled sources and system libraries, and by ensuring that the
	test suite passes. Once done, commit the changes to all of the above
	files/paths. For example:

	```shell
	git commit -m "Bump libmongoc to 1.20.0" config.m4 config.w32 src/libmongoc src/LIBMONGOC_VERSION_CURRENT sbom.json
	```

File Metadata

Mime Type: text/plain
Expires: Sat, Nov 14, 11:19 PM (1 d, 10 h)
Storage Engine: blob
Storage Format: Raw Data
Storage Handle: 111387
Default Alt Text: CONTRIBUTING.md (12 KB)

CONTRIBUTING.mdNo OneTemporaryActions

CONTRIBUTING.mdView Options

File Metadata

Event Timeline

CONTRIBUTING.md
No OneTemporary
Actions

CONTRIBUTING.md
View Options