Relay Example Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require dbp/relay-example-bundle
   

   Add to config/bundles.php:

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

2. First Use Case: Health Check Test the bundled health endpoint immediately:

   php bin/console server:run
   

   Visit http://localhost:8000/health to verify the health check is active.

3. Explore the Example Entity Check the generated CRUD routes (e.g., /example/{id}) and inspect the Example entity in src/Entity/Example.php for structure.

Implementation Patterns

Core Workflows

1. Custom Console Commands Extend the bundled command structure by creating new commands in src/Command/:

   namespace App\Command;
   use Symfony\Component\Console\Command\Command;
   use Symfony\Component\Console\Input\InputInterface;
   use Symfony\Component\Console\Output\OutputInterface;
   
   class MyCommand extends Command {
       protected function execute(InputInterface $input, OutputInterface $output) {
           $output->writeln('Custom command!');
       }
   }
   

   Register via services.yaml:

   services:
       App\Command\MyCommand:
           tags: ['console.command']
   

2. Entity & Controller Integration Follow the Example entity pattern to scaffold new entities:

   • Place entities in src/Entity/.
   • Use make:controller to generate controllers (e.g., ExampleController).
   • Implement HTTP methods (GET, POST, PUT, DELETE) in controllers, leveraging the bundle’s route definitions.

3. Route Customization Override routes in config/routes.yaml:

   relay_example:
       resource: '@RelayExampleBundle/Resources/config/routes.yaml'
       prefix: '/api'
   

4. Health Checks & Middleware Extend the health check by adding custom checks in src/DependencyInjection/RelayExampleExtension.php:

   public function load(array $configs, ContainerBuilder $container) {
       $container->setParameter('relay_example.health_checks', [
           'database' => true,
           'custom_check' => fn() => true, // Add your logic
       ]);
   }
   

Gotchas and Tips

Pitfalls

1. Namespace Collisions The bundle uses DigitalBlueprint\RelayExampleBundle; ensure your app’s namespaces (e.g., App\Entity) don’t conflict. Prefix custom entities/controllers to avoid clashes.

2. Route Overrides If you modify routes.yaml, clear the cache:

   php bin/console cache:clear
   

   Otherwise, changes may not reflect due to Symfony’s route compiler.

3. Command Autoloading Custom commands must be tagged as console.command in services.yaml. Forgetting this will prevent them from appearing in ./bin/console list.

4. Health Check Dependencies The health endpoint assumes certain services (e.g., database) are configured. If checks fail, verify:

   • .env variables (e.g., DATABASE_URL).
   • Service availability in config/services.yaml.

Debugging Tips

• Enable Debug Mode Set APP_ENV=dev in .env to see detailed error messages and route debug output.

• Log Custom Events Use Symfony’s logger in controllers/commands:

  use Psr\Log\LoggerInterface;
  public function __construct(private LoggerInterface $logger) {}
  $this->logger->info('Custom event triggered');
  

• Inspect Bundle Configuration Dump the loaded config:

  php bin/console debug:config relay_example
  

Extension Points

1. Customize the Example Entity Override the Example entity by creating App\Entity\Example and using inheritance or traits. The bundle’s ExampleRepository can be extended similarly.

2. Add New HTTP Methods Extend controllers with custom actions (e.g., PATCH for partial updates) and update routes.yaml:

   example_patch:
       path: /example/{id}
       methods: [PATCH]
       controller: App\Controller\ExampleController::patchAction
   

3. Modify the Bundle’s Behavior Override bundle services in config/services.yaml:

   services:
       DigitalBlueprint\RelayExampleBundle\Service\ExampleService:
           class: App\Service\CustomExampleService
           arguments: ['@some_custom_service']
   

4. Integrate with Relay API Gateway If using the Relay gateway, ensure your bundle’s routes align with the gateway’s expectations (e.g., versioning, authentication). Example:

   # config/routes/relay_example.yaml
   _relay:
       resource: "@RelayExampleBundle/Resources/config/relay_routes.yaml"
       type: relay
       prefix: /v1