Search by

itsjustvita / laravel-znuny

itsjustvita

Laravel SDK for the Znuny / OTRS Community Edition Generic Interface REST API

Package info

github.com/itsjustvita/laravel-znuny

pkg:composer/itsjustvita/laravel-znuny

Statistics

Installs: 358

Dependents: 0

Suggesters: 0

Stars: 1

Open Issues: 0

v0.3.1 2026-11-07 08:30 UTC

This package is auto-updated.

Last update: 2026-11-07 08:31:50 UTC


README

Latest Version on Packagist Tests Znuny 6.5 to 7.3 Total Downloads PHP Version License

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

  • 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

  1. Get the web service definition:
    • Znuny 6.5.11+ and 7.1.3+ list GenericTicketConnectorREST under 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.

  2. Keep the name GenericTicketConnectorREST or choose your own. The base URL is https://<host>/otrs/nph-genericinterface.pl/Webservice/<name>; use your installation's script alias if it is not /otrs/.
  3. 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 off SessionCheckRemoteIP in 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=false lets 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 throws ZnunyAccessDeniedException. 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.

  1. Enable the endpoint and set a secret:

    ZNUNY_WEBHOOKS_ENABLED=true
    ZNUNY_WEBHOOK_TOKEN=a-long-random-string

    This registers POST /znuny/webhooks/{event?} (see webhooks.route_prefix) with the api middleware group and the znuny.webhook authentication middleware.

  2. 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-ME where the secret belongs; --with-token writes it instead. Webhooks are delivered by the Znuny daemon; --sync sends them during the triggering request. To set the requester up by hand:

    • network transport HTTP::REST with the endpoint https://your-app.example.com/znuny/webhooks;
    • an invoker of type Ticket::Generic, triggered by the events you need (for example TicketCreate, ArticleCreate, TicketStateUpdate);
    • a controller mapping for the invoker, e.g. POST to /TicketCreate (the last path segment becomes the event name);
    • the additional header X-Znuny-Token: <your token> (or Authorization: Bearer <your token>). Alternatively use Znuny's BasicAuth together with ZNUNY_WEBHOOK_AUTH=basic, ZNUNY_WEBHOOK_USERNAME and ZNUNY_WEBHOOK_PASSWORD.
  3. 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 a TicketGet response 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 ZnunyManager in 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.