README

A plugin for accessing MongoDB NoSQL data stores in CakePHP 3.x.

Requirements

Composer
CakePHP 3.x
PHP 5.4+
MongoDB
Pecl Mongo extension

Installation

In your CakePHP root directory: run the following command:

composer require lewestopher/cakephp-monga

Then in your config/bootstrap.php in your project root, add the following snippet:

// In project_root/config/bootstrap.php:

Plugin::load('CakeMonga');

or you can use the following shell command to enable to plugin in your bootstrap.php automatically:

bin/cake plugin load CakeMonga

Extended Documentation

For the extended docs, please visit our Wiki.

Usage

First, we define a new Datasource in our config/app.php file with our namespaced Connection class name:

// In project_root/config/app.php:

'Datasources' => [

    'default' => [
        // ... Default SQL Datasource
    ],

    'mongo_db' => [
        'className' => 'CakeMonga\Database\MongoConnection',
    ]
],

Then we can instantiate our MongoDB connection anywhere that we need in the application via the ConnectionManager class:

class ExampleController extends Controller
{
    public function index()
    {
        $cake_monga = ConnectionManager::get('mongo_db');
    }
}

Then from there we can get our Monga instance by using the connect() method on the returned connection:

$cake_monga = ConnectionManager::get('mongo_db');
$mongodb = $cake_monga->connect(); // An instance of the Monga Connection object
$database_list = $mongodb->listDatabases(); // We can call all of the methods on that Monga object provided by their API

Note that the $mongodb object instantiated above with the connect() method is the same object returned by Monga::connection() in the Monga API:

$cake_monga = ConnectionManager::get('mongo_db');
$mongodb = $cake_monga->connect();

// Alternatively:

$mongodb = Monga::connection($dns, $config_opts);

This information should help you make the bridge between instantiating the Datasource using CakePHP and utilizing the Monga API for data retrieval and saving.

Configuration

cakephp-monga accepts all of the same options in the Datasource configuration that can be passed into the MongoClient() object in PHP. Documentation for these options is defined here.

// In project_root/config/app.php: 

'Datasources' => [

    'default' => [
        // ... Default SQL Datasource
    ],

    'mongo_db' => [
        'className' => 'CakeMonga\Database\MongoConnection',
        'logger' => null,
        'authMechanism' => null,
        'authSource' => null,
        'connect' => true,
        'connectTimeoutMS' => 60000,
        'db' => null,
        'dns' => 'mongodb://localhost:27017',
        'fsync' => null,
        'journal' => null,
        'gssapiServiceName' => 'mongodb',
        'username' => null,
        'password' => null,
        'readPreference' => null,
        'readPreferenceTags' => null,
        'replicaSet' => null,
        'secondaryAcceptableLatencyMS' => 15,
        'socketTimeoutMS' => 30000,
        'ssl' => false,
        'w' => 1,
        'wTimeoutMS' => 10000
    ]
],

Connecting to a custom DNS using this library

By default, this library connects to the mongodb://localhost:27017 DNS string. You can specify a custom DNS to connect on by setting a 'dns' key on the connection's Datasource hash in the config/app.php file:

// In project_root/config/app.php:

'Datasources' => [

    'mongo_db' => [
        'className' => 'CakeMonga\Database\MongoConnection',
        'dns' => 'mongodb://your.remote.host:27017'
    ]
],

API and Accessing your MongoDB Instance

This plugin is a wrapper of the Mongo plugin by the League of Extraordinary Packages. To find out how to query, save, and update data within your Mongo collections, check out the Monga documentation.

Defining a custom Collection class

View the Accessing Collections Extended Docs page for more information on creating Collection classes.

As of version 0.2.0, CakeMonga supports the usage of custom Collection classes. These custom classes are located with the src/Model/MongoCollection folder an extend the CakeMonga\MongoCollection\BaseCollection class. Now you can use these classes to encapsulate data layer logic into the appropriate class locations. These methods are direct abstractions of their Monga counterparts. You can view the docs for these methods on the Monga API Docs. The BaseCollection class provides the following methods for data access:

class BaseCollection {
    public function getCollection();
    public function find($query = [], $fields = [], $findOne = false);
    public function findOne($query = [], $fields = []);
    public function drop();
    public function listIndexes();
    public function save($document, $options = []);
    public function update($values = [], $query = null, $options = []);
    public function insert(array $data, $options = []);
    public function remove($criteria, $options = []);
    public function truncate();
    public function aggregate($aggregation = []);
    public function distinct($key, $query = []);
    public function count($query = []);
}

