# Ctrl Common¶

What’s inside?¶

Entity Services
- Base class for Doctrine Entity based Domain Services
- Doctrine Based Finder for Entity retrieval
- Criteria
  
  Resolve array based criteria and apply them to sets
  
  Resolver implementation that applies criteria to Doctrine QueryBuilder
Tools
- Extended Doctrine Paginator with extra features
- Symfony Commands to dump or import to and from sql files

Entity Services¶

A basic Service layer defined by a simple interface:

interface ServiceInterface
{
    public function getEntityClass();

    public function getRootAlias();

    public function assertEntityInstance($entity);

    public function getFinder();

    public function find(array $criteria = array(), array $orderBy = array());

    public function remove($idOrEntity, $failOnNotFound = false);

    public function persist($entity, $flush = true);

    public function flush();
}

Since it’s mainly designed to work with Doctrine ORM there are some methods that remind us of Doctrine concepts.

Currently only one concrete implementation is shipped. This implementation leaves one abstract function for the child to implement:

getEntityClass() which expects the FQCN to be returned.

use Ctrl\Common\EntityService;

class UserService extends AbstractDoctrineService
{
    public function getEntityClass()
    {
        return User::class;
    }
}

The find() method is a shortcut to the service’s Finder::find() method.

Finder¶

The EntityService class delegates find operations to its Finder. This is a small layer on top of Doctrine to simplify queries to the database.

The Finder parses properties and automatically creates joins recursively. As an example, let’s assume we have the following entities:

Article hasMany Comment
Comment hasOne User

If we want to find all articles with comments by a certain user, we can write this in a single criteria:

$articleFinder->find(["article.comment.user" => $user->getId()]);

// the root entity is also optional, so we could also write
$articleFinder->find(["comment.user" => $user->getId()]);

values can be passing in several different ways:

// literals
$finder->find('id = 1');

// special checks
$finder->find('id IS NULL');

// key/values
$finder->find(['id' => 1]);

// key/values with unnamed parameters
$finder->find(['id = ?' => 1]);

// key/values with named parameters
$finder->find(['id = :id' => ['id' => 1]]);

// multiple unnamed parameters
$finder->find(['id = ? and name = ?' => [1, 'john']]);

// multiple mixed parameters
$finder->find(['id = ? and name = :name' => [1, 'name' => 'john']]);

// complex conditions
$finder->find([
    'id = ? and (name = :name or email = :email)' => [
        1,
        'name' => 'john',
        'email' => 'john@doe.com'
    ]
]);

// add a relations to join and select (eager loading)
$finder->find(['id = 1', 'article.user.comments']);

Symfony Console Commands¶

Currently there are 2 commands available:

dump database
import database dump

Both only work for MySQL

Configuration¶

There is a yml file which loads up some config for symfony, like registering the commands.

To add this config, add the following file to your app/config/config.yml:

imports:
    - { resource: ../../vendor/ctrl-f5/ctrl-common/config/symfony_services.yml }

Tools¶

Helper classes for performing common tasks.

class ArrayHelper¶

collection of static helper functions for working with arrays

countValues(array $array, $caseSensitive = true)¶

A wrapper around array_count_values() that cleans the array values first, and allows to ignore string case.

class StringHelper¶

collection of static helper functions for working with strings

BRACKET_SQUARE = '[]'

BRACKET_ROUND = '()'

BRACKET_CURLY = '{}'

BRACKET_CHEVRON = '<>'

canonicalize($string, $toLowerCase = true, $allowDash = false)¶

cleans a string, leaving only alphanumeric values, and optionally allow dashes.

Parameters:	$string (string) – input string $toLowerCase (bool) – transform string to lowercase $allowDash (bool) – remove dashes
Returns:	the canonicalized string

bracesToArray($string, $braces = self::BRACKET_ROUND, $first = true)¶

explodes strings into arrays based on braces.

$string = "(my)(string(value))";
$array = StringHelper::bracesToArray($string);

// $array now contains:
[
    ["my"],
    [
        ["string"],
        [
            ["value"]
        ]
    ]
]