Download the PHP package oasis/doctrine-addon without Composer

oasis/doctrine-addon component

Doctrine is the most popular vendor for PHP database components. The core projects under this name are a Object Relational Mapper (ORM) and the Database Abstraction Layer (DBAL) it is built upon.

The oasis/doctrine-addon component provides a few useful features to extend the doctrine/orm component:

• a trait to ease declaration of auto generated id field
• a trait/mechanism to make cache invalidating more flexible, during object removal phase

Installation

Install the latest version with command below:

AutoIdTrait

The AutoIdTrait defines an id property and the getter method getId(). It can be used in any entity class that uses id as its primary index.

Cascade Removal Solution

When cache is presented for an ORM-enabled application, cache invalidation has always been an interesting topic to deal with. One most common exception in ORM is when you try to access a collection that contains out-dated entity. This problem is commonly referred to as the cascade removal problem. An exmaple is like below:

You have a Tean entity that holds a collection of its members, which are User entities. When you remove a User entity, without proper invalidation process, accessing the Team that holds reference to this User will throw an exception.

By default, doctrine/orm provides two ways to solve this problem:

• Manual invalidation upon each removal
• Use the cascade={"remove"} annotation

However, either of the two solutions are not optimal. Needless to say, the manual removal is complex and will become a nightmare when you have a reference chain. On the other hand, using the cascade annotation is very effecient development wise, but extremely slow in performance especially when the relation map is complicated and dataset is large.

oasis/doctrine-addon introduces another solution to the cascade removal problem, by providing the CascadeRemoveTrait. Any entity that wants to utilise the CascadeRemoveTrait must:

• declare with the ORM\HasLifecycleCallbacks annotation
• implement the CascadeRemovableInterface
• use the CascadeRemoveTrait
• use database provided schema to delete strongly related entities

Implementing the CascadeRemovableInterface further requires implementation of the following two methods:

• getCascadeRemoveableEntities(), which takes no arguments and returns an array of strongly related entities
• getDirtyEntitiesOnInvalidation(), which takes no arguments and returns an array of loosely related entities

A strongly related entity is an entity that should also be removed when the current entity is removed.

A loosely related entity is an entity that holds a reference to the current entity, either directly (To-One relation) or through a collection (To-Many relation). This reference should be invalidated when the current entity is removed.

The real removal of strongly related entity is achieved by database constraint, which must be ON DELETE CASCADE.

Code Sample (very simple CMS)

Imagine we have a simple CMS that has 3 types of entities: Categroy, Article and Tag. The system must meet the following requirements:

• An Article may belong to a Category
• An Article and can have more than one Tag
• Different Articles can share Tags

Below is the implementation:

NOTE: there is always one side and only one side in a bidirectional relation, that should be accessed by the outside users. In this example, you setCategory() on an Article, and you never call addArticle() directly on a Category. To further ensure this behavior and let the IDE helps us locate potential bug, we should decalre the hidden method @internal so that every call from outside will trigger a warning.

HOMEWORK: there is only addTag() method on an Article. You can try to write your implementation of removeTag() method to futher familiarize yourself with the ORM tool.