PHPackages                             rconfig/laravel-zabbix - 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. [Logging & Monitoring](/categories/logging)
4. /
5. rconfig/laravel-zabbix

ActiveLibrary[Logging & Monitoring](/categories/logging)

rconfig/laravel-zabbix
======================

Laravel-first Zabbix JSON-RPC API client with fluent, testable DX.

1.0.4(6mo ago)0641↑66.7%[3 PRs](https://github.com/rconfig/laravel-zabbix/pulls)MITPHPPHP ^8.2|^8.3|^8.4CI passing

Since Aug 9Pushed 2mo agoCompare

[ Source](https://github.com/rconfig/laravel-zabbix)[ Packagist](https://packagist.org/packages/rconfig/laravel-zabbix)[ Docs](https://github.com/rconfig/laravel-zabbix)[ RSS](/packages/rconfig-laravel-zabbix/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (6)Versions (8)Used By (0)

Laravel Zabbix by rConfig
=========================

[](#laravel-zabbix-by-rconfig)

[![Tests](https://github.com/rConfig/laravel-zabbix/actions/workflows/tests.yml/badge.svg)](https://github.com/rConfig/laravel-zabbix/actions/workflows/tests.yml)[![License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](LICENSE)[![PHP Version](https://camo.githubusercontent.com/d939ed2787af03e76ef8d8b6cd0ffa17e5da11b7772994ae6ac95f50cb146d5f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322532422d626c75653f6c6f676f3d706870)](https://www.php.net/)[![Laravel Version](https://camo.githubusercontent.com/b5810ddf412dce8aa7320d8f2307f6074f6f07b20ef7b9fb5155bb2bce0c849c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d31302e7825323025374325323031312e7825323025374325323031322e782d7265643f6c6f676f3d6c61726176656c)](https://laravel.com)

A Laravel-first, developer-friendly client for the [Zabbix JSON-RPC API](https://www.zabbix.com/documentation/current/en/manual/api) that makes monitoring integrations a breeze, developed by rConfig.

✨ Features
----------

[](#-features)

- 🎯 **Fluent, Eloquent-style queries** for hosts and host groups
- 🚀 **First-class developer experience** with expressive, chainable methods
- 🧪 **Local testing without a live Zabbix server** via HTTP fakes
- 🔧 **Optional real server integration** for end-to-end testing
- 📦 **Laravel package best practices** with auto-discovery
- 🔌 **Extensible design** for additional Zabbix endpoints

---

📦 Installation
--------------

[](#-installation)

Install via Composer:

```
composer require rconfig/laravel-zabbix
```

The service provider will be auto-discovered. Optionally publish the config:

```
php artisan vendor:publish --tag=zabbix-config
```

---

⚙️ Configuration
----------------

[](#️-configuration)

### Environment Variables

[](#environment-variables)

```
# Server connection
ZABBIX_BASE_URL=https://zabbix.example.com
ZABBIX_ENDPOINT=/api_jsonrpc.php

# Authentication (use token when possible)
ZABBIX_API_TOKEN=your_api_token_here

# Legacy fallback
ZABBIX_USERNAME=Admin
ZABBIX_PASSWORD=zabbix

# HTTP client settings
ZABBIX_TIMEOUT=15
ZABBIX_RETRIES=2

# Testing mode
ZABBIX_FAKE_BY_DEFAULT=true
```

### Config File

[](#config-file)

The config file at `config/zabbix.php` provides sensible defaults:

```
return [
    'base_url' => env('ZABBIX_BASE_URL', 'http://localhost'),
    'endpoint' => env('ZABBIX_ENDPOINT', '/api_jsonrpc.php'),

    // Prefer API token (Zabbix 5.4+)
    'token' => env('ZABBIX_API_TOKEN'),

    // Legacy authentication
    'username' => env('ZABBIX_USERNAME'),
    'password' => env('ZABBIX_PASSWORD'),

    // HTTP settings
    'timeout' => (int) env('ZABBIX_TIMEOUT', 15),
    'retries' => (int) env('ZABBIX_RETRIES', 2),
    'retry_sleep_ms' => (int) env('ZABBIX_RETRY_SLEEP_MS', 250),

    // Testing
    'fake_by_default' => env('ZABBIX_FAKE_BY_DEFAULT', true),
];
```

---

🚀 Quick Start
-------------

[](#-quick-start)

```
use Rconfig\Zabbix\Facades\Zabbix;

// Get API version
$version = Zabbix::apiVersion(); // "7.0.0"

// List all hosts
$hosts = Zabbix::hosts()->all();

// Find hosts with filters
$activeLinux = Zabbix::hosts()->where([
    'status' => 0,
    'name' => 'linux-server'
]);

// Create a new host
$newHost = Zabbix::hosts()->create([
    'host' => 'app-01',
    'interfaces' => [[
        'type' => 1, 'main' => 1, 'useip' => 1,
        'ip' => '10.0.0.50', 'port' => '10050'
    ]],
    'groups' => [['groupid' => '2']],
]);
```

---

🔍 Fluent Queries
----------------

[](#-fluent-queries)

Build complex queries with an Eloquent-style fluent interface:

### Hosts

[](#hosts)

```
$hosts = Zabbix::hosts()->get(
    Zabbix::hosts()->query()
        ->select(['hostid', 'host', 'status'])
        ->withInterfaces()
        ->withGroups()
        ->where(['status' => 0])
        ->limit(50)
        ->sort('host')
);
```

### Host Groups

[](#host-groups)

```
$groups = Zabbix::hostGroups()->get(
    Zabbix::hostGroups()->query()
        ->select(['groupid', 'name'])
        ->limit(20)
);
```

---

📊 Version Matrix & Compatibility
------------------------------------

[](#-version-matrix--compatibility)

Zabbix VersionTested MinorNotes6.0 LTS6.0.29Fully supported. `apiinfo.version` requires auth in some setups.7.x7.0.2Fully supported. Some methods differ slightly in param requirements.We recommend running your integration tests against **both LTS and current major** to catch method or parameter changes early.

🚫 Unsupported Operations
------------------------

[](#-unsupported-operations)

Some Zabbix API resources do not implement all CRUD operations.
For example, certain system resources cannot be created or deleted.

In these cases:

- Methods like `create()`, `update()`, or `delete()` will throw an `UnsupportedOperationException`
- This makes it clear the operation isn’t available for that resource, rather than failing silently.

Example:

```
use Rconfig\Zabbix\Exceptions\UnsupportedOperationException;

try {
    Zabbix::apiinfo()->delete(['id' => 1]);
} catch (UnsupportedOperationException $e) {
    echo $e->getMessage(); // "Delete is not supported for Apiinfo resource"
}

---

## 🛡️ Lightweight Parameter Validation

An **optional** guard can warn or throw if obviously invalid parameters are passed.
This is not a full schema validator — just common-sense checks to help catch mistakes early.

* Wrong data types for known fields
* Mutually exclusive params used together
* Missing required params for certain calls

Enable warnings in `.env`:

```env
ZABBIX_PARAM_VALIDATION=true
```

Example:

```
// Will trigger a warning about 'limit' being a string instead of an integer
Zabbix::hosts()->get(['limit' => 'fifty']);
```

---

🔐 Authentication
----------------

[](#-authentication)

### API Token (Recommended)

[](#api-token-recommended)

For Zabbix 5.4+ with API tokens:

```
ZABBIX_API_TOKEN=your_api_token_here
```

### Username/Password

[](#usernamepassword)

Legacy authentication fallback:

```
ZABBIX_USERNAME=Admin
ZABBIX_PASSWORD=zabbix
```

The package automatically chooses the best authentication method available.

---

🧪 Testing
---------

[](#-testing)

### Fake Mode (Default)

[](#fake-mode-default)

Perfect for local development and unit testing:

```
ZABBIX_FAKE_BY_DEFAULT=true
```

All API calls return realistic mock data without needing a real Zabbix server.

### Integration Testing

[](#integration-testing)

Test against a real Zabbix server:

```
RUN_ZABBIX_INTEGRATION=1
ZABBIX_BASE_URL=https://zabbix.example.com
ZABBIX_API_TOKEN=your_token
```

### Example Test

[](#example-test)

```
it('fetches hosts via fluent query', function () {
    $hosts = Zabbix::hosts()->all();
    expect($hosts)->toBeArray()->not->toBeEmpty();
});
```

⚠️ Error Handling
-----------------

[](#️-error-handling)

The package provides specific exceptions for different error types:

```
use Rconfig\Zabbix\Exceptions\ZabbixException;
use Rconfig\Zabbix\Exceptions\ZabbixHttpException;

try {
    $hosts = Zabbix::hosts()->all();
} catch (ZabbixException $e) {
    // API-level errors (invalid params, auth issues, etc.)
    logger()->error('Zabbix API error: ' . $e->getMessage());
} catch (ZabbixHttpException $e) {
    // HTTP transport errors (timeouts, connectivity, etc.)
    logger()->error('Zabbix HTTP error: ' . $e->getMessage());
}
```

🛠️ Local Development
--------------------

[](#️-local-development)

### Package Development Setup

[](#package-development-setup)

For developing this package alongside a Laravel application:

```
/code
  ├─ myapp/                   # Your Laravel app
  └─ rconfig-laravel-zabbix/  # This package

```

#### 1. Link the Package

[](#1-link-the-package)

In your Laravel app's `composer.json`:

```
{
  "repositories": [
    {
      "type": "path",
      "url": "../rconfig-laravel-zabbix",
      "options": { "symlink": true }
    }
  ]
}
```

#### 2. Install the Package

[](#2-install-the-package)

```
cd myapp
composer require rconfig/laravel-zabbix:"dev-main"
php artisan vendor:publish --tag=zabbix-config
```

#### 3. Test in Tinker

[](#3-test-in-tinker)

```
php artisan tinker
>>> use Rconfig\Zabbix\Facades\Zabbix;
>>> Zabbix::apiVersion()      // "7.0.0" (fake)
>>> Zabbix::hosts()->all()    // Mock data
```

#### 4. Quick Test Route

[](#4-quick-test-route)

```
// routes/web.php
Route::get('/zabbix-test', function () {
    return [
        'version' => Zabbix::apiVersion(),
        'hosts' => Zabbix::hosts()->all(5),
    ];
});
```

Here’s a clean way to add it to your main README so contributors (or future you) know exactly how to cut a release. I’d suggest adding a **"Releases"** or **"Publishing"** section at the bottom:

📦 Publishing a New Release
--------------------------

[](#-publishing-a-new-release)

We use [Semantic Versioning](https://semver.org/) for all releases.

### 1. Update the Changelog

[](#1-update-the-changelog)

- Edit `CHANGELOG.md`
- Add a new section at the top for the version you’re releasing:

```
## [0.1.0] - 2025-08-09
### Added
- Initial public release of the Laravel Zabbix client.
```

- Commit the changes:

```
git add CHANGELOG.md
git commit -m "docs: update changelog for v0.1.0"
git push origin main
```

### 2. Tag the Release

[](#2-tag-the-release)

Create an annotated Git tag and push it:

```
git tag -a v0.1.0 -m "v0.1.0 initial public release"
git push origin v0.1.0
```

### 3. Create the GitHub Release

[](#3-create-the-github-release)

1. Go to the [GitHub Releases](../../releases) page.
2. Click **Draft a new release**.
3. Select the tag you just pushed (`v0.1.0`).
4. Set the title to match the tag (e.g. `v0.1.0`).
5. Paste the changelog notes for that version.
6. Publish the release.

> 💡 **Tip:** If the Packagist webhook is active, the new version will appear there automatically within minutes.

---

🗺️ Roadmap
----------

[](#️-roadmap)

Planned features for future releases:

- Pagination Support
- More fluent convenience methods

🤝 Contributing
--------------

[](#-contributing)

We welcome contributions! Here's how to get started:

### Development Setup

[](#development-setup)

1. **Fork and clone** the repository
2. **Install dependencies:**```
    composer install
    ```
3. **Run the test suite:**```
    vendor/bin/pest
    ```
4. **Make your changes** in a feature branch
5. **Submit a pull request** with a clear description

### Coding Standards

[](#coding-standards)

- Follow **PSR-12** for PHP code style
- Use **Pint** for automatic formatting. Push to main will fail if there are formatting issues. ```
    vendor/bin/pint
    ```
- Keep methods **small and expressive**
- Add **tests** for new features and bug fixes
- Update **documentation** when applicable
- Use **meaningful commit messages**

### Running Tests

[](#running-tests)

```
# Run all tests with fakes
vendor/bin/pest

# Run integration tests (requires real Zabbix server)
RUN_ZABBIX_INTEGRATION=1 \
ZABBIX_BASE_URL=https://your-zabbix.com \
ZABBIX_API_TOKEN=your_token \
vendor/bin/pest
```

📄 License
---------

[](#-license)

This package is open-sourced software licensed under the [MIT license](LICENSE).

Code of Conduct
---------------

[](#code-of-conduct)

While we aren't directly affiliated with Zabbix or Laravel, but we follow their respective Codes of Conduct. We expect you to abide by these guidelines as well.

Authors
-------

[](#authors)

This library is created by rConfig Developers.

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE) for more information.

**Built with ❤️ by rConfig for the Zabbix and Laravel communities**

###  Health Score

43

—

FairBetter than 91% of packages

Maintenance79

Regular maintenance activity

Popularity17

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity58

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 ~9 days

Total

3

Last Release

182d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/20505440?v=4)[rConfig](/maintainers/rConfig)[@rconfig](https://github.com/rconfig)

---

Top Contributors

[![rconfig](https://avatars.githubusercontent.com/u/20505440?v=4)](https://github.com/rconfig "rconfig (10 commits)")

---

Tags

apiclientlaravelmonitoringfluentjson-rpczabbix

###  Code Quality

TestsPest

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/rconfig-laravel-zabbix/health.svg)

```
[![Health](https://phpackages.com/badges/rconfig-laravel-zabbix/health.svg)](https://phpackages.com/packages/rconfig-laravel-zabbix)
```

PHPackages © 2026

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