PHPackages                             onramplab/laravel-clean-architecture - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. onramplab/laravel-clean-architecture

ActiveLibrary[Utility & Helpers](/categories/utility)

onramplab/laravel-clean-architecture
====================================

An composer template

12.0.0(1y ago)224.6k↓43.7%[3 issues](https://github.com/OnrampLab/laravel-clean-architecture/issues)MITPHPPHP >=8.2

Since Feb 1Pushed 1y ago6 watchersCompare

[ Source](https://github.com/OnrampLab/laravel-clean-architecture)[ Packagist](https://packagist.org/packages/onramplab/laravel-clean-architecture)[ RSS](/packages/onramplab-laravel-clean-architecture/feed)WikiDiscussions 12.x Synced 2d ago

READMEChangelogDependencies (14)Versions (32)Used By (0)

laravel-clean-architecture
==========================

[](#laravel-clean-architecture)

[![Software License](https://camo.githubusercontent.com/55c0218c8f8009f06ad4ddae837ddd05301481fcf0dff8e0ed9dadda8780713e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](LICENSE.md)[![CircleCI](https://camo.githubusercontent.com/9f0818b1930cac5705f3679d30b2c24143ed57ffcba3a4dd416439da5569ef0a/68747470733a2f2f636972636c6563692e636f6d2f67682f4f6e72616d704c61622f6c61726176656c2d636c65616e2d6172636869746563747572652e7376673f7374796c653d736869656c64)](https://circleci.com/gh/OnrampLab/laravel-clean-architecture)[![Total Downloads](https://camo.githubusercontent.com/72b942068df45bcc023b4e4ab1c755f33d4058e28f0d199b4704d2d9c1018f0b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6f6e72616d706c61622f6c61726176656c2d636c65616e2d6172636869746563747572652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/onramplab/laravel-clean-architecture)

Package to simply setup a Clean Architecture Application in Laravel.

Requirements
------------

[](#requirements)

- PHP >= 7.4;
- composer.

Installation
------------

[](#installation)

```
composer require onramplab/laravel-clean-architecture
```

Features
--------

[](#features)

### UseCase

[](#usecase)

The `UseCase` class combines both DTO and business logic into single class in order to reduce the number of files since the DTO usually is tight to a specific use case. Here are the features when creating your own `UseCase` classes:

- Define a DTO
    - Define fields with validation rules (You can create your own validation attributes).
- Define the business logic.

### Usefull logs

[](#usefull-logs)

By using our exception handler, you will have better logging and API error response (We follows [JSON API Spec](https://jsonapi.org/format/)). It will include more contexts.

Here is the example of api error response:

```
{
  "errors": [
    {
      "title": "Fake Domain Exception",
      "detail": "A fake message",
      "status": 400
    }
  ]
}
```

Here is the example of error log context:

```
{
  "detail": "A fake message",
  "adapter": {
    "type": "API",
    "route": "test-route",
    "method": "GET",
    "url": "http://localhost/test-route",
    "input": []
  },
  "errors": [
    {
      "title": "Unable To Do Something",
      "detail": "A fake message",
      "exception_class": "OnrampLab\\CleanArchitecture\\Exceptions\\UseCaseException",
      "stacktrace": [
        "## /var/www/html/tests/Unit/Exceptions/HandlerTest.php(149)",
        "#0 /var/www/html/vendor/phpunit/phpunit/src/Framework/TestCase.php(1548): OnrampLab\\CleanArchitecture\\Tests\\Unit\\Exceptions\\HandlerTest->handleUseCaseException2()"
      ]
    },
    {
      "title": "Fake Domain Exception",
      "detail": "A fake message",
      "exception_class": "OnrampLab\\CleanArchitecture\\Tests\\Unit\\Exceptions\\FakeDomainException",
      "stacktrace": [
        "## /var/www/html/tests/Unit/Exceptions/HandlerTest.php(146)",
        "#0 /var/www/html/vendor/phpunit/phpunit/src/Framework/TestCase.php(1548): OnrampLab\\CleanArchitecture\\Tests\\Unit\\Exceptions\\HandlerTest->handleUseCaseException2()"
      ]
    }
  ]
}
```

### Exception Architecture for clean architecture

[](#exception-architecture-for-clean-architecture)

- `GeneralException`
    - Domain Layer
        - `DomainException`
        - `CustomDomainException`
    - Application Layer
        - `UseCaseException`
        - `InternalServerException`
    - Adapter Layer
        - Low level exception

How To
------

[](#how-to)

### How to create an use case

[](#how-to-create-an-use-case)

```
namespace App\UseCases;

use OnrampLab\CleanArchitecture\UseCase;
use Spatie\LaravelData\Attributes\Validation\Url;

class DoSomethingUseCase extends UseCase
{
    #[Url()]
    public string $url;

    public function handle(): string
    {
        return 'do something';
    }
}
```

And then in your controller:

```
use App\Http\Controllers\Controller;
use App\UseCases\DoSomethingUseCase;
use Illuminate\Http\Request;

class DoSomethingController extends Controller
{
    public function doSomething(Request $request)
    {
        $result = DoSomethingUseCase::perform([
            'url' => $request->input('url'),
        ]);

        return response()->json([
            'result' => $result,
        ]);
    }
}
```

### How to replace exception handler

[](#how-to-replace-exception-handler)

Make your Laravel default handler to extend our Handler. For example:

```
namespace App\Exceptions;

use OnrampLab\LaravelExceptions\Handler as ExceptionHandler;

class Handler extends ExceptionHandler
{
   // ...
}
```

### How to add custom validation attributes

[](#how-to-add-custom-validation-attributes)

You can follow the document in [Creating your validation attribute](https://spatie.be/docs/laravel-data/v2/advanced-usage/validation-attributes#content-creating-your-validation-attribute).

Useful Tools
------------

[](#useful-tools)

Running Tests:
--------------

[](#running-tests)

```
php vendor/bin/phpunit

```

or

```
composer test

```

Code Sniffer Tool:
------------------

[](#code-sniffer-tool)

```
php vendor/bin/phpcs --standard=PSR2 src/

```

or

```
composer psr2check

```

Code Auto-fixer:
----------------

[](#code-auto-fixer)

```
composer psr2autofix
composer insights:fix
rector:fix

```

Building Docs:
--------------

[](#building-docs)

```
php vendor/bin/phpdoc -d "src" -t "docs"

```

or

```
composer docs

```

Changelog
---------

[](#changelog)

To keep track, please refer to [CHANGELOG.md](https://github.com/Onramplab/laravel-clean-architecture/blob/master/CHANGELOG.md).

Contributing
------------

[](#contributing)

1. Fork it.
2. Create your feature branch (git checkout -b my-new-feature).
3. Make your changes.
4. Run the tests, adding new ones for your own code if necessary (phpunit).
5. Commit your changes (git commit -am 'Added some feature').
6. Push to the branch (git push origin my-new-feature).
7. Create new pull request.

Also please refer to [CONTRIBUTION.md](https://github.com/Onramplab/laravel-clean-architecture/blob/master/CONTRIBUTION.md).

Folder Structure
----------------

[](#folder-structure)

This will create a basic project structure for you:

- **/build** is used to store code coverage output by default;
- **/src** is where your codes will live in, each class will need to reside in its own file inside this folder;
- **/tests** each class that you write in src folder needs to be tested before it was even "included" into somewhere else. So basically we have tests classes there to test other classes;
- **.gitignore** there are certain files that we don't want to publish in Git, so we just add them to this fle for them to "get ignored by git";
- **CHANGELOG.md** to keep track of package updates;
- **CONTRIBUTION.md** Contributor Covenant Code of Conduct;
- **LICENSE** terms of how much freedom other programmers is allowed to use this library;
- **README.md** it is a mini documentation of the library, this is usually the "home page" of your repo if you published it on GitHub and Packagist;
- **composer.json** is where the information about your library is stored, like package name, author and dependencies;
- **phpunit.xml** It is a configuration file of PHPUnit, so that tests classes will be able to test the classes you've written;
- **.travis.yml** basic configuration for Travis CI with configured test coverage reporting for code climate.

Tech Features
-------------

[](#tech-features)

- PSR-4 autoloading compliant structure;
- PSR-2 compliant code style;
- Unit-Testing with PHPUnit 6;
- Comprehensive guide and tutorial;
- Easy to use with any framework or even a plain php file;
- Useful tools for better code included.

License
-------

[](#license)

Please refer to [LICENSE](https://github.com/Onramplab/laravel-clean-architecture/blob/master/LICENSE).

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance25

Infrequent updates — may be unmaintained

Popularity29

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity69

Established project with proven stability

 Bus Factor1

Top contributor holds 90.5% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~29 days

Recently: every ~14 days

Total

29

Last Release

424d ago

Major Versions

v8.2.1 → v10.2.22025-02-25

v10.2.2 → v11.0.22025-02-25

v8.3.0 → v10.3.02025-03-10

10.x-dev → v11.1.02025-03-10

11.x-dev → 12.x-dev2025-05-06

PHP version history (2 changes)v1.0.0PHP >=8.1

v11.0.1PHP >=8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/bbca07d652fcb7978dab39dde32df72ff90e7645cd4e51be87f7454853d510a7?d=identicon)[onramplab](/maintainers/onramplab)

---

Top Contributors

[![koshuang](https://avatars.githubusercontent.com/u/1978357?v=4)](https://github.com/koshuang "koshuang (38 commits)")[![tobeygit](https://avatars.githubusercontent.com/u/33450688?v=4)](https://github.com/tobeygit "tobeygit (3 commits)")[![l443018](https://avatars.githubusercontent.com/u/7532024?v=4)](https://github.com/l443018 "l443018 (1 commits)")

---

Tags

ddduse casehexagonal-architecture

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Rector

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/onramplab-laravel-clean-architecture/health.svg)

```
[![Health](https://phpackages.com/badges/onramplab-laravel-clean-architecture/health.svg)](https://phpackages.com/packages/onramplab-laravel-clean-architecture)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)[illuminate/routing

The Illuminate Routing package.

1419.2M3.0k](/packages/illuminate-routing)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)