itsjustvita / laravel-znuny
Laravel SDK for the Znuny / OTRS Community Edition Generic Interface REST API
Requires
- php: ^8.3
- illuminate/cache: ^12.0 || ^13.0
- illuminate/console: ^12.0 || ^13.0
- illuminate/events: ^12.0 || ^13.0
- illuminate/http: ^12.0 || ^13.0
- illuminate/log: ^12.0 || ^13.0
- illuminate/pagination: ^12.0 || ^13.0
- illuminate/routing: ^12.0 || ^13.0
- illuminate/support: ^12.0 || ^13.0
- nesbot/carbon: ^3.0
Requires (Dev)
- laravel/pint: ^1.0
- orchestra/testbench: ^10.0 || ^11.0
- phpstan/phpstan: ^2.1
- phpunit/phpunit: ^12.0
- symfony/yaml: ^7.0 || ^8.0
Suggests
- ext-fileinfo: Detects attachment MIME types in Attachment::fromPath()
Provides
None
Conflicts
None
Replaces
None
README
Laravel SDK for the Znuny / OTRS Community Edition Generic Interface REST API.
Works out of the box with the GenericTicketConnectorREST example web service that Znuny ships, and with any custom web service through configurable routes. You get typed DTOs, a fluent ticket search with batching and pagination, attachments, ticket history, session handling with automatic re-login, inbound webhooks, events, logging, and a generic call() for every other operation.
Contents
- Requirements
- Installation
- Setting up the web service in Znuny
- Configuration
- Tickets
- Searching tickets
- Attachments
- Calling any operation
- Lookups (custom operations)
- Dynamic fields
- Webhooks (Znuny to Laravel)
- Events
- Logging
- Exceptions
- Artisan commands
- Troubleshooting
- Testing your application
- Upgrading
Requirements
- PHP 8.3+
- Laravel 12 or 13
- Znuny 6.5 or 7.x with a Generic Interface web service that has a REST provider. Every change is tested against real Znuny 6.5, 7.0, 7.1, 7.2 and 7.3 instances. Znuny 6.0 and OTRS 6 work too: set
'auth_transport' => 'payload'(they do not read authentication headers) and, for their example web service,'routes' => 'generic-ticket-connector-classic'.
Installation
composer require itsjustvita/laravel-znuny php artisan vendor:publish --tag=znuny-config
ZNUNY_BASE_URL=https://znuny.example.com/otrs/nph-genericinterface.pl/Webservice/GenericTicketConnectorREST ZNUNY_USERNAME=api-agent ZNUNY_PASSWORD=secret
php artisan znuny:test-connection
The command checks the login, the routes and the time zone setting.
Setting up the web service in Znuny
- Get the web service definition:
-
Znuny 6.5.11+ and 7.1.3+ list
GenericTicketConnectorRESTunder Admin → Web Services → Add Web Service → Ready2Adopt Web Services. Import it there; the default route preset matches it. -
For every other version, for other routes and for webhooks, generate the definition from your connection:
php artisan znuny:webservice --output=znuny-webservice.yml
and import it under Admin → Web Services → Add Web Service → Import web service, or on the Znuny server with
bin/otrs.Console.pl Admin::WebService::Add --name GenericTicketConnectorREST --source-path znuny-webservice.yml. CI imports generated definitions into Znuny 6.5, 7.0, 7.1, 7.2 and 7.3.
-
- Keep the name
GenericTicketConnectorRESTor choose your own. The base URL ishttps://<host>/otrs/nph-genericinterface.pl/Webservice/<name>; use your installation's script alias if it is not/otrs/. - Create an agent for the API and give it permissions on the queues it needs.
Web services that were set up from the older example in development/webservices/ (they search with GET /Ticket) need 'routes' => 'generic-ticket-connector-classic'. php artisan znuny:test-connection tells you whether the routes match.
Configuration
Connections
// config/znuny.php 'connections' => [ 'default' => [ 'base_url' => env('ZNUNY_BASE_URL'), 'username' => env('ZNUNY_USERNAME'), 'password' => env('ZNUNY_PASSWORD'), 'routes' => env('ZNUNY_ROUTES', 'generic-ticket-connector'), 'auth' => env('ZNUNY_AUTH', 'session'), 'user_type' => env('ZNUNY_USER_TYPE', 'agent'), 'auth_transport' => env('ZNUNY_AUTH_TRANSPORT', 'auto'), 'verify_ssl' => env('ZNUNY_VERIFY_SSL', true), 'timeout' => env('ZNUNY_TIMEOUT', 30), 'connect_timeout' => env('ZNUNY_CONNECT_TIMEOUT', 3), ], ],
verify_ssl is true, false or the absolute path of a CA bundle; any other value is rejected, so a typo cannot switch certificate verification off.
A connection can also set retries, retry_delay (milliseconds), batch_size and search_limit; they default to the values under http. Retries repeat reads after timeouts and server errors. Writes such as TicketCreate and TicketUpdate are only repeated when no connection could be established, so a slow Znuny never receives the same ticket twice.
Routes
Znuny maps REST routes to operations per web service. Tell the package which routes yours uses:
routes |
Meaning |
|---|---|
generic-ticket-connector (default) |
The example web service Znuny ships (var/webservices/examples/): POST /Session, GET/DELETE /Session/:SessionID, POST /Ticket, GET /Ticket/:TicketID, POST /Ticket/Search, PATCH /Ticket/:TicketID, GET /Ticket/History/:TicketID |
generic-ticket-connector-classic |
The older example (development/webservices/) that many OTRS and Znuny installations were set up from: like the default, but GET /Ticket (search), GET /TicketHistory/:TicketID and GET /TicketList |
operation-name |
Routes named after the operations: POST /<Operation>, plus POST /TicketGet/:TicketID, POST /TicketUpdate/:TicketID and POST /QueueGet/:QueueID |
| array | Your own mapping in Znuny's notation "METHOD /Path/:Param", optionally starting from a preset with extends |
'routes' => [ 'extends' => 'generic-ticket-connector', 'QueueList' => 'GET /Queue', // custom operations of your web service 'FAQSearch' => 'POST /FAQ/Search', ],
Operations without a mapping are sent to POST /<Operation>. php artisan znuny:routes prints the effective routes of a connection.
For GET routes the parameters go into the query string the way Znuny parses it (States=new&States=open). Nested parameters such as dynamic field search conditions cannot be expressed in a query string. This affects TicketSearch with the classic preset; to search by dynamic fields there, add a POST route for TicketSearch to the web service and map it, e.g. 'TicketSearch' => 'POST /Ticket/Search'.
Authentication
| Key | Values | Default |
|---|---|---|
auth |
session: log in once via SessionCreate and reuse the cached SessionID; an expired session is replaced and the request retried once. credentials: send login and password with every request. |
session |
user_type |
agent (UserLogin) or customer (CustomerUserLogin) |
agent |
auth_transport |
auto: X-OTRS-Header-* headers for GET routes, request data otherwise. payload: always in the request data. headers: always as headers. |
auto |
Headers keep session IDs and passwords out of URLs and access logs. They need Znuny 6.5 or newer; on older versions use payload.
Znuny binds a session to the IP address that created it and deletes it when another address uses it. The package therefore keeps one session per host name, so servers and workers that share a cache store do not invalidate each other's session.
- If a single host reaches Znuny from changing addresses, use
'auth' => 'credentials'or switch offSessionCheckRemoteIPin Znuny. - Hosts with short-lived names, such as autoscaled containers or job pods, log in once each. If they all reach Znuny from the same address,
ZNUNY_SESSION_PER_HOST=falselets them share one session.
Time zone
'timezone' => env('ZNUNY_TIMEZONE', 'UTC'),
Znuny reads search dates and returns dates in its OTRSTimeZone (Admin → System Configuration), whatever the time zone of your app is. It is UTC unless an administrator changed it. If your Znuny uses another time zone, set ZNUNY_TIMEZONE to the name Znuny shows, for example Europe/Berlin; otherwise dates and date filters are off by Znuny's UTC offset. Offsets and abbreviations that Znuny does not offer, such as +02:00 or CEST, are rejected because they ignore daylight saving time; the legacy names CET, EET, MET, WET, EST, MST and HST are replaced by their region, for example CET by Europe/Brussels. A connection can override the value with its own timezone key.
php artisan znuny:test-connection checks the setting against the dates Znuny returns. It compares the UTC offsets for the newest ticket and, if they exist, for tickets from about four and eight months ago, and fails with a hint if they differ.
Multiple and runtime connections
use ItsJustVita\LaravelZnuny\Facades\Znuny; Znuny::connection('tenant-a')->tickets()->find('12345'); // Connections that only exist at runtime, e.g. stored per tenant: Znuny::build([ 'name' => 'tenant-42', // optional; shown in logs and events 'base_url' => $tenant->znuny_url, 'username' => $tenant->znuny_user, 'password' => $tenant->znuny_password, 'routes' => 'operation-name', ])->tickets()->find('12345'); // Shorthand: Znuny::usingCredentials($url, $username, $password, options: ['routes' => 'operation-name']);
Tickets
use ItsJustVita\LaravelZnuny\Data\Attachment; use ItsJustVita\LaravelZnuny\Facades\Znuny; $ticket = Znuny::tickets()->find('12345'); $ticket = Znuny::tickets()->find('12345', withArticles: true, withDynamicFields: true, withAttachments: true); $tickets = Znuny::tickets()->findMany(['12345', '12346']); // batched; keeps the order $ticket = Znuny::tickets()->create([ 'title' => 'Printer on fire', 'queue' => 'Support', 'state' => 'new', 'priority' => '3 normal', 'customerUser' => 'jane@example.com', ]) ->withArticle([ 'subject' => 'Printer on fire', 'body' => 'Please send help.', 'contentType' => 'text/plain; charset=utf8', 'communicationChannel' => 'Email', 'senderType' => 'customer', ]) ->withDynamicFields(['OrderId' => 'ORD-2026-001']) ->withAttachments([Attachment::fromPath(storage_path('app/photo.jpg'))]) ->save(); // returns the created Ticket Znuny::tickets()->update('12345', ['state' => 'open'], dynamicFields: ['OrderId' => 'ORD-2']); $articleId = Znuny::tickets()->addArticle('12345', [ 'subject' => 'Internal note', 'body' => 'Customer called back.', 'communicationChannel' => 'Internal', 'senderType' => 'agent', 'isVisibleForCustomer' => false, ]); Znuny::tickets()->close('12345'); // state "closed successful" Znuny::tickets()->lock('12345'); // and unlock() Znuny::tickets()->assign('12345', 'agent-login'); // an int is an agent ID Znuny::tickets()->move('12345', 'Second Level'); // an int is a queue ID Znuny::tickets()->setPending('12345', now()->addDays(3)); // "pending reminder" Znuny::tickets()->setPending('12345', now()->addWeek(), 'pending auto close+'); $ticket = Znuny::tickets()->findByNumber('2026110610000017'); // the number customers see $history = Znuny::tickets()->history('12345'); // Collection<HistoryEntry>
A pendingTime in create() and update() can be any DateTimeInterface; it is converted to Znuny's time zone and read to the minute. $ticket->pendingUntil is the pending time while the ticket is in a pending state, null otherwise. findByNumber() matches the exact number only: wildcards never match, so a number a customer enters returns that ticket or none. Whether the ticket belongs to that customer is still for your application to check.
Input keys are camelCase (queueId, customerUser, isVisibleForCustomer, …). Any other key is passed to Znuny unchanged, so 'HistoryComment' => '…' works too. Articles are sent as text/plain; charset=utf8 unless you pass a contentType (or mimeType and charset).
Ticket, Article and the other DTOs expose typed properties plus every raw field Znuny returned. Dates are CarbonImmutable.
$ticket->owner; // typed property $ticket->attribute('EscalationTime'); // raw field
Raw TicketGet parameters can be passed to find() and findMany(), for example find('12345', options: ['Extended' => 1, 'ArticleLimit' => 5]).
attribute() supports dot notation for nested data. TicketGet returns flat ticket fields, but webhook payloads include, for example, the customer user's data: $event->ticket()->attribute('CustomerUser.UserEmail').
Znuny checks permissions before existence:
find()on a ticket that does not exist usually throwsZnunyAccessDeniedException.findMany()skips tickets that are missing or not accessible.
Searching tickets
$tickets = Znuny::tickets() ->whereState(['new', 'open']) ->whereQueue('Support') ->whereCreatedAfter(now()->subDays(30)) ->whereChangedBefore(now()->subDay()) ->orderBy('Age', 'desc') ->limit(50) ->get(); // Collection<Ticket> $page = Znuny::tickets()->whereCustomerUser('jane')->paginate(perPage: 25, page: 1); $count = Znuny::tickets()->whereLock('lock')->whereOwnerId(3)->count(); $ids = Znuny::tickets()->whereFullText('printer')->ids(); foreach (Znuny::tickets()->whereQueue('Support')->lazy(chunkSize: 100) as $ticket) { // processes tickets chunk by chunk } // Any TicketSearch parameter: Znuny::tickets()->where('CreatedUserIDs', [3, 4])->ids(); // Dynamic field conditions (the default preset searches via POST; for the classic preset see Routes): Znuny::tickets()->whereDynamicField('OrderId', 'ORD-*', 'Like')->ids();
| Filters | Znuny parameter |
|---|---|
whereTicketNumber(), whereTitle() (* is a wildcard) |
TicketNumber, Title |
whereState(), whereStateId(), whereStateType() |
States, StateIDs, StateType |
whereQueue(), whereQueueId() |
Queues, QueueIDs |
wherePriority(), wherePriorityId(), whereType(), whereTypeId() |
Priorities, PriorityIDs, Types, TypeIDs |
whereOwnerId(), whereResponsibleId(), whereLock() |
OwnerIDs, ResponsibleIDs, Locks |
whereCustomerId(), whereCustomerUser() |
CustomerID, CustomerUserLogin |
whereService(), whereSla() |
Services, SLAs |
whereFullText() |
Fulltext (subject, body, From, To, Cc of the articles) |
whereDynamicField() |
DynamicField_<Name> |
includeArchived(), onlyArchived() |
SearchInArchive |
Filters with a plural Znuny parameter take a value or a list. All of them, and every other search method, can be called on Znuny::tickets() directly or on Znuny::tickets()->query().
Date filters accept any DateTimeInterface and convert it to Znuny's time zone; the dates of the returned tickets, articles and history entries are read in it as well.
| Filter | Compares |
|---|---|
whereCreatedAfter(), whereCreatedBefore() |
the creation time ($ticket->created) |
whereLastChangedAfter(), whereLastChangedBefore() |
the time of the last change ($ticket->changed) |
whereChangedAfter() |
the ticket history: any entry after the date |
whereChangedBefore() |
same as whereLastChangedBefore() |
whereClosedAfter(), whereClosedBefore() |
the close time |
wherePendingAfter(), wherePendingBefore() |
the pending time |
get(), paginate() and lazy() load articles and dynamic fields by default; use withoutArticles(), withoutDynamicFields() or withAttachments() to change that, and withOptions(['ArticleLimit' => 5]) for other TicketGet parameters. paginate() fetches all matching IDs first and then loads only the tickets of the requested page.
Incomplete results
Znuny cuts a search without a limit off at its SearchLimit, 500 tickets by default, and does not say so. The package therefore sends its own search_limit (500 by default): a search without limit() returns every matching ticket up to that number and throws a ZnunySearchLimitExceededException if more match. Then narrow the search down, call limit() to accept only the first tickets, or raise the limit:
ZNUNY_SEARCH_LIMIT=5000
A connection can have its own search_limit. The package's limit replaces Znuny's SearchLimit, so use at least that value if an administrator raised it. get() holds every ticket with its articles in memory; for more than a few hundred tickets use lazy() or paginate().
ZNUNY_SEARCH_LIMIT=null switches the check off, as in 0.2. Then a search that returns exactly 500 tickets is logged as a warning, because Znuny probably cut it off.
Attachments
use ItsJustVita\LaravelZnuny\Data\Attachment; Attachment::fromPath('/path/to/file.pdf'); // filename and MIME type detected Attachment::fromContent('report.csv', $csv, 'text/csv'); Attachment::fromUploadedFile($request->file('photo')); // MIME type detected from the content Attachment::fromStorage('tickets/photo.jpg', disk: 's3'); Znuny::tickets()->addArticle('12345', $article, attachments: [ Attachment::fromContent('log.txt', $log, 'text/plain'), ]); $ticket = Znuny::tickets()->find('12345', withAttachments: true); foreach ($ticket->articles as $article) { foreach ($article->attachments as $attachment) { Storage::put($attachment->filename, $attachment->content); // decoded bytes } }
Calling any operation
Every other operation — Znuny add-ons such as FAQ or ITSM, or your own — goes through the same routing, authentication, error handling, events and logging:
$result = Znuny::call('FAQSearch', ['Title' => 'VPN*']); $result = Znuny::connection('tenant-a')->call('ConfigItemSearch', ['ConfigItem' => ['Number' => '1000*']]);
call() returns Znuny's decoded response as an array.
Lookups (custom operations)
Znuny has no operations for listing queues, states, priorities, types or customer users. If your web service exposes such custom operations, these helpers use them and cache the results (see cache.ttl):
| Method | Operation | Expected response |
|---|---|---|
Znuny::queues()->all(), findByName() |
QueueList |
{"Queue": [{"QueueID", "Name", "GroupID", "ValidID", "Comment"}]} |
Znuny::queues()->find($id) |
QueueGet (QueueID) |
{"Queue": [{...}]} |
Znuny::states()->all() |
StateList |
{"State": [{"StateID", "Name", "TypeName", "ValidID"}]} |
Znuny::priorities()->all() |
PriorityList |
{"Priority": [{"PriorityID", "Name", "ValidID"}]} |
Znuny::types()->all() |
TypeList |
{"Type": [{"TypeID", "Name", "ValidID"}]} |
Znuny::customers()->find($id) |
CustomerUserGet (CustomerUserID) |
{"CustomerUser": [{"CustomerID", "UserLogin", "UserEmail", ...}]} |
If the web service does not expose an operation you get a ZnunyRouteNotFoundException. Map the operations in routes if they use other paths.
Dynamic fields
// 1. Plain array, always works ->withDynamicFields(['OrderId' => 'ORD-001', 'Segment' => 'business']) // 2. Validation in config/znuny.php 'dynamic_fields' => [ 'Segment' => ['type' => 'string', 'allowed' => ['business', 'private']], 'Amount' => ['type' => 'float', 'min' => 0], 'Tags' => ['type' => 'array', 'allowed' => ['vip', 'urgent']], 'Rating' => ['type' => 'integer', 'min' => 1, 'max' => 5], 'Flag' => ['type' => 'boolean'], ], // Invalid values throw InvalidDynamicFieldException before anything is sent (create and update). // 3. Typed helper generated from that config php artisan znuny:generate-fields
Webhooks (Znuny to Laravel)
The package can receive Znuny's outgoing events and dispatch them as Laravel events.
-
Enable the endpoint and set a secret:
ZNUNY_WEBHOOKS_ENABLED=true ZNUNY_WEBHOOK_TOKEN=a-long-random-string
This registers
POST /znuny/webhooks/{event?}(seewebhooks.route_prefix) with theapimiddleware group and theznuny.webhookauthentication middleware. -
In Znuny create a web service with a requester. The easiest way is to generate it together with the provider routes and import it (see Setting up the web service):
php artisan znuny:webservice --webhooks=TicketCreate,ArticleCreate --webhook-url=https://your-app.example.com --output=znuny-webservice.yml
The file contains
CHANGE-MEwhere the secret belongs;--with-tokenwrites it instead. Webhooks are delivered by the Znuny daemon;--syncsends them during the triggering request. To set the requester up by hand:- network transport
HTTP::RESTwith the endpointhttps://your-app.example.com/znuny/webhooks; - an invoker of type
Ticket::Generic, triggered by the events you need (for exampleTicketCreate,ArticleCreate,TicketStateUpdate); - a controller mapping for the invoker, e.g.
POSTto/TicketCreate(the last path segment becomes the event name); - the additional header
X-Znuny-Token: <your token>(orAuthorization: Bearer <your token>). Alternatively use Znuny's BasicAuth together withZNUNY_WEBHOOK_AUTH=basic,ZNUNY_WEBHOOK_USERNAMEandZNUNY_WEBHOOK_PASSWORD.
- network transport
-
Listen to the event:
use ItsJustVita\LaravelZnuny\Events\ZnunyWebhookReceived; Event::listen(function (ZnunyWebhookReceived $event) { if ($event->is('TicketCreate')) { $ticket = $event->ticket(); // built from the payload; null if no ticket data was sent // dates use the configured time zone; for another Znuny: ticket('Europe/Berlin') // $event->ticketId, $event->articleId, $event->payload, $event->parameters } });
The endpoint answers 200 {}; Znuny applies data returned by the endpoint to the ticket, so nothing else is returned. Requests without valid credentials get 401, and if no secret is configured every request is rejected.
For several Znuny systems, for example one per tenant, register your own route with the middleware:
use ItsJustVita\LaravelZnuny\Webhooks\WebhookController; Route::post('tenants/{tenant}/znuny', WebhookController::class)->middleware('znuny.webhook'); // $event->parameters === ['tenant' => 'acme']
Events
| Event | Fired when |
|---|---|
ZnunyRequestSent |
before every HTTP call (connection, operation, method, path, redacted payload) |
ZnunyResponseReceived |
after a successful response (responseTimeMs, status, response) |
ZnunyRequestFailed |
when a call fails (exception) |
ZnunySessionRefreshed |
after an expired session was replaced |
ZnunyTicketCreated |
after create()->save() |
ZnunyTicketUpdated |
after update() (changes, dynamicFields) |
ZnunyArticleAdded |
after addArticle() (article, articleId) |
ZnunyWebhookReceived |
when Znuny calls the webhook endpoint |
Passwords, session IDs and tokens are replaced with [REDACTED] in event payloads, logs and exceptions.
Logging
The package logs to the channel named in znuny.logging.channel (ZNUNY_LOG_CHANNEL, default znuny). If your application does not define that channel, the package registers it as a daily file, storage/logs/znuny.log. To log elsewhere, define the channel yourself or point ZNUNY_LOG_CHANNEL at an existing one, e.g. stack:
// config/logging.php 'channels' => [ 'znuny' => [ 'driver' => 'daily', 'path' => storage_path('logs/znuny.log'), 'level' => 'debug', 'days' => 14, ], ],
znuny.logging.log_requests (info), log_responses (debug, with status and duration; attachment contents are shortened) and log_errors (error) control what is written. Set ZNUNY_LOGGING_ENABLED=false to turn logging off.
Exceptions
ZnunyException (abstract, extends RuntimeException)
├── ZnunyConfigurationException // invalid config, missing route parameter, nested GET parameter
│ └── ZnunyRouteNotFoundException // the web service has no route for the request
├── ZnunyConnectionException // network, timeout, TLS
├── ZnunyAuthenticationException // wrong credentials, HTTP 401/403
│ └── ZnunySessionExpiredException // handled by the automatic re-login
├── ZnunyAccessDeniedException // *.AccessDenied
├── ZnunyValidationException // *.MissingParameter, *.InvalidParameter, ...
│ ├── InvalidQueueException
│ ├── InvalidStateException
│ ├── InvalidPriorityException
│ └── InvalidDynamicFieldException
├── ZnunyNotFoundException
│ ├── TicketNotFoundException
│ ├── CustomerNotFoundException
│ └── QueueNotFoundException
├── ZnunySearchLimitExceededException // a search without limit() matches more than search_limit tickets
├── ZnunyRateLimitException
├── ZnunyServerException // HTTP 5xx, unexpected responses
└── GenericZnunyException // everything else
Every exception carries getOperation(), getErrorCode(), getConnection(), getHttpStatus(), the redacted getRequestPayload() and getResponseBody().
Artisan commands
| Command | Purpose |
|---|---|
znuny:test-connection [connection] |
Shows the connection settings, logs in, runs a TicketSearch and a TicketGet to check routing and permissions, and compares the time zone setting with the dates Znuny returns |
znuny:routes [connection] |
Prints the effective route map |
znuny:cache-clear [connection] [--resource=queues] [--all] |
Clears cached lookups |
znuny:generate-fields [--output=path] |
Generates a typed dynamic field helper from the config |
znuny:webservice [connection] [--routes=preset] [--webhooks=events] [--webhook-url=url] [--with-token] [--sync] [--output=path] |
Generates the Znuny web service definition for the connection's routes, optionally with a webhook requester |
Troubleshooting
| Symptom | Cause and fix |
|---|---|
| Dates are off by one or more hours, or date filters miss tickets | The timezone setting does not match Znuny's OTRSTimeZone. Set ZNUNY_TIMEZONE; php artisan znuny:test-connection tells you whether it is right. See Time zone. |
ZnunyRouteNotFoundException |
The routes of the connection do not match the web service. php artisan znuny:routes prints the routes the package uses; pick the matching preset or map the routes. See Routes. |
ZnunyConnectionException with "Empty reply from server" |
The web service named in base_url does not exist in Znuny. |
ZnunyAccessDeniedException for a ticket that does not exist |
Znuny checks permissions before existence, so a missing ticket is reported as access denied. |
A search returns exactly 500 tickets although search_limit is off |
Znuny cut the result off. Remove ZNUNY_SEARCH_LIMIT=null to get an exception instead. See Incomplete results. |
ZnunySearchLimitExceededException |
A search without limit() matches more than search_limit tickets. Narrow it down, call limit(), or raise ZNUNY_SEARCH_LIMIT. See Incomplete results. |
ZnunySessionRefreshed fires on almost every request |
Requests reach Znuny from changing IP addresses, and Znuny deletes a session that another address uses. See Authentication. |
Testing your application
Znuny::fake() answers Znuny operations from fixed responses, so your tests need no Znuny and no knowledge of its REST routes. Resources, search builders and DTOs run as in production.
use ItsJustVita\LaravelZnuny\Exceptions\ZnunyAccessDeniedException; use ItsJustVita\LaravelZnuny\Facades\Znuny; Znuny::fake([ 'TicketSearch' => ['TicketID' => ['42']], 'TicketGet' => Znuny::fakeTickets(['TicketID' => '42', 'Title' => 'Printer on fire']), 'TicketCreate' => fn (array $payload) => ['TicketID' => '43', 'TicketNumber' => '2026110643'], 'TicketUpdate' => new ZnunyAccessDeniedException('TicketUpdate: no permission'), 'TicketHistoryGet' => Znuny::sequence(['TicketHistory' => []], ['TicketHistory' => []]), ]); // ... run your code ... Znuny::assertCalled('TicketCreate', fn (array $payload) => $payload['Ticket']['Queue'] === 'Support'); Znuny::assertCalledTimes('TicketGet', 1); Znuny::assertNotCalled('TicketUpdate');
fakeTickets()builds aTicketGetresponse from complete default tickets; pass only the fields that matter.findByNumber()returns a ticket only if its number is exactly the one asked for, so give the faked ticket that number:Znuny::fakeTickets(['TicketID' => '42', 'TicketNumber' => '2026110610000042']).- A response can be an array, a closure that receives the payload and the connection name, an exception to throw, or a
Znuny::sequence()that answers one call after the other.'*'answers every operation without its own response. - An operation without a response throws a
StrayZnunyCallException, so a forgotten fake shows up in the test. - The fake replaces
ZnunyManagerin the container as well, needs no configured connection and keeps the configured time zone, search limit and batch size.Znuny::recorded()returns all calls with their connection and payload.
The package uses Laravel's HTTP client, so Http::fake() works too, if you want to test at the HTTP level:
Http::fake([ '*/Session' => Http::response(['SessionID' => 'test']), '*/Ticket/42*' => Http::response(['Ticket' => [['TicketID' => '42', 'Title' => 'Hello', 'State' => 'open']]]), ]); $ticket = Znuny::tickets()->find('42');
Upgrading
See UPGRADE.md and CHANGELOG.md.
License
MIT, see LICENSE.md.