caseyamcl / mongorecord
Customized clone of the original MongoRecord library (https://github.com/lunaru/MongoRecord)
Requires
- php: >=5.3.0
This package is auto-updated.
Last update: 2019-04-11 18:06:31 UTC
README
MongoActiveRecord is a PHP Mongo Active Record Pattern ORM layer built on top of the PHP Mongo PECL extension
MongoActiveRecord is a fork of the “MongoRecord Tool”http://github.com/###/MongoRecord, which was an extraction from online classifieds site Oodle. Oodle’s requirements for a manageable, easy to understand interface for dealing with the super-scalable Mongo datastore was the primary reason for MongoRecord. It was developed to use with PHP applications looking to add Mongo’s scaling capabilities while dealing with a nice abstraction layer.
This fork differs from the original in that it requires that you explicitely declare the properties for your objects. This allows you to define the data structure in your application, and be able to easily see exactly what properties each record in each collection contains simply by looking at the source of your MongoRecord classes.
Features
- Collection names by convention
- Attributes by convention
- Validations
- Callbacks
- Sorting, offsets, limits
Requirements
- PHP 5.3+
- Mongo PECL
Installation
Extract the source files into a directory in your PHP library path.
Usage
Basic
Using MongoRecord is as simple as declaring classes that are extensions of the base ORM class, and adding private
or protected
properties for attributes you wish to have.
class Person extends BaseMongoRecord { protected $firstName;
protected $lastName; }
// initialize connection and database name BaseMongoRecord::$connection = new Mongo(); BaseMongoRecord::$database = 'myapp';
This gives Person
basic CRUD methods: save()
, destroy()
, findOne()
, and find()
.
Every class automatically gets mapped to a Mongo collection by convention.
E.g.Person
→ people
MyClass
→ my_classes
It is possible to set collection name manualy for child class.
You can do it by overriding class name as in example.
class PersonClassNameIsTooComplicated extends BaseMongoRecord { protected static $collectionName = 'person'; }
Creating and Fetching
New records can be created by instantiating and saving:
$person = new Person(); $person->save(); // true or false depending on success
$person = Person::findOne(); $person->destroy();
You can also add options to how you want to find.
// find the first Person sorted by name, starting from the tenth Person::find(array(), array('sort' => array('name' => 1), 'offset' => 10, 'limit' => 1));
Attributes
Attributes can be set several different ways:
In bulk on the constructor:
$person = new Person(array('name' => 'Bob', 'description' => 'foobar'));
One-by-One:
pre.. $person->age = 25; $pseron->gender = 'Male';
Chained:
pre.. $person->setAge(25)->setGender("Male"); $person->save(); // returns true or false Person::find(array('name' => 'Bob', 'gender' => 'Male')); // finds all male Bobs in the people collection.
Validations
Validations can be added based on the name of the attribute
class Person extends BaseMongoRecord { public function validatesName($name) { if ($name == 'Bob') return false; else return true; } }
$person = new Person(); $person->setName("Bob"); $person->save(); // fails!
Callbacks
Callbacks can be added for the following events:
- beforeSave()
- afterSave()
- beforeValidation()
- afterValidation()
- beforeDestroy()
- afterNew()
In a new, save, destroy cycle, the validations are called in the following order:
afterNew -> beforeValidation -> afterValidation -> beforeSave -> afterSave -> beforeDestroy
class Person extends BaseMongoRecord { public function beforeSave() { if ($this->getName() == 'Bob') $this->setName('Bill'); } }
Differences between MongoRecord 1.x and 2.x
In 2.x the find()
method is lazy and returns a MongoRecordIterator
instead of a MongoRecord
. The Iterator can be treated like an array
and implements the PHP Iterator
and Countable
interfaces.
Because of this, 2.x is not backwards compatible with 1.x, since the result of find()
is not guaranteed to behave the same. (e.g. $results[3] does not work with @find()
in 2.×.) You may use findAll()
instead, which exhibits the same behavior as find()
in 1.×.
Credits
Thanks to Rasmus for the suggestion for lazy find().