clean architecture core php Download - clean architecture core php Source code download

Core Library for Clean Architecture in PHP

Introduction

This documentation guides you through the utilization of the core library for implementing clean architecture in PHP. We'll explore the creation of custom application requests and use cases, paying special attention to handling missing and unauthorized fields.

Practical examples are provided using code snippets to showcase the library's usage in building a modular and clean PHP application.

Prerequisites

Ensure that you have the following:

PHP installed on your machine (version 8.2.0 or higher).
Composer installed for dependency management.

Installation

To install the core library, run the following command in your project directory:

composer require ug-php/clean-architecture-core

Core Overview

Application Request

Request serve as input objects, encapsulating data from your HTTP controller. In the core library, use the UrichyCoreRequestRequest class as the foundation for creating custom application request objects. Define the expected fields using the requestPossibleFields property.

<?php

declare(strict_types=1);

use UrichyCoreRequestRequest;
use UrichyCoreRequestRequestInterface;
use AssertAssert;

final class PatientRecordRequest extends Request
{
    protected static array $requestPossibleFields = [
        'patient_name' => true, // required parameter
        'old' => true, // required parameter
        'medical_history' => [
            'allergies' => false, // optional parameter
            'current_medications' => true, // required nested parameter
            'past_surgeries' => [
                'surgery_name' => true, // required nested parameter
                'surgery_date' => true, // required nested parameter
            ],
        ],
    ];

    protected static function applyConstraintsOnRequestFields(array $requestData): void
    {
        Assert::that($requestData['patient_name'], '[patient_name] must not be an empty string.')->notEmpty()->string();
        Assert::that($requestData['old'], '[old] must be an integer.')->integer()->greaterThan(0);
        Assert::that($requestData['medical_history']['current_medications'], '[current_medications] must not be an empty string.')->notEmpty()->string();
        Assert::that($requestData['medical_history']['past_surgeries']['surgery_name'], '[surgery_name] must not be an empty string.')->notEmpty()->string();
        Assert::that($requestData['medical_history']['past_surgeries']['surgery_date'], '[surgery_date] must be a valid date.')->date();

        // Optional field constraint
        if (isset($requestData['medical_history']['allergies'])) {
            Assert::that($requestData['medical_history']['allergies'], '[allergies] must be a string.')->string();
        }
    }
}

Handling unauthorized fields:

<?php

declare(strict_types=1);

try {
    PatientRecordRequest::createFromPayload([
        'patient_name' => 'Jane Doe',
        'old' => 45,
        'medical_history' => [
            'current_medications' => 'aspirin',
            'past_surgeries' => [
                'surgery_name' => 'Appendectomy',
                'surgery_date' => '2022-01-01',
            ],
            'extra_field' => 'unexpected',
        ],
    ]);
} catch (BadRequestContentException $exception) {
    // Handle unauthorized fields
    dd($exception->getErrors()); // ["medical_history.extra_field"]
}

Handling missing fields:

<?php

declare(strict_types=1);

try {
    PatientRecordRequest::createFromPayload([
        'patient_name' => 'Jane Doe',
        'medical_history' => [
            'current_medications' => 'aspirin',
            'past_surgeries' => [
                'surgery_name' => 'Appendectomy',
            ],
        ],
    ]);
} catch (BadRequestContentException $exception) {
    // Handle missing fields
    dd($exception->getErrors()); // ["old" => "required", "medical_history.past_surgeries.surgery_date" => "required"]
}

When request successfully created.

<?php

declare(strict_types=1);

$request = PatientRecordRequest::createFromPayload([
    'patient_name' => 'Jane Doe',
    'old' => 45,
    'medical_history' => [
        'current_medications' => 'aspirin',
        'past_surgeries' => [
            'surgery_name' => 'Appendectomy',
            'surgery_date' => '2022-01-01',
        ],
    ],
]);

dd($request->getRequestId()); // 6d326314-f527-483c-80df-7c157acdb95b
dd([
    'patient_name' => $request->get('patient_name'), 
    'current_medications' => $request->get('medical_history.current_medications'),
    'unknown' => $request->get('unknown', 'default_value'),
]); // ['patient_name' => 'Jane Doe', 'current_medications' => 'aspirin', 'unknown' => 'default_value']

