4.4.6 2017-03-17 17:47 UTC


MongoDB Object Persister

Latest Stable Version License [![Scrutinizer Code Quality](]( [![Code Coverage](](



Quick Install

composer require maslosoft/mangan

Install mongofill if no ext-mongo available (for hhvm, php7 too):

composer require mongofill/mongofill:"@dev"

This extension originally started as a fork of YiiMongoDbSuite, written by canni and further improved by several developers (mintao, et al). YiiMongoDbSuite originally started as a fork of MongoRecord extension written by tyohan, to fix some major bugs, and add full featured suite for MongoDB developers.

This file is very outdated, however contains some usefull information about what it is.

The Key Feature List:

Features Covered From Standard Yii Implementations

  • Support of using $model->find / findAll / count / countByAttributes and other Yii ActiveRecord syntax.
  • Named scopes, along with default scope and parameterized scopes, just like in AR.
  • Ready to go out-of-box EFFICIENT DataProvider, witch use native php db driver sort, limit and offset features for returning results!
  • Model classes and embedded documents can use plain php objects (only need to implement empty interface AnnotattedInterface)
  • Relations support
  • Easy to use criteria object, you don't have to create complex MongoDB query arrays.

MongoDB Related Feature List

  • Support of schema-less documents defined just by classes
  • Embedded document and arrays of embedded documents support
  • DbRefs and DbRefs arrays (cross db too)
  • Related and related arrays (cross db too)
  • Ability to set FSync and/or Safe flag of DB write operations on different scopes, globally, on model level, and on single model object
  • Ability to use efficient MongoDB Cursors instead of raw arrays of results, returned by the findAll methods*
  • MongoDB GridFS feature support, thanks to work of Jose Martinez and Philippe Gaultier
  • Support for using any other than _id field(s) as a Primary Key, for a collection
  • Automated efficient index definition for collections, per model
  • Automatic partial documents based on class hierarchy
  • Ability to do Extreme Efficent document partial updates, that make use of MongoDB $set operator/feature
  • Multi db connections

Yii Addendum Related Feature List

  • Easy model definition
  • Clean view of any model field options/properties
  • Lightweight and extensible model metadata


  • The main limitations are only those present in MongoDB itself, like the 16mb data transfer limit.
  • In it's current incarnation, This extension does NOT work with the "$or" criteria operator. When we get it working we will remove this line and add an example.


  • Yii 1.1.14+ is recommended.
  • MongoDB 2.4.0+ is recommended. Percona DB recommended.
  • Mongo PHP Driver 1.4.5+
  • PHP 5.5+
  • composer


Use composer to install extension:

composer require maslosoft/mangan <version>

In your protected/config/main.php config file. Add mongodb array for your database in the components section, and add the following to the file:

	'mongodb' => [
		'connectionString' => 'mongodb://',
		'dbName' => 'db_name',
		'class' => Maslosoft\Mangan\Mangan::class
  • ConnectionString: 'localhost' should be changed to the ip or hostname of your host being connected to. For example if connecting to a server it might be 'connectionString' => 'mongodb://username@xxx.xx.xx.xx' where xx.xx.xx.xx is the ip (or hostname) of your webserver or host.
  • dbName: The database name, where your collections will be be stored in.
  • fsyncFlag If set to true, this makes mongodb make sure all writes to the database are safely stored to disk (true by default).
  • safeFlag If set to true, mongodb will wait to retrieve status of all write operations, and check if everything went OK (true by default).
  • useCursors If set to true, extension will return Cursor instead of raw pre-populated arrays, from findAll* methods (defaults to false for backwards compatibility).

That's all you have to do for setup. You can use it very much like the active record. For example:

    $client = new Client();
    $clients = Client::model()->findAll();

Basic Usage

Just define following model:

	use Maslosoft\Mangan\Document;
    class User extends Document
       * @Label('User login')
       * @RequiredValidator
      public $login;
       * @Label('Full name')
       * @LengthValidator(max => 255)
      public $name;
       * @Label('Password')
       * @RequiredValidator
       * @LengthValidator(min => 6, max => 20)
      public $password;

And that's it! Now start using this User model class like standard Yii AR model.

Embedded Documents

NOTE: For performance reasons embedded documents should extend from EmbeddedDocument instead of Document.

EmbeddedDocument is almost identical as Document, in fact Document extends from EmbeddedDocument and adds to it the DB connection and related functions.

So if you have a User.php model, and an UserAddress.php model which is the embedded document. Lest assume we have following embedded document:

    use Maslosoft\Mangan\EmbeddedDocument;
    class UserAddress extends EmbeddedDocument
       * @Label('City')
       * @LengthValidator(max => 255)
      public $city;
       * @Label('Street')
       * @LengthValidator(max => 255)
      public $street;
       * @Label('Home number')
       * @LengthValidator(max => 255)
      public $house;
       * @Label('Apartment number')
       * @LengthValidator(max => 10)
      public $apartment;
       * @Label('Postal code')
       * @LengthValidator(max => 6)
      public $zip;

Now we can add this document to our User model from previous section:

	use Maslosoft\Mangan\Document;
    class User extends Document {

       * @Embedded('UserAddress')
      public $address = null;


And using it is as easy as π!

    $client = new Client;
    $client->address->city='New York';

This will automatically call validation for the model and all its embedded documents. You can even nest embedded documents in embedded documents and array of embbedded document, also mix any embedded document types! IMPORTANT: This mechanism uses recurrency, and will not handle circular nesting, so use this feature with care.


Simple arrays

  • Just define a property for an array, and store an array in it.
	 * @SafeValidator
	 * @var string[]
	public $addresses = [];

Arrays of embedded documents

  • Just need to add @EmbeddedArray annotation
     * @EmbeddedArray('UserAddress')
	 * @var UserAddress[]
    public $addresses = [];

So for the user, if you want them to be able to save multiple addresses, you can do this:

    $c = new Client;
    $c->addresses[0] = new ClientAddress;
    $c->save(); // will handle validation of array too

Then you can loop addresses:

    $c = Client::model()->find();
    foreach($c->addresses as $addr)
        echo $addr->city;


This is one of the things that makes this extension great. It's very easy to query for the objects you want.

    // simple find first. just like normal AR.
    $object = ModelClass::model()->find()

Now suppose you want to only retrieve users, that have a status of 1 (active). There is an object just for that, making queries easy.

	use Maslosoft\Mangan\Criteria;
    $c = new Criteria;
    $c->status('==', 1);
    $users = ModelClass::model->findAll($c);

and now $users will be an array of all users with the status key in their document set to 1. This is a good way to list only active users. What's that? You only want to show the 10 most recent activated users? Thats easy too.

    use Maslosoft\Mangan\Criteria;
    $c = new Criteria;
    $c->active('==', 1)->limit(10);

    $users = ModelClass::model->findAll($c);

It's that easy. In place of the 'equals' key, you can use any of the following operators:

- 'greater'   | >
- 'greaterEq' | >=
- 'less'      | <
- 'lessEq'    | <=
- 'notEq'     | !=, <>
- 'in'        |
- 'notIn'     |
- 'all'       |
- 'size'      |
- 'exists'    |
- 'type'      | // BSON type see mongodb docs for this
- 'notExists' |
- 'mod'       | %
- 'equals'    | ==
- 'where'     | // JavaScript operator

*NOTICE: the $or operator in newer versions of mongodb does NOT work with this extension yet. We will add it to the list above when it is fixed. Newer versions of MongoDB will work, just not the $or operator. For examples and use for how to use these operators effectively, use the MongoDB Operators Documentation here.

Here are a few more examples for using criteria:

	use Maslosoft\Mangan\Criteria;
    $criteria = new Criteria;

    // find the single user with the personal_number == 12345
    $criteria->personal_number('==', 12345);
    // OR like this:
    $criteria->personal_number = 12345;

    $user = User::model->find($criteria);

    // find all users in New York. This will search in the embedded document of UserAddress
    $criteria->address->city('==', 'New York');
    // Or
    $criteria->address->city = 'New York';
    $users = User::model()->findAll($criteria);

    // Ok now try this. Only active users, only show at most 10 users, and sort by first name, descending, and offset by 20 (pagination):
    // note the sort syntax. it must have an array value and use the => syntax.
    $criteria->status('==', 1)->limit(10)->sort(array('firstName' => Criteria::SORT_DESC))->offset(20);
    $users = User::model()->findAll($criteria);

    // A more advanced case. All users with a personal_number evenly divisible by 10, sorted by first name ascending, limit 10 users, offset by 25 users (pagination), and remove any address fields from the returned result.
    $criteria->personal_number('%', array(10, 0)) // modulo => personal_number % 10 == 0
             ->sort(array('firstName' => Criteria::SORT_ASC))
    $users = User::model()->findAll($criteria);

    // You can even use the where operator with javascript like so:
    $criteria->fieldName('where', ' expression in javascript ie: this.field > this.field2');
    // but remember that this kind of query is a bit slower than normal finds.

Regexp / SQL LIKE Replacemt

You can use native PHP Mongo driver class MongoRegex, to query:

	use Maslosoft\Mangan\Criteria;
    $criteria = new Criteria;
    // Find all records witch have first name starring on a, b and c, case insensitive search
    $criteria->first_name = new MongoRegex('/[abc].*/i');
    $clients = Client::model()->findAll($criteria);
    // see phpdoc for MongoRegex class for more examples

for reference on how to use query array see:

Creating Criteria Objects From Arrays

	use Maslosoft\Mangan\Criteria;
    // Example criteria
    $array = array(
        	// field name => operator definition
        	'FieldName1'=>array('greaterEq' => 10), // Or 'FieldName1'=>array('>=', 10)
        	'FieldName2'=>array('in' => array(1, 2, 3)),
        'sort'=>array('fieldName1' => Criteria::SORT_ASC, 'fieldName4' => Criteria::SORT_DESC),
    $criteria = new Criteria($array);
    // or
    $clients = ClientModel::model()->findAll($array);

Known bugs

  • Remember, this is not complete yet. So at this stage, it can have some
  • If you find any please let me know.
  • As said before, it does not work with the OR operators.


Contribution needed!

  • Any help would be great :)


We stand upon the shoulders of giants:

  • canni, for leading continued development, bug testing, and merging contributions.
  • tyohan, for first inspirations and the extension's concept.
  • luckysmack, for big help with testing and documentation.
  • Jose Martinez and Philippe Gaultier, for implementing and sharing GridFS support.
  • Nagy Attila Gábor, for big help with new functionality and testing.