Relay Template Bundle Laravel Package

Getting Started

Minimal Steps to First Use

1. Prerequisites:

   • Ensure your project uses Symfony 6.4+, PHP 8.4+, and API Platform 4.x.
   • Install the relay-template-bundle as a dependency:

     composer require dbp/relay-template-bundle
     

2. Enable the Bundle: Add the bundle to your config/bundles.php:

   return [
       // ...
       DigitalBlueprint\RelayTemplateBundle\RelayTemplateBundle::class => ['all' => true],
   ];
   

3. Generate a New Relay Bundle: Use the provided command to scaffold a new bundle (replace YourBundle with your bundle name):

   php bin/console make:relay-bundle YourBundle
   

   This creates:

   • A new bundle directory (src/YourBundle/).
   • Pre-configured REST controllers, DTOs, and state processors.
   • Example resources (e.g., ExampleResource).

4. First Use Case: Extend the generated ExampleResource to model your domain. For example:

   • Create a new entity (e.g., src/YourBundle/Entity/YourEntity.php).
   • Generate a corresponding DTO (e.g., src/YourBundle/Dto/YourEntityDto.php).
   • Customize the controller (src/YourBundle/Controller/YourEntityController.php) to handle business logic.

5. Register Routes: Add routing in config/routes/your_bundle.yaml:

   your_bundle_example:
       resource: |
           alias: 'your_bundle.example'
           path: '/example'
           controller: 'YourBundle\Controller\ExampleController'
       type: 'apiPlatform'
   

6. Test Locally: Run the Symfony server and test the API:

   symfony serve
   

   Access endpoints like http://localhost:8000/api/example.

Implementation Patterns

Usage Patterns

1. Bundle Generation:

   • Use make:relay-bundle to create standardized bundles with:
     • Controllers: Pre-configured REST controllers with API Platform annotations.
     • DTOs: Data Transfer Objects for input/output validation.
     • State Processors: Services to handle pre/post operations (e.g., validation, side effects).
     • Entities: Doctrine entities with PHP attributes (e.g., @ORM\Entity).

2. Resource Customization:

   • Extend the generated ExampleResource to fit your domain:

     #[ApiResource(
         collectionOperations: ['get', 'post'],
         itemOperations: ['get', 'put', 'delete'],
         shortName: 'your_entity'
     )]
     class YourEntity extends ExampleResource
     {
         // Override or add custom logic
     }
     

3. State Processors:

   • Implement custom logic in state processors (e.g., src/YourBundle/Processor/YourEntityProcessor.php):

     class YourEntityProcessor implements StateProcessorInterface
     {
         public function __invoke(Operation $operation, mixed $data, array $uriVariables): void
         {
             // Custom logic (e.g., validation, side effects)
         }
     }
     

   • Register processors in services.yaml:

     YourBundle\Processor\YourEntityProcessor:
         tags: ['api_platform.state_processor']
     

4. Validation:

   • Use Symfony’s Validator component with constraints (e.g., @Assert\NotBlank).
   • Example DTO:

     class YourEntityDto
     {
         #[Assert\NotBlank]
         public string $name;
     
         #[Assert\Positive]
         public int $value;
     }
     

5. Event-Driven Workflows:

   • Leverage Symfony’s event system for cross-cutting concerns:

     // src/YourBundle/EventListener/YourEntityListener.php
     class YourEntityListener
     {
         public function onPostCreate(YourEntityEvent $event): void
         {
             // Handle post-create logic
         }
     }
     

   • Register listeners in services.yaml:

     YourBundle\EventListener\YourEntityListener:
         tags: ['kernel.event_listener', { event: 'your_bundle.example.post_create' }]
     

Workflows

1. CRUD API Development:

   • Create: Generate bundle → extend ExampleResource → customize entity/DTO → register routes.
   • Update: Modify controllers/processors → update DTOs → test.
   • Delete: Remove routes → clean up entities/DTOs.

