Zammad Api Client Php Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require zammad/zammad-api-client-php
   

   Ensure your project uses PHP 7.2+.

2. Basic Client Initialization:

   use ZammadAPIClient\Client;
   
   $client = new Client([
       'url'      => 'https://your-zammad-instance.com',
       'username' => 'api-user@example.com',
       'password' => 'secure-password',
   ]);
   

3. First Use Case: Fetch a ticket by ID (e.g., ID 1):

   use ZammadAPIClient\ResourceType;
   
   $ticket = $client->resource(ResourceType::TICKET)->get(1);
   echo $ticket->getValue('title'); // Output ticket title
   

Where to Look First

• Examples: Check the examples directory in the repo for practical use cases.
• API Docs: Refer to Zammad’s REST API documentation for field/endpoint specifics.
• Resource Types: Use the table in the README to verify supported operations (e.g., search, save, delete).

Implementation Patterns

Core Workflows

1. CRUD Operations

• Create:

  $ticket = $client->resource(ResourceType::TICKET);
  $ticket->setValue('title', 'New Issue');
  $ticket->setValue('priority_id', 1);
  $ticket->save(); // Persists to Zammad
  

• Read:

  $ticket = $client->resource(ResourceType::TICKET)->get(1);
  $title = $ticket->getValue('title');
  

• Update:

  $ticket->setValue('title', 'Updated Title');
  $ticket->save();
  

• Delete:

  $ticket->delete(); // Requires fetching the resource first
  

2. Searching and Pagination

• Full-text search:

  $tickets = $client->resource(ResourceType::TICKET)->search('urgent');
  

• Field-specific search:

  $tickets = $client->resource(ResourceType::TICKET)->search('title:"High Priority" AND state_id:3');
  

• Pagination:

  $tickets = $client->resource(ResourceType::TICKET)->all(2, 20); // Page 2, 20 items
  

3. Handling Attachments

• Fetch attachment content:

  $article = $ticket->getTicketArticles()[0];
  $content = $article->getAttachmentContent(1); // Attachment ID 1
  

4. Bulk Operations

• CSV Import (e.g., text modules):

  $csvData = file_get_contents('modules.csv');
  $client->resource(ResourceType::TEXT_MODULE)->import($csvData);
  

5. Tags Management

• Add/remove tags to tickets:

  $client->resource(ResourceType::TAG)->add(1, 'urgent', 'Ticket');
  $client->resource(ResourceType::TAG)->remove(1, 'urgent', 'Ticket');
  

Integration Tips

• Error Handling: Always check for errors after API calls:

  if ($ticket->hasError()) {
      log::error($ticket->getError());
  }
  

• Debugging: Enable debug mode for verbose output:

  $client = new Client(['url' => '...', 'debug' => true]);
  

• Authentication: Use http_token or oauth2_token for token-based auth:

  $client = new Client(['url' => '...', 'http_token' => 'your-token']);
  

• On-Behalf-Of: Impersonate users:

  $client->setOnBehalfOfUser('impersonated-user@example.com');
  

Gotchas and Tips

Pitfalls

1. Field Validation: The client does not validate fields before save(). Zammad will reject invalid data (e.g., non-existent priority_id). Always check the API docs for valid values.

2. Resource Reuse:

   • After get(), search(), or all(), the Resource object is "consumed." Create a new one for subsequent operations:

     // ❌ Wrong: Reusing a consumed object
     $ticket->get(2); // Fetches ticket 2
     $ticket->get(3); // Fails silently or errors
     
     // ✅ Correct: New object
     $ticket2 = $client->resource(ResourceType::TICKET)->get(3);
     

3. Pagination Limits: Zammad enforces server-side limits (e.g., 500 items/page). Ignoring this may return truncated results.

4. Attachment IDs: Attachment IDs are local to the article. Fetch the article first to get valid IDs:

   $article = $ticket->getTicketArticles()[0];
   $attachments = $article->getValue('attachments'); // List IDs here
   

5. CSV Import Quirks:

   • Ensure CSV format matches Zammad’s expected structure (check API docs).
   • Large files may time out. Use chunked uploads or increase PHP’s max_execution_time.

Debugging Tips

• Inspect Last Response:

  $response = $client->getLastResponse();
  echo $response->getStatusCode(); // HTTP status
  echo $response->getBody();       // Raw response
  

• Enable Debug Output: Set 'debug' => true in the client config to log HTTP requests/responses.

Extension Points

1. Custom HTTP Client: Inject a PSR-18 client (e.g., Guzzle) for advanced use cases:

   use ZammadAPIClient\Client;
   use GuzzleHttp\Client as GuzzleClient;
   
   $httpClient = new GuzzleClient(['timeout' => 30]);
   $client = new Client(['url' => '...', 'http_client' => $httpClient]);
   

2. Event Hooks: Extend the Client or Resource classes to intercept requests/responses (e.g., logging, retries):

   $client->onRequest(function ($request) {
       logger()->debug('API Request:', ['url' => $request->getUri()]);
   });
   

3. Resource Extensions: Add custom methods to Resource objects via traits or inheritance:

   class ExtendedTicketResource extends \ZammadAPIClient\Resource {
       public function getCustomerName() {
           return $this->getValue('customer_user__name');
       }
   }
   

Configuration Quirks

• SSL Verification: Disable with 'verify' => false (insecure) or provide a CA bundle path:

  $client = new Client(['url' => '...', 'verify' => '/path/to/cabundle.pem']);
  

• Timeouts: Default is 5 seconds. Set to 0 for no timeout:

  $client = new Client(['url' => '...', 'timeout' => 15]);
  

Performance Tips

• Batch Operations: Use all() with pagination for large datasets instead of looping get().
• Caching: Cache frequent queries (e.g., ticket lists) in Laravel’s cache:

  $tickets = Cache::remember('tickets', 300, function () {
      return $client->resource(ResourceType::TICKET)->all();
  });