dd($request->toArray());
/*
[
    'patient_name' => 'Jane Doe',
    'old' => 45,
    'medical_history' => [
        'current_medications' => 'aspirin',
        'past_surgeries' => [
            'surgery_name' => 'Appendectomy',
            'surgery_date' => '2022-01-01',
        ],
    ],
]*/

Presenter

Presenter handle the output logic of your use case. Extend UrichyCorePresenterPresenter and implement UrichyCorePresenterPresenterInterface.

<?php

declare(strict_types=1);

use UrichyCorePresenterPresenter;
use UrichyCorePresenterPresenterInterface;
use UrichyCoreResponseResponseInterface;

final class ArrayResponsePresenter extends Presenter
{
    public function getResponse(): array
    {
        return $this->response->output();
    }
}

Response

Response encapsulate the data returned by use cases. They include status information, messages, and any relevant data. Use UrichyCoreResponseResponse to create use case responses.

<?php

declare(strict_types=1);

use UrichyCoreResponseResponse;

// success response
$response = Response::create(
    success: true,
    statusCode: StatusCode::OK->value,
    message: 'success.response',
    data: [
        'user_id' => '6d326314-f527-483c-80df-7c157acdb95b',
    ]
)

// or failed response
$response = Response::create(
    success: false,
    statusCode: StatusCode::NOT_FOUND->value,
    message: 'failed.response',
    data: [
        'field' => 'value',
    ]
)

dd($response->isSuccess()); // true or false
dd($response->getStatusCode()); // 200 or 404
dd($response->getMessage()); // 'success.response' or 'failed.response'
dd($response->getData()); // ['field' => 'value'] or ['user_id' => '6d326314-f527-483c-80df-7c157acdb95b']
dd($response->get('field')); // 'value'
dd($response->get('unknown_field')); // null

Use Case

Use cases encapsulate business logic and orchestrate the flow of data between requests, entities, and presenters. Extend the UrichyCoreUsecaseUsecase class and implement UrichyCoreUsecaseUsecaseInterface with the execute method.

@see example below

Exception

When an exception is thrown during processing, you can use some method to handle the exception data.

How to create an exception ?

Create an exception class that extends UrichyCoreExceptionException

<?php

declare(strict_types=1);

use UrichyCoreExceptionException;

final class BadRequestContentException extends Exception
{
}

final class UserNotFoundException extends Exception
{
}

Throw an exception when something has gone wrong and handling it.

<?php

declare(strict_types=1);

use UrichyCoreExceptionException;
use UrichyCoreExceptionBadRequestContentException;
use UrichyCoreExceptionUserNotFoundException;

try {
    //...
    throw new BadRequestContentException([
        'message' => 'bad.request.content',
        'details' => [
            'email' => [
                '[email] field is required.',
                '[email] must be a valid email.',
            ]
        ] // array with error contexts
    ]);
    // or
    throw new UserNotFoundException([
        'message' => 'user.not.found',
        'details'  => [
            'error' => 'User with [ulrich] username not found.'
        ] // array with error contexts
    ]);
} catch(ExceptionInterface $exception) {
    // for exception, some method are available
    dd($exception->getErrors()); // print details
    [
        'details' => [
            'email' => [
                '[email] field is required.',
                '[email] must be a valid email.',
            ]
        ],
    ]
    // or
    [
        'details' => [
            'error' => 'User with [ulrich] username not found.',
        ],
    ]

    dd($exception->getDetails()); // print error details
    [
        'email' => [
            '[email] field is required.',
            '[email] must be a valid email.',
        ]
    ]

    // or 

    [
        'error' => 'User with [ulrich] username not found.',
    ],

    dd($exception->getMessage()) // 'error.message'
    dd($exception->getDetailsMessage()) // 'User with [ulrich] username not found.', only if 'error' key is defined in details.

    dd($exception->getErrorsForLog()) // print error with more context
    [
        'message' => $this->getMessage(),
        'code' => $this->getCode(),
        'errors' => $this->errors,
        'file' => $this->getFile(),
        'line' => $this->getLine(),
        'previous' => $this->getPrevious(),
        'trace_as_array' => $this->getTrace(),
        'trace_as_string' => $this->getTraceAsString(),
    ]

    dd($exception->format());
    [
        'status' => 'success' or 'error',
        'error_code' => 400,
        'message' => 'throw.error',
        'details' => [
            'email' => [
                '[email] field is required.',
                '[email] must be a valid email.',
            ],
            'lastname' => [
                '[lastname] field is required.',
            ]
        ],
    ]
}

