Hexagonal Maker Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Hexagonal Architecture Alignment: The bundle is purpose-built for Hexagonal (Ports & Adapters) Architecture, aligning with Symfony’s ecosystem. It enforces separation of concerns by generating:
  • Domain Layer: Use cases, requests, responses, and presenter interfaces.
  • Infrastructure Layer: (Implicitly supported via Symfony’s Maker Bundle extensions).
• Symfony Maker Bundle Compatibility: Leverages Symfony’s existing maker-bundle, reducing friction for teams already using it.
• DDD & Clean Architecture Synergy: Supports Domain-Driven Design (DDD) principles by scaffolding bounded contexts, use cases, and API contracts.

Integration Feasibility

• Low-Coupling Design: Generates files without modifying existing code, making it non-intrusive for legacy systems.
• Symfony Flex Support: Auto-configuration via Flex reduces manual setup, but manual activation is required if Flex fails.
• Customizable Paths: Allows alignment with existing project structures (e.g., src/Domain/, src/Application/).

Technical Risk

• Limited Adoption (0 Dependents): Low community validation; risk of undocumented edge cases or lack of long-term maintenance.
• Symfony-Specific: Not portable to non-Symfony PHP projects (e.g., Laravel, plain PHP).
• Interactive CLI Dependency: Relies on Symfony’s Maker Bundle for prompts; may conflict with custom CLI overrides.
• No API Contract Enforcement: Generates interfaces but does not enforce their implementation (e.g., no auto-wiring or validation).

Key Questions

1. Does the team already use Symfony’s Maker Bundle? If not, additional setup is required.
2. Are custom paths (e.g., src/) already defined? Misalignment may require post-generation refactoring.
3. How strict is the Hexagonal Architecture adoption? The bundle enforces structure but may not cover all use cases (e.g., event sourcing, CQRS).
4. Is there a need for non-Symfony integration? If the project uses Laravel or other frameworks, this bundle is incompatible.
5. What’s the team’s comfort level with CLI-driven development? Interactive prompts may slow down developers unfamiliar with the workflow.

Integration Approach

Stack Fit

• Primary Fit: Symfony 5.4+ applications using Hexagonal Architecture or DDD.
• Secondary Fit: Symfony projects exploring Clean Architecture or Ports & Adapters.
• Non-Fit: Laravel, plain PHP, or non-Symfony frameworks (e.g., Silex, API Platform without Symfony).

Migration Path

1. Prerequisite Check:
   • Ensure symfony/maker-bundle is installed (composer require --dev symfony/maker-bundle).
   • Verify Symfony Flex is configured (or manually activate the bundle).
2. Installation:

   composer require --dev adrienlbt/hexagonal-maker-bundle
   

   • If Flex doesn’t auto-configure, add to config/bundles.php:

     AdrienLbt\HexagonalMakerBundle\HexagonalMakerBundle::class => ['dev' => true]
     

3. Configuration (Optional):
   • Override default paths in config/packages/hexagonal_maker.yaml if needed.
4. Testing:
   • Run bin/console make:hexagonal:usecase to validate generation.
   • Manually verify generated files adhere to project standards.

Compatibility

• Symfony Version: Tested on Symfony 5.4+ (check composer.json constraints).
• PHP Version: Requires PHP 8.0+ (aligns with Symfony’s minimum).
• Existing Code: Safe to use alongside custom Maker commands or other bundles.
• CI/CD Impact: Minimal; bundle is dev-only and doesn’t affect production.

Sequencing

1. Phase 1: Pilot Use Case
   • Generate 1–2 use cases manually to validate the structure.
   • Compare with existing patterns (e.g., does the generated PresenterInterface align with API contracts?).
2. Phase 2: Team Adoption
   • Document the workflow in the team’s internal wiki.
   • Train developers on the CLI commands and generated file conventions.
3. Phase 3: Customization
   • Extend the bundle via Symfony’s Maker Bundle hooks if additional templates are needed.
   • Consider wrapping the CLI commands in a custom script for non-developers.

Operational Impact

Maintenance

• Low Overhead: Dev-only bundle with no runtime dependencies.
• Updates: Monitor adrienlbt/hexagonal-maker-bundle for breaking changes (e.g., Symfony 6+ compatibility).
• Forking Risk: Low, but if the bundle stagnates, forking may be necessary for critical fixes.

Support

• Documentation: Basic README and CHANGELOG exist but lack depth (e.g., no troubleshooting for edge cases).
• Community: Limited stars/dependents; issues may go unanswered.
• Workarounds: Teams may need to:
  • Extend templates via Symfony’s Maker Bundle customization.
  • Manually adjust generated files for project-specific needs.

Scaling

• Performance: CLI generation is lightweight; no impact on production.
• Team Scaling: Reduces boilerplate for new developers, accelerating onboarding.
• Monorepo Compatibility: May require path adjustments if used across multiple apps.

Failure Modes

1. Bundle Incompatibility:
   • Symfony version mismatch (e.g., bundle tested on 5.4 but project uses 6.2).
   • Conflict with custom Maker commands or other bundles.
2. Generated Code Issues:
   • Incorrect namespace/path generation if hexagonal_maker.yaml is misconfigured.
   • Missing dependencies (e.g., PresenterInterface not implemented in infrastructure).
3. Developer Adoption:
   • Resistance to CLI-driven workflows.
   • Over-reliance on generated code without understanding Hexagonal principles.

Ramp-Up

• Developer Onboarding:
  • Time: 1–2 hours to learn the CLI commands and generated structure.
  • Resources: Create a cheat sheet for common commands (e.g., make:hexagonal:usecase, make:hexagonal:command).
• Team Training:
  • Workshop on Hexagonal Architecture principles alongside the bundle’s usage.
  • Pair programming sessions for the first 2–3 use cases.
• Feedback Loop:
  • Gather input after 1 sprint to identify pain points (e.g., missing file types, awkward naming).
  • Decide whether to extend the bundle or use it as a starting point for custom scripts.