Download the PHP package zammad/zammad-api-client-php without Composer

Zammad API Client for PHP (v3)

PSR-compliant PHP client for the Zammad REST API. PHP 8.1+.

We want your feedback! Report a bug · Start a discussion

Quick Start

1. Install via Composer (published on Packagist):

Using Laravel or Symfony? See Framework integration to resolve ZammadClient from the container instead of constructing it by hand.

2. Connect — point the client at your Zammad instance and pass a personal access token:

3. Try it — fetch, create, update and search tickets:

That's it. The rest of this README covers authentication options, the DTO and error handling. Runnable recipes live in examples/cookbook/.

How to use

This library offers three interaction styles. Choose based on your use case:

Repositories are accessed via typed accessors: $client->ticket(), $client->user(), $client->organization(), $client->group(), $client->ticketArticle(), $client->ticketState(), $client->ticketPriority(), $client->tag(), $client->textModule(), $client->link(). The underlying repo() method is internal.

Connecting

Fetching

Accessing values

Creating

Updating

Stateful resource

$repo->resource($id) returns a Resource wrapper — not a DTO. Properties are accessed and mutated via __get/__set magic (not typed properties), and changes are automatically tracked. save() sends only modified fields; destroy() sends DELETE.

Use this for interactive workflows where you read, modify, then write. For single-field changes, prefer patch().

Choosing the right update method

patch() is the only update method. It accepts arrays, TicketUpdateDTO, or any DTO (via toArray()). Zammad uses HTTP PUT for all updates and merges the payload with the existing resource. Null values are excluded from all request bodies, so absent fields are never overwritten.

Deleting

All repositories expose a delete() method. Repositories implementing DeletableInterface perform the actual API call. Other repositories throw a BadMethodCallException — catchable, unlike a fatal error.

Searching

Listing all

Ticket articles

Tags

CSV import

All import() methods return an array — the Zammad API response containing import statistics (rows processed, skipped, errors). CSV format follows Zammad's import specification (header row with field names matching API field names).

Examples

The primary example is the examples/cookbook/ directory — runnable recipes covering tickets, stateful resources, pagination, error handling, impersonation, and search. Run them against any Zammad instance:

The env vars are named ...UNIT_TESTS... for historical reasons. They are used by integration tests and the cookbook example. Unit tests (make test) need no env vars.

For user and organization CRUD examples, refer to the integration tests in docs/migration-v3-examples.md.

Authentication

Framework integration

Prefer to resolve ZammadClient from your framework's container instead of constructing it by hand? Bridges are provided for Laravel and Symfony — configure credentials once, then inject the same shared client everywhere.

Full runnable setups: examples/cookbook/07-laravel.php and examples/cookbook/08-symfony.php.

Laravel

The service provider is auto-discovered (Laravel 5.5+). Publish the config and set your credentials in .env:

Then inject the shared ZammadClient anywhere via the container:

For older Laravel versions, register ZammadAPIClient\Bridge\LaravelServiceProvider::class in config/app.php manually.

Symfony

Register the bundle in config/bundles.php:

Configure credentials in config/packages/zammad.yaml:

Then type-hint ZammadClient in any service — autowiring injects the shared instance:

Error Handling

All errors are typed exceptions:

Data Transfer Objects (DTOs)

Each repository returns typed DTOs. Below are the fields for each DTO. Fields marked yes have no default and are required in the constructor. Fields marked creation are nullable in the type signature but required by the Zammad API when creating a new resource — omitting them will result in a ValidationException (422).

The id field is available both as a property ($dto->id) and a convenience method ($dto->id()). Both return the same server-assigned ID; prefer the property for readability.

TicketDTO

TicketUpdateDTO

Used with patch() for partial ticket updates. Only non-null fields are sent to the API.

UserDTO

OrganizationDTO

GroupDTO

TicketArticleDTO

TicketStateDTO

TicketPriorityDTO

TextModuleDTO

TagDTO

LinkDTO

Impersonation

Development

Unit tests

No environment variables needed. Unit tests mock the HTTP layer and run fully isolated.

Integration tests

These require a running Zammad instance and authentication credentials:

* Either ZAMMAD_PHP_API_CLIENT_UNIT_TESTS_TOKEN or USERNAME+PASSWORD must be set.

Migration from v2

See docs/migration-v3-examples.md for side-by-side code examples. v2 reference documentation is preserved in docs/v2-reference.md.

License

AGPL-3.0 or MIT.