{"id":41427616,"url":"https://github.com/giacomomasseron/php-clean-architecture","last_synced_at":"2026-01-23T14:19:14.718Z","repository":{"id":318762278,"uuid":"1042769017","full_name":"giacomomasseron/php-clean-architecture","owner":"giacomomasseron","description":"An implementation of Clean Architecture in a PHP project","archived":false,"fork":false,"pushed_at":"2025-12-09T10:31:04.000Z","size":64,"stargazers_count":13,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-12T21:58:11.773Z","etag":null,"topics":["clean-architecture","clean-code","php"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/giacomomasseron.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"Giacomo Masseroni"}},"created_at":"2025-08-22T14:44:26.000Z","updated_at":"2025-12-09T10:31:01.000Z","dependencies_parsed_at":"2025-10-15T07:40:55.662Z","dependency_job_id":"3a3ff2ea-bfba-4a36-bcf4-ebfecc61432d","html_url":"https://github.com/giacomomasseron/php-clean-architecture","commit_stats":null,"previous_names":["giacomomasseron/php-clean-architecture"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/giacomomasseron/php-clean-architecture","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giacomomasseron%2Fphp-clean-architecture","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giacomomasseron%2Fphp-clean-architecture/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giacomomasseron%2Fphp-clean-architecture/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giacomomasseron%2Fphp-clean-architecture/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/giacomomasseron","download_url":"https://codeload.github.com/giacomomasseron/php-clean-architecture/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giacomomasseron%2Fphp-clean-architecture/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28693844,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-23T14:15:13.573Z","status":"ssl_error","status_checked_at":"2026-01-23T14:09:05.534Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clean-architecture","clean-code","php"],"created_at":"2026-01-23T14:19:13.992Z","updated_at":"2026-01-23T14:19:14.710Z","avatar_url":"https://github.com/giacomomasseron.png","language":"PHP","funding_links":["https://github.com/sponsors/Giacomo Masseroni"],"categories":[],"sub_categories":[],"readme":"# Implements Clean Architecture with PHP\n\n[![Latest Version on Packagist](https://img.shields.io/packagist/v/giacomomasseron/php-clean-architecture.svg?style=flat-square)](https://packagist.org/packages/giacomomasseron/php-clean-architecture)\n[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/giacomomasseron/php-clean-architecture/run-tests.yml?branch=main\u0026label=tests\u0026style=flat-square)](https://github.com/giacomomasseron/php-clean-architecture/actions?query=workflow%3Arun-tests+branch%3Amain)\n[![GitHub Code Style Action Status](https://img.shields.io/github/actions/workflow/status/giacomomasseron/php-clean-architecture/fix-php-code-style-issues.yml?branch=main\u0026label=code%20style\u0026style=flat-square)](https://github.com/giacomomasseron/php-clean-architecture/actions?query=workflow%3A\"Fix+PHP+code+style+issues\"+branch%3Amain)\n[![Total Downloads](https://img.shields.io/packagist/dt/giacomomasseron/php-clean-architecture.svg?style=flat-square)](https://packagist.org/packages/giacomomasseron/php-clean-architecture)\n\nImplements Clean Architecture as described by Robert C. Martin (Uncle Bob) here:      \n[Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)\n\nThis is an opinionated package that defines levels of the architecture and the dependencies between them.    \nAnd uses deptrac to check if the levels are respected.\n\n- [Installation](#installation)\n- [Getting started](#Getting-started)\n  - [Commands](#Commands)\n    - [Install](#Install) \n    - [Check](#Check)\n    - [Rector](#Rector)\n    - [Make Entity](#Make-Entity)\n    - [Make Repository](#Make-Repository)\n    - [Make UseCase](#Make-UseCase)\n    - [Make Controller](#Make-Controller)\n    - [Make Service](#Make-Service)\n- [Why Clean Architecture](#Why-Clean-Architecture)\n- [Concepts](#Concepts)\n  - [Architecture Level](#Architecture-Level)\n  - [UseCase](#UseCase)\n- [How it works](#How-it-works)\n  - [Levels](#Levels)\n  - [Define a level inside the project](#Define-a-level-inside-the-project)\n  - [UseCases](#UseCases)\n    - [BaseUseCase](#BaseUseCase)\n    - [Events](#events)\n- [CI/CD](#CICD)\n- [Testing](#testing)\n- [Frameworks](#frameworks)\n  - [Laravel](#laravel)\n    - [Pulse](#pulse) \n\n## Installation\n\nYou can install the package via composer:\n\n```bash  \ncomposer require giacomomasseron/php-clean-architecture\n```  \n  \nAfter the installation, you must run the *install* command to publish the *deptrac.yaml*, *php-clean-architecture.yaml* and *rector.php* config files to your root folder:  \n\n```bash  \nvendor/bin/php-clean-architecture install\n```  \n  \n## Getting started  \n  \nTo check the architecture levels in your project, use the following command:  \n  \n```bash  \nvendor/bin/php-clean-architecture check\n```  \n  \n### Commands  \n\nAll make commands read the *php-clean-architecture.yaml* config file to know where to put the files created and which namespace they belong to.\n\n#### Install\n\nThe install command publishes needed files your root folder.  \nIf you have already rector installed, you must add these lines of code in your *rector.php* file: \n\n```php \nreturn RectorConfig::configure() // This line is already present in your rector.php file\n    -\u003ewithConfiguredRule(\n        \\GiacomoMasseroni\\PHPCleanArchitecture\\Rector\\Rules\\AddPHPCleanArchitectureInterfaceControllerToClassesRector::class,\n        [\n            'targetNamespaces' =\u003e [\n                'App\\Http\\Controllers',\n            ]\n        ]\n    )\n    -\u003ewithConfiguredRule(\n        \\GiacomoMasseroni\\PHPCleanArchitecture\\Rector\\Rules\\AddPHPCleanArchitectureInterfaceEntityToClassesRector::class,\n        [\n            'targetNamespaces' =\u003e [\n                'App\\Entities',\n            ]\n        ]\n    )\n    -\u003ewithConfiguredRule(\n        \\GiacomoMasseroni\\PHPCleanArchitecture\\Rector\\Rules\\AddPHPCleanArchitectureInterfaceRepositoryToClassesRector::class,\n        [\n            'targetNamespaces' =\u003e [\n                'App\\Repositories',\n            ]\n        ]\n    )\n    -\u003ewithConfiguredRule(\n        \\GiacomoMasseroni\\PHPCleanArchitecture\\Rector\\Rules\\AddPHPCleanArchitectureInterfaceServiceToClassesRector::class,\n        [\n            'targetNamespaces' =\u003e [\n                'App\\Services',\n            ]\n        ]\n    )\n    -\u003ewithConfiguredRule(\n        \\GiacomoMasseroni\\PHPCleanArchitecture\\Rector\\Rules\\AddPHPCleanArchitectureInterfaceUseCaseToClassesRector::class,\n        [\n            'targetNamespaces' =\u003e [\n                'App\\UseCases',\n            ]\n        ]\n    )\n```  \n\n#### Check\n\nThe check command checks the architecture levels in your project.  \nYou can use it in your CI/CD pipeline to be sure that the architecture levels are respected.  \n  \n\n#### Rector  \n\nThe *rector* command adds the needed interfaces to your classes based on namespaces defined in your config files.\n\n#### Make Entity  \n  \nTo create an Entity, you can use the following command:  \n  \n```bash  \nvendor/bin/php-clean-architecture make:entity EntityInYourProject\n```  \n  \n#### Make Repository  \n  \nTo create a Repository, you can use the following command:  \n  \n```bash  \nvendor/bin/php-clean-architecture make:repository UserRepository\n```  \n  \n#### Make UseCase  \n  \nTo create a UseCase, you can use the following command:  \n  \n```bash  \nvendor/bin/php-clean-architecture make:usecase DoSomethingUseCase\n```  \n  \n#### Make Controller  \n  \nTo create a Controller, you can use the following command:  \n  \n```bash  \nvendor/bin/php-clean-architecture make:controller UserController\n```  \n  \n#### Make Service  \n  \nTo create a Service, you can use the following command:  \n  \n```bash  \nvendor/bin/php-clean-architecture make:service ThirdyPartyService  \nvendor/bin/php-clean-architecture make:service ThirdyParty\n```  \n  \nIn both cases, the created class will be named *ThirdyPartyService*.  \n  \n## Why Clean Architecture?  \n  \nWhy not?    \nIt is a well-known, well-structured architecture system.  \n  \n## Concepts  \n  \n### Architecture Level  \n  \nIn the Clean Architecture, a level is a layer of the architecture with a specific function, **only connected to the upper level**.  \n  \nThe rule of thumb of the Clean Architecture is:    \n**An inner circle must never know anything about the circles around it**.  \n  \n### UseCase  \n  \nUseCase is a concept of Use Cases level.  \n  \nA UseCase is every action your project performs.    \nGood examples of use cases are:  \n- Login  \n- Register  \n- CompleteOrder  \n- UpdateProfile  \n  \n**A use case should be a single, very specific action. It shouldn’t do anything more than its name suggests.**  \n  \n## How it works  \n  \nThe package uses [deptrac](https://github.com/deptrac/deptrac) to define the levels and to check the dependencies between them.  \n  \n### Levels  \n  \nThese are the levels defined:  \n  \n- Entity  \n- Repository  \n- UseCase  \n- Controller  \n- Service  \n  \nThese are the dependencies between the levels:  \n  \n```mermaid  \ngraph TD;  \n Controller--\u003eUseCase--\u003eRepository; UseCase--\u003eService; Repository--\u003eService; Repository--\u003eEntity;  \n```  \n\nThe *Entity* level must not depend on any other level.    \nThe *Repository* level can only depend on *Entity* or *Service* levels.    \nThe *UseCase* level can only depend on *Repository* or *Service* levels.    \nThe *Controller* level can only depend on *UseCase* levels.\n\n**What is the Service level?**  \nThe Service level can be used for third-party tools or libraries.\n\n### Define a level inside the project\n\nThe package comes with these interfaces:\n\n- **EntityInterface**: implement this interface if the class belongs to the Entity level.\n- **RepositoryInterface**: implement this interface if the class belongs to the Repository level.\n- **UseCaseInterface**: implement this interface if the class belongs to the UseCase level.\n- **ControllerInterface**: implement this interface if the class belongs to the Controller level.\n- **ServiceInterface**: implement this interface if the class belongs to the Service level.\n\n\nIf you want your controller to be part of the Controller level, you need to implement the ControllerInterface.    \nFor example:\n\n```php  \nuse GiacomoMasseroni\\PHPCleanArchitecture\\Contracts\\ControllerInterface;  \n  \npublic class YourController implements ControllerInterface  \n```  \n\n### UseCases\n\nWhen you create a UseCase, the class needs to extend the BaseUseCase class, and you need to implement the UseCaseInterface.  \nFor example:\n\n```php  \nuse GiacomoMasseroni\\PHPCleanArchitecture\\BaseUseCase;  \nuse GiacomoMasseroni\\PHPCleanArchitecture\\Contracts\\UseCaseInterface;  \n  \npublic class DoSomething extends BaseUseCase implements UseCaseInterface  \n{  \n    public function handle(...$arguments): mixed\n    { \n        // \n    }\n}  \n```  \n\nTo execute the UseCase, you need to call the *run* method defined in the BaseUseCase class:\n\n```php  \nDoSomething::run($arg1, $arg2);  \n```  \n\n#### BaseUseCase\n\nThe package defines an abstract class for use cases: *BaseUseCase*.    \nThis class defines variable for the user executing the use case:\n\n```php  \nUseCaseExecutorInterface $executor\n```   \n\nYou can set the executor using the following example:  \n  \n```php  \nDoSomething::actingAs($user)-\u003erun($arg1, $arg2);  \n```  \n\nIf you need to rollback the use case, you can override the *rollback* method:\n\n```php  \npublic function rollback(): void  \n{  \n}  \n```  \n\n#### Events\n\nThe package dispatches two events, one when the use case starts, and one when the use case ends.  \nIt uses the [Symfony Event Dispatcher Component](https://symfony.com/doc/current/components/event_dispatcher.html).\n\nThe events are:\n\n- UseCaseStartedEvent\n- UseCaseCompletedEvent\n\n## CI/CD\n\nIf you want to check the architecture levels in your CI/CD pipeline, you can use the following command:\n\n```bash  \nvendor/bin/php-clean-architecture check\n```  \n  \nThis command will stop your pipeline if there are architecture violations, based on the deptrac configuration file.  \n\n## Testing\n\n```bash  \ncomposer test\n```  \n\n## Frameworks\n\n### Laravel\n\n[I wrote an article on how to use this package with Laravel](https://dev.to/giacomomasseron/clean-architecture-in-a-laravel-project-3oh3)\n\n#### Pulse\n\nLaravel pulse is a package that helps you to monitor the health of your Laravel application.  \nIf you want to monitor use cases execution time, you can:\n\n- Create two laravel events, ```UseCaseStarted``` and ```UseCaseCompleted```\n- Create a Pulse card that listens to these events and measures the execution time.\n- Add this code to ```register``` function in ```AppServiceProvider.php``` file:\n    ```php \n    \\GiacomoMasseroni\\PHPCleanArchitecture\\Dispatcher::getInstance()-\u003eaddListener(\\GiacomoMasseroni\\PHPCleanArchitecture\\Events\\UseCaseStartedEvent::class, function (\\GiacomoMasseroni\\PHPCleanArchitecture\\Events\\UseCaseStartedEvent $event): void {\n        // Just propagate the event to Laravel event system\n        \\App\\Events\\UseCaseStarted::dispatch($event-\u003euseCase);\n    });\n    \n    \\GiacomoMasseroni\\PHPCleanArchitecture\\Dispatcher::getInstance()-\u003eaddListener(\\GiacomoMasseroni\\PHPCleanArchitecture\\Events\\UseCaseCompletedEvent::class, function (\\GiacomoMasseroni\\PHPCleanArchitecture\\Events\\UseCaseCompletedEvent $event): void {\n        // Just propagate the event to Laravel event system\n        \\App\\Events\\UseCaseCompleted::dispatch($event-\u003euseCase);\n    });\n    ```\n\n\n## Changelog  \n  \nPlease see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.  \n  \n## Contributing  \n  \nPlease see [CONTRIBUTING](CONTRIBUTING.md) for details.  \n  \n## Security Vulnerabilities  \n  \nPlease review [our security policy](../../security/policy) on how to report security vulnerabilities.  \n  \n## Credits  \n  \n- [Giacomo Masseroni](https://github.com/giacomomasseron)  \n- [All Contributors](../../contributors)  \n  \n## License  \n  \nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiacomomasseron%2Fphp-clean-architecture","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgiacomomasseron%2Fphp-clean-architecture","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiacomomasseron%2Fphp-clean-architecture/lists"}