Zammadapibundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ahmadsajid1989/zammadapibundle
   

   Ensure your composer.json includes the bundle under "require" (even if using dev-master).

2. Enable the Bundle: Add to config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 3/2):

   new \ahmadsajid1989\ZammadApiBundle\ZammadApiBundle(),
   

3. Configure: Add to config/packages/zammad_api.yaml (Symfony 4+) or app/config/config.yml:

   zammad_api:
       url: 'https://your-zammad-instance.com'
       username: '%env(ZAMMAD_USERNAME)%'
       password: '%env(ZAMMAD_PASSWORD)%'
       debug: '%kernel.debug%'
   

4. First Use Case: Inject the client in a service/controller and call an API method:

   use ahmadsajid1989\ZammadApiBundle\Service\ZammadApiClient;
   
   class TicketController extends AbstractController
   {
       public function __construct(private ZammadApiClient $zammad)
       {
       }
   
       public function createTicket()
       {
           $ticket = $this->zammad->ticket()->create([
               'title' => 'Test Ticket',
               'body' => 'Hello from Symfony!',
               'priority' => '3',
           ]);
           return new Response(json_encode($ticket));
       }
   }
   

Implementation Patterns

Common Workflows

1. Service Integration: Use dependency injection to access Zammad APIs in services:

   class TicketService
   {
       public function __construct(private ZammadApiClient $zammad)
       {
       }
   
       public function fetchOpenTickets(): array
       {
           return $this->zammad->ticket()->get(['state' => 'open']);
       }
   }
   

2. Command-Line Automation: Create Symfony console commands to interact with Zammad:

   use Symfony\Component\Console\Command\Command;
   use Symfony\Component\Console\Input\InputInterface;
   use Symfony\Component\Console\Output\OutputInterface;
   
   class SyncTicketsCommand extends Command
   {
       protected static $defaultName = 'zammad:sync-tickets';
   
       public function __construct(private ZammadApiClient $zammad)
       {
           parent::__construct();
       }
   
       protected function execute(InputInterface $input, OutputInterface $output): int
       {
           $tickets = $this->zammad->ticket()->get();
           // Process tickets...
           return Command::SUCCESS;
       }
   }
   

3. Event-Driven Actions: Trigger Zammad actions on Symfony events (e.g., user registration):

   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   use Symfony\Component\HttpKernel\KernelEvents;
   use Symfony\Component\HttpKernel\Event\RequestEvent;
   
   class ZammadEventSubscriber implements EventSubscriberInterface
   {
       public function __construct(private ZammadApiClient $zammad)
       {
       }
   
       public static function getSubscribedEvents(): array
       {
           return [KernelEvents::REQUEST => 'onKernelRequest'];
       }
   
       public function onKernelRequest(RequestEvent $event)
       {
           if ($event->isMainRequest()) {
               $this->zammad->ticket()->create(['title' => 'New User Alert']);
           }
       }
   }
   

4. Form Integration: Use Zammad APIs to validate or enrich form data:

   use Symfony\Component\Form\AbstractType;
   use Symfony\Component\Form\FormBuilderInterface;
   
   class TicketFormType extends AbstractType
   {
       public function __construct(private ZammadApiClient $zammad)
       {
       }
   
       public function buildForm(FormBuilderInterface $builder, array $options)
       {
           $builder->add('title');
           $builder->add('body');
           $builder->add('priority', ChoiceType::class, [
               'choices' => $this->zammad->ticket()->getPriorities(),
           ]);
       }
   }
   

Gotchas and Tips

Pitfalls

1. Authentication Issues:

   • Ensure username and password in config match your Zammad user credentials.
   • Debug with debug: true in config to inspect API responses:

     zammad_api:
         debug: true
     

   • Handle rate limits by implementing retry logic (e.g., using Symfony’s RetryStrategy).

2. Deprecated Symfony Versions:

   • The bundle targets Symfony 2/3 (PHP 5.6+). For Symfony 4/5, manually adapt the bundle or fork it.
   • If using Symfony 4+, update AppKernel.php to config/bundles.php and config.yml to yaml.

3. API Version Mismatch:

   • The underlying zammad/zammad-api-client-php (v1.2) may not support newer Zammad API versions (e.g., v6+).
   • Test endpoints like /api/v1/ticket to verify compatibility.

4. CORS/SSL Issues:

   • If Zammad runs on HTTPS, ensure your Symfony app trusts its certificate (e.g., via curl.cainfo in php.ini).
   • For local development, disable SSL verification temporarily (not recommended for production):

     zammad_api:
         options:
             verify_ssl: false
     

Debugging Tips

1. Log API Responses: Extend the client to log requests/responses:

   $this->zammad->getClient()->setHandler(new \GuzzleHttp\HandlerStack([
       new \GuzzleHttp\Middleware::tap(function ($request, $next) {
           \Symfony\Component\Debug\Debug::info('Zammad API Request:', [$request->getUri(), $request->getBody()]);
           return $next($request);
       }),
   ]));
   

2. Validate Config: Use Symfony’s parameter validation to catch misconfigurations:

   # config/validator/constraints/ZammadConfig.yaml
   Zammad\Config:
       properties:
           url:
               - NotBlank: ~
               - Url: ~
           username:
               - NotBlank: ~
   

3. Mocking for Tests: Use Guzzle’s mock handler to test without hitting Zammad:

   use GuzzleHttp\Handler\MockHandler;
   use GuzzleHttp\Psr7\Response;
   
   $mock = new MockHandler([
       new Response(200, [], json_encode(['id' => 123])),
   ]);
   $this->zammad->getClient()->setHandler($mock);
   

Extension Points

1. Custom API Endpoints: Extend the bundle to add missing endpoints (e.g., for Zammad v6+):

   // src/Service/ZammadApiClient.php
   public function customEndpoint(array $data)
   {
       return $this->client->post('/api/v1/custom', $data);
   }
   

2. Rate Limiting: Implement a decorator to handle rate limits:

   class RateLimitedZammadClient
   {
       public function __construct(private ZammadApiClient $client, private int $maxRetries = 3)
       {
       }
   
       public function ticket()
       {
           return new RateLimitedTicketService($this->client->ticket(), $this->maxRetries);
       }
   }
   

3. Webhook Integration: Use Symfony’s HttpClient to listen for Zammad webhooks:

   use Symfony\Component\HttpClient\HttpClient;
   
   $client = HttpClient::create();
   $response = $client->request('POST', 'https://your-app.com/zammad-webhook', [
       'body' => json_encode($webhookPayload),
   ]);
   

4. Caching Responses: Cache frequent API calls (e.g., ticket lists) with Symfony’s cache:

   use Symfony\Contracts\Cache\CacheInterface;
   
   class CachedZammadClient
   {
       public function __construct(
           private ZammadApiClient $client,
           private CacheInterface $cache
       ) {}
   
       public function getTickets(): array
       {
           return $this->cache->get('zammad_tickets', function () {
               return $this->client->ticket()->get();
           });
       }
   }