diff --git a/README.md b/README.md new file mode 100644 index 0000000..7ddbd73 --- /dev/null +++ b/README.md @@ -0,0 +1,298 @@ +CONTENTS OF THIS FILE +--------------------- + + * Introduction + * Installation + * Variables + * Collections + * Module specific configuration + + +INTRODUCTION +------------ + +MongoDB integration for Drupal. This module is a collection of several modules, +allowing to store different Drupal data in MongoDB. + +Module | Information +----------------------|--------------------------------------------------------- +mongodb | Support library for the other modules. +mongodb_block | Store block information in MongoDB. Very close to the core block API. +mongodb_cache | Store cache in MongoDB. +mongodb_field_storage | Store fields in MongoDB. +mongodb_queue | DrupalQueueInterface implementation using MongoDB. +mongodb_session | Store sessions in MongoDB. +mongodb_watchdog | Store watchdog messages in MongoDB. + + +INSTALLATION +------------ + +Install as usual, see http://drupal.org/node/895232 for further information. + +The MongoDB module and sub-modules need some amount of configuration before they +will properly work. This guide assumes that a MongoDB instance is already +installed and configured on localhost or remote server. This module additionally +provides Drush integration to make queries against the MongoDB databases used by +Drupal. + +If MongoDB is installed on localhost, you may view the web admin interface: +> http://localhost:28017/ + + +CONFIGURATION VARIABLES +----------------------- + +MongoDB uses several specific configuration variables that are not currently +exposed in the UI. Non-developers should note that all $conf variables should +be placed at the bottom of the sites settings.php file under a #MongoDB comment. + +### 1: mongodb_connections + +The `mongodb_connections` variable holds the databases available to the module. +The contents are arranged as an associative array holding the name (alias) of +the connection, the database address, and the name of the database. If not +defined, it makes a single default entry.. + +EXAMPLE: + + $conf['mongodb_connections'] = array( + // Connection name/alias + 'default' => array( + // Omit USER:PASS@ if Mongo isn't configured to use authentication. + 'host' => 'mongodb://USER:PASS@localhost', + // Database name + 'db' => 'drupal_default', + ), + ); + +If `mongodb_connections` is not defined, `default` is automatically created with +the following settings: + + 'default' => array( + 'host' => 'localhost', + 'db' => 'drupal' + ) + +Also, `connection_options` might be specified to allow for connecting to +replica sets (and any other options listed on [http://php.net/manual/mongoclient.construct.php][construct] + +[construct]: (http://php.net/manual/mongoclient.construct.php) + + $conf['mongodb_connections'] = array( + // Connection name/alias + 'default' => array( + 'host' => 'mongodb://[username:password@]host1[:port1][,host2[:port2:],...]', + // Database name + 'db' => 'drupal_default', + 'connection_options' => array('replicaSet' => 'replicasetname'), + ), + ); + +Where square brackets indicate `username`, `password`, `port1` etc are optional. + +Querying a slave is also possible by creating a new connection alias and +specifying the `slave_ok` option. + + $conf['mongodb_connections'] = array( + // Connection name/alias. + 'slave' => array( + 'host' => 'slave1', + // Database name. + 'db' => 'drupal_default', + 'slave_ok' => TRUE, + ), + ); + +As of the mongoDB 1.3 php driver, `slave_ok` has been deprecated and instead +`read preference` should be used when dealing with a replica set. These +preferences can be set at a connection or collection level ; see below for the +collection information. + + $conf['mongodb_connections'] = array( + // Connection name/alias + 'slave' => array( + 'host' => 'slave1', + // Database name + 'db' => 'drupal_default', + 'read_preference' => array( + 'preference' => 'secondaryPreferred', + 'tags' => array( + array('dc' => 'east', 'use' => 'reporting'), + array('dc' => 'west'), + ), + ), + 'connection_options' => array('replicaSet' => 'main'), + ), + ); + +### 2: mongodb_debug + +A variable meant primarily for developers, `mongodb_debug` causes a collection +to return a `MongoDebugCollection` and `MongoDebugCursor` instead of their +normal equivalents. If not defined, defaults to `FALSE`. + +EXAMPLE: + + $conf['mongodb_debug'] = FALSE; + +### 3: mongodb_session + +This variable holds the name of the collection used by the mongodb_session +sub-module. If not defined, it defaults to `"session"`. + +EXAMPLE: + + $conf['mongodb_session'] = 'anyname'; + +### 4: mongodb_slave + +This variable holds an array of the slaves used for the mongodb field storage +sub-module. If not defined, it defaults to an empty `array()`. + +### 5: mongodb_watchdog + +This variable holds the name of the collection used by the mongodb_watchdog +module. It defaults to `"watchdog"`. + +EXAMPLE: + + $conf['mongodb_watchdog'] = 'drupalogs'; + +Whatever the name of the main collection defined with this variable, the +per-message-type collections are called `watchdog_(objectId)`. + +### 6: mongodb_watchdog_items + +This variable defines the maximum item limit on the capped collection used by +the mongodb_watchdog sub-module. If not defined, it defaults to 10000. The +actual (size-based) limit is derived from this variable, assuming 1 kiB per +watchdog entry. + +EXAMPLE: + + $conf['mongodb_watchdog_items'] = 15000; + +### 7: watchdog_limit + +This variable define the maximum severity level to save into watchdog. Errors +below this level will be ignored by watchdog. If not defined, all errors will +saved. + +EXAMPLE: + + $conf['watchdog_limit'] = WATCHDOG_CRITICAL; + +See [watchdog_severity_levels()][levels] for further information about Watchdog severity levels. + +[levels]: http://api.drupal.org/api/drupal/includes--common.inc/function/watchdog_severity_levels/7 + +### 8: mongodb_collections + +See the COLLECTIONS section below. + + +COLLECTIONS +----------- + +Collections are MongoDB's equivalent of relational database tables. In the +context of this module, they can be used to span data from the multiple +sub-modules into separate databases. This is accomplished by aliasing the +collection name to a connection name (as defined in the `mongodb_connections` +variable). If you want everything in a single database, `mongodb_collections` do +not need to be configured and everything is written to the local default +database using the default collection names (given below). The dot is allowed in +the name of mongodb collections. Before the dot, mongodb_field_storage uses +`"fields_current"` or `"fields_revision"` and puts the entity type after. + +MODULE | COLLECTION NAMES +-----------------------|----------------------------------- +mongodb_block | "block" +mongodb_cache | "cache_bootstrap" + | "cache_menu" + | ... +mongodb_field_storage | "fields_current.node", + | "fields_current.taxonomy_term" + | "fields_revision.user" + | ... +mongodb_queue | "queue." + | "queue." + | ... +mongodb_session | "session" (variable) +mongodb_watchdog | "watchdog" (variable) + + +In the following example, the watchdog collection will be handled by +the hypothetical connection alias `logginghost` + +EXAMPLE: + + $conf['mongodb_collections'] = array('watchdog' => 'logginghost'); + +If you are using the 1.3 or more recent drivers you can specify the following +connection options: `db_connection` and `read_preference`. These options allow +you to control collection-level mongo read preferences and whether any tags +should be used. + + $conf['mongodb_collections'] = array( + 'watchdog' => array( + 'db_connection' => 'logginghost', + 'read_preference' => array( + 'preference' => 'secondaryPreferred', + 'tags' => array( + array('dc' => 'east', 'use' => 'reporting'), + array('dc' => 'west'), + ), + ), + ), + ); + +If you do not need read_preference you can continue to utilise the existing +array structure for the 1.3 and more recent drivers. + + +MODULE-SPECIFIC CONFIGURATION +----------------------------- + +The following configuration variables are needed to use the features provided +by the the following sub-modules. + +### mongodb_cache + +EXAMPLE: + + # -- Configure Cache. + $conf['cache_backends'][] = 'sites/all/modules/mongodb/mongodb_cache/mongodb_cache.inc'; + $conf['cache_default_class'] = 'DrupalMongoDBCache'; + + # -- Don't touch SQL if in Cache. + $conf['page_cache_without_database'] = TRUE; + $conf['page_cache_invoke_hooks'] = FALSE; + +### mongodb_session + +EXAMPLE: + + # Session Caching + $conf['session_inc'] = 'sites/all/modules/mongodb/mongodb_session/mongodb_session.inc'; + $conf['cache_session'] = 'DrupalMongoDBCache'; + +### mongodb_field_storage + +EXAMPLE: + + # Field Storage + $conf['field_storage_default'] = 'mongodb_field_storage'; + + +TROUBLESHOOTING +--------------- + +If installing mongodb_field_storage from an Install Profile: + +* Do not enable the module in the profile `.info` file. +* Do not include the module specific `$conf` variable in `settings.php` during install. +* In the profiles `hook_install()` function, include: + + module_enable(array('mongodb_field_storage')); + drupal_flush_all_caches(); diff --git a/README.txt b/README.txt deleted file mode 100644 index 82925a8..0000000 --- a/README.txt +++ /dev/null @@ -1,278 +0,0 @@ -CONTENTS OF THIS FILE ---------------------- - - * Introduction - * Installation - * Variables - * Collections - * Module specific configuration - - -INTRODUCTION ------------- - -MongoDB integration for Drupal. This module is a collection of several modules, -allowing to store different Drupal data in MongoDB. - -mongodb Support library for the other modules. -mongodb_block Store block information in MongoDB. Very close to the - core block API. -mongodb_cache Store cache in MongoDB. -mongodb_field_storage Store fields in MongoDB. -mongodb_queue DrupalQueueInterface implementation using MongoDB. -mongodb_session Store sessions in MongoDB. -mongodb_watchdog Store watchdog messages in MongoDB. - - -INSTALLATION & CONFIGURATION ------------- - -Install as usual, see http://drupal.org/node/895232 for further information. - -The MongoDB module and sub-modules need some amount of configuration before they -will properly work. This guide assumes that a MongoDB instance is already -installed and configured on localhost or remote server. This module additionally -provides Drush integration to make queries against the MongoDB databases used by -Drupal. - -If MongoDB is installed on localhost, you may view the web admin interface: -> http://localhost:28017/ - - -VARIABLES ------------- -MongoDB uses several specific configuration variables that are not currently -exposed in the UI. Non-developers should note that all $conf variables should -be placed at the bottom of the sites settings.php file under a #MongoDB comment. - -Configuration Variables - -#1: mongodb_connections - - The mongodb_connections variable holds the databases available to the module. - The contents are arranged as an associative array holding the name (alias) of - the connection, the database address, and the name of the database. If not - defined, it makes a single default entry. See the note below *. - - EXAMPLE: - $conf['mongodb_connections'] = array( - // Connection name/alias - 'default' => array( - // Omit USER:PASS@ if Mongo isn't configured to use authentication. - 'host' => 'mongodb://USER:PASS@localhost', - // Database name - 'db' => 'drupal_default', - ), - ); - - * If mongodb_connections is not defined, 'default' is automatically - created with the following settings: - 'default' => array('host' => 'localhost', 'db' => 'drupal') - - Also, connection_options might be specified to allow for connecting to - replicate sets (and any other options listed on - http://www.php.net/manual/mongo.construct.php) - - $conf['mongodb_connections'] = array( - // Connection name/alias - 'default' => array( - 'host' => 'mongodb://[username:password@]host1[:port1][,host2[:port2:],...]', - // Database name - 'db' => 'drupal_default', - 'connection_options' => array('replicaSet' => 'replicasetname'), - ), - ); - - Where square brackets indicate username, password, port1 etc are optional. - - Querying a slave is also possible by creating a new connection alias - and specifying slave_ok option. - - $conf['mongodb_connections'] = array( - // Connection name/alias - 'slave' => array( - 'host' => 'slave1', - // Database name - 'db' => 'drupal_default', - 'slave_ok' => TRUE, - ), - ); - - As of the mongoDB 1.3 php driver slave_ok has been deprecated and instead - read preferences should be used when dealing with a replica set. These - preferences can be set at a connection or collection level see below for the - collection information. - - $conf['mongodb_connections'] = array( - // Connection name/alias - 'slave' => array( - 'host' => 'slave1', - // Database name - 'db' => 'drupal_default', - 'read_preference' => array( - 'preference' => 'secondaryPreferred', - 'tags' => array( - array('dc' => 'east', 'use' => 'reporting'), - array('dc' => 'west'), - ), - ), - 'connection_options' => array('replicaSet' => 'main'), - ), - ); - -#2: mongodb_debug - - A variable primarily for developers, mongodb_debug causes a collection - to return a mongoDebugCollection and mongoDebugCursor instead of their - normal equivalents. If not defined, defaults to FALSE. - - EXAMPLE: - $conf['mongodb_debug'] = FALSE; - -#3: mongodb_session - - This variable holds the name of the collection used by the mongodb_session - sub-module. If not defined, it defaults to "session". - - EXAMPLE: - $conf['mongodb_session'] = 'anyname'; - -#4: mongodb_slave - - This variable holds an array of the slaves used for the mongodb field storage - sub-module. If not defined, it defaults to an empty array(). - -#5: mongodb_watchdog - - This variable holds the name of the collection used by the mongodb_watchdog - module. It defaults to "watchdog". - - EXAMPLE: - $conf['mongodb_watchdog'] = 'drupalogs'; - -#6: mongodb_watchdog_items - - This variable defines the maximum item limit on the capped collection used by - the mongodb_watchdog sub-module. If not defined, it defaults to 10000. - The actual (size-based) limit is derived from this variable, assuming 1 kiB - per watchdog entry. - - EXAMPLE: - $conf['mongodb_watchdog_items'] = 15000; - -#7: watchdog_limit - - This variable define the maximum severity level to save into watchdog. Errors - under this level will be ignored by watchdog. If not defined, all errors will - saved. - - EXAMPLE: - $conf['watchdog_limit'] = WATCHDOG_CRITICAL; - - See http://api.drupal.org/api/drupal/includes--common.inc/function/watchdog_severity_levels/7 - for further information about Watchdog severity levels. - -#8: mongodb_collections - - See COLLECTIONS below. - - -COLLECTIONS ------------- - -Collections are MongoDB's equivalent of relational database tables. In the -context of this module, they can be used to span data from the multiple -submodules into separate databases. This is accomplished by aliasing the -collection name to a connection name (as defined in the 'mongodb_connections' -variable). If you want everything in a single database, collections do not need -to be configured and everything is written to the local default database using -the default collection names (given below). The dot is allowed in the name of -mongodb collections. Before the dot, mongodb_field_storage uses "fields_current" -or "fields_revision" and puts the entity type after. - -MODULE COLLECTION NAMES ------------------------------------------------------------ -mongodb_block "block" -mongodb_cache "cache_bootstrap" - "cache_menu" - ... -mongodb_field_storage "fields_current.node", - "fields_current.taxonomy_term" - "fields_revision.user" - ... -mongodb_queue "queue." - "queue." - ... -mongodb_session "session" (variable) -mongodb_watchdog "watchdog" (variable) ------------------------------------------------------------ - -In the following example, the watchdog collection will be handled by -the hypothetical connection alias 'logginghost' - -EXAMPLE: -$conf['mongodb_collections'] = array('watchdog' => 'logginghost'); - -If you are using the 1.3 drivers you can specify the following connection -options db_connection and read_preference. These options allow to control -collection level mongo read preferences and whether any tags should be used. - -$conf['mongodb_collections'] = array( - 'watchdog' => array( - 'db_connection' => 'logginghost', - 'read_preference' => array( - 'preference' => 'secondaryPreferred', - 'tags' => array( - array('dc' => 'east', 'use' => 'reporting'), - array('dc' => 'west'), - ), - ), - ), -); - -If you do not need read_preference you can continue to utilise the existing -array structure for the 1.3 drivers. - -MODULE-SPECIFIC CONFIGURATION ------------- - -The following configuration variables are needed to use the features provided -by the the following sub-modules. - -=> mongodb_cache - - EXAMPLE: - # -- Configure Cache - $conf['cache_backends'][] = - 'sites/all/modules/mongodb/mongodb_cache/mongodb_cache.inc'; - $conf['cache_default_class'] = 'DrupalMongoDBCache'; - # -- Don't touch SQL if in Cache - $conf['page_cache_without_database'] = TRUE; - $conf['page_cache_invoke_hooks'] = FALSE; - -=> mongodb_session - - EXAMPLE: - # Session Caching - $conf['session_inc'] = - 'sites/all/modules/mongodb/mongodb_session/mongodb_session.inc'; - $conf['cache_session'] = 'DrupalMongoDBCache'; - -=> mongodb_field_storage - - EXAMPLE: - # Field Storage - $conf['field_storage_default'] = 'mongodb_field_storage'; - -TROUBLESHOOTING ------------- - -If installing mongodb_field_storage from an Install Profile: - -* Do not enable the module in the profiles .info file. -* Do not include the module specific $conf variable in settings.php during - install. -* In the profiles hook_install() function include - - module_enable(array('mongodb_field_storage')); - drupal_flush_all_caches(); diff --git a/mongodb.module b/mongodb.module index 388f6e1..47ae399 100644 --- a/mongodb.module +++ b/mongodb.module @@ -1,22 +1,40 @@ ' . t('MongoDB implements a generic MongoDB interface.', - array( - '!project' => 'http://drupal.org/project/mongodb', - '!mongo' => 'http://www.mongodb.org/', - )); - break; + return '