Example Usage

From Scratch (PHP Without a Framework)

Project Structure

├── src
│   ├── Controller
│   │   └── BookController.php
│   ├── Request
│   │   └── BookRecordRequest.php
│   ├── Presenter
│   │   └── JsonResponsePresenter.php
│   ├── UseCase
│   │   └── RegisterBookUsecase.php
│   └── Response
│       └── Response.php
├── public
│   └── index.php
└── composer.json

Code Examples

`public/index.php`

<?php

declare(strict_types=1);

require '../vendor/autoload.php';

use AppControllerBookController;
use SymfonyComponentHttpFoundationRequest;

$request = Request::createFromGlobals();
$controller = new BookController();
$response = $controller->registerBook($request);
$response->send();

`src/Controller/BookController.php`

<?php

declare(strict_types=1);

namespace AppController;

use AppRequestBookRecordRequest;
use AppPresenterJsonResponsePresenter;
use AppUseCaseRegisterBookUsecase;
use SymfonyComponentHttpFoundationRequest as SymfonyRequest;
use SymfonyComponentHttpFoundationJsonResponse;

final class BookController
{
    public function registerBook(SymfonyRequest $request): JsonResponse
    {
        $bookRequest = BookRecordRequest::createFromPayload([
            'title' => $request->get('title'),
            'publication' => [
                'date' => $request->get('published_date'),
                'publisher' => $request->get('publisher'),
            ],
            'isbn' => $request->get('isbn'),
        ]);

        // you can also use $request->toArray() (in createFromPayload method) to get request payload if POST request

        $presenter = new JsonResponsePresenter();
        $useCase = new RegisterBookUsecase();
        $useCase
            ->withRequest($bookRequest)
            ->withPresenter($presenter)
            ->execute();

        return $presenter->getResponse();
    }
}

`src/Request/BookRecordRequest.php`

Using `beberlei/assert` validation library

<?php

declare(strict_types=1);

namespace AppRequest;

use UrichyCoreRequestRequest;
use UrichyCoreRequestRequestInterface;
use AssertAssert;

// interface is optional. You can directly use the implementation
interface BookRecordRequestInterface extends RequestInterface {}

final class BookRecordRequest extends Request implements BookRecordRequestInterface
{
    protected static array $requestPossibleFields = [
        'title' => true, // required parameters
        'publication' => [
            'date' => true,
            'publisher' => false, // optional parameters
        ],
        'isbn' => true,
    ];

    /**
     * @param array<string, mixed> $requestData
     * @return void
     */
    protected static function applyConstraintsOnRequestFields(array $requestData): void
    {
        Assert::that($requestData['title'], '[title] must not be an empty string.')->notEmpty()->string();
        Assert::that($requestData['publication']['date'], '[date] must be a valid date.')->date();
        Assert::that($requestData['isbn'], '[isbn] must not be an empty string.')->notEmpty()->string();
        if (isset($requestData['publication']['publisher'])) {
            Assert::that($requestData['publication']['publisher'], '[publisher] must be a string.')->string();
        }
    }
}

Using `Symfony Validator` library

<?php

declare(strict_types=1);

namespace AppRequest;

use UrichyCoreRequestRequest;
use UrichyCoreRequestRequestInterface;
use SymfonyComponentValidatorValidation;
use SymfonyComponentValidatorConstraints as SymfonyAssert;
use SymfonyComponentValidatorConstraintViolationListInterface;

// interface is optional. You can directly use the implementation
interface BookRecordRequestInterface extends RequestInterface {}

