Download the PHP package zammad/zammad-api-client-php without Composer
On this page you can find all versions of the php package zammad/zammad-api-client-php. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download zammad/zammad-api-client-php
More information about zammad/zammad-api-client-php
Files in zammad/zammad-api-client-php
Package zammad-api-client-php
Short Description Zammad API client for PHP
License AGPL-3.0 MIT
Homepage https://github.com/zammad/zammad-api-client-php
Informations about the package zammad-api-client-php
Zammad API Client for PHP
This client can be used to access the API of the open source helpdesk Zammad via PHP.
Zammad version support
This client supports Zammad 3.4.1 and newer.
Installation
Requirements
The API client needs composer. For installation have a look at its documentation. Additionally, the API client needs PHP 7.2 or newer.
Integration into your project
Add the following to the "require" section of your project's composer.json file:
Installing the API client's dependencies
Fetch the API client's code and its dependencies by updating your project's dependencies with composer:
Once installed, you have to include the generated autoload.php into your project's code:
How to use the API client
Example code
You can find example code within the directory examples
.
The Client object
Your starting point is the Client
object:
Besides using a combination of username
and password
, you can alternatively give an http_token
or an oauth2_token
.
Important: You have to activate API access in Zammad.
Fetching a single Resource object
To fetch a Resource
object by ID, e. g. a ticket with ID 34, use the Client
object:
$ticket
now is a Resource
object which holds the data of the ticket and provides all of the methods for setting/getting specific values (like the title of the ticket) and sending changed values to Zammad to update the ticket.
Note: Once you successfully called get
on a Resource
object, you cannot call it again, instead you have to create a new one with resource
.
Accessing values of Resource objects
You can access the values of a Resource
object via its 'value' methods.
Please note that the API client does not provide checks for nor does it know about the available fields of the Resource
objects. If you set or get a value of a non-existing field or set an invalid value, Zammad will ignore it or return an error.
So, how can you know which fields are available? Just fetch an existing Resource
object and have a look at the returned fields. A fresh Zammad system always contains an object with ID 1 for every resource type.
Additionally you can have a look at the REST interface documentation of Zammad:
Introduction to the REST interface
Fetching a ticket's articles
If you already have a ticket object, you can easily fetch its articles:
Fetching content of ticket article attachments
The content of ticket article attachments can be fetched with a call of getAttachmentContent()
of the ticket article resource object:
In the above example 23 is the ID of the attachment. This ID can be found within the attachments
array of the ticket article data. Usually you want to loop over this array to fetch the content of all attachments.
Updating Resource objects
If you fetched a Resource
object and changed some values, you have to send your changes to Zammad. You do this with a simple call:
save()
will check it itself but if you somehow need to know if a Resource
object has unsaved changes, you can check it with:
Note: Some resource types don't support updating the values of certain fields. Please refer to the API documentation (see links above).
Creating Resource objects
To create a new Resource
object, use the following code (example):
Searching Resource objects
Some types of resources can be searched, pagination is available.
Note that there is a configurable server-side limit for the number of returned objects (e. g. 500). This limit also applies to the number of entries per page. If you call search() with 1000 entries per page and the server-side limit is set to 500, the server-side limit will be applied.
A successful search (which might have zero results) returns an array of objects (or an empty array). If the result is the original caller object, there was an error (see error handling below). Therefore, the code for searching should look like the following:
Note: You cannot use a Resource
object that contains data (either via get
, search
, all
or by setting values on a new object) to execute a search. Use a new Resource
object instead.
Fetching 'all' Resource objects
For some types of resources, all available objects can be fetched, pagination is available.
A successful call of all
(which might have zero results) returns an array of objects (or an empty array). If the result is the original caller object, there was an error (see error handling below).
Therefore, the code to use all
should look like the following:
Note: You cannot use a Resource
object that contains data (either via get
, search
, all
or by setting values on a new object) to execute all
. Use a new Resource
object instead.
Deleting a Resource object
To be able to delete a Resource
object that exists in Zammad, you must first fetch it from Zammad, either via get
, all
or search
.
You can also delete a newly created Resource
object that has not been sent to Zammad yet. But this should only rarely be necessary because you can simply create a new Resource
object via the Client
object.
To delete a Resource
object, simply call delete
on it:
This clears the object from all data and if possible deletes it in Zammad. The PHP object itself remains. You can reuse it for another Resource
object or simply drop it.
Working with tags
Adding a tag to an object
Zammad can assign tags to an object. Currently this is only supported for ticket objects.
Remove a tag from an object
Getting all tags assigned to an object
Search for Tags
Object import
Besides the usual methods available for objects, there is also a method available to import these via CSV. Example for text module CSV import:
See Available resource types and their access methods below for resource types that support CSV import.
Handling Zammad errors
When you access Zammad, you always will get a Resource
object (or an array of such objects) in return, regardless if Zammad returned data or executed your request. In case of errors (e. g. that above ticket with ID 34 does not exist in Zammad), you will get a Resource
object with a set error which can be checked with the following code:
If you additionally need more detailed information about connection/request errors, you can access the Response
object of the Client
object. It holds the response of the last request that was made.
With this object, you can e. g. get the HTTP status code and the body of the last response.
Executing an API call on behalf of another user
If you want Zammad to execute an API call on behalf of another user than the one you used for authentication, use the following code before executing the API call(s):
Any API call after above code will use this setting. If you want to return to using the user you used for authentication, call:
Using this setting will be ignored by Zammad before version 2.4.
Available resource types and their access methods
To be able to use the 'short form' for the resource type, add a
to your code. You then can reference the resource type like
Resource type | get | all | search | save | delete | add | remove | import |
---|---|---|---|---|---|---|---|---|
TICKET | ✔ | ✔ | ✔ | ✔ | ✔ | – | – | – |
TICKET_ARTICLE | ✔ | – | ✔ | ✔ | ✔ | – | – | – |
TICKET_STATE | ✔ | ✔ | – | ✔ | ✔ | – | – | – |
TICKET_PRIORITY | ✔ | ✔ | – | ✔ | ✔ | – | – | – |
TEXT_MODULE | ✔ | ✔ | – | ✔ | ✔ | – | – | ✔ |
ORGANIZATION | ✔ | ✔ | ✔ | ✔ | ✔ | – | – | ✔ |
GROUP | ✔ | ✔ | – | ✔ | ✔ | – | – | – |
USER | ✔ | ✔ | ✔ | ✔ | ✔ | – | – | ✔ |
TAG | ✔ | – | ✔ | – | – | ✔ | ✔ | – |
Publishing
- Add release to CHANGELOG.md
- Commit, tag and push.
- As a logged-in user, use the "update" button on the packagist.org page of zammad-api-client-php to create the new version automatically from the git tag.
Contributing
Bug reports and pull requests are welcome on GitHub. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.