Hex Tools

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

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

Command	Description
hex:install	Publish config, create docs/build folders, optionally install composer scripts
hex:deptrac:layers	Generate deptrac.layers.yaml for strict technical layer checks
hex:deptrac:modules	Generate deptrac.modules.yaml for business module boundary checks
hex:map {module}	Print grouped class map for a module
hex:inspect	Inspect modules, layers, dependencies, and architecture issues
hex:doctor	Check package configuration and quality-tooling health
hex:docs	Generate architecture intelligence documentation
hex:baseline	Baseline current architecture issues for legacy projects
hex:explain {rule}	Explain a known architecture rule code
hex:module:init {module}	Create module folder skeleton and docs stub
hex:docs:generate	Generate architecture documentation from config
hex:adr:create {title}	Create a numbered Architecture Decision Record

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

Command	Description
hex:phpmd:install	Install PHPMD ruleset and optional composer scripts
hex:phpmd:generate	Regenerate PHPMD ruleset
hex:phpmd:baseline	Print or run PHPMD baseline generation
hex:phpmd:run	Run PHPMD using generated rules

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

Command	Description
hex:phpstan:install	Install PHPStan configs and optional composer scripts
hex:phpstan:generate	Regenerate PHPStan config files
hex:phpstan:baseline	Print or run PHPStan baseline generation

License

MIT