README

kwidoo/hex-tools is a pragmatic Laravel/PHP toolkit for generating, inspecting, documenting, and enforcing hexagonal architecture boundaries.

Supported Versions: Laravel 11, 12 | PHP 8.2+

TODO: Laravel 13 support is planned for a future release.

Installation

composer require --dev kwidoo/hex-tools
composer require --dev deptrac/deptrac

php artisan hex:install
php artisan hex:deptrac:layers
php artisan hex:deptrac:modules

Commands

Layer config vs Module config

deptrac.layers.yaml enforces technical layer boundaries:

• Domain may only depend on itself
• Application may depend on Domain
• Http may depend on Application, Domain, framework, and vendor
• Infrastructure may depend on Application, Domain, Models, framework, and vendor
• Models may depend on Domain, framework, and vendor

This prevents technical violations like Http -> Models or Domain -> Eloquent.

deptrac.modules.yaml enforces business module boundaries:

Each module (e.g. Product, Order) is collected from all technical layers but treated as a single unit. Rules define which modules may depend on which others.

Configuration

Publish the config file:

php artisan vendor:publish --tag=hex-tools-config

Edit config/hex-tools.php to define your modules and allowed dependencies.

Module Configuration

The package uses a neutral default configuration with example modules. You should replace these with your own business domain modules:

// config/hex-tools.php

'modules' => [
    // Define your business modules here
    'User',
    'Product',
    'Order',
    'Payment',
    'Shared',  // Common utilities shared across modules
],

'module_rules' => [
    // Define which modules each module can depend on
    'Shared' => ['Shared'],
    'User' => ['User', 'Shared'],
    'Product' => ['Product', 'Shared'],
    'Order' => ['Order', 'Product', 'User', 'Shared'],
    'Payment' => ['Payment', 'Order', 'User', 'Shared'],
],

Guidelines:

• Each module represents a bounded context in your domain
• The Shared module is typically used for common code that other modules can depend on
• A module may depend on itself implicitly (no need to list it)
• Avoid circular dependencies between modules

Example

# Show architecture map for Product module
php artisan hex:map Product

# Generate architecture checks
composer hex:layers
composer hex:modules

# Inspect a specific module membership in Deptrac
vendor/bin/deptrac debug:layer --config-file=deptrac.modules.yaml Product

# Check if Product depends on Pickup
vendor/bin/deptrac debug:dependencies --config-file=deptrac.modules.yaml Product Pickup

# Find unassigned classes
vendor/bin/deptrac debug:unassigned --config-file=deptrac.modules.yaml

# Create a new module skeleton
php artisan hex:module:init NewModule --with-folders

# Create an Architecture Decision Record
php artisan hex:adr:create "Domain must not use Eloquent" --status=accepted

Architecture Intelligence

php artisan hex:inspect --format=json
php artisan hex:inspect --module=Product --fail-on-violations
php artisan hex:doctor --strict
php artisan hex:docs --output=docs/architecture --force
php artisan hex:baseline --output=.hex/baseline/architecture.json
php artisan hex:explain domain_depends_on_framework

hex:inspect analyzes source structure and reports conservative rule violations such as Domain depending on framework or Infrastructure code. hex:doctor checks setup health, including config files, quality tooling, CI workflow, module paths, and composer scripts. hex:baseline stores stable hashes for current issues so future inspections can distinguish existing baseline issues from new ones.

PHPMD

Hex Tools can generate a Laravel-friendly PHPMD ruleset.

Install PHPMD:

composer require --dev phpmd/phpmd

Generate config:

php artisan hex:phpmd:install
php artisan hex:phpmd:install --composer-scripts

Run:

composer md
composer md:domain
composer md:application

Generate baseline for existing projects:

composer md:baseline

PHPStan/Larastan

Hex Tools can generate PHPStan/Larastan configs for Laravel Hexagonal Architecture projects.

composer require --dev larastan/larastan

php artisan hex:phpstan:install
php artisan hex:phpstan:install --composer-scripts

Generated configs:

• phpstan.neon.dist
• phpstan-domain.neon
• phpstan-application.neon

Run:

composer stan
composer stan:domain
composer stan:application

License

MIT