Laravel Hexagonal

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

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.

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. The 1.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.