final class BookRecordRequest extends Request implements BookRecordRequestInterface
{
    protected static array $requestPossibleFields = [
        'title' => true,
        'publication' => [
            'date' => true,
            'publisher' => false,
        ],
        'isbn' => true,
    ];

    /**
     * @param array<string, mixed> $requestData
     * @return void
     */
    protected static function applyConstraintsOnRequestFields(array $requestData): void
    {
        $validator = Validation::createValidator();
        $constraints = [
            'title' => [
                new SymfonyAssertNotBlank(message: '[title] cannot be blank'),
                new SymfonyAssertType(type: 'string', message: '[title] must be a string'),
            ],
            'publication' => new SymfonyAssertCollection([
                'date' => [
                    new SymfonyAssertNotBlank(message: '[date] cannot be blank'),
                    new SymfonyAssertDate(message: '[date] must be a valid date'),
                ]
            ]),
            'isbn' => [
                new SymfonyAssertNotBlank(message: '[isbn] cannot be blank'),
                new SymfonyAssertType(type: 'string', message: '[isbn] must be a string'),
            ],
        ];

        if (isset($requestData['publication']['publisher'])) {
            $constraints['publication']['publisher'] = [
                new SymfonyAssertType(type: 'string', message: '[publisher] must be a string'),
            ];
        }

        $violations = $validator->validate($requestData, new SymfonyAssertCollection($constraints));

        self::throwViolationsWhenErrors($violations);
    }

    private static function throwViolationsWhenErrors(ConstraintViolationListInterface $violations): void
    {
        $errors = [];
        foreach ($violations as $violation) {
            $propertyPath = $violation->getPropertyPath();
            $errors[$propertyPath][] = $violation->getMessage();
        }

        if (!empty($errors)) {
            $errors['message'] = 'invalid.request.field';
            throw new BadRequestContentException($errors);
        }
    }
}

`src/Presenter/JsonResponsePresenter.php`

<?php

declare(strict_types=1);

namespace AppPresenter;

use UrichyCorePresenterPresenter;
use UrichyCorePresenterPresenterInterface;
use SymfonyComponentHttpFoundationJsonResponse;

final class JsonResponsePresenter extends Presenter implements PresenterInterface
{
    public function getResponse(): JsonResponse
    {
        $responseData = $this->response->output();
        return new JsonResponse($responseData, $responseData['code']);
    }
}

`src/Presenter/HtmlResponsePresenter.php`

<?php

declare(strict_types=1);

namespace AppPresenter;

use UrichyCorePresenterPresenter;
use UrichyCorePresenterPresenterInterface;
use SymfonyComponentHttpFoundationResponse;

final class HtmlResponsePresenter extends Presenter implements PresenterInterface
{
    public function getResponse(): Response
    {
        $responseData = $this->response->output();
        $htmlContent = "<html><body><h1>{$responseData['message']}</h1><p>" . json_encode($responseData['data']) . "</p></body></html>";
        return new Response($htmlContent, $responseData['code']);
    }
}

`src/UseCase/RegisterBookUsecase.php`

<?php

declare(strict_types=1);

namespace AppUseCase;

use UrichyCoreUsecaseUsecase;
use UrichyCoreUsecaseUsecaseInterface;
use UrichyCoreResponseResponse;
use UrichyCoreResponseStatusCode;

interface RegisterBookUsecaseInterface extends UsecaseInterface {}

final class RegisterBookUsecase extends Usecase implements RegisterBookUsecaseInterface
{
    public function __construct(
        // inject your dependencies here (always use dependencie interface, not implementation)
        private BookRepositoryInterface $bookRepository
    ) {}

    public function execute(): void
    {
        $requestData = $this->getRequestData();
        $requestId = $this->getRequestId();

        $book = [
            'title' => $this->getField('title'),
            'author' => $this->getField('publication.publisher'),
            'publication_date' => $this->getField('publication.date'),
            'isbn' => $this->getField('isbn'),
        ];

        // process your business logic here
        try {
            $this->bookRepository->save(Book::from($book))
        } catch (PersistenceException $e) {
            // handle persistence exception here or log it or send failed response.
        }

        $this->presentResponse(Response::create(
            success: true,
            statusCode: StatusCode::OK->value,
            message: 'book.registered.successfully.',
            data: $book
        ));
    }
}

