A lightweight framework that provides a standard and easy way to implement a model service layer

v0.8.1 2016-04-27 14:02 UTC



Matryoshka ----------

Latest Stable Version Build Status Coveralls branch Total Downloads Matryoshka Model's Slack

Matryoshka is not an ORM.

Matryoshka is a micro framework (< 1000 SLOC) that helps you to build your model service layer in a structured way without the need of using the complex ORM systems, avoiding overheads. Matryoshka does not provide a persistence layer implementation itself and does not require adapters: you have the full control over the persistence layer by implementing criterias. Its layered design aims to provide a strong seperation between the persistence and the rest of your application, whether the datagateway you need to use (i.e. Zend\Db, MongoCollection, a REST client or anything else). In order to simplify your job with common persistence systems, a set of wrappers are already provided as separated repositories. They are just a set of ready-to-use classes. Matryoshka uses a few of Zend Framework 2 components but does not require you to use Zend Framework: you are free to use Matryoshka with any framework. Last but not least, the Matryoshka design allows you to use just single components or all of them in cooperations. Anyway you can decide how to design your own application model: only you know what your application needs.

Read more about Matryoshka components


Integration modules:


Other addons, plugins, and modules made with Matryoshka.


For questions and support please visit the slack channel (get an invite here).

Theory of operation

Matryoshka doesn't provide a persistence layer implementation itself, but it can work with any third party implementation that acts as datagateway. Regardless of the datagateway you choose, Matryoshka provides to clients (i.e. your controller) the same set of handful API. To accomplish this goal Matryoshka uses criteria interfaces that developer have to implement.

Think a criteria as a small piece of code that tell to the datagateway how to perform an operation on your dataset: for example filter some rows. So, each criteria represent a simple task: different kind of criteria interfaces are defined for write, read and delete operations. Also, in concrete criteria classes, the developer can add methods to augment the "query interface" with domain specific logic.

A concrete criteria class acts both as a criterion defining a query interface and also as mediator between model layer and datagateway. Only criteria classes performs operations against the datagateway interface, instead Matryoshka's components do not.

So Matryoska is unawareness about the datagateway interface, that makes it working with any kind of third-party datagateway implementation.

Matryoshka dolls (layers):

  • ModelManager A dedicated service locator for your model service classes (i.e., model)

  • Model An end user service that manages a collection of related data by using criterias (similar to a table gateway or a document collection)

  • Criteria An "user query interface" from an API point of view, also acting as mediator between model and datagateway

Finally, in the empty space of the innermost doll you can put:

  • Datagateway Any kind of datagateway, like Zend\Db\TableGateway or \MongoCollection or a REST client

Basic usage example:

//Assiming MyModel an instance of a Matryoshka Model class registered in Matryoshka model manager
$myModel = $modelManager->get('MyModel');

//Assuming MyCriteria a class extending ReadableCriteriaInterface
$criteria = new MyCriteria();

//Execute a query
$resultSet = $myModel->find($criteria);


Install it using composer.

Add the following to your composer.json file:

"require": {
    "matryoshka-model/matryoshka": "~0.8.0"


  • PHP >= 5.5


Read about Matryoshka configuration here