README

ImaticDataBundle

This bundle makes it easy to work with data.

Main goals of the bundle

Accessing data in uniform way (no matter where they are stored) and possibility to have filtering, sorting, paging capabilities with small effort.
Executing arbitrary operations (activating users, making orders in eshop...) in uniform way (no matter if the operation was executed by user from a browser, via some message queues, console or something else).

Accessing data in uniform way

This bundle uses query objects to retrieve/store data from arbitrary storage. Currently, we have drivers for doctrine dbal and doctrine orm. Other drivers can be relatively easily implemented.

All query objects have to implement QueryObjectInterface of specific driver in order to query data.

Example of querying active users using doctrine orm driver

First we need to create query of active users.

<?php

use Doctrine\ORM\EntityManager;
use Doctrine\ORM\QueryBuilder;
use Imatic\Bundle\DataBundle\Data\Driver\DoctrineORM\QueryObjectInterface;

class ActiveUsersQuery implements QueryObjectInterface
{
    public function build(EntityManager $em): QueryBuilder
    {
        return $em->getRepository(User::class)->createQueryBuilder('u')
            ->select('u')
            ->where('u.active = :active')
            ->setParameter('active', true);
    }
}

Now we can execute the query using query executor.

<?php

$queryExecutor = $container->get('Imatic\Bundle\DataBundle\Data\Driver\DoctrineORM\QueryExecutor');
/** @var User[] */
$activeUsers = $queryExecutor->execute(new ActiveUsersQuery());

Variable $activeUsers now contains objects of active users.

To learn more about query objects (how to do filtering, sorting, pagination, etc.) see query object documentation.

Executing operations

This bundle uses commands to execute operations. Command instance is passed to a command executor, which calls command handler to do the actual work.

Example of exporting all active users using command

First we need to create command handler, which will export all active users in passed format (note that used class UserExporter does not exist and its responsibility is to export passed users in given format).

<?php

use Imatic\Bundle\DataBundle\Data\Command\CommandInterface;
use Imatic\Bundle\DataBundle\Data\Command\HandlerInterface;

ExportActiveUsersHandler implements HandlerInterface
{
    private $userExporter;
    private $queryExecutor;

    public __construct(UserExporter $userExporter, QueryExecutor $queryExecutor)
    {
        $this->userExporter = $userExporter;
        $this->queryExecutor = $queryExecutor;
    }

    public function handle(CommandInterface $command)
    {
        $exportFormat = $command->getParameter('format');
        $activeUsers = $this->queryExecutor->execute(new ActiveUsersQuery());
        $this->userExporter->export($activeUsers, $exportFormat);
    }
}

Then we need to register the handler in the container.

services:
    ExportActiveUsersHandler:
        arguments:
            - '@app.user_exporter'
            - '@Imatic\Bundle\DataBundle\Data\Driver\DoctrineORM\QueryExecutor'
        tags:
            - { name: 'imatic_data.handler' }

Then we can run the command via command executor. First argument of the command is handler alias (specified when registering handler in the container), second argument is optional and specifies options passed to the handler).

<?php

use Imatic\Bundle\DataBundle\Data\Command\Command;

$commandExecutor = $container->get('Imatic\Bundle\DataBundle\Data\Command\CommandExecutor');
$commandExecutor->execute(new Command('export_active_users', ['format' => 'json']));

To learn more about commands, see command documentation.

imatic / data-bundle

Maintainers

Details