PHPackages                             bytes-commerce/zabbix-api - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. bytes-commerce/zabbix-api

ActiveSymfony-bundle[API Development](/categories/api)

bytes-commerce/zabbix-api
=========================

A PHP library for interacting with the Zabbix API using JSON-RPC 2.0

1.2.3.2(3mo ago)0512↑162.5%proprietaryPHPPHP >=8.3CI passing

Since Jan 18Pushed 3mo agoCompare

[ Source](https://github.com/bytes-commerce/zabbix-api)[ Packagist](https://packagist.org/packages/bytes-commerce/zabbix-api)[ RSS](/packages/bytes-commerce-zabbix-api/feed)WikiDiscussions master Synced today

READMEChangelog (8)Dependencies (27)Versions (15)Used By (0)

Zabbix API Symfony Bundle
=========================

[](#zabbix-api-symfony-bundle)

Modern Symfony bundle for Zabbix API integration with persistent authentication, type-safe actions, and history data retrieval.

Features
--------

[](#features)

✨ **Persistent Session Management** - Automatic token caching with retry-on-failure 🏭 **Factory Pattern** - Type-safe action instantiation 📊 **History Data Retrieval** - Query monitoring data with type-specific methods 🔒 **Self-Contained Actions** - No globals, clean architecture 🎯 **PHP 8.3+ Ready** - Full strict typing, readonly properties, enums ⚡ **Zero Configuration** - Works out of the box with environment variables 📦 **Complete API Coverage** - Host, HostGroup, Item, History, Graph, Trigger, and more 🚀 **Asynchronous Monitoring** - Push metrics and events via Symfony Messenger 🛠️ **Automatic Setup** - Auto-provisioning of hosts, items, and dashboards

```
composer require bytes-commerce/zabbix-api
```

Bundle auto-registers via Symfony Flex.

Quick Start
-----------

[](#quick-start)

### 1. Configure

[](#1-configure)

Create `.env.local`:

```
ZABBIX_API_BASE_URI=https://zabbix.example.com/api_jsonrpc.php
ZABBIX_USERNAME=monitoring_user
ZABBIX_PASSWORD=secure_password
ZABBIX_AUTH_TTL=3600  # Optional: cache TTL in seconds
APP_NAME=MyApplication # Used for host identification
```

### 2. Use Actions (Recommended)

[](#2-use-actions-recommended)

```
use BytesCommerce\ZabbixApi\ZabbixServiceInterface;
use BytesCommerce\ZabbixApi\Actions\History;
use BytesCommerce\ZabbixApi\Actions\HostGroup;
use BytesCommerce\ZabbixApi\Actions\Dto\GetHostGroupDto;
use BytesCommerce\ZabbixApi\Enums\HistoryTypeEnum;

class MonitoringController
{
    public function __construct(
        private readonly ZabbixServiceInterface $zabbix
    ) {}

    public function cpuMetrics(): array
    {
        // Factory pattern - type-safe instantiation
        $history = $this->zabbix->action(History::class);

        // Get last 24 hours of CPU data (float values)
        return $history->getLast24Hours(
            itemIds: ['12345'],
            historyType: HistoryTypeEnum::NUMERIC_FLOAT,
            limit: 100
        );
    }

    public function getHostGroups(): array
    {
        // Get all host groups
        $hostGroup = $this->zabbix->action(HostGroup::class);
        $dto = new GetHostGroupDto(
            groupids: null,
            hostids: null,
            filter: null,
            output: 'extend',
            selectHosts: true,
            selectTemplates: null,
            sortfield: null,
            sortorder: null,
            limit: null,
            preservekeys: null,
        );

        return $hostGroup->get($dto)->hostGroups;
    }
}
```

Core Concepts
-------------

[](#core-concepts)

### Actions (Self-Contained API Modules)

[](#actions-self-contained-api-modules)

Each action represents a Zabbix API namespace:

Action ClassAPI PrefixMethods Example`History``history``get()`, `getLast24Hours()`, `getLatest()``Host``host``get()`, `create()`, `update()`, `delete()``HostGroup``hostgroup``get()`, `create()`, `update()`, `delete()`, `exists()`, `getObjects()`, `isReadable()`, `isWritable()`, `massAdd()`, `massRemove()`, `massUpdate()``Dashboard``dashboard``get()`, `create()`, `update()`, `delete()``Item``item``get()`, `create()`, `update()`, `delete()``User``user``login()`### Factory Pattern

[](#factory-pattern)

```
// Instantiate actions via factory
$hostAction = $zabbix->action(Host::class);
$hosts = $hostAction->get(['output' => 'extend']);

// Type-safe - IDE autocomplete works
$history = $zabbix->action(History::class);
$data = $history->getLast24Hours(['itemId']);
```

### Persistent Authentication

[](#persistent-authentication)

**Authentication is automatic** - no manual login needed:

1. First request checks cache (`zabbix_bearer_token`)
2. If missing: auto-login via `user.login`, store token with TTL
3. If expired during request: invalidate → re-login → retry once
4. Token sent as `Authorization: Bearer ` header

```
// No manual auth - handled transparently
$history = $zabbix->action(History::class);
$data = $history->getLatest(['12345']); // Auto-authenticates if needed
```

Usage Examples
--------------

[](#usage-examples)

### History Data Retrieval

[](#history-data-retrieval)

```
use BytesCommerce\ZabbixApi\Actions\History;
use BytesCommerce\ZabbixApi\Enums\HistoryTypeEnum;

$history = $zabbix->action(History::class);

// Latest values (default: last 10)
$latest = $history->getLatest(
    itemIds: ['10084', '10085'],
    historyType: HistoryTypeEnum::NUMERIC_FLOAT
);

// Custom time range
$data = $history->get(
    itemIds: ['10084'],
    historyType: HistoryTypeEnum::NUMERIC_UNSIGNED,
    timeFrom: strtotime('-7 days'),
    timeTill: time(),
    limit: 500
);

// Last 24 hours (convenience method)
$recent = $history->getLast24Hours(
    itemIds: ['10084'],
    historyType: HistoryTypeEnum::LOG
);
```

### History Data Types

[](#history-data-types)

EnumValueUse Case`NUMERIC_FLOAT`0CPU load, temperature, percentages`CHARACTER`1Short strings`LOG`2Log file entries`NUMERIC_UNSIGNED`3Disk space, counts (default)`TEXT`4Long text values`BINARY`5Base64-encoded binary (Zabbix 6.0+)### Host Management

[](#host-management)

```
use BytesCommerce\ZabbixApi\Actions\Host;

$host = $zabbix->action(Host::class);

// Get hosts with filters
$hosts = $host->get([
    'output' => ['hostid', 'name', 'status'],
    'filter' => ['status' => 0],  // Active hosts only
    'limit' => 50
]);

// Create host
$result = $host->create([[
    'host' => 'New Server',
    'groups' => [['groupid' => '2']],
    'interfaces' => [[
        'type' => 1,
        'main' => 1,
        'useip' => 1,
        'ip' => '192.168.1.100',
        'dns' => '',
        'port' => '10050'
    ]]
]]);

// Update host
$host->update([[
    'hostid' => '10084',
    'status' => 0
]]);

// Delete hosts
$host->delete(['10084', '10085']);
```

### HostGroup Management

[](#hostgroup-management)

```
use BytesCommerce\ZabbixApi\Actions\HostGroup;
use BytesCommerce\ZabbixApi\Actions\Dto\GetHostGroupDto;

$hostGroup = $zabbix->action(HostGroup::class);

// Get host groups with DTO
$dto = new GetHostGroupDto(
    groupids: ['15'],
    hostids: null,
    filter: null,
    output: 'extend',
    selectHosts: true,
    selectTemplates: null,
    sortfield: null,
    sortorder: null,
    limit: null,
    preservekeys: null,
);
$groups = $hostGroup->get($dto)->hostGroups;

// Create host group
$createDto = new CreateHostGroupDto([
    ['name' => 'Linux Servers'],
    ['name' => 'Windows Servers'],
]);
$result = $hostGroup->create($createDto);
echo "Created group IDs: " . implode(', ', $result->groupids);

// Update host group
$updateDto = new UpdateHostGroupDto([
    [
        'groupid' => '15',
        'name' => 'Linux Production Servers',
    ],
]);
$result = $hostGroup->update($updateDto);

// Delete host groups
$deleteDto = new DeleteHostGroupDto(['15', '16']);
$hostGroup->delete($deleteDto);

// Check if host group exists
$existsDto = new ExistsHostGroupDto(
    groupids: ['15'],
    hostids: null,
    filter: null,
    name: null,
);
$exists = $hostGroup->exists($existsDto)->exists;

// Get host groups by filters
$getObjectsDto = new GetObjectsHostGroupDto(
    groupids: null,
    hostids: null,
    filter: ['name' => 'Linux'],
    name: null,
);
$groups = $hostGroup->getObjects($getObjectsDto)->hostGroups;

// Check if host groups are readable
$isReadableDto = new IsReadableHostGroupDto(
    groupids: ['15'],
    hostids: null,
);
$isReadable = $hostGroup->isReadable($isReadableDto)->isReadable;

// Check if host groups are writable
$isWritableDto = new IsWritableHostGroupDto(
    groupids: ['15'],
    hostids: null,
);
$isWritable = $hostGroup->isWritable($isWritableDto)->isWritable;

// Mass add hosts to host groups
$massAddDto = new MassAddHostGroupDto(
    groups: ['15'],
    hosts: ['10084', '10085'],
    templates: null,
);
$result = $hostGroup->massAdd($massAddDto);

// Mass remove hosts from host groups
$massRemoveDto = new MassRemoveHostGroupDto(
    groupids: ['15'],
    hostids: ['10084'],
    templateids: null,
);
$result = $hostGroup->massRemove($massRemoveDto);

// Mass update host groups
$massUpdateDto = new MassUpdateHostGroupDto(
    groups: ['15'],
    hosts: ['10084', '10085'],
    templates: null,
);
$result = $hostGroup->massUpdate($massUpdateDto);
```

### Dashboard Management

[](#dashboard-management)

```
use BytesCommerce\ZabbixApi\Actions\Dashboard;
use BytesCommerce\ZabbixApi\Actions\Dto\GetDashboardDto;

$dashboard = $zabbix->action(Dashboard::class);

// Get dashboards with DTO
$dto = new GetDashboardDto(
    dashboardids: ['15'],
    filter: null,
    output: 'extend',
    selectPages: true,
    selectUsers: true,
    selectUserGroups: null,
    sortfield: null,
    sortorder: null,
    limit: null,
    preservekeys: null,
);
$dashboards = $dashboard->get($dto)->dashboards;

// Create dashboard
$createDto = new CreateDashboardDto([
    [
        'name' => 'Production Dashboard',
        'pages' => [
            [
                'name' => 'Overview',
                'widgets' => [],
            ],
        ],
    ],
]);
$result = $dashboard->create($createDto);
echo "Created dashboard IDs: " . implode(', ', $result->dashboardids);

// Update dashboard
$updateDto = new UpdateDashboardDto([
    [
        'dashboardid' => '15',
        'name' => 'Updated Dashboard',
    ],
]);
$result = $dashboard->update($updateDto);

// Delete dashboards
$deleteDto = new DeleteDashboardDto(['15', '16']);
$dashboard->delete($deleteDto);
```

### Item Operations

[](#item-operations)

```
use BytesCommerce\ZabbixApi\Actions\Item;
use BytesCommerce\ZabbixApi\Actions\Dto\GetItemDto;

$item = $zabbix->action(Item::class);

// Get items with DTO
$dto = new GetItemDto();
$dto->hostids = ['10084'];
$dto->output = 'extend';

$items = $item->get($dto)->items;

// Create item
$createDto = new CreateItemDto();
$createDto->items = [
    new CreateSingleItemDto(
        name: 'CPU Load',
        key_: 'system.cpu.load',
        hostid: '10084',
        type: ItemTypeEnum::ZABBIX_AGENT,
        value_type: ValueTypeEnum::NUMERIC_FLOAT,
        delay: '60s'
    )
];
$item->create($createDto);
```

### Manual AuthenticationUser Action

[](#manual-authenticationuser-action)

While automatic, you can manually trigger login if needed:

```
use BytesCommerce\ZabbixApi\Actions\User;

$user = $zabbix->action(User::class);
$token = $user->login('username', 'password');
// Token is now cached automatically
```

Asynchronous Operations (Messenger)
-----------------------------------

[](#asynchronous-operations-messenger)

The bundle integrates with Symfony Messenger to push metrics and events without blocking the main request.

### 1. Push Metrics

[](#1-push-metrics)

Send numeric values to Zabbix items:

```
use BytesCommerce\ZabbixApi\Message\PushMetricMessage;
use Symfony\Component\Messenger\MessageBusInterface;

public function trackLogin(MessageBusInterface $bus): void
{
    $bus->dispatch(new PushMetricMessage(
        key: 'app.user.login',
        value: 1,
        tags: ['env' => 'prod']
    ));
}
```

### 2. Push Events

[](#2-push-events)

Send complex event data:

```
use BytesCommerce\ZabbixApi\Message\PushEventMessage;
use Symfony\Component\Messenger\MessageBusInterface;

public function trackError(MessageBusInterface $bus, \Exception $e): void
{
    $bus->dispatch(new PushEventMessage(
        key: 'app.error',
        payload: [
            'message' => $e->getMessage(),
            'file' => $e->getFile(),
            'line' => $e->getLine()
        ]
    ));
}
```

### 3. Transport Configuration

[](#3-transport-configuration)

By default, messages are routed to the `async` transport. You can change this in your configuration:

```
zabbix_api:
  messenger_transport: async # Use 'sync' for immediate execution or 'false' to disable auto-routing
```

Automatic Setup
---------------

[](#automatic-setup)

The bundle can automatically ensure that the necessary Zabbix infrastructure (Hosts, Items, Dashboards) exists.

### Configuration

[](#configuration)

```
zabbix_api:
  setup_enabled: true
  app_name: 'My Application'
  host_group: 'Application Servers'
  dashboard_config_path: '%kernel.project_dir%/config/zabbix/dashboards'
```

### Usage

[](#usage)

When `setup_enabled` is true, the bundle will automatically dispatch an `EnsureZabbixSetupMessage` to verify and create the required resources in Zabbix.

Advanced Usage
--------------

[](#advanced-usage)

### ActionService (Backward Compatible)

[](#actionservice-backward-compatible)

For dynamic method calls:

```
use BytesCommerce\ZabbixApi\ActionServiceInterface;
use BytesCommerce\ZabbixApi\Actions\History;

public function __construct(
    private readonly ActionServiceInterface $actionService
) {}

public function dynamicCall(): mixed
{
    return $this->actionService->call(History::class, [
        'method' => 'get',
        'params' => [
            'itemids' => ['10084'],
            'history' => 3,
            'limit' => 100
        ]
    ]);
}
```

### Direct Low-Level Client

[](#direct-low-level-client)

For raw API calls:

```
use BytesCommerce\ZabbixApi\ZabbixClientInterface;
use BytesCommerce\ZabbixApi\Enums\ZabbixAction;

public function __construct(
    private readonly ZabbixClientInterface $client
) {}

public function rawCall(): mixed
{
    return $this->client->call(
        ZabbixAction::HISTORY_GET,
        ['itemids' => ['10084'], 'history' => 0, 'limit' => 10]
    );
}
```

Error Handling
--------------

[](#error-handling)

All errors throw `ZabbixApiException` with context:

```
use BytesCommerce\ZabbixApi\ZabbixApiException;

try {
    $result = $history->get(['10084']);
} catch (ZabbixApiException $e) {
    echo "Error: {$e->getMessage()}\n";
    echo "Code: {$e->getErrorCode()}\n";

    if ($data = $e->getErrorData()) {
        echo "Data: {$data}\n";
    }
}
```

### Auto-Retry on Auth Failure

[](#auto-retry-on-auth-failure)

Authentication errors (-32602, "Session terminated") trigger automatic recovery:

1. Cache invalidated
2. Fresh login performed
3. Original request retried once
4. If still fails: exception thrown

Configuration Reference
-----------------------

[](#configuration-reference)

### YAML (Optional)

[](#yaml-optional)

`config/packages/zabbix_api.yaml`:

```
zabbix_api:
  # API Connection
  base_uri: '%env(ZABBIX_API_BASE_URI)%'
  api_token: '%env(ZABBIX_API_TOKEN)%' # Alternative to username/password
  username: '%env(ZABBIX_USERNAME)%'
  password: '%env(ZABBIX_PASSWORD)%'
  auth_ttl: 3600  # seconds, default: 3600

  # Monitoring Configuration
  app_name: '%env(APP_NAME)%' # Application name for monitoring
  host_group: 'Application Servers' # Default Zabbix host group

  # Messenger Integration
  messenger_transport: async  # Messenger transport for Zabbix messages (e.g. async, sync, or false to disable auto-routing)

  # Automatic Setup
  setup_enabled: false # Enable Zabbix setup commands
  dashboard_config_path: '%kernel.project_dir%/config/zabbix/dashboards' # Path to dashboard configuration files
```

### Environment Variables

[](#environment-variables)

```
# Required (either API Token or Username/Password)
ZABBIX_API_BASE_URI=https://zabbix.example.com/api_jsonrpc.php
ZABBIX_API_TOKEN=your_api_token
# OR
ZABBIX_USERNAME=monitoring_user
ZABBIX_PASSWORD=secure_password

# Optional
ZABBIX_AUTH_TTL=3600  # Token cache TTL in seconds
APP_NAME=MyApplication # Used for host identification
```

Creating Custom Actions
-----------------------

[](#creating-custom-actions)

Extend `AbstractAction` and implement `getActionPrefix()`:

```
namespace App\Zabbix\Actions;

use BytesCommerce\ZabbixApi\Actions\AbstractAction;
use BytesCommerce\ZabbixApi\Enums\ZabbixAction;

final class CustomAction extends AbstractAction
{
    public static function getActionPrefix(): string
    {
        return 'custom';  // API prefix: custom.method
    }

    public function myMethod(array $params): array
    {
        $result = $this->client->call(
            ZabbixAction::from('custom.myMethod'),
            $params
        );

        return is_array($result) ? $result : [];
    }
}

// Usage
$custom = $zabbix->action(CustomAction::class);
$result = $custom->myMethod(['param' => 'value']);
```

Testing
-------

[](#testing)

```
# Run tests inside Docker
docker compose exec php bash -c "vendor/bin/phpunit"

# With coverage
docker compose exec php bash -c "XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-text"

# Static analysis
docker compose exec php bash -c "vendor/bin/phpstan analyse --level=max src"
```

Architecture
------------

[](#architecture)

- **ZabbixService**: Factory for action instantiation
- **ZabbixClient**: Low-level HTTP client with auth management
- **Actions**: Self-contained API modules (Host, HostGroup, Dashboard, Item, History, Graph, Trigger, etc.)
- **Enums**: Type-safe constants (HistoryTypeEnum, ZabbixAction, etc.)
- **DTOs**: Structured request/response objects

Requirements
------------

[](#requirements)

- PHP 8.3+
- Symfony 7.4+
- Zabbix API 7+ (tested with 8.0)

License
-------

[](#license)

MIT

Support
-------

[](#support)

For issues and feature requests, please use the GitHub issue tracker.

###  Health Score

43

—

FairBetter than 89% of packages

Maintenance80

Actively maintained with recent releases

Popularity17

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity57

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~7 days

Total

8

Last Release

115d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/7ecc09b9aec2e66ff72e4e7f5565a150845eb4a47935ecfdeb81725cd392be60?d=identicon)[bytes-commerce](/maintainers/bytes-commerce)

---

Top Contributors

[![bytes-max](https://avatars.githubusercontent.com/u/6654389?v=4)](https://github.com/bytes-max "bytes-max (34 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Rector

Type Coverage Yes

### Embed Badge

![Health badge](/badges/bytes-commerce-zabbix-api/health.svg)

```
[![Health](https://phpackages.com/badges/bytes-commerce-zabbix-api/health.svg)](https://phpackages.com/packages/bytes-commerce-zabbix-api)
```

###  Alternatives

[easycorp/easyadmin-bundle

Admin generator for Symfony applications

4.3k17.9M387](/packages/easycorp-easyadmin-bundle)[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.5k5.9M738](/packages/sylius-sylius)[sulu/sulu

Core framework that implements the functionality of the Sulu content management system

1.3k1.4M203](/packages/sulu-sulu)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

585.6M574](/packages/shopware-core)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)