Download the PHP package tey/laravel-ddd without Composer

Domain Driven Design Toolkit for Laravel

Laravel-DDD is a toolkit to support domain driven design (DDD) in Laravel applications. One of the pain points when adopting DDD is the inability to use Laravel's native make commands to generate objects outside the App\* namespace. This package aims to fill the gaps by providing equivalent commands such as ddd:model, ddd:dto, ddd:view-model and many more.

Installation

You can install the package via composer:

[!IMPORTANT] Upgrading from lunarstorm/laravel-ddd v2? First update to v2.1.2, then run ddd:upgrade:

See UPGRADING for full details.

You may initialize the package using the ddd:install artisan command. This will publish the config file, register the domain path in your project's composer.json psr-4 autoload configuration on your behalf, and allow you to publish generator stubs for customization if needed.

Configuration

For first-time installations, a config wizard is available to populate the ddd.php config file interactively:

For existing installations with a config file published from a previous version, you may use the ddd:config update command to rebuild and merge it with the latest package copy:

See Configuration Utility for details about other available options.

Peer Dependencies

The following additional packages are suggested (but not required) while working with this package.

• Data Transfer Objects: spatie/laravel-data
• Actions: lorisleiva/laravel-actions

The default DTO and Action stubs of this package reference classes from these packages. If this doesn't apply to your application, you may publish and customize the stubs accordingly.

Deployment

In production, ensure you run php artisan ddd:optimize during the deployment process to optimize autoloading. If you already run php artisan optimize in production, this will be handled automatically.

Version Compatibility

See UPGRADING for more details about upgrading across different versions.

Usage

Syntax

All domain generator commands use the following syntax:

Available Commands

Generators

Generated objects will be placed in the appropriate domain namespace as specified by ddd.namespaces.* in the config file.

Config Utility (Since 1.2)

A configuration utility was introduced in 1.2 to help manage the package's configuration over time.

Output:

These config tasks are also invokeable directly using arguments:

Other Commands

Advanced Usage

Application Layer (since 1.2)

Some objects interact with the domain layer, but are not part of the domain layer themselves. By default, these include: controller, request, middleware. You may customize the path, namespace, and which ddd:* objects belong in the application layer.

The configuration above will result in the following:

Output:

Custom Layers (since 1.2)

Often times, additional top-level namespaces are needed to hold shared components, helpers, and things that are not domain-specific. A common example is the Infrastructure layer. You may configure these additional layers in the ddd.layers array.

The configuration above will result in the following:

Output:

After defining new layers in ddd.php, make sure the corresponding namespaces are also registered in your composer.json file. You may use the ddd:config helper command to handle this for you.

Nested Objects

For any ddd:* generator command, nested objects can be specified with forward slashes.

This is essential for objects without a fixed namespace such as class, interface, trait, each of which have a blank namespace by default. In other words, these objects originate from the root of the domain.

Subdomains (nested domains)

Subdomains can be specified with dot notation wherever a domain option is accepted.

Overriding Configured Namespaces at Runtime

If for some reason you need to generate a domain object under a namespace different to what is configured in ddd.namespaces.*, you may do so using an absolute name starting with /. This will generate the object from the root of the domain.

Custom Object Resolution

If you require advanced customization of generated object naming conventions, you may register a custom resolver using DDD::resolveObjectSchemaUsing() in your AppServiceProvider's boot method:

The example above will result in the following:

Customizing Stubs

This package ships with a few ddd-specific stubs, while the rest are pulled from the framework. For a quick reference of available stubs and their source, you may use the ddd:stub --list command:

Stub Priority

When generating objects using ddd:*, stubs are prioritized as follows:

• Try stubs/ddd/*.stub (customized for ddd:* only)
• Try stubs/*.stub (shared by both make:* and ddd:*)
• Fallback to the package or framework default

Publishing Stubs

To publish stubs interactively, you may use the ddd:stub command:

You may also use shortcuts to skip the interactive steps:

To publish multiple stubs with common prefixes at once, use * or . as a wildcard ending to indicate "stubs that starts with":

Output:

Domain Autoloading and Discovery

Autoloading behaviour can be configured with the ddd.autoload configuration option. By default, domain providers, commands, policies, and factories are auto-discovered and registered.

Service Providers

When ddd.autoload.providers is enabled, any class within the domain layer extending Illuminate\Support\ServiceProvider will be auto-registered as a service provider.

Console Commands

When ddd.autoload.commands is enabled, any class within the domain layer extending Illuminate\Console\Command will be auto-registered as a command when running in console.

Policies

When ddd.autoload.policies is enabled, the package will register a custom policy discovery callback to resolve policy names for domain models, and fallback to Laravel's default for all other cases. If your application implements its own policy discovery using Gate::guessPolicyNamesUsing(), you should set ddd.autoload.policies to false to ensure it is not overridden.

Factories

When ddd.autoload.factories is enabled, the package will register a custom factory discovery callback to resolve factory names for domain models, and fallback to Laravel's default for all other cases. Note that this does not affect domain models using the Tey\LaravelDDD\Factories\HasDomainFactory trait. Where this is useful is with regular models in the domain layer that use the standard Illuminate\Database\Eloquent\Factories\HasFactory trait.

If your application implements its own factory discovery using Factory::guessFactoryNamesUsing(), you should set ddd.autoload.factories to false to ensure it is not overridden.

Migrations

When ddd.autoload.migrations is enabled, paths within the domain layer matching the configured ddd.namespaces.migration namespace will be auto-registered as a database migration path and recognized by php artisan migrate.

Event Listeners (Since 2.1.1)

When ddd.autoload.listeners is enabled, the package will automatically discover and register event listeners and event subscribers found within the domain layer, using Laravel's native event discovery mechanism (i.e., #[ListensTo] attribute or $listen property on the listener).

This is opt-in and disabled by default:

When enabled, any listener class within the domain layer that handles a specific event — via the handle() method or the #[ListensTo] attribute — will be automatically registered with Laravel's event dispatcher. Classes that implement a subscribe() method (event subscribers) are also detected and registered via Event::subscribe().

Ignoring Paths During PSR-4 Class Scanning

To specify folders that should be excluded from PSR-4 class scanning, add them to the ddd.autoload_ignore configuration option. By default, the Tests and Database/Migrations folders are excluded.

[!NOTE] This setting only affects PSR-4 class scanning (i.e., auto-discovery of Service Providers, Console Commands, Policies, Factories, and Listeners). It has no effect on migration path discovery, which uses a separate mechanism driven by ddd.autoload.migrations.

Paths specified here are relative to the root of each domain. e.g., src/Domain/Invoicing/{path-to-ignore}. If more advanced filtering is needed, a callback can be registered using DDD::filterAutoloadPathsUsing(callback $filter) in your AppServiceProvider's boot method:

The filter callback is based on Symfony's Finder Component.

Disabling Autoloading

You may disable autoloading by setting the respective autoload options to false in the configuration file as needed, or by commenting out the autoload configuration entirely.

Autoloading in Production

In production, you should cache the autoload manifests using the ddd:optimize command as part of your application's deployment process. This will speed up the auto-discovery and registration of domain providers and commands. The ddd:clear command may be used to clear the cache if needed. If you are already running php artisan optimize, ddd:optimize will be included within that pipeline. The framework's optimize and optimize:clear commands will automatically invoke ddd:optimize and ddd:clear respectively.

Configuration File

This is the content of the published config file (ddd.php):

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Jasper Tey
• All Contributors

License

The MIT License (MIT). Please see License File for more information.