README

Laravel scaffolding for modular Hexagonal Architecture (Ports and Adapters). It gives a fresh Laravel application a repeatable module structure without shipping an example domain into the application.

The complete Account money-transfer example lives in the companion repository:

https://github.com/koshuang/laravel-hexagonal-architecture

Requirements

PHP 8.4 or 8.5
Laravel 13
nwidart/laravel-modules 13

Installation

composer require koshuang/laravel-hexagonal
php artisan hexagonal:install
composer update nwidart/laravel-modules deptrac/deptrac
composer dump-autoload

The installer is idempotent. Existing files are preserved by default. Use --force only when intentionally replacing generated files:

php artisan hexagonal:install --force

Create a module:

php artisan hexagonal:make-module Order

New modules are registered as enabled in modules_statuses.json, which lets Nwidart load the generated module immediately. To scaffold a disabled module, use:

php artisan hexagonal:make-module Order --no-active

Custom stubs

The package ships with the default module, Shared contracts, and Deptrac stubs. Publish them when the application needs to customize the generated files:

php artisan vendor:publish --tag=hexagonal-stubs

The published files are placed under stubs/hexagonal. Subsequent runs of hexagonal:install and hexagonal:make-module use those files automatically. For a one-off module template, pass a different directory explicitly:

php artisan hexagonal:make-module Order --stub-path=stubs/custom-module

Custom module stubs must keep the filenames shipped by the package and may use the {{MODULE}}, {{MODULE_LOWER}}, {{MODULE_NAMESPACE}}, and {{PROVIDER}} placeholders.

The generated module has this dependency direction:

Infrastructure -> Application -> Domain

Domain contains business rules and must not depend on Laravel framework classes.
Application contains use cases and inbound/outbound ports.
Infrastructure contains Laravel adapters, persistence, routes, and bindings.

Generated structure

Modules/Order/
├── Application/
│   ├── Port/In
│   ├── Port/Out
│   └── Services
├── Domain/
│   ├── Entities
│   ├── Services
│   └── ValueObjects
├── Infrastructure/
│   ├── Adapter/In
│   ├── Adapter/Out
│   ├── Config
│   └── Providers
└── Tests/
    ├── Feature
    └── Unit

The installer also creates Modules/Shared/Domain/Contracts, a generic deptrac.yaml, and the Modules\\ PSR-4 autoload entry in the application. It adds deptrac/deptrac to the application's development dependencies so the architecture check is reproducible in local development and CI. It also adds nwidart/laravel-modules and enables its Composer merge plugin in the application root, because Composer plugin permissions are root-project configuration and cannot be inherited from a package.

The generated deptrac.yaml covers both app/ and Modules/. Carbon and Illuminate allowances can be disabled in config/hexagonal.php under deptrac.allowances before rerunning php artisan hexagonal:install --force.

Validate the dependency direction after adding module code:

php artisan hexagonal:validate

The generated rules enforce Infrastructure -> Application -> Domain and do not allow Domain code to depend on Laravel framework classes.

Development

composer install
composer validate --strict
composer test
composer lint

The package development suite includes:

PHPUnit and Orchestra Testbench for Laravel integration tests
PHPStan Level 9 with Larastan
PHPCS with the Onramp Lab Laravel standard
PHP Insights
PHPMD
Deptrac dependency direction checks
Rector dry-run checks
GitHub Actions on PHP 8.4 and 8.5

The package keeps its external interface small: the Laravel service provider, the three Artisan commands, and the publishable stub set. File writing and module scaffolding are internal seams covered by unit tests.

Versioning

Releases follow Semantic Versioning. This project is pre-1.0: while the external interface is stable in practice, breaking changes land in 0.x minor bumps rather than a 1.0 major, so pin a ^0.<minor> constraint to stay stable during onboarding. The 0.x line targets Laravel 13 and PHP 8.4+. Laravel major-version support changes require a compatibility update in composer.json, CI, and this document.

Contributing

See CONTRIBUTING.md for development and pull request requirements. Changes are tracked in CHANGELOG.md.

License

This package is open-sourced software licensed under the MIT license.

koshuang / laravel-hexagonal

Maintainers

Package info

Statistics

Security