Suml Symfony Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require avris/suml-symfony
   

   Register the bundle in config/bundles.php (Symfony 4+):

   return [
       // ...
       Avris\SUML\SUMLBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config (if needed) and adjust config/packages/avris_suml.yaml:

   avris_suml:
       api_key: '%env(SUML_API_KEY)%'
       base_uri: 'https://api.suml.ai'
       debug: '%kernel.debug%'
   

3. First Use Case: Fetching a SUML Model Inject the SUMLClient service and call a basic method:

   use Avris\SUML\Client\SUMLClient;
   
   class MyController extends AbstractController
   {
       public function __construct(private SUMLClient $sumlClient) {}
   
       public function index()
       {
           $model = $this->sumlClient->getModel('user');
           return $this->json($model);
       }
   }
   

Implementation Patterns

Common Workflows

1. Model Management

   • Fetching Models: Use getModel($name) to retrieve SUML models (e.g., user, product).
   • Creating Models: Pass an array of attributes to createModel($name, $attributes).
   • Updating Models: Use updateModel($id, $attributes) with the model ID and updated data.

2. Querying Data

   • Filtering: Chain methods like filterBy($field, $value) before fetching:

     $this->sumlClient->getModels('user')->filterBy('role', 'admin')->all();
     

   • Pagination: Use limit($limit) and offset($offset) for large datasets.

3. Webhook Integration

   • Register a route to handle SUML webhooks (e.g., /suml/webhook):

     $this->sumlClient->handleWebhook($request);
     

   • Validate payloads with validateWebhook($payload).

4. Event Listeners

   • Subscribe to SUML events (e.g., suml.model.created) in EventSubscriber:

     public static function getSubscribedEvents()
     {
         return [
             SUMLEvents::MODEL_CREATED => 'onModelCreated',
         ];
     }
     

Integration Tips

• Symfony Forms: Bind SUML models to forms using ModelType for CRUD operations.
• API Platform: Extend ApiResource to expose SUML models as API endpoints.
• Doctrine ORM: Map SUML models to Doctrine entities for local persistence:

  #[ORM\Entity]
  class User
  {
      #[ORM\Id]
      private ?string $sumlId;
  
      // ...
  }
  

Gotchas and Tips

Pitfalls

1. API Key Management

   • Hardcoding api_key in config violates security best practices. Always use environment variables (%env(SUML_API_KEY)%).
   • Rotate keys periodically and revoke compromised ones via SUML dashboard.

2. Rate Limiting

   • SUML enforces rate limits (e.g., 60 requests/minute). Cache responses aggressively:

     $this->sumlClient->getModel('user', ['cache' => true]);
     

   • Implement exponential backoff for retries:

     $this->sumlClient->setRetryPolicy(new ExponentialBackoffPolicy());
     

3. Webhook Idempotency

   • SUML may retry webhooks. Use idempotency_keys in payloads to avoid duplicate processing:

     $this->sumlClient->handleWebhook($request, ['idempotency_key' => $request->get('idempotency_key')]);
     

4. Model Schema Changes

   • SUML may update model schemas without notice. Validate responses dynamically:

     $model = $this->sumlClient->getModel('user');
     if (!$this->sumlClient->validateSchema($model, 'user')) {
         throw new \RuntimeException('Schema mismatch');
     }
     

Debugging

• Enable Debug Mode: Set debug: true in config to log API requests/responses.
• Mock SUMLClient: Use dependency injection to mock SUMLClient in tests:

  $this->mock(SUMLClient::class)
       ->shouldReceive('getModel')
       ->andReturn(['id' => 1, 'name' => 'Test']);
  

• Check HTTP Status Codes: SUML returns non-200 codes for errors (e.g., 404 for missing models). Handle them explicitly:

  try {
      $model = $this->sumlClient->getModel('nonexistent');
  } catch (HttpException $e) {
      if ($e->getStatusCode() === 404) {
          // Handle missing model
      }
  }
  

Extension Points

1. Custom HTTP Client Override the default Guzzle client by binding your own:

   # config/packages/avris_suml.yaml
   avris_suml:
       http_client: 'your_custom_client_id'
   

   Register the client in services.yaml:

   services:
       your_custom_client_id:
           class: 'GuzzleHttp\Client'
           calls:
               - ['setBaseUri', ['%env(SUML_BASE_URI)%']]
   

2. Event Customization Extend SUML events to trigger custom logic:

   $dispatcher->addListener(SUMLEvents::MODEL_UPDATED, function ($event) {
       // Send notification or log changes
   });
   

3. Model Transformers Convert SUML responses to custom DTOs using a transformer:

   $transformer = new SUMLModelTransformer();
   $userDto = $transformer->transform($this->sumlClient->getModel('user'));