Rest Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require caseboxdev/rest-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       Casebox\RestBundle\CaseboxRestBundle::class => ['all' => true],
   ];
   

2. Configuration Follow the Casebox documentation to configure config/packages/casebox_rest.yaml:

   casebox_rest:
       api_url: '%env(CASEBOX_API_URL)%'
       api_key: '%env(CASEBOX_API_KEY)%'
       default_locale: 'en'
   

3. First Use Case Trigger a basic API call via a controller:

   use Casebox\RestBundle\Controller\CaseboxApiController;
   
   class MyController extends AbstractController
   {
       public function __invoke(CaseboxApiController $caseboxApi)
       {
           $response = $caseboxApi->get('/cases'); // Example endpoint
           return $this->json($response->getData());
       }
   }
   

Implementation Patterns

REST API Integration

• Service Layer Abstraction Use the CaseboxApiService to encapsulate API calls:

  $cases = $this->get('casebox_rest.api_service')->get('/cases');
  

  Inject the service via dependency injection (DI) in controllers/services.

• Resource Routing Leverage Symfony’s routing to map Casebox endpoints:

  # config/routes.yaml
  casebox_api:
      path: /api/casebox/{endpoint}
      controller: Casebox\RestBundle\Controller\CaseboxApiController::handle
      methods: [GET, POST, PUT, DELETE]
  

• DTO Mapping Transform API responses into domain objects using Symfony’s Serializer:

  $serializer = $this->get('serializer');
  $case = $serializer->deserialize($response->getContent(), Case::class, 'json');
  

Workflows

1. Authentication Handle API keys via middleware or Symfony’s HttpClient interceptors:

   $client = $this->get('http_client');
   $client->setOptions([
       'auth_bearer' => '%env(CASEBOX_API_KEY)%',
   ]);
   

2. Error Handling Use the bundle’s CaseboxExceptionHandler to centralize API error responses:

   try {
       $response = $caseboxApi->post('/cases', $data);
   } catch (\Casebox\RestBundle\Exception\CaseboxException $e) {
       return $this->json(['error' => $e->getMessage()], 400);
   }
   

3. Pagination Process paginated responses with Paginator:

   $paginator = new Paginator($response->getData(), false);
   $cases = $paginator->getIterator();
   

Gotchas and Tips

Pitfalls

• Deprecated Symfony3 CMF The bundle targets Symfony 3.x and may conflict with modern Symfony (5/6) features (e.g., HttpClient vs. Guzzle). Use a wrapper or fork if upgrading.

• API Key Exposure Avoid hardcoding keys. Use Symfony’s %env() or a secrets manager (e.g., symfony/secret).

• Rate Limiting Casebox may throttle requests. Implement retries with exponential backoff:

  use Symfony\Contracts\HttpClient\Exception\ClientExceptionInterface;
  use Symfony\Contracts\HttpClient\Exception\RedirectionExceptionInterface;
  use Symfony\Contracts\HttpClient\Exception\ServerExceptionInterface;
  use Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface;
  
  try {
      $response = $client->request('GET', '/cases');
  } catch (TransportExceptionInterface $e) {
      // Retry logic here
  }
  

Debugging

• Enable API Logging Configure Monolog to log API calls:

  # config/packages/monolog.yaml
  handlers:
      casebox_api:
          type: stream
          path: "%kernel.logs_dir%/casebox.log"
          level: debug
          channels: ["casebox"]
  

• Mock API Responses Use HttpClient mocks for testing:

  $mockResponse = new Response(json_encode(['id' => 123]));
  $client = $this->createMock(HttpClientInterface::class);
  $client->expects($this->any())
         ->method('request')
         ->willReturn($mockResponse);
  $this->container->set('http_client', $client);
  

Extension Points

• Custom Endpoints Extend CaseboxApiController to add domain-specific routes:

  class CustomCaseboxController extends CaseboxApiController
  {
      public function customEndpoint()
      {
          return $this->get('/custom-endpoint');
      }
  }
  

• Response Transformers Override the CaseboxApiService to modify responses:

  class CustomCaseboxApiService extends CaseboxApiService
  {
      protected function transformResponse(ResponseInterface $response): array
      {
          $data = parent::transformResponse($response);
          // Add custom logic (e.g., hide sensitive fields)
          return $data;
      }
  }
  

• Event Listeners Subscribe to casebox.api.response events to intercept responses:

  // src/EventListener/CaseboxResponseListener.php
  class CaseboxResponseListener
  {
      public function onResponse(CaseboxApiEvent $event)
      {
          $event->setData(array_merge($event->getData(), ['custom_field' => true]));
      }
  }
  

  Register in services.yaml:

  services:
      App\EventListener\CaseboxResponseListener:
          tags:
              - { name: kernel.event_listener, event: casebox.api.response, method: onResponse }