Skip to content

Latest commit

 

History

History
90 lines (68 loc) · 4.04 KB

DETAILS.md

File metadata and controls

90 lines (68 loc) · 4.04 KB

Home

This documentation details the architecture and inner workings of the laravel_module_create library, designed to automate module creation within the Laravel ecosystem, following Domain-Driven Design (DDD) principles and facilitating the adoption of Test-Driven Development (TDD).

Architecture Documentation: Laravel Module Create

The library utilizes a modular architecture based on Actions, allowing for a clear separation of concerns and facilitating maintenance and testability.

1. Architectural Patterns

1.1. Module Structure (Target)

The modules generated by the library follow a structure organized by domain within app/MyProject/:

  • Controllers: Management of HTTP requests.
  • Models: Data representation and essential business rules.
  • Providers: Service registration and bindings within the Laravel Service Container.
  • Requests: Input data validation.
  • Resources: Model transformation for API responses (Eloquent Resources).
  • Routes: Definition of domain-specific endpoints.
  • Services: Complex business logic layer, isolating the Controllers.

1.2. Internal Library Architecture (Source)

The library in src/ utilizes:

  • Action Pattern: Each task (e.g., creating a file, processing a template) is encapsulated in an Action class within src/Actions.
  • Command Pattern: Command-line interface (CLI) via src/Commands, utilizing the symfony/console component.
  • Template Engine: Use of stub files in src/Templates for dynamic code generation.

2. Full Workflow

  1. Input: The user executes a command via Console (e.g., php artisan module:create Customer).
  2. Configuration Processing: The library reads configurations in src/Config and identifies the target path.
  3. Action Execution:
    • Validation of the module name.
    • Mapping of required directories.
    • Reading of templates (src/Templates).
    • Placeholder substitution (e.g., {{moduleName}}, {{namespace}}).
  4. File Writing: Physical creation of classes and directories in app/MyProject/[Module].
  5. Registration: (Optional) Automation of the new ServiceProvider registration in Laravel's app.php.

3. TDD Guide (Test-Driven Development)

To ensure robustness, the library was structured to support rigorous testing using PHPUnit.

3.1. Unit Tests (tests/Unit)

Focus on the isolated logic of Actions and Helpers.

  • What to test:
    • Whether the NameFormatter correctly transforms "customer_orders" into "CustomerOrders".
    • Whether validation Actions reject invalid module names.
  • Example flow:
    1. Create a test for a new formatting Action.
    2. The test fails.
    3. Implement the logic in the Action.
    4. The test passes.

3.2. Feature/Integration Tests (tests/Feature)

Focus on the complete command and the final result in the filesystem.

  • What to test:
    • The execution of the module:create command.
    • Verification that all files (Controller, Service, etc.) were created in the correct paths.
    • Verification that the content of the generated files has the correct Namespace and class names.
  • Useful tools:
    • Use of Illuminate\Support\Facades\File to mock or verify the filesystem.
    • $this->artisan('module:create', ['name' => 'TestModule'])->assertExitCode(0);

4. Main Technologies and Dependencies

  • PHP 8.0+
  • Laravel Framework (Illuminate Components): For support with Collections, Filesystem, and Service Container.
  • Symfony Console: For the CLI interface.
  • PHPUnit 12+: For the automated test suite.
  • Carbon: For date manipulation if needed in stubs/logs.

5. Extension Flow

To add a new component to the module generation (e.g., Repositories):

  1. Create the stub in src/Templates/Repository.stub.
  2. Create a CreateRepositoryAction Action in src/Actions.
  3. Register the new Action in the main command within src/Commands.
  4. Add the test case in tests/Feature/CustomerFeatureTest.php.