Be specific

Languages / Tools / Design patterns / …

Agile / BDD / DDD / …

« Web applications » over « Websites »

« Business rules » over « Code »

What should we do with these business rules?

Specifications

The specification pattern

“The central idea of Specification is to separate the statement of how to match a candidate, from the candidate object that it is matched against.”

A specification = a business rule

Specifications are composable

Webreader

« A book supports the web reader if it's an ePub not protected by Adobe DRM »

Sample specification

class SupportsWebReader implements Specification
{
    const FORMATS_EPUB = ['epub', 'epub 3', 'epub fixed layout'];

    public function isSatisfiedBy($book)
    {
        return in_array($book->getFormat(), self::FORMATS_EPUB)
            && $book->getProtection() !== 'adobe drm';
    }
}

« A book supports the web reader if it's an ePub not protected by Adobe DRM »

Sample specification

class SupportsWebReader implements Specification
{
    const FORMATS_EPUB = ['epub', 'epub 3', 'epub fixed layout'];

    public function isSatisfiedBy($book)
    {
        return in_array($book->getFormat(), self::FORMATS_EPUB)
            && $book->getProtection() !== 'adobe drm';
    }

    public function andX(Specification $spec)
    {
        return new AndSpecification($this, $spec);
    }
    public function orSatisfies(Specification $spec) { /* … */ }
    public function not() { /* … */ }
}

« A book supports the web reader if it's an ePub not protected by Adobe DRM »

Usage

$spec = (new SupportsWebReader())
    ->andX(new AvailableInCountry('FR'))
    ->andX((new PublisherBlacklisted())->not());

$isViewableOnline = $spec->isSatisfiedBy($book); // bool(true)

Pros …

• SOLID ;
• unit-testable.

… & cons

• could be clearer ;
• only usable on a Book instance.

Features

• data-agnostic DSL to express business rules ;
• works at the instance level ;
• works at the data-source level.

Same rule

format IN :formats_epub AND protection != "adobe drm"

« A book supports the web reader if it's an ePub not protected by Adobe DRM »

Same usage

$rule = 'format IN :formats_epub AND protection != "adobe drm"';

// use the textual rule
$isViewableOnline = $rulerz->satisfies($book, $rule, [
    'formats_epub' => ['epub', 'epub 3', 'epub fixed layout'],
]); // bool(true)

Same specification

class SupportsWebReader extends AbstractSpecification
{
    public function getRule()
    {
        return 'format IN :formats_epub AND protection != "adobe drm"';
    }

    public function getParameters()
    {
        return [
            'formats_epub' => ['epub', 'epub 3', 'epub fixed layout'],
        ];
    }
}

« A book supports the web reader if it's an ePub not protected by Adobe DRM »

Same usage

// build a specification object
$spec = (new SupportsWebReader())
    ->andX(new AvailableInCountry('FR'))
    ->andX((new PublisherBlacklisted())->not());

$isViewableOnline = $rulerz->satisfiesSpec($book, $spec); // bool(true)

Usage on a datasource

// our app uses Doctrine to query the database
$queryBuilder = $entityManager
    ->createQueryBuilder()
    ->select('book')
    ->from('Entity\Book', 'book');

// and we want to find the viewable online books
$viewableOnlineBooks = $rulerz->filterSpec($queryBuilder, $spec);

var_dump($viewableOnlineBooks); // array<Entity\Book>

Architecture

Repositories – Before

class DoctrineBookRepository implements BookRepository
{
    public function findByEan($ean) { }
    public function findByTitle($title) { }
    public function findPublished() { }
    public function findViewableOnline() { }
    public function findNotViewableOnline() { }

    public function findPublishedAndViewableOnline() { }

    // …
}

Repositories – After

class DoctrineBookRepository implements BookRepository
{
    public function matching(Specification $spec)
    {
        $qb = $this->createQueryBuilder('book');

        return $this->rulerz->satisfiesSpec($qb, $spec);
    }
}

Search forms

One field → One specification object

Wallabag

Tagging rules

Other use cases

e-commerce coupons / …