Starter Laravel Package

Technical Evaluation

Architecture Fit

• Strengths:

  • DDD Alignment: Perfectly aligns with DDD principles (bounded contexts, entities, value objects, repositories, services) while maintaining Laravel’s conventions. The domain/module separation enforces clean architecture boundaries.
  • Modularity: Encourages loose coupling via interfaces (e.g., RepositoryInterface) and dependency injection, reducing tight integration with Laravel’s core.
  • Testability: Built-in test generation (PHPUnit/Pest) for entities, services, and repositories promotes unit/feature testing from day one.
  • API/HTTP Readiness: Routes are domain-specific (routes/domains/) and controllers are thin, delegating logic to services—ideal for REST/GraphQL APIs.
  • AI Context: Optional AGENTS.md provides structured documentation for AI agents (e.g., GitHub Copilot, custom LLM workflows) to understand domain logic.

• Weaknesses:

  • Overhead for Simple Projects: The DDD structure may feel excessive for CRUD-heavy apps without complex domains. The package lacks a "lite mode" to opt out of certain layers (e.g., skip repositories for trivial use cases).
  • Laravel-Specific Assumptions: Hardcodes paths like app_path('Domains') and relies on Eloquent for persistence, which could limit portability to non-Laravel PHP apps.
  • Learning Curve: Developers unfamiliar with DDD may struggle with concepts like ubiquitous language, aggregates, or domain events, despite the package’s scaffolding.

Integration Feasibility

• Laravel 12/13: Seamlessly integrates with modern Laravel, including first-party features like model observers, policies, and middleware.
• PHP 8.4+: Leverages modern PHP features (e.g., enums, attributes) for base classes (Entity, ValueObject).
• Composer: Zero-config installation via composer require and interactive CLI.
• Existing Codebase: Can be retrofitted into a greenfield Laravel project but may require refactoring for brownfield apps (e.g., migrating legacy controllers to thin controllers).

Technical Risk

Key Questions

1. Domain Complexity:

   • Does the project require bounded contexts (e.g., "Ordering," "Inventory," "Payments") or is a traditional MVC approach sufficient?
   • Decision: If domains are tightly coupled (e.g., monolithic business logic), DDD may add unnecessary complexity.

2. Team Expertise:

   • Is the team experienced with DDD, or will training be required?
   • Decision: Allocate time for workshops if DDD is new to the team.

3. Persistence Strategy:

   • Will the project use Eloquent, Doctrine ORM, or another persistence layer?
   • Decision: The package defaults to Eloquent; custom repository implementations may be needed for other ORMs.

4. API Requirements:

   • Are there strict versioning or contract-first (OpenAPI) needs?
   • Decision: The package supports API resources but lacks built-in OpenAPI/Swagger integration.

5. CI/CD Impact:

   • How will the new structure affect test coverage, deployment pipelines, and monitoring?
   • Decision: Plan for domain-specific test suites and infrastructure-as-code updates.

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • First-Party: Works with Laravel’s authentication (Breeze/Sanctum), validation, middleware, and testing.
  • Third-Party: Compatible with packages like Laravel Scout (search), Laravel Horizon (queues), or Laravel Nova (admin panel) via domain-specific extensions.
• PHP Extensions:
  • Doctrine: Replace Eloquent repositories with Doctrine implementations (requires custom stubs).
  • Symfony Components: Leverage HttpFoundation for HTTP layer if needed.
• Frontend:
  • API-First: The domain-specific routes and resources align with frontend frameworks (React, Vue, Svelte) consuming REST/GraphQL.
  • Livewire/Inertia: Thin controllers work well with Livewire; Inertia.js may need adjustments for domain-specific route names.

Migration Path

1. Greenfield Projects:
   • Start with composer create-project laravel/laravel my-app → composer require laravel-ddd/starter → php artisan ddd:install.
   • Select auth, test package, and sample module during installation.
2. Brownfield Projects:
   • Phase 1: Isolate a single domain (e.g., Users) into the DDD structure.

     php artisan ddd:make-module Users
     

   • Phase 2: Gradually migrate controllers/services to the new structure using feature flags.
   • Phase 3: Retire legacy code once the domain is fully migrated.
3. Hybrid Approach:
   • Use the package for new features while keeping existing code in MVC style.
   • Example: New Orders domain uses DDD; legacy Products remains in app/Http/Controllers.

Compatibility

Sequencing

1. Pre-Integration:
   • Define bounded contexts and ubiquitous language for each domain.
   • Train the team on DDD fundamentals (e.g., entities vs. value objects, aggregates).
2. Installation:
   • Run php artisan ddd:install with selected options (auth, tests, sample module).
3. Core Setup:
   • Publish config: php artisan vendor:publish --tag=ddd-config.
   • Customize base classes (e.g., extend Entity for global behavior).
4. Domain Development:
   • Start with a sample module (e.g., Users) to validate the structure.
   • Generate components incrementally:

     php artisan ddd:make-module Products
     php artisan ddd:make-entity Product Products --migration --model
     php artisan ddd:make-service ProductService Products
     

5. API/HTTP Layer:
   • Register domain routes in routes/api.php or routes/web.php:

     require app_path('Domains/Products/Routes/Products.php');
     

6. Testing:
   • Run tests for each component:

     ./vendor/bin/pest test --filter=Products
     

7. CI/CD:
   • Update pipelines to include domain-specific test suites and deployments.
   • Example GitHub Actions workflow:

     jobs:
       test:
         runs-on: ubuntu-latest
         steps:
           - run: ./vendor/bin/pest test --filter=Domains
     

Operational Impact

Maintenance

• Pros:
  • Self-Documenting: Domain-specific folders (Domains/Users/) make code navigation intuitive.
  • Isolated Changes: Modifying a domain (e.g., Orders) doesn’t risk breaking unrelated domains.
  • Generator-Driven: Artisan commands reduce boilerplate (e.g., ddd:make-entity).
• Cons:
  • Config Management: The ddd.php config requires manual updates for custom paths or behaviors.
  • Tooling Dependencies: Artisan commands may need maintenance if Laravel updates break them (e.g., new route registration syntax).
  • Legacy Code: Mixing DDD and MVC can lead to "two-speed" maintenance challenges.

Support

• Developer Onboarding:
  • Pros: Clear folder structure and interactive installer reduce ramp-up time.
  • Cons: DDD concepts may require additional documentation (e.g., "When