Fcc Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require fontai/fcc-bundle
   

   Add to config/bundles.php (Symfony) or config/app.php (Laravel via bridge):

   return [
       // ...
       Fontai\FccBundle\FontaiFccBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php artisan vendor:publish --provider="Fontai\FccBundle\FontaiFccBundle" --tag="config"
   

   Edit config/fontai_fcc.php to set API endpoints, credentials, and default options.

3. First Use Case: API Request Inject the client into a service/controller:

   use Fontai\FccBundle\Client\FccClient;
   
   public function __construct(private FccClient $fccClient) {}
   
   public function fetchData()
   {
       $response = $this->fccClient->get('/api/v1/data');
       return $response->json();
   }
   

Implementation Patterns

Core Workflows

1. API Integration

   • Standard Requests: Use the fluent interface for GET/POST/PUT/DELETE:

     $this->fccClient->get('/endpoint', ['param' => 'value'])
                    ->withHeaders(['Authorization' => 'Bearer token'])
                    ->send();
     

   • Authentication: Pass tokens via config or dynamically:

     $this->fccClient->setAuthToken('dynamic_token');
     

2. Data Transformation

   • Use the built-in Response wrapper to parse/validate:

     $data = $this->fccClient->post('/transform', $payload)
                            ->assertStatus(200)
                            ->getData();
     

3. Event-Driven Extensions

   • Subscribe to fcc.before_request/fcc.after_response events in EventServiceProvider:

     protected $listen = [
         'fcc.before_request' => [
             \App\Listeners\LogFccRequest::class,
         ],
     ];
     

Integration Tips

• Laravel-Specific: Bind the client to the container in AppServiceProvider:

  $this->app->bind(FccClient::class, function ($app) {
      return new FccClient(config('fontai_fcc.base_uri'));
  });
  

• Caching Responses: Decorate the client to cache responses:

  $cachedClient = new CachedFccClient($this->fccClient, new FileCache());
  

• Testing: Mock the client in tests:

  $this->mock(FccClient::class)->shouldReceive('get')->andReturn(new Response(200, [], '{}'));
  

Gotchas and Tips

Pitfalls

1. Deprecated Guzzle Version

   • The package requires Guzzle 6.3, which is outdated. Upgrade to Guzzle 7.x manually if needed:

     composer require guzzlehttp/guzzle:^7.0
     

   • Override the service provider to use the new Guzzle:

     $this->app->bind(\GuzzleHttp\Client::class, function () {
         return new \GuzzleHttp\Client();
     });
     

2. No Laravel-Specific Docs

   • The bundle is Symfony-first. Laravel users must:
     • Manually bridge events (e.g., KernelEvents::REQUEST).
     • Handle dependency injection via Laravel’s container.

3. Config Overrides

   • The config/fontai_fcc.php may not load by default. Ensure the bundle is registered in config/app.php:

     'providers' => [
         // ...
         Fontai\FccBundle\FontaiFccBundle::class,
     ],
     

Debugging

• Enable Guzzle Debugging: Add to config/fontai_fcc.php:

  'debug' => env('APP_DEBUG', false),
  

  Logs will appear in storage/logs/laravel.log.

• Common Errors:

  • 401 Unauthorized: Verify auth_token in config or use dynamic auth.
  • 500 Server Error: Check the base_uri endpoint and payload structure.

Extension Points

1. Custom Clients Extend FccClient to add middleware:

   class CustomFccClient extends FccClient {
       public function __construct(string $baseUri) {
           parent::__construct($baseUri);
           $this->getEmitter()->addListener(
               'request',
               function (RequestInterface $request) {
                   $request = $request->withHeader('X-Custom-Header', 'value');
                   return $request;
               }
           );
       }
   }
   

2. Response Decorators Create a decorator to transform responses:

   class DecoratedFccClient implements FccClientInterface {
       public function __construct(private FccClient $client) {}
   
       public function get(string $uri, array $options = []): ResponseInterface {
           $response = $this->client->get($uri, $options);
           return $this->decorateResponse($response);
       }
   
       private function decorateResponse(ResponseInterface $response): ResponseInterface {
           // Add custom logic (e.g., normalize data)
           return $response;
       }
   }
   

3. Event Listeners Listen for fcc.response to modify responses globally:

   public function handle(FccResponseEvent $event) {
       $event->setData($this->normalizeData($event->getData()));
   }