openclassrooms/use-case

Use case library

UseCase

, _(*1)

UseCase is a library that provides facilities to manage technical code over a Use Case in a Clean / Hexagonal / Use Case Architecture. - Security access - Cache management - Transactional context - Events - Logs, _(*2)

The goal is to have only functional code on the Use Case and manage technical code in an elegant way using annotations., _(*3)

More details on : - Clean Architecture. - Hexagonal Architecture. - Use Case Driven Development., _(*4)

Installation

composer require openclassrooms/use-case or by adding the package to the composer.json file directly., _(*5)

{
    "require": {
        "openclassrooms/use-case": "*"
    }
}

```php, <sub>(*6)</sub>

<?php require 'vendor/autoload.php';, <sub>(*7)</sub>

use OpenClassrooms\UseCase\Application\Services\Proxy\UseCases\UseCaseProxy;, <sub>(*8)</sub>

//do things, <sub>(*9)</sub>

<a name="install-nocomposer"/>

### Instantiation
The UseCaseProxy needs a lot of dependencies. 

The Dependency Injection Pattern is clearly helpful.

For an implementation with Symfony2, the UseCaseBundle is more appropriate.

UseCaseProxy can be instantiate as following:
```php

class app()
{
    /**
     * @var OpenClassrooms\UseCase\Application\Services\Proxy\UseCases\UseCaseProxyBuilder
     */
    private $builder;   

    /**
     * @var OpenClassrooms\UseCase\Application\Services\Security\Security;
     */
    private $security;

    /**
     * @var OpenClassrooms\Cache\Cache\Cache; 
     */
    private $cache;

    /**
     * @var OpenClassrooms\UseCase\Application\Services\Transaction\Transaction;
     */
    private $transaction;

    /**
     * @var OpenClassrooms\UseCase\Application\Services\EventSender\EventSender;
     */
    private $event;

    /**
     * @var OpenClassrooms\UseCase\Application\Services\EventSender\EventFactory
     */
    private $eventFactory;

    /**
     * @var Psr\Log\LoggerInterface
     */
     private $logger;

    /**
     * @var Doctrine\Common\Annotations\Reader
     */
    private $reader;

    public function method()
    {
        $useCase = $this->builder
                    ->create(new OriginalUseCase())
                    ->withReader($this->reader)
                    ->withSecurity($this->security)
                    ->withCache($this->cache)
                    ->withTransaction($this->transaction)
                    ->withEventSender($this->event)
                    ->withEventFactory($this->eventFactory)
                    ->withLogger($this->logger)
                    ->build();
    }                    
}                

Only UseCaseProxyBuilder::create(UseCase $useCase) and UseCaseProxyBuilder::withReader(AnnotationReader $reader) are mandatory., <sub>(*10)</sub>

Usage

A classic Use Case in Clean / Hexagonal / Use Case Architecture style looks like this:, <sub>(*11)</sub>

use OpenClassrooms\UseCase\BusinessRules\Requestors\UseCase;
use OpenClassrooms\UseCase\BusinessRules\Requestors\UseCaseRequest;
use OpenClassrooms\UseCase\BusinessRules\Responders\UseCaseResponse;

class AUseCase implements UseCase
{
    /**
     * @return UseCaseResponse
     */
    public function execute(UseCaseRequest $useCaseRequest)
    {
        // do things

        return $useCaseResponse;
    }
}

The library provides a Proxy of the UseCase., <sub>(*12)</sub>

Security

@Security annotation allows to check access., <sub>(*13)</sub>

use OpenClassrooms\UseCase\BusinessRules\Requestors\UseCase;
use OpenClassrooms\UseCase\BusinessRules\Requestors\UseCaseRequest;
use OpenClassrooms\UseCase\BusinessRules\Responders\UseCaseResponse;
use OpenClassrooms\UseCase\Application\Annotations\Security;

class AUseCase implements UseCase
{
    /**
     * @Security (roles = "ROLE_1")
     *
     * @return UseCaseResponse
     */
    public function execute(UseCaseRequest $useCaseRequest)
    {
        // do things

        return $useCaseResponse;
    }
}

"roles" is mandatory., <sub>(*14)</sub>

Other options :, <sub>(*15)</sub>

/**
 * @Security (roles = "ROLE_1, ROLE_2")
 * Check the array of roles
 *
 * @Security (roles = "ROLE_1", checkRequest = true)
 * Check access for the object $useCaseRequest
 *
 * @Security (roles = "ROLE_1", checkField = "fieldName")
 * Check access for the field "fieldName" of the object $useCaseRequest
 */

Cache

@Cache annotation allows to manage cache., <sub>(*16)</sub>

use OpenClassrooms\UseCase\BusinessRules\Requestors\UseCase;
use OpenClassrooms\UseCase\BusinessRules\Requestors\UseCaseRequest;
use OpenClassrooms\UseCase\BusinessRules\Responders\UseCaseResponse;
use OpenClassrooms\UseCase\Application\Annotations\Cache;