`src/Response/Response.php`

<?php

declare(strict_types=1);

namespace AppResponse;

use UrichyCoreResponseResponse as LibResponse;
use UrichyCoreResponseStatusCode;

abstract class Response extends LibResponse
{
    public static function createSuccessResponse(array $data, StatusCode $statusCode, ?string $message = null): self
    {
        return new self(true, $statusCode->value, $message, $data);
    }

    public static function createFailedResponse(array $errors = [], StatusCode $statusCode, ?string $message = null): self
    {
        return new self(false, $statusCode->value, $message, $errors);
    }
}

Example with Symfony

Project Structure

├── src
│   ├── Controller
│   │   └── BookController.php
│   ├── Request
│   │   └── BookRecordRequest.php
│   ├── Presenter
│   │   └── JsonResponsePresenter.php
|   |   └── HtmlResponsePresenter.php
│   ├── UseCase
│   │   └── RegisterBookUsecase.php
│   └── Response
│       └── Response.php
├── public
│   └── index.php
├── config
│   └── services.yaml
└── composer.json

Code Examples

`src/Controller/BookController.php`

<?php

declare(strict_types=1);

namespace AppController;

use AppRequestBookRecordRequest;
use AppPresenterJsonResponsePresenter;
use AppPresenterHtmlResponsePresenter;
use AppUseCaseRegisterBookUsecase;
use SymfonyComponentHttpFoundationRequest as SymfonyRequest;
use SymfonyComponentHttpFoundationJsonResponse;
use SymfonyBundleFrameworkBundleControllerAbstractController;
use SymfonyComponentRoutingAnnotationRoute;

#[Route('/register-book', name: 'register_book', methods: 'POST')]
final class BookController extends AbstractController
{
    public function __construct(
        private readonly RegisterBookUsecase $registerBookUsecase
    ) {}

    public function __invoke(SymfonyRequest $request): JsonResponse
    {
        try {
            $bookRequest = BookRecordRequest::createFromPayload([
                'title' => $request->get('title'),
                'author' => $request->get('author'),
                'publication' => [
                    'published_date' => $request->get('published_date'),
                    'publisher' => $request->get('publisher'),
                ],
                'isbn' => $request->get('isbn'),
            ]);

            $presenter = $this-getPresenterAccordingToRequestContentType($request->getContentType());
            $this->registerBookUsecase
                ->withRequest($bookRequest)
                ->withPresenter($presenter)
                ->execute();

            $response = $presenter->getResponse()->output();
        } catch (Exception $exception) {
            return $this->json($exception->format(), $exception->getCode());
        }

        return $this->json($response, $response['code']);
    }

    // you can instanciate presenter according to the request context
    private function getPresenterAccordingToRequestContentType(string $contentType): PresenterInterface
    {
        switch ($contentType) {
            case 'text/html':
                return new HtmlResponsePresenter();
            default:
                break;
        }
        return new JsonResponsePresenter();
    }
}

Example with Laravel

Project Structure

├── app
│   ├── Http
│   │   └── Controllers
│   │       └── BookController.php
│   ├── Requests
│   │   └── BookRecordRequest.php
│   ├── Presenters
│   │   └── JsonResponsePresenter.php
│   ├── UseCases
│   │   └── RegisterBookUsecase.php
│   └── Responses
│       └── Response.php
├── public
│   └── index.php
└── composer.json

Code Examples

`app/Http/Controllers/BookController.php`

With request and presenter

<?php

declare(strict_types=1);

namespace AppHttpControllers;

use AppRequestsBookRecordRequest;
use AppPresentersJsonResponsePresenter;
use AppPresentersHtmlResponsePresenter;
use AppUseCasesRegisterBookUsecase;
use IlluminateHttpRequest as LaravelRequest;
use IlluminateHttpJsonResponse;

