README

Doctrine ORM compilation target for RulerZ.

Usage

Doctrine ORM is one of the targets supported by RulerZ.

This cookbook will show you how to retrieve objects using Doctrine and RulerZ.

Here is a summary of what you will have to do:

configure Doctrine ORM;
configure RulerZ;
filter your target.

Configure Doctrine ORM

This subject won't be directly treated here. You can either follow the official documentation or use a bundle/module/whatever the framework you're using promotes.

Configure RulerZ

Once Doctrine is installed and configured we can the RulerZ engine:

$rulerz = new RulerZ(
    $compiler, [
        new \RulerZ\DoctrineORM\Target\DoctrineORM(), // this line is Doctrine-specific
        // other compilation targets...
    ]
);

The only Doctrine-related configuration is the DoctrineQueryBuilder target being added to the list of the known compilation targets.

Filter your target

Now that both Doctrine and RulerZ are ready, you can use them to retrieve data.

The DoctrineQueryBuilder instance that we previously injected into the RulerZ engine only knows how to use QueryBuilders so the first step is to create one:

$playersQueryBuilder = $entityManager
    ->createQueryBuilder()
    ->select('p')
    ->from(Entity\Player::class, 'p');

And as usual, we call RulerZ with our target (the QueryBuilder object) and our rule. RulerZ will build the right executor for the given target and use it to filter the data, or in our case to retrieve data from a database.

$rule  = 'gender = :gender and points > :points';
$parameters = [
    'points' => 30,
    'gender' => 'M',
];

var_dump($rulerz->filter($playersQueryBuilder, $rule, $parameters));

Handling joins

More often that not, your entities will have relationships with other entities in your application.

Let's imagine that our Entity\Player entity has a 1-1 association with a Entity\Group entity and that we want to retrieve all the players that are in a group having the role ROLE_ADMIN.

There are two ways to write rules using that association. In the first one, we let RulerZ automatically determine how to join the entities:

$playersQueryBuilder = $entityManager
    ->createQueryBuilder()
    ->select('p')
    ->from(Entity\Player::class, 'p');

$rule = '"ROLE_ADMIN" IN group.roles';

var_dump(
    iterator_to_array($rulerz->filter($playersQueryBuilder, $rule))
);

It's important to notice that group is not an ordinary attribute: it's another entity, joined by RulerZ.

N.B: RulerZ will call the join() method on the query builder, so it will perform INNER joins by default.

If you need more control on how the joins are handled, we can prepare the query builder and join the entities you need ourselves:

$playersQueryBuilder = $entityManager
    ->createQueryBuilder()
    ->select('p')
    ->from('Entity\Player', 'p')
    ->innerJoin('Entity\Group', 'g');

$rule = '"ROLE_ADMIN" IN g.roles';

var_dump(
    iterator_to_array($rulerz->filter($playersQueryBuilder, $rule))
);

This time, RulerZ is smart enough to understand that g might be a joined entity and that it should not try to join it itself.

License

This library is under the MIT license.

rulerz-php / doctrine-orm

Maintainers

Details