theaddresstechnology / ddd

v1.1.14 2025-04-22 11:58 UTC

Requires

• laravel/passport: ^12.3
• spatie/laravel-activitylog: ^4.0
• spatie/laravel-query-builder: ^6.3

Requires (Dev)

• orchestra/testbench: ^5.1

MIT

• theaddresstechnology

Published on Packagist.org on 2025-04-22 12:01 UTC

README

theaddresstechnology/ddd generates REST/web application code and manages modules under src/Domain. Version 2 adds security hardening, module diagnostics and modern dependencies. GraphQL support and generation have been removed.

Existing v1 application? Start with the v1 → v2 upgrade guide. Updating Composer does not update previously generated application code.

Requirements

Component	Supported version
PHP	8.4.1+ within PHP 8.x
Required PHP extensions	DOM and Fileinfo, plus Laravel's requirements
Laravel	12 or 13
Passport	^13.8
Spatie Activitylog	^5.1.1
Spatie Query Builder	^7.3.5
Node, for generated module assets	^20.19 or >=22.12; CI uses Node 24
Vite / Sass, for generated module assets	^8.3.2 / ^1.105.1

The library does not ship a consumer lockfile. Commit your application's composer.lock and use composer install during deployment.

Install in an existing Laravel application

composer require theaddresstechnology/ddd:^2.0

Add "Src\\": "src/" to your application's existing autoload.psr-4 map, keeping its other entries, then run:

composer dump-autoload
php artisan vendor:publish --tag=ddd-config
php artisan module:setup
php artisan module:make Blog --api
php artisan module:list
vendor/bin/ddd-doctor --json

Review an existing config/modules.php before publishing. This package and nwidart/laravel-modules use overlapping helpers, config and commands and cannot be installed together. Read the comparison and migration notes.

The root Src\\ mapping loads normal DDD classes. To merge per-module dependencies, autoload files and additional PSR-4 mappings, install and explicitly trust wikimedia/composer-merge-plugin as described in module setup. module:setup writes the include pattern; it does not install or trust plugins.

Generate application code

For an application already using the DDD scaffold:

php artisan ddd:make Domain --name=Sales
php artisan ddd:make Crud --name=Order --domain=Sales

CRUD generation creates a model, migration, factory, seeder, requests, repository, resource, policies and controllers/routes. It does not generate a completed business module, tenant isolation, views or a datatable automatically. Implement validation, policy decisions, ownership/tenant scopes, and repository allowlists. Generated CRUD policies and broadcast channels deny access by default.

For a new disposable Laravel application only, php artisan ddd:directory --force creates the legacy DDD application structure. It rewrites bootstrap, routes, auth configuration, migrations and src/. Its automatic backup covers only src/; never use this command to upgrade a production application.

Modules and upgrade diagnostics

• module.json describes identity, providers, included PHP files, priority and requires dependencies. Dependencies boot first; cycles and missing/disabled dependencies fail clearly. Active dependents prevent disabling/deleting prerequisites.
• Enabled modules load routes, config, views, PHP/JSON translations and migrations. Published views take precedence. Boot bookkeeping is scoped to the application.
• module:disable Blog preserves its files and data. Clear deployment caches and restart workers; module state is not a PHP execution sandbox or authorization rule.
• vendor/bin/ddd-doctor [app-directory] --json --strict checks migration readiness without booting Laravel or modifying application files. Errors return exit 1; --strict also fails on warnings. Read diagnostic scope.
• Artifact generators refuse to overwrite existing files. Module asset builds use Vite 8 and produce JS/CSS tags through module_vite().

Security behavior

Generated domain administration requires auth:api and a manage-domains gate; admin middleware requires access-admin. Generated login validates and throttles credentials, rotates sessions, and hashes User passwords. Repository criteria require declared searchable fields and explicit allowed fields, sorts and includes. Uploads accept matching JPEG/PNG/GIF/WebP/PDF content up to 10 MiB.

Filesystem operations reject paths escaping their configured roots. Status writes are locked and atomic. Unknown module selections fail before maintenance runs; migrations, seeders and pruning propagate command failures.

These safeguards require application policies, scopes, upload serving controls and deployment procedures. They do not replace reviewing generated code.

Documentation

• v1 → v2 upgrade and rollback
• Module setup, dependencies, assets and diagnostics
• Command reference
• Laravel Modules comparison and remaining additions
• V2 audit, validation and limits
• Original security findings
• Changelog

Development

composer update --no-plugins --no-scripts
composer validate --strict
composer audit
vendor/bin/phpunit --fail-on-warning --fail-on-risky --fail-on-deprecation --fail-on-phpunit-deprecation --fail-on-phpunit-notice

CI covers PHP 8.4/8.5 with Laravel 12/13 plus a real generated module asset build. Testbench 10 selects the latest compatible PHPUnit 13.1; Testbench 11 selects 13.3.6. PHPUnit 13.4 is currently rejected by Testbench's upstream constraints.