2. Integration with Relay Gateway:

   • Deploy the bundle as a microservice in the Relay ecosystem.
   • Configure API Gateway routes to proxy requests to your bundle’s endpoints.

3. Testing:

   • Use Symfony’s WebTestCase for API tests:

     class YourEntityTest extends WebTestCase
     {
         public function testGetExample(): void
         {
             $client = static::createClient();
             $client->request('GET', '/api/example');
             $this->assertResponseIsSuccessful();
         }
     }
     

   • Integrate with PHPUnit 11 and PHPStan for static analysis.

Integration Tips

1. Leverage API Platform Features:

   • Use collection/item operations for standardized endpoints.
   • Implement filters, pagination, and sorting via API Platform’s metadata.

2. Symfony Dependency Injection:

   • Autowire services in controllers/processors:

     class YourEntityController
     {
         public function __construct(
             private YourEntityManager $manager
         ) {}
     }
     

3. Database Migrations:

   • Use Doctrine Migrations for database schema updates:

     php bin/console doctrine:migrations:diff
     php bin/console doctrine:migrations:migrate
     

4. Documentation:

   • Generate OpenAPI/Swagger docs automatically:

     php bin/console api:docs:generate
     

5. CI/CD:

   • Add tests and static analysis to your pipeline:

     # .github/workflows/test.yml
     jobs:
       test:
         runs-on: ubuntu-latest
         steps:
           - uses: actions/checkout@v4
           - run: composer install
           - run: phpstan analyse src --level=5
           - run: phpunit
     

Gotchas and Tips

Pitfalls

1. Symfony vs. Laravel Conflicts:

   • Issue: Mixing Symfony bundles with Laravel can cause routing or service container conflicts.
   • Fix: Isolate the bundle in a separate Symfony project or use a microservice architecture.

2. PHP Attribute Migration:

   • Issue: Legacy code using annotations (e.g., @ORM\Entity) won’t work with PHP attributes.
   • Fix: Use doctrine/annotations as a bridge or migrate to attributes:

     composer require doctrine/annotations
     

3. API Platform Version Mismatch:

   • Issue: The bundle expects API Platform 4.x. Using an older version (e.g., 3.x) will break functionality.
   • Fix: Upgrade API Platform:

     composer require api/api-platform-core:^4.0
     

4. Event System Differences:

   • Issue: Symfony’s event system differs from Laravel’s. Custom events may not work as expected.
   • Fix: Use Symfony’s EventDispatcher or create a wrapper for Laravel’s events.

5. Doctrine vs. Eloquent:

   • Issue: The bundle uses Doctrine ORM, which may conflict with Laravel’s Eloquent.
   • Fix: Stick to Doctrine or use a hybrid approach with doctrine/dbal.

6. Service Container Conflicts:

   • Issue: Symfony’s service container may override Laravel’s services.
   • Fix: Explicitly define service priorities or use separate containers.

7. Testing Environment:

   • Issue: Symfony’s WebTestCase may not work seamlessly with Laravel’s testing helpers.
   • Fix: Mock Laravel-specific services or use a hybrid testing approach.

Debugging Tips

1. Enable Debug Mode:

   • Set APP_DEBUG=true in .env for detailed error messages:

     APP_DEBUG=1
     

2. Symfony Profiler:

   • Use the Symfony Profiler to inspect requests, services, and events:

     php bin/console debug:container YourBundle\Service\YourService
     

3. Log Configuration:

   • Configure Monolog for detailed logging in config/packages/monolog.yaml:

     monolog:
         handlers:
             main:
                 type: stream
                 path: "%kernel.logs_dir%/%kernel.environment%.log"
                 level: debug
     

4. Dependency Dumping:

   • Clear cache and dump autoload files:

     php bin/console cache:clear
     composer dump-autoload
     

5. API Platform Debug:

   • Inspect API resource metadata:

     php bin/console debug:api
     

Configuration Quirks

1. **Bundle