README

This package was developed to give you a quick start to creating tickets via the Zendesk API.

💡 What is Zendesk?

Zendesk is a cloud-based help desk management solution offering customizable tools to build customer service portals, knowledge base and online communities.

🛠 Requirements

Package	PHP	Laravel	Zendesk
v13.0	^8.3 - ^8.5	13.x	✅
v12.0	^8.2 - ^8.4	12.x	✅
v11.0	^8.2 - ^8.3	11.x	✅
v1.0	^8.2	10.x	✅

Authentication

The currently supported authentication methods are:

Method	Supported
Basic Auth	✅
API token	✅
OAuth access token	❌

⚙️ Installation

You can install the package via composer:

composer require codebar-ag/laravel-zendesk

Optionally, you can publish the config file with:

php artisan vendor:publish --provider="CodebarAg\Zendesk\ZendeskServiceProvider" --tag="config"

You can add the following env variables to your .env file:

ZENDESK_SUBDOMAIN=your-subdomain #required
ZENDESK_AUTHENTICATION_METHOD=token #default ['basic', 'token']
ZENDESK_EMAIL_ADDRESS=test@example.com #required
ZENDESK_API_TOKEN=your-api-token #required only for token authentication
ZENDESK_API_PASSWORD=your-password #required only for basic authentication

Note: We handle base64 encoding for you so you don't have to encode your credentials.

You can retrieve your API token from your Zendesk Dashboard

Usage

To use the package, you need to create a ZendeskConnector instance.

use CodebarAg\Zendesk\ZendeskConnector;
...

$connector = new ZendeskConnector();

Requests

The following requests are currently supported:

Request	PHP class	Supported
List tickets	`AllTicketsRequest`	✅
Count tickets	`CountTicketsRequest`	✅
Get ticket	`SingleTicketRequest`	✅
Create ticket	`CreateSingleTicketRequest`	✅
Create attachment	`CreateAttachmentRequest`	✅

Responses

The following responses are currently supported for retrieving the response body:

Response Methods	Description	Supported
body	Returns the HTTP body as a string	✅
json	Retrieves a JSON response body and json_decodes it into an array.	✅
object	Retrieves a JSON response body and json_decodes it into an object.	✅
collect	Retrieves a JSON response body and json_decodes it into a Laravel collection. Requires illuminate/collections to be installed.	✅
dto	Converts the response into a DTO. This package provides DTOs for the requests above; Saloon also allows custom DTOs.	✅

See https://docs.saloon.dev/the-basics/responses for more information.

Enums

We provide enums for the following values:

Enum	Values
TicketPriority	'urgent', 'high', 'normal', 'low'
TicketType	'incident', 'problem', 'question', 'task'
MalwareScanResult	'malware_found', 'malware_not_found', 'failed_to_scan', 'not_scanned'

Note: When using the dto method on a response, the enum values will be converted to their respective enum class.

Zendesk API and DTO coverage

Official ticket JSON is documented in the Zendesk Tickets API. SingleTicketDTO maps a large subset of fields returned by Zendesk; it is not guaranteed to include every property the API may return. For example, the docs show custom_status_id and generated_timestamp on ticket objects; those keys are not mapped on SingleTicketDTO today.

DTOs

We provide DTOs for the following:

DTO	PHP class
AttachmentDTO	`CodebarAg\Zendesk\Dto\Tickets\Attachments\AttachmentDTO`
ThumbnailDTO	`CodebarAg\Zendesk\Dto\Tickets\Attachments\ThumbnailDTO`
UploadDTO	`CodebarAg\Zendesk\Dto\Tickets\Attachments\UploadDTO`
CommentDTO	`CodebarAg\Zendesk\Dto\Tickets\Comments\CommentDTO`
AllTicketsDTO	`CodebarAg\Zendesk\Dto\Tickets\AllTicketsDTO`
CountTicketsDTO	`CodebarAg\Zendesk\Dto\Tickets\CountTicketsDTO`
SingleTicketDTO	`CodebarAg\Zendesk\Dto\Tickets\SingleTicketDTO`

Note: This is the preferred way to work with requests and responses. You can still use the json, object, and collect methods, and pass arrays into requests where supported.

Examples

Create a ticket

use CodebarAg\Zendesk\Requests\CreateSingleTicketRequest;
use CodebarAg\Zendesk\Dto\Tickets\SingleTicketDTO;
use CodebarAg\Zendesk\Dto\Tickets\Comments\CommentDTO;
use CodebarAg\Zendesk\Enums\TicketPriority;
...

$ticketResponse = $connector->send(
    new CreateSingleTicketRequest(
        SingleTicketDTO::fromArray([
            'comment' => CommentDTO::fromArray([
                'body' => 'The smoke is very colorful.',
            ]),
            'priority' => TicketPriority::URGENT,
            "subject" => "My printer is on fire!",
            "custom_fields" => [
                [
                    "id" => 12345678910111,
                    "value" => "Your custom field value"
                ],
                [
                    "id" => 12345678910112,
                    "value" => "Your custom field value 2"
                ],
            ],
        ])
    )
);

$ticket = $ticketResponse->dto();

List all tickets

use CodebarAg\Zendesk\Requests\AllTicketsRequest;
...

$listTicketResponse = $connector->send(new AllTicketsRequest());
$listTicketResponse->dto();

Count all tickets

use CodebarAg\Zendesk\Requests\CountTicketsRequest;
...

$countTicketResponse = $connector->send(new CountTicketsRequest());
$countTicketResponse->dto();

Get a ticket

use CodebarAg\Zendesk\Requests\SingleTicketRequest;
...

$ticketId = 1;

$ticketResponse = $connector->send(new SingleTicketRequest($ticketId));
$ticketResponse->dto();

Upload an attachment

use CodebarAg\Zendesk\Requests\CreateAttachmentRequest;
use CodebarAg\Zendesk\Requests\CreateSingleTicketRequest;
use CodebarAg\Zendesk\Dto\Tickets\SingleTicketDTO;
use CodebarAg\Zendesk\Dto\Tickets\Comments\CommentDTO;
use Illuminate\Support\Facades\Storage;

$uploadResponse = $connector->send(
    new CreateAttachmentRequest(
        fileName: 'someimage.png',
        mimeType: Storage::disk('local')->mimeType('public/someimage.png'),
        stream: Storage::disk('local')->readStream('public/someimage.png')
    )
);

$token = $uploadResponse->dto()->token;

$ticketResponse = $connector->send(
    new CreateSingleTicketRequest(
        SingleTicketDTO::fromArray([
            'comment' => CommentDTO::fromArray([
                ...
                'uploads' => [
                    $token,
                ],
            ]),
        ])
    )
);

$ticket = $ticketResponse->dto();

🚧 Testing

Copy your own phpunit.xml-file.

cp phpunit.xml.dist phpunit.xml

Run the tests:

./vendor/bin/pest

📝 Changelog

Please see CHANGELOG for recent changes.

✏️ Contributing

Please see CONTRIBUTING for details.

composer test

Code Style

./vendor/bin/pint

codebar-ag / laravel-zendesk

Maintainers

Package info

Statistics

Security