Download the PHP package phpixie/orm without Composer

ORM

PHPixie ORM library

• ORM
  • Initializing
  • Models
    • Configuration
    • Entities
    • Queries
    • Extending Models
  • Relationships
    • Querying relationships
    • One To Many
    • One to One
    • Many To Many
  • Embedded Models in MongoDB
    • Embeds One
    • Embeds Many
  • Nested Set

Initializing

If you are using the PHPixie Framework the ORM component is already set up for you. It is accessable via $frameworkBuilder->components()->orm() and can be configured in the config/orm.php file of your bundle.

Models

A Model consists of a Repository, Queries and Entities and will usually map to a table in a relational database or a document collection in MongoDB.

• Entity - a single item, stored in the database, e.g. an article
• Repository - is used to create and save Entities
• Query - is used to select, update or delete Entities

You can start using the models right away without any configuration, which will use defaults based on the name of the model.

Configuration

By default ORM assumes that the table name is the plural of the name of the model, and that the name of the primary key is 'id'. For MongoDB database the default id field '_id' is assumed. You can override these settings for a particular model in your configuration file:

Entities

Queries

ORM queries share a lot of syntax with the Database queries, here are a few query examples:

If findOne is used, a query will return either a single item or null. When using find a Loader is returned which can be used as follows:

If you are going to access a particular relationship for multiple items that you are selecting you should preload their relationships to avoid multiple datbase queries. This is called eager loading.

Queries can also be used for updating and deleting items:

Extending Models

Extending ORM Models usually forces the developer into coupling business logic to the database, which makes them hard to test and and debug. In these cases performing any kind of testing requires inserting some dummy test data into the database. PHPixie ORM solves this problem by allowing Decorator-like behavior with Wrappers. Instead of extending a class you provide wrappers that might be used to wrap ORM Entities, Queries and Repositories and add functionality to them.

Now we have to register these classes with the ORM.

Pass an instance of this class when creating the ORM instance:

When using the PHPixie Framework, you already have the ORMWrappers class already registered and present in your bundle.

Relationships

PHPixie supports one-to-many, one-to-one, many-to-many relationships, as well as embeds-one and embeds-many for embedded models. Each relationship defines a set of properties that are added to entities and queries and can be used to access related data. You can configure them using the relationships key in the configuration file:

It is possible to define relationships between tables in same database, different databases or even between relational databases and MongoDB

Querying relationships

Before looking at actual relationship types, let's see how can you define conditions on a relationship:

One To Many

This is the most common relationship. A category can own many articles, a topic has many replies, etc.

Now that we have relationship properties defined we may start using them:

Note how using properties instead of conventional methods like addArticle, removeAllArticles tidies up your entities, and doesn't result in a heap of methods added to single class when there are multiple relationships defined

Queries also have properties, just like Entities do. This allows you to perform more operations with less calls to the database.

Using queries instead of iterating over entities provides a huge boost to your performance

It may seem like too many options at this point, but you can just stick to whichever syntax you prefer best. The generated queries stay exactly the same.

One to One

One to One relationships are very similar to One To Many. The main difference is that as soon as you attach a new item to an owner, the previous item gets detached. A good example of this would be a relationship between an auction lot and the highest bidder. As soon as we set a new person as the highest bidder the old one is unset. Another example wold be tasks and workers. Where each task can be performed by a single worker.

The interface in oneToOne relationships is the same on both sides and is identical to the owner property in oneToMany relationships

Many To Many

The most common many-to-many relationship is between articles and tags. These relationships require a special pivot table (or a MongoDB collection) to store the links between items.

Using a many-to-many relationship is simiar to using the owner side of a one-to-many one.

Using queries for bulk operations here makes it possible to assign and remove relationships with a single database call

A lot of work went into optimizing these query operations, and at the moment no other PHP ORM supports editing relationships between queries. Instead of requiring m*n queries to edit many-to-many relationships, the query approach can achieve it in one go.

Embedded Models in MongoDB

MongoDB supports nested documents, which allows using embedded models. E.g. the author of an article:

Embedded models consist only of Entities and have neither Repositories nor Queries. Subdocuments and subarrays are not automatically registered as embedded relationships, you have to do it inside your configuration:

There are also some usage differences between embedded and database models:

Embeds One

This is a relationship with a subdocument like the above article author example.

Note how we don't define the property for accessing the article from the author. This is because accessing the owner is always done using $entity->owner() for embedded entities.

Embeds Many

Defines a relationship with an embedded array of subdocuments. E.g. forum topic replies:

Nested Set

Nested Set is an efficient approach to storing trees in SQL databases. A good example would be storing category and comment trees. PHPixie is the only PHP framework to optimize it even further by namespacing subtrees which results in much faster inserts and updates to the tree. The code behind it is more complex than the usual Nested Set implementation, but is really simple from the user perspective.

This relationship defines four relationship properties instead of the usual two. The children property refers to immediate children, while allChildren represents all children of a node. In the same way parent is the immediate parent and allParents relates to all parents of the node.

The basic usage is straightforward an similar to the one-to-many relationship.

Some more advanced usage:

Special caution has to made when deleting nodes. PHPixie will only allow you to delete items if they either don't have any children or their children are also being deleted. For example:

The important part is to remember that parent and children refer only to the immediate parent an children, while allParents and allChildren refer to all related nodes recursively.