class AUseCase implements UseCase
{
    /**
     * @Cache
     *
     * @return UseCaseResponse
     */
    public function execute(UseCaseRequest $useCaseRequest)
    {
        // do things

        return $useCaseResponse;
    }
}

The key is equal to : md5(serialize($useCaseRequest)) and the TTL is the default one., <sub>(*17)</sub>

Other options:, <sub>(*18)</sub>

/**
 * @Cache (lifetime=1000)
 * Add a TTL of 1000 seconds
 *
 * @Cache (namespacePrefix="namespace_prefix")
 * Add a namespace to the id with a namespace id equals to "namespace_prefix" 
 *
 * @Cache (namespacePrefix="namespace prefix", namespaceAttribute="fieldName")
 * Add a namespace to the id with a namespace id equals to "namespace_prefix" . "$useCaseRequest->fieldName"
 */

Transaction

@Transaction annotation gives a transactional context around the Use Case. - begin transaction - execute() - commit - rollback on exception, <sub>(*19)</sub>

use OpenClassrooms\UseCase\BusinessRules\Requestors\UseCase;
use OpenClassrooms\UseCase\BusinessRules\Requestors\UseCaseRequest;
use OpenClassrooms\UseCase\BusinessRules\Responders\UseCaseResponse;
use OpenClassrooms\UseCase\Application\Annotations\Transaction;

class AUseCase implements UseCase
{
    /**
     * @Transaction
     *
     * @return UseCaseResponse
     */
    public function execute(UseCaseRequest $useCaseRequest)
    {
        // do things

        return $useCaseResponse;
    }
}

Event

@Event annotation allows to send events., <sub>(*20)</sub>

An implementation of OpenClassrooms\UseCase\Application\Services\EventSender\EventFactory must be written in the application context., <sub>(*21)</sub>

use OpenClassrooms\UseCase\BusinessRules\Requestors\UseCase;
use OpenClassrooms\UseCase\BusinessRules\Requestors\UseCaseRequest;
use OpenClassrooms\UseCase\BusinessRules\Responders\UseCaseResponse;
use OpenClassrooms\UseCase\Application\Annotations\EventSender;

class AUseCase implements UseCase
{
    /**
     * @Event
     *
     * @return UseCaseResponse
     */
    public function execute(UseCaseRequest $useCaseRequest)
    {
        // do things

        return $useCaseResponse;
    }
}

The message can be send: - pre execute - post execute - on exception or all of them., <sub>(*22)</sub>

Post is default., <sub>(*23)</sub>

The name of the event is the name of the use case with underscore, prefixed by the method. For previous example, the name would be : use_case.post.a_use_case, <sub>(*24)</sub>

Prefixes can be : - use_case.pre. - use_case.post. - use_case.exception., <sub>(*25)</sub>

/**
 * @Event(name="event_name")
 * Send an event with event name equals to *prefix*.event_name
 * (note: the name is always converted to underscore)
 *
 * @Event(methods="pre")
 * Send an event before the call of UseCase->execute()
 *
 * @Event(methods="pre, post, onException")
 * Send an event before the call of UseCase->execute(), after the call of UseCase->execute() or on exception
 * 
 * @Event(name="first_event")
 * @Event(name="second_event")
 * Send two events
 */

Log

@Log annotation allows to add log following the PSR standard., <sub>(*26)</sub>

use OpenClassrooms\UseCase\BusinessRules\Requestors\UseCase;
use OpenClassrooms\UseCase\BusinessRules\Requestors\UseCaseRequest;
use OpenClassrooms\UseCase\BusinessRules\Responders\UseCaseResponse;
use OpenClassrooms\UseCase\Application\Annotations\Log;

class AUseCase implements UseCase
{
    /**
     * @Log
     *
     * @return UseCaseResponse
     */
    public function execute(UseCaseRequest $useCaseRequest)
    {
        // do things

        return $useCaseResponse;
    }
}

The log can be: - pre execute - post execute - on exception or all of them., <sub>(*27)</sub>

On exception is default., <sub>(*28)</sub>

Level can be specified following PSR's levels. Warning is default., <sub>(*29)</sub>

/**
 * @Log(level="error")
 * Log with the level 'error'
 * 
 * @Log (message="message with context {foo}", context={"foo":"bar"})
 * Log with standard message
 *
 * @Log(methods="pre")
 * Log before the call of UseCase->execute()
 *
 * @Log(methods="pre, post, onException")
 * Log before the call of UseCase->execute(), after the call of UseCase->execute() or on exception
 * 
 * @Log(methods="pre", level="debug")
 * @Log(methods="onException", level="error")
 * Log before the call of UseCase->execute() with debug level and on exception with error level
 */

Workflow

The execution order is the following:, <sub>(*30)</sub>

Pre Excecute: - log (pre) - security - cache (fetch) - transaction (begin transaction) - event (pre), <sub>(*31)</sub>

Post Excecute: - cache (save if needed) - transaction (commit) - event (post) - log (post), <sub>(*32)</sub>

On Exception: - log (on exception) - transaction (rollback) - event (on exception), <sub>(*33)</sub>

Utils

The library provide a generic response for paginated collection., <sub>(*34)</sub>