Download the PHP package koshuang/laravel-hexagonal without Composer

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

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

Create a module:

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

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:

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:

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:

• 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

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:

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

Development

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.