Zabbix Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require crifi/zabbix-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       Crifi\ZabbixBundle\CrifiZabbixBundle::class => ['all' => true],
   ];
   

2. Configuration Define Zabbix API credentials in config/packages/crifi_zabbix.yaml:

   crifi_zabbix:
       url: 'http://your-zabbix-server/api_jsonrpc.php'
       username: 'Admin'
       password: 'zabbix'
   

3. First Use Case: Fetch Hosts Inject the ZabbixClient service and call a method:

   use Crifi\ZabbixBundle\Client\ZabbixClient;
   
   class MyService {
       public function __construct(private ZabbixClient $zabbix) {}
   
       public function getHosts() {
           return $this->zabbix->host->get(['output' => 'extend']);
       }
   }
   

Implementation Patterns

Common Workflows

1. Host Management

   • Fetch hosts: $zabbix->host->get()
   • Create/update: $zabbix->host->create() or $zabbix->host->update()
   • Example: Bulk host creation from a CSV:

     $hosts = collect($csvData)->map(fn($row) => [
         'host' => $row['name'],
         'interfaces' => [['type' => 1, 'main' => 1, 'useip' => 1, 'ip' => $row['ip']]],
     ]);
     $this->zabbix->host->create($hosts->toArray());
     

2. Item/Trigger Operations

   • Link items to hosts:

     $item = [
         'hostid' => $hostId,
         'name' => 'CPU Load',
         'key_' => 'system.cpu.load[percpu,avg1]',
         'type' => 0,
     ];
     $this->zabbix->item->create($item);
     

3. Authentication & Rate Limiting

   • Use dependency injection for the client:

     public function __construct(private ZabbixClient $zabbix) {}
     

   • Handle API rate limits via middleware (extend ZabbixClient or wrap calls in a retry loop).

4. Event-Driven Integrations

   • Poll for alerts and trigger Symfony events:

     $alerts = $this->zabbix->alert->get(['output' => 'extend', 'selectHosts' => 'extend']);
     foreach ($alerts as $alert) {
         $this->dispatch(new ZabbixAlertEvent($alert));
     }
     

Gotchas and Tips

Pitfalls

1. Authentication Failures

   • Issue: Silent failures if credentials are wrong (no exception thrown).
   • Fix: Enable debug mode in config/packages/crifi_zabbix.yaml:

     debug: true
     

     Or wrap calls in a try-catch:

     try {
         $this->zabbix->host->get();
     } catch (\RuntimeException $e) {
         // Log or retry
     }
     

2. API Version Mismatch

   • Issue: The bundle defaults to Zabbix 5.0 API. If using a newer version (e.g., 6.0), override the version in config:

     api_version: '6.0'
     

3. Large Data Responses

   • Issue: API calls with output=extend return nested arrays, which can be memory-intensive.
   • Fix: Use output=shortenKeys or limit fields:

     $this->zabbix->host->get(['output' => 'shortenKeys', 'selectInterfaces' => 'extend']);
     

4. Idempotency in Updates

   • Issue: update() requires the hostid (or similar) to be included in the payload.
   • Fix: Always fetch the ID first or use create() with updateExisting=true (if supported).

Tips

1. Custom API Methods Extend the bundle by creating a custom client:

   use Crifi\ZabbixBundle\Client\ZabbixClient;
   
   class CustomZabbixClient extends ZabbixClient {
       public function getHostWithItems(int $hostId) {
           return $this->call('host.get', [
               'output' => 'extend',
               'filter' => ['hostid' => $hostId],
               'selectItems' => ['output' => 'extend'],
           ]);
       }
   }
   

   Register as a service in services.yaml:

   services:
       App\Service\CustomZabbixClient:
           arguments:
               $client: '@crifi_zabbix.client'
   

2. Caching Responses Cache frequent API calls (e.g., host lists) using Symfony’s cache system:

   $cache = $this->container->get('cache.app');
   $hosts = $cache->get('zabbix_hosts', function() {
       return $this->zabbix->host->get();
   });
   

3. Logging API Calls Add a subscriber to log all API requests:

   use Crifi\ZabbixBundle\Event\ZabbixEvent;
   
   class ZabbixLoggerSubscriber implements EventSubscriberInterface {
       public static function getSubscribedEvents() {
           return [ZabbixEvent::API_CALL => 'onApiCall'];
       }
   
       public function onApiCall(ZabbixEvent $event) {
           $this->logger->info('Zabbix API Call', [
               'method' => $event->getMethod(),
               'params' => $event->getParams(),
           ]);
       }
   }
   

4. Testing Mock the ZabbixClient in tests:

   $mock = $this->createMock(ZabbixClient::class);
   $mock->method('host->get')->willReturn([['hostid' => 1, 'host' => 'Test']]);
   $this->container->set('crifi_zabbix.client', $mock);
   

5. Environment-Specific Config Use Symfony’s parameter bag for environment-specific settings:

   # config/packages/dev/crifi_zabbix.yaml
   crifi_zabbix:
       debug: true
       timeout: 30