Sam Core Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require canaltp/sam-core-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       CanalTP\SamCoreBundle\CanalTPSamCoreBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console canal-tp:sam-core:install
   

   Update config/packages/canal_tp_sam_core.yaml with your API credentials and environment settings.

3. First Use Case: API Client Initialization Inject the SamCoreClient service in a controller or command:

   use CanalTP\SamCoreBundle\Client\SamCoreClient;
   
   class MyController extends AbstractController
   {
       public function __construct(private SamCoreClient $samCoreClient) {}
   
       public function index(): Response
       {
           $response = $this->samCoreClient->get('/api/v1/resource');
           // Process response
       }
   }
   

Implementation Patterns

Common Workflows

1. API Requests Use the fluent interface for requests:

   $this->samCoreClient
       ->setEndpoint('/api/v1/orders')
       ->setMethod('POST')
       ->setData(['order' => $orderData])
       ->send();
   

2. Authentication Handle OAuth2 or API keys via config:

   canal_tp_sam_core:
       api:
           auth:
               type: 'oauth2' # or 'api_key'
               credentials: '%env(SAM_CORE_API_KEY)%'
   

3. Response Handling Decouple response processing:

   $response = $this->samCoreClient->get('/api/v1/users');
   $users = $response->getData(); // Parsed JSON
   $status = $response->getStatusCode();
   

4. Event Listeners Subscribe to sam_core.response events for centralized logging/validation:

   // src/EventListener/SamCoreListener.php
   public function onSamCoreResponse(ResponseEvent $event) {
       if ($event->getResponse()->getStatusCode() >= 400) {
           // Handle errors
       }
   }
   

5. Batch Processing Use the BatchProcessor for bulk operations:

   $processor = $this->samCoreClient->getBatchProcessor();
   $processor->addRequest('GET', '/api/v1/orders/1')
             ->addRequest('GET', '/api/v1/orders/2')
             ->process();
   

Gotchas and Tips

Pitfalls

1. Rate Limiting

   • The bundle enforces rate limits by default. Override in config:

     canal_tp_sam_core:
         api:
             rate_limit: 100 # requests/minute
     

2. Caching Quirks

   • Responses are cached by default for 5 minutes. Disable with:

     $this->samCoreClient->disableCache();
     

3. Deprecated Methods

   • Avoid SamCoreClient::call() (deprecated). Use send() instead.

4. Environment-Specific Config

   • Ensure SAM_CORE_API_KEY is in .env, not hardcoded.

Debugging Tips

1. Enable Verbose Logging

   canal_tp_sam_core:
       debug: true
   

   Logs will appear in var/log/dev.log.

2. Mocking the Client For tests, use the MockSamCoreClient:

   $mockClient = new MockSamCoreClient();
   $mockClient->shouldReceive('get')->andReturn(new Response(200, [], '{}'));
   

3. Common HTTP Errors

   • 401: Check SAM_CORE_API_KEY or OAuth2 token.
   • 429: Increase rate_limit or implement exponential backoff.

Extension Points

1. Custom Response Transformers Override CanalTP\SamCoreBundle\Response\Transformer\JsonTransformer to handle non-JSON APIs.

2. Middleware Integration Add custom middleware via config:

   canal_tp_sam_core:
       middleware:
           - App\Middleware\CustomSamCoreMiddleware
   

3. Event Subscribers Extend functionality via events:

   • sam_core.request (before request)
   • sam_core.response (after response)
   • sam_core.error (on failure)

4. Custom Endpoints Dynamically add endpoints at runtime:

   $this->samCoreClient->addEndpoint('custom', 'https://custom-api.example.com');