Download the PHP package mawelous/yamop without Composer

Yamop

Yet another MongoDB ODM for PHP

• What's that?
• Requirements
• Installation
• Usage
  • getting
  • save, update, delete
  • embedded objects
  • relations
  • output format
  • pagination
  • timestamps
  • dates and time
  • transactions
  • advanced
    • multiple connections
• Issues
• License

What's that?

This is yet another, open source, and very simple ODM for MongoDB. It works like the standard MongoDB PHP extension interface but returns objects instead of arrays (as ODM). Queries stay the same. One of its coolest features are joins which allow you to query for related objects.

List of features:

• String IDs (easier linking in views)
• Embedded objects
• Related objects (performing "join like" operations)
• JSON format
• Paginator
• Timestamps (created_at and updated_at fields added on demand)
• Printing date and time
• Transactions (PHP error support only)

Requirements

• PHP 5.3+
• PHP MongoDB Extension

Installation

You can simply download it here or use Composer.

In the require key inside the composer.json file add the following

Save it and run the Composer update command

$ composer update

After Composer is done you only need to add the following lines to your code

You can pass any MongoDB instance to the setDatabase function.

Now extend Mawelous\Yamop\Model from within any of your models:

That's it!

Usage

Each object has an _id, which is a MongoId, and an id key which is its string representation.

Every document in MongoDB is returned as an object, every key is a property - here a sample document inside MongoDB

The document above would be represented in PHP as follows:

There are two possibilities to pass properties to object

After version 0.2.1 (excluding it) Yamop returns null when you try to get a property that doesn't exist.

Getting data

Want to get a document by its id? There is a simple way.

Getting one document by query is simple too. Method findOne works exactly like native findOne but it returns an object. As second parameter you can pass an array of fields. This means the parameters and queries stay the same, which is pretty great!

Introducing Mapper

There is a Mapper class in Yamop which is responsible for retrieving data. I separated it from Model so it can stay as data container. If you want to create more complicated queries you want to use the mapper. You can get it by using the getMapper method or creating new instance of it passing model class as string.

Find methods

findOne introduced before for Model is Mapper's method. Model just refers to it. You could call it like this

There is a find method that gets more then one document. It also works like native find but it returns a Mapper. You can then perform other operations on it like sort, limit, skip which all work like native as well. To get result as array of objects use get method.

findAndModify is equivalent to native findAndModify but serves objects.

Save, Update and Delete

save method is used to create and update objects. That's the code to create new object and write it to the database

You can get _id of newly created object just after save.

Deleting is simple

Those methods return the same results as the native remove and save methods. If you want to update multiple documents use the native function like here.

Extending Mapper

You can extend Mapper if you want to add more methods. For example I created UserMapper which has a method that posts a message on an user's Facebook wall. Just let Mapper know which Model class to use.

If you want to register a different Mapper for a model just declare it in the model

Now you just execute the Mapper

This will return an instance of UserMapper. You can also just create a new mapper

Count, Indexes, multi update and others

All methods called on Mapper that are not present are passed to the original MongoCollection. So you can use update, count, batchInsert, ensureIndex and even drop directly with the native methods.

Embedded objects

Do you have more objects within the current object? Yamop will convert it automatically. Just let it know.

Then it will convert object embedded in address field to Address PHP object and notifications array of objects to array of Notification PHP objects. All embedded objects can be pure models - they can only extend \Mawelous\Yamop\Model.

Related objects

If there are relations between objects (there are sometimes) and you would like to "join" them, it's simpler than you would expect, even with MongoDB. All you need is to keep the MongoId of the related object within your base object.

You don't have to register it anywhere. In my opinion it's better to do this explicit and avoid queries in background.

Here's the magic:

One

The joinOne method in every Model takes three parameters. First is the name of the property which keeps the MongoId of the related object, second is the related objects class, and third, optional, is the property name it will be joined at.

Many

The joinMany method in every Model has also three parameters. First is the name of the property which keeps an array of MongoId, second is the related objects class, and third, optional, is the property name it will be joined at.

If you want to join items to a list of items use join in a Mapper. Three parameters as in joinOne.

Output format

Default fetching mode converts arrays to objects but you can also get array or JSON with getArray and getJson. As default getArray returns array with keys holding MongoId as string. If you want to receive numeric array call it with false param getArray(false)

You can also get the native MongoCursor by calling the getCursor method.

Pagination

Yamop supports pagination with a little help from you. It has a getPaginator method which has three parameters. First is the amount of items per page, second is the current page number, and the third is a variable which you can pass to your paginator. All three are optional.

Your framework probably has its own paginator. Before you use the getPaginator method you have to implement the _createPaginator method in a mapper that extends Mawelous\Yamop\Mapper.

Laravel would be extended like this:

Timestamps

It's common to have a created_at and updated_at key in our objects. If you want to have them be set automatically for your Model, just declare it:

Printing date and time

Whether you have a timestamp or not, you might still like to print the date or time. It's recommend to keep dates as MongoDate this way you can echo it with getTime or getDate which takes two parameters. First is the MongoDate property name, second is a string that represents format passed to the PHP date function:

Mawelous\Yamop\Model has its default date format defined in the public static $dateFormat property and a time format in $timeFormat. You can override it if you like.

Transactions

EXPERIMENTAL! - It's an addition to Yamop which works independently. It doesn't support a two phase commit but at least it can revert changes.

That's what Mawelous\Yamop\Transaction is for. First you have to handle errors and run the rollback method within it.

Similar to this:

Then you can start using the add method. With add you add code to revert changes you made with save or update. You can use a closure to do that.

Here an example:

Now when error happens rollback will invoke all added methods.

Advanced

Multiple connections

It's simple to have different connections for models. setDatabase can take MongoDb or array of MongoDbs as param. Keys in array are connection names.

This is how you specify connection name in model.

If it's not specified model will use first connection.

Issues

Any issues or questions please report here

License

Yamop is free software distributed under the terms of the MIT license