final class BookController extends Controller
{
    public function __construct(
        private readonly RegisterBookUsecase $registerBookUsecase
    ) {}

    public function __invoke(LaravelRequest $request): JsonResponse
    {
        try {
            $bookRequest = BookRecordRequest::createFromPayload([
                'title' => $request->input('title'),
                'author' => $request->input('author'),
                'publication' => [
                    'published_date' => $request->input('published_date'),
                    'publisher' => $request->input('publisher'),
                ],
                'isbn' => $request->input('isbn'),
            ]);

            $jsonPresenter = new JsonResponsePresenter();
            $this
                ->registerBookUsecase
                ->withRequest($bookRequest)
                ->withPresenter($jsonPresenter)
                ->execute();

            $response = $jsonPresenter->getResponse()->output();
        } catch (Exception $exception) {
            return response()->json($exception->format(), $exception->getCode());
        }

        return response()->json($response, $response['code']);
    }
}

Without presenter, but with request.

<?php

declare(strict_types=1);

namespace AppHttpControllers;

use AppRequestsBookRecordRequest;
use AppUseCasesRegisterBookUsecase;
use IlluminateHttpRequest as LaravelRequest;
use IlluminateHttpJsonResponse;

final class BookController extends Controller
{
    public function __construct(
        private readonly RegisterBookUsecase $registerBookUsecase
    ) {}

    public function __invoke(LaravelRequest $request): JsonResponse
    {
        try {
            $bookRequest = BookRecordRequest::createFromPayload([
                'title' => $request->input('title'),
                'author' => $request->input('author'),
                'publication' => [
                    'published_date' => $request->input('published_date'),
                    'publisher' => $request->input('publisher'),
                ],
                'isbn' => $request->input('isbn'),
            ]);

            $this
                ->registerBookUsecase
                ->withRequest($bookRequest)
                ->execute();

        } catch (Exception $exception) {
            return response()->json($exception->format(), $exception->getCode());
        }

        return response()->json([]);
    }
}

Without request and presenter

<?php

declare(strict_types=1);

namespace AppHttpControllers;

use AppRequestsBookRecordRequest;
use AppUseCasesRegisterBookUsecase;
use IlluminateHttpRequest as LaravelRequest;
use IlluminateHttpJsonResponse;

final class BookController extends Controller
{
    public function __construct(
        private readonly RegisterBookUsecase $registerBookUsecase
    ) {}
    
    public function __invoke(): JsonResponse
    {
        try {
            $this
                ->registerBookUsecase
                ->execute();

        } catch (Exception $exception) {
            return response()->json($exception->format(), $exception->getCode());
        }

        return response()->json([]);
    }
}

Unit Tests

Command to Run Unit Tests

$ make tests

License

Information on Copyright and MIT License

Clean architecture core is open-sourced software licensed under the MIT license

Expand

clean architecture core php

Core Library for Clean Architecture in PHP

Introduction

Prerequisites

Installation

Core Overview

Application Request

Presenter

Response

Use Case

Exception

Example Usage

From Scratch (PHP Without a Framework)

Project Structure

Code Examples

public/index.php

src/Controller/BookController.php

src/Request/BookRecordRequest.php

Using beberlei/assert validation library

Using Symfony Validator library

src/Presenter/JsonResponsePresenter.php

src/Presenter/HtmlResponsePresenter.php

src/UseCase/RegisterBookUsecase.php

src/Response/Response.php

Example with Symfony

Project Structure

Code Examples

src/Controller/BookController.php

Example with Laravel

Project Structure

Code Examples

app/Http/Controllers/BookController.php

Unit Tests

Command to Run Unit Tests

License

Information on Copyright and MIT License

`public/index.php`

`src/Controller/BookController.php`

`src/Request/BookRecordRequest.php`

Using `beberlei/assert` validation library

Using `Symfony Validator` library

`src/Presenter/JsonResponsePresenter.php`

`src/Presenter/HtmlResponsePresenter.php`

`src/UseCase/RegisterBookUsecase.php`

`src/Response/Response.php`

`src/Controller/BookController.php`

`app/Http/Controllers/BookController.php`