' . t('MongoDB implements a generic MongoDB interface.', array( + '!project' => 'http://drupal.org/project/mongodb', + '!mongo' => 'http://www.mongodb.org/', + )); } } /** * Returns an MongoDB object. + * + * @param string $alias + * The name of a MongoDB connection alias. If it is not passed, or if the + * alias does not match a connection definition, the function will fall back + * to the 'default' alias. + * + * @return \MongoDB|\MongoDummy + * A MongoDummy is returned in case a MongoConnectionException is thrown. + * + * @throws \InvalidArgumentException + * If the database cannot be selected. + * @throws \MongoConnectionException + * If the connection cannot be established. + * + * @see mongoDummy */ function mongodb($alias = 'default') { static $mongo_objects; @@ -25,9 +43,13 @@ function mongodb($alias = 'default') { $alias = 'default'; } $connection = isset($connections[$alias]) ? $connections[$alias] : array(); - $connection += array('host' => 'localhost', 'db' => 'drupal', 'connection_options' => array()); + $connection += array( + 'host' => 'localhost', + 'db' => 'drupal', + 'connection_options' => array(), + ); $host = $connection['host']; - $options = $connection['connection_options'] + array('connect' => TRUE); + $options = $connection['connection_options'] + array('connect' => TRUE); $db = $connection['db']; if (!isset($mongo_objects[$host][$db])) { try { @@ -52,7 +74,7 @@ function mongodb($alias = 'default') { $mongo_objects[$host][$db]->connection = $mongo; } catch (MongoConnectionException $e) { - $mongo_objects[$host][$db] = new mongoDummy; + $mongo_objects[$host][$db] = new MongoDummy(); throw $e; } } @@ -61,6 +83,16 @@ function mongodb($alias = 'default') { /** * Returns a MongoCollection object. + * + * @return \MongoCollection|\MongoDebugCollection|\MongoDummy + * Return a MongoCollection in normal situations, a MongoDebugCollection if + * mongodb_debug is enabled, or a MongoDummy if the MongoDB connection could + * not be established. + * + * @throws \InvalidArgumentException + * If the database cannot be selected. + * @throws \MongoConnectionException + * If the connection cannot be established. */ function mongodb_collection() { $args = array_filter(func_get_args()); @@ -76,8 +108,10 @@ function mongodb_collection() { $collections = variable_get('mongodb_collections', array()); if (isset($collections[$collection_name])) { // We might be dealing with an array or string because of need to preserve - // backwards comptability. - $alias = is_array($collections[$collection_name]) && !empty($collections[$collection_name]['db_connection']) ? $collections[$collection_name]['db_connection'] : $collections[$collection_name]; + // backwards compatibility. + $alias = is_array($collections[$collection_name]) && !empty($collections[$collection_name]['db_connection']) + ? $collections[$collection_name]['db_connection'] + : $collections[$collection_name]; } else { $alias = 'default'; @@ -94,51 +128,129 @@ function mongodb_collection() { $collection->setReadPreference($collections[$alias]['read_preference']['preference'], $tags); } $collection->connection = $mongodb_object->connection; - return variable_get('mongodb_debug', FALSE) ? new mongoDebugCollection($collection) : $collection; + return variable_get('mongodb_debug', FALSE) ? new MongoDebugCollection($collection) : $collection; } -class mongoDebugCollection { - function __construct($collection) { +/** + * Class MongoDebugCollection is a debug decorator for MongoCollection. + */ +class MongoDebugCollection { + /** + * Constructor. + * + * @param string $collection + * The collection to decorate. + */ + public function __construct($collection) { $this->collection = $collection; } - function find($query = array(), $fields = array()) { + /** + * A decorator for the MongoCollection::find() method adding debug info. + * + * @param array $query + * A MongoCollection;:find()-compatible query array. + * @param array $fields + * A MongoCollection;:find()-compatible fields array. + * + * @return \MongoDebugCursor + * A debug cursor wrapping the decorated find() results. + */ + public function find($query = array(), $fields = array()) { debug('find'); debug($query); debug($fields); - return new mongoDebugCursor($this->collection->find($query, $fields)); + return new MongoDebugCursor($this->collection->find($query, $fields)); } - function __call($name, $arguments) { + /** + * Decorates the standard __call() by debug()-ing its arguments. + * + * @param string $name + * The name of the called method. + * @param array $arguments + * The arguments for the decorated __call(). + * + * @return mixed + * The result of the decorated __call(). + */ + public function __call($name, array $arguments) { debug($name); debug($arguments); return call_user_func_array(array($this->collection, $name), $arguments); } + } -class mongoDebugCursor { - function __construct($collection) { +/** + * Class MongoDebugCursor is a debug decorator for MongoCollection::find(). + */ +class MongoDebugCursor { + /** + * Constructor. + * + * @param string $collection + * The name of the collection on which the cursor applies. + * + * @see mongoDebugCollection::find() + */ + public function __construct($collection) { $this->collection = $collection; } - function __call($name, $arguments) { + /** + * Decorates the standard __call() by debug()-ing its arguments. + * + * @param string $name + * The name of the called method. + * @param array $arguments + * The arguments for the decorated __call(). + * + * @return mixed + * The result of the decorated __call(). + */ + public function __call($name, array $arguments) { debug($name); debug($arguments); return call_user_func_array(array($this->collection, $name), $arguments); } + } -class mongoDummy { +/** + * Class MongoDummy is a fake object accepting any method and doing nothing. + */ +class MongoDummy { + public $connection; - function selectCollection() { - return new mongoDummy; + + /** + * Pretend to return a collection. + * + * @return \MongoDummy + * The returned value is actually a new MongoDummy instance. + */ + public function selectCollection() { + return new MongoDummy(); } - function __call($name, $arguments) { + + /** + * Magic __call accepting any method name and doing nothing. + * + * @param string $name + * Ignored. + * @param array $arguments + * All arguments are ignored. + */ + public function __call($name, array $arguments) { } + } /** - * Returns the name to use for the collection, which works with prefixes and simpletest. + * Returns the name to use for the collection. + * + * Also works with prefixes and simpletest. */ function mongodb_collection_name($name) { global $db_prefix; @@ -161,6 +273,14 @@ function mongodb_collection_name($name) { return $simpletest_prefix . $name; } +/** + * Implements hook_test_group_finished(). + * + * @throws \InvalidArgumentException + * If the database cannot be selected. + * @throws \MongoConnectionException + * If the connection cannot be established. + */ function mongodb_test_group_finished() { $aliases = variable_get('mongodb_connections', array()); $aliases['default'] = TRUE; @@ -177,10 +297,10 @@ function mongodb_test_group_finished() { /** * Allow for the database connection we are using to be changed. * - * @param $alias - * String the alias that we want to change the connection for. - * @param $connection_name - * String the name of the connection we will use. + * @param string $alias + * The alias that we want to change the connection for. + * @param string $connection_name + * The name of the connection we will use. */ function mongodb_set_active_connection($alias, $connection_name = 'default') { // No need to check if the connection is valid as mongodb() does this. @@ -231,8 +351,9 @@ function mongodb_next_id($name, $existing_id = 0) { /** * Returns default options for MongoDB write operations. * - * @param $safe + * @param bool $safe * Set it to FALSE for "fire and forget" write operation. + * * @return array * Default options for Mongo write operations. */