Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Browse files

Initial commit of a readme for developers

  • Loading branch information...
commit fd434c402f20f882e870e22b25da4072a2349403 1 parent 11a8bc5
@bjori bjori authored committed
Showing with 104 additions and 0 deletions.
  1. +104 −0
@@ -0,0 +1,104 @@
+## Do you want to contribute?
+This is a README for developers wanting to contribute to the MongoDB PHP driver.
+## Current branches
+* 1.2 is the current release branch/stable branch (bugfix only)
+* master is the development branch for new features (to become 1.3)
+## Github
+The official repository of this driver is on [Github](
+When fixing a bug in the current release branch, please ensure you branch from it, and submit the Pull Request
+against it again.
+If there has been a while since you update your local fork, please ensure you rebase it properly :)
+Bugfixes and Pull Requests should be filed against the *lowest release branch*
+All *new* development happens in master (i.e. new features, BC changes, ..).
+## Running the tests
+To execute the "tests/generic/" tests in a specific mongod environment you can export
+`MONGO_SERVER` environment variable to overwrite the default environment (standalone):
+ MONGO_SERVER=REPLICASET-auth php run-tests.php tests/generic/mongo-listdbs-001.phpt
+If you export the variable, remember to unset it later - otherwise the test suite may not
+be executed correctly in the environment you expect it too.
+## Writing tests
+The tests/ file has several helper functions to ease running the same test case
+in several different environment at once (i.e. via 'make tests').
+Testscases in the generic/ folder are executed in all configured environments
+(see tests/, the testcases in the replicaset/ folder only when replicaset
+environment is available, the testcases in standalone-auth/ only in Standalone (with auth enabled)
+environment and so on and on.
+The most important helper function is the mongo() function, which out of the box will return a Mongo
+object configured for the current environment.
+When writing testcases for the Mongo construct, using the helper function won't give you much as it
+abstracts the logic of connecting to servers and doesn't provide a whole lot of room for custom options.
+This is however easily achieved by using the other helper functions such as hostname(), port(),
+username() etc etc. These will return back the configured values for the currently being executed environment.
+If you need to do the same "trick" over and over again in a testcase, it is probably worth writing a helper
+function for it in tests/
+## Test template
+ --TEST--
+ Test for PHP-XYZ: The ticket title
+ --SKIPIF--
+ <?php /* Minimum mongod requirement $needs = "2.2.0"; */ ?>
+ <?php require dirname(__FILE__) ."/"; ?>
+ --FILE--
+ <?php
+ $cn = "PHP-XYZ";
+ require_once dirname(__FILE__) . "/../";
+ $m = mongo();
+ $c = $m->selectCollection(dbname(), $cn);
+ /** Write your test code here **/
+ ?>
+ ===DONE===
+ <?php exit(0); ?>
+ --CLEAN--
+ <?php $c = "PHP-XYZ"; require dirname(__FILE__) ."/"; ?>
+ ** Expected output here **
+ ===DONE===
+Some notes about the template:
+* The dirname() is for PHP 5.2 compatibility.
+* Setting the $needs variable verifies minimum mongod requirements
+* checks if the extension is loaded and general sanity
+* is `require_once` as requires that file too
+* If $cn is set, that collection in the dbname() database will be dropped before the test runs
+* mongo() will return a connected Mongo object according to the envrionment or test folder
+* Please use a collection named after the ticket number (for easier tracking)
+* The exit(0); statement allows you to run the testcase standalone from
+ the command line (without running it via run-tests.php) and see what is going on
+ without being flooded with hundred of lines from the --EXPECTF-- section.
+* The --CLEAN-- section is to drop the collection name assigned to $cn
+## Code coverage
+Code coverage is generated by running the test suite after having enabled coverage before compiling the driver
+ $ phpize
+ $ ./configure --enable-coverage
+ $ make clean all tests
+Then you should have a coverage/ folder with the juicy details.

0 comments on commit fd434c4

Please sign in to comment.
Something went wrong with that request. Please try again.