Note that the MongoDB collection that is utilized by custom Collection classes is the tableized name of the Collection class itself. For example, UsersCollection.php would map to the users collection inside of your MongoDB instance.

Retrieving a custom Collection model using CollectionRegistry

As of 0.2.0, custom Collection models extended from BaseCollection can be retrieved using the CollectionRegistry singleton with the same syntax that TableRegistry employs:

// Define a custom User collection at src/Model/MongoCollection/UserCollection.php. 
use CakeMonga\MongoCollection\BaseCollection;

class UsersCollection extends BaseCollection
{
    public function getUsersNamedJohn()
    {
        return $this->find(['name' => 'John']);
    }
}

// We can retrieve this UsersCollection by using the static ::get() method on CollectionRegistry
use CakeMonga\MongoCollection\CollectionRegistry;

$users_collection = CollectionRegistry::get('Users');

By default, the CollectionRegistry utilizes the default connection defined as 'mongo_db' in your app.php file. Want to use a different Mongo datasource? No problem, just pass in a datasource string to the 'connection' attribute of the config array for CollectionRegistry::get():

$users_collection = CollectionRegistry::get('Users', [
    'connection' => 'secondary_mongo_datasource'
]

This would construct the UsersCollection class with a connection to the other datasource.

Collection Event Hooks

As of 0.4.0, you can now define the following events on your Collection classes:

use CakeMonga\MongoCollection\BaseCollection;

class CustomCollection extends BaseCollection
{
    public function beforeFind($event, $query, $fields, $findOne);
    public function beforeSave($event, $document);
    public function afterSave($event, $document)
    public function beforeInsert($event, $data);
    public function afterInsert($event, $results)
    public function beforeUpdate($event, $values, $query)
    public function afterUpdate($event, $document);
    public function beforeRemove($event, $criteria);
    public function afterRemove($event, $result, $criteria);
}

You can find more information on Collection events on the Accessing Collections Wiki Page

Custom Behaviors

As of 0.5.0, you can attach Behaviors to classes extending the BaseCollection class in the same manner that you would to a Table object. To create a custom behavior for a BaseCollection, you should extend the MongoBehavior class instead of the regular Behavior class.

You can find out more about Behaviors on collections on the Accessing Collections Wiki Page.

Query Logging

As of version 0.3.0, CakeMonga supports query logging via the Mongo logging context. To learn how to enable logging and create custom loggers, visit the Query Logging Wiki Page.

What is cakephp-monga?

This plugin is a wrapper for the popular Monga library provided by The League of Extraordinary packages. In it's current form, this plugin is intended to get you quickly set up and running with access to a MongoDB instance so that you can access your data in your application. This plugin provides all of the same functionality that the Monga library provides in terms of building queries and retrieving your data.

What is cakephp-monga not?

This plugin is not currently intended as a drop in replacement for the SQL ORM provided by CakePHP core. While you could theoretically build an entire application using cakephp-monga as the data layer, this plugin does not have the kind of application level integration (Events, Logging, etc) that the current ORM does. Additionally, there is not abstraction layer for Database level, Collection level, or Entity level objects (EG - Defining methods on a supposed UserCollection.php, or creating a Mongo Entity at User.php), although this is on the roadmap for a future version very soon.

Additionally, it's important to recognize that while certain relational features can be emulated within a MongoDB dataset, Mongo is still not an ACID compliant database. In the future, Collection level classes will be built for object abstraction that will implement CakePHP's Repository interface, but it should be noted that full ORM features will not be supported as Mongo is not a true object relational database.

Roadmap

Here are some of the features that I plan on integrating into this project very soon:

Basic Connection object support for retrieving an instance of the Monga class for simple data retrieval. Added in 0.1.0
Collection ~~and Entity level~~ abstraction layers (EG - UserCollection.php ~~and User.php~~ for Mongo) Added in 0.2.0
SSL Support via the stream context on the third argument of the MongoClient constructor
Query logging via the stream context on the third argument of the MongoClient constructor Added in 0.3.0
A CollectionRegistry class for retrieving Mongo collections with connection params already passed in. Added in 0.2.0
Custom behavior support on the Collection level class Added in 0.5.0
Events integration on the Collection level class Added in 0.4.0
Validation Support

Support

For bugs and feature requests, please use the issues section of this repository.

Contributing

To contribute to this plugin please follow a few basic rules.

Contributions must follow the CakePHP coding standard.
Unit tests are required.

Change Log

Yes, we have one of those.

Creators

Wes King

Frank de Jonge - Creator of the Monga Dependency

Monga Contributors

License

Licensed under The MIT License Redistributions of files must retain the above copyright notice.

lewestopher / cakephp-monga

Maintainers

Details