Rentgen Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require czogori/rentgen-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       Czogori\RentgenBundle\RentgenBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console config:dump-reference RentgenBundle
   

   Override settings in config/packages/rentgen.yaml:

   rentgen:
       api_key: 'your-api-key-here'
       base_uri: 'https://api.rentgen.example.com'
   

3. First Use Case Inject the RentgenClient service into a controller or command:

   use Czogori\RentgenBundle\Client\RentgenClient;
   
   class MyController extends AbstractController
   {
       public function __construct(private RentgenClient $rentgen)
       {
       }
   
       public function index()
       {
           $response = $this->rentgen->get('/documents');
           return $this->json($response);
       }
   }
   

Implementation Patterns

Common Workflows

1. API Integration Use the client for RESTful operations:

   // GET request
   $documents = $this->rentgen->get('/documents', ['query' => ['limit' => 10]]);
   
   // POST request with payload
   $this->rentgen->post('/documents', ['title' => 'Contract']);
   

2. Authentication Handle API keys or OAuth via config:

   rentgen:
       auth:
           type: 'api_key'
           api_key: '%env(RENTGEN_API_KEY)%'
   

3. Response Handling Normalize responses with custom decoders:

   $this->rentgen->setDecoder(new CustomDecoder());
   

4. Event-Driven Extensions Subscribe to rentgen.response events for middleware:

   // src/EventListener/RentgenResponseListener.php
   public function onResponse(ResponseEvent $event)
   {
       $event->setData($event->getData() + ['custom_field' => true]);
   }
   

5. Dependency Injection Bind custom clients in services.yaml:

   services:
       App\Service\CustomRentgenClient:
           arguments:
               $client: '@rentgen.client'
   

Integration Tips

• Symfony Messenger: Use the client in async handlers for background processing.
• API Platform: Integrate Rentgen responses as data providers.
• Doctrine: Map Rentgen entities to Doctrine models via custom hydrators.
• Testing: Mock the RentgenClient in PHPUnit:

  $this->mockBuilder()
       ->getMockBuilder(RentgenClient::class)
       ->disableOriginalConstructor()
       ->onlyMethods(['get', 'post'])
       ->getMock();
  

Gotchas and Tips

Pitfalls

1. API Key Exposure

   • Never hardcode keys in config. Use %env() or a secrets manager.
   • Validate the RentgenBundle config schema:

     php bin/console debug:config rentgen
     

2. Rate Limiting

   • Implement retry logic for 429 Too Many Requests:

     $this->rentgen->setRetryStrategy(new ExponentialBackoff());
     

3. Response Parsing

   • Custom decoders may break if Rentgen’s API response structure changes. Test thoroughly.

4. Caching

   • Avoid caching sensitive data. Use CacheInterface with caution:

     $this->rentgen->setCache($cachePool);
     

Debugging

• Logging: Enable debug mode in rentgen.yaml:

  rentgen:
      debug: true
  

• HTTP Interceptor: Use Symfony’s HttpClient interceptor for debugging:

  $this->rentgen->getHttpClient()->getEventDispatcher()->addListener(
      'request',
      function (RequestEvent $event) {
          dump($event->getRequest());
      }
  );
  

Extension Points

1. Custom Clients Extend AbstractRentgenClient for domain-specific logic:

   class DocumentClient extends AbstractRentgenClient
   {
       public function uploadDocument(array $fileData): array
       {
           return $this->post('/documents/upload', $fileData);
       }
   }
   

2. Middleware Add request/response middleware via Symfony’s HttpClient:

   $this->rentgen->getHttpClient()->setDefaultOptions([
       'auth_bearer' => $token,
       'headers' => ['X-Custom-Header' => 'value'],
   ]);
   

3. Event Dispatcher Listen for rentgen.request and rentgen.response events to modify payloads or log activity.

4. Configuration Overrides Dynamically override settings per environment:

   # config/packages/rentgen_prod.yaml
   rentgen:
       base_uri: '%env(RENTGEN_PROD_URI)%'