Skip to content

Commit f823047

Browse files
RhysLeesRhysLees
committed
WIP
1 parent 521dd0d commit f823047

File tree

2 files changed

+126
-59
lines changed

2 files changed

+126
-59
lines changed

‎README.md

Lines changed: 118 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,8 @@ knowledge base and online communities.
1515
## 🛠 Requirements
1616

1717
| Package | PHP | Laravel | Zendesk |
18-
|-----------|-------|----------------|-----------|
19-
| >v1.0 | >8.2 | > Laravel 10.0 | ✅ |
18+
|-----------|-------|----------------|:---------:|
19+
| >v1.0 | >8.2 | > Laravel 10.0 | ✅ |
2020

2121
## Authentication
2222

@@ -45,13 +45,18 @@ php artisan vendor:publish --provider="CodebarAg\Zendesk\ZendeskServiceProvider"
4545
You can add the following env variables to your `.env` file:
4646

4747
```dotenv
48-
ZENDESK_SUBDOMAIN= # required
49-
ZENDESK_AUTHENTICATION_METHOD= # basic or token, (token is default)
50-
ZENDESK_EMAIL_ADDRESS= # required for both basic and token
51-
ZENDESK_API_TOKEN= # required only for token authentication
52-
ZENDESK_API_PASSWORD= # required only for basic authentication
48+
ZENDESK_SUBDOMAIN=your-subdomain #required
49+
ZENDESK_AUTHENTICATION_METHOD=token #default ['basic', 'token']
50+
ZENDESK_EMAIL_ADDRESS=[email protected] #required
51+
ZENDESK_API_TOKEN=your-api-token #required only for token authentication
52+
ZENDESK_API_PASSWORD=your-password #required only for basic authentication
5353
```
5454

55+
`Note: We handle base64 encoding for you so you don't have to encode your credentials.`
56+
57+
You can retrieve your API token from
58+
your [Zendesk Dashboard](https://developer.zendesk.com/api-reference/introduction/security-and-auth/)
59+
5560
## Usage
5661

5762
To make use of the package, you need to create a ZendeskConnector instance.
@@ -61,7 +66,6 @@ use CodebarAg\Zendesk\ZendeskConnector;
6166
...
6267

6368
$connector = new ZendeskConnector();
64-
6569
````
6670

6771
### Requests
@@ -81,85 +85,142 @@ The following requests are currently supported:
8185
The following responses are currently supported for retrieving the response body:
8286

8387
| Response Methods | Description | Supported |
84-
|----------------|------------------------------------------------------------------------------------------------------------------------------------|:-----------:|
85-
| body() | Returns the HTTP body as a string | ✅ |
86-
| json() | Retrieves a JSON response body and json_decodes it into an array. | ✅ |
87-
| object() | Retrieves a JSON response body and json_decodes it into an object. | ✅ |
88-
| collect() | Retrieves a JSON response body and json_decodes it into a Laravel collection. **Requires illuminate/collections to be installed.** | ✅ |
89-
| dto() | Converts the response into a data-transfer object. You must define your DTO first | ✅ |
88+
|-------------------|------------------------------------------------------------------------------------------------------------------------------------|:-----------:|
89+
| body | Returns the HTTP body as a string | ✅ |
90+
| json | Retrieves a JSON response body and json_decodes it into an array. | ✅ |
91+
| object | Retrieves a JSON response body and json_decodes it into an object. | ✅ |
92+
| collect | Retrieves a JSON response body and json_decodes it into a Laravel collection. **Requires illuminate/collections to be installed.** | ✅ |
93+
| dto | Converts the response into a data-transfer object. You must define your DTO first | ✅ |
9094

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

97+
### Enums
98+
99+
We provide enums for the following values:
100+
101+
| Enum | Values |
102+
|-------------------|:---------------------------------------------------------------------:|
103+
| TicketPriority | 'urgent', 'high', 'normal', 'low' |
104+
| TicketType | 'incident', 'problem', 'question', 'task' |
105+
| MalwareScanResult | 'malware_found', 'malware_not_found', 'failed_to_scan', 'not_scanned' |
106+
107+
`Note: When using the dto method on a response, the enum values will be converted to their respective enum class.`
108+
109+
### DTOs
110+
111+
We provide DTOs for the following:
112+
113+
| DTO |
114+
|-----------------|
115+
| AttachmentDTO |
116+
| ThumbnailDTO |
117+
| UploadDTO |
118+
| CommentDTO |
119+
| AllTicketsDTO |
120+
| CountTicketsDTO |
121+
| SingleTicketDTO |
122+
123+
`Note: This is the prefered method of interfacing with Requests and Responses however you can still use the json, object and collect methods. and pass arrays to the requests.`
124+
93125
### Examples
94-
--
95-
#### Upload an attachment
126+
127+
#### Create a ticket
96128

97129
```php
98-
$upload = $connector->send(
99-
new CreateAttachmentRequest(
100-
fileName: 'head8.png',
101-
mimeType: Storage::disk('local')->mimeType('public/head8.png'),
102-
stream: Storage::disk('local')->readStream('public/head8.png')
130+
use CodebarAg\Zendesk\Requests\CreateSingleTicketRequest;
131+
use CodebarAg\Zendesk\DTOs\SingleTicketDTO;
132+
use CodebarAg\Zendesk\DTOs\CommentDTO;
133+
use CodebarAg\Zendesk\Enums\TicketPriority;
134+
...
135+
136+
$ticketResponse = $connector->send(
137+
new CreateSingleTicketRequest(
138+
SingleTicketDTO::fromArray([
139+
'comment' => CommentDTO::fromArray([
140+
'body' => 'The smoke is very colorful.',
141+
]),
142+
'priority' => TicketPriority::URGENT,
143+
"subject" => "My printer is on fire!",
144+
"custom_fields" => [
145+
[
146+
"id" => 12345678910111,
147+
"value" => "Your custom field value"
148+
],
149+
[
150+
"id" => 12345678910112,
151+
"value" => "Your custom field value 2"
152+
],
153+
],
154+
])
103155
)
104156
);
105157

106-
return $upload->json();
158+
$ticket = $ticketResponse->dto();
107159
````
108160

109-
```json
161+
#### List all tickets
110162

111-
```
163+
```php
164+
use CodebarAg\Zendesk\Requests\AllTicketsRequest;
165+
...
112166

167+
$listTicketResponse = $connector->send(new AllTicketsRequest());
168+
$listTicketResponse->dto();
169+
````
113170

114-
```php
171+
#### Count all tickets
115172

116-
use CodebarAg\Zendesk\Requests\AllTicketsRequest;
173+
```php
117174
use CodebarAg\Zendesk\Requests\CountTicketsRequest;
118-
use CodebarAg\Zendesk\Requests\CreateAttachmentRequest;
119-
use CodebarAg\Zendesk\Requests\CreateSingleTicketRequest;
120-
use CodebarAg\Zendesk\Requests\SingleTicketRequest;
121-
use CodebarAg\Zendesk\DTO\CommentDTO;
122-
use CodebarAg\Zendesk\DTO\CreateTicketDTO;
123-
use CodebarAg\Zendesk\Enums\TicketPriority;
124-
use Illuminate\Support\Facades\Storage;
125-
use CodebarAg\Zendesk\ZendeskConnector;
175+
...
176+
177+
$countTicketResponse = $connector->send(new CountTicketsRequest());
178+
$countTicketResponse->dto();
179+
````
180+
181+
#### Show a ticket
126182

183+
```php
184+
use CodebarAg\Zendesk\Requests\ShowTicketRequest;
127185
...
128186

129-
$connector = new ZendeskConnector();
187+
$ticketID = 1;
130188

131-
$listTicketResponse = $connector->send(new AllTicketsRequest());
132-
dump($listTicketResponse->dto());
189+
$showTicketResponse = $connector->send(new ShowTicketRequest($ticketID));
190+
$showTicketResponse->dto();
191+
````
133192

134-
$showTicketResponse = $connector->send(new SingleTicketRequest(1));
135-
dump($showTicketResponse->dto());
193+
#### Upload an attachment
136194

137-
$countTicketResponse = $connector->send(new SingleTicketRequest(1));
138-
dump($countTicketResponse->dto());
195+
```php
196+
use CodebarAg\Zendesk\Requests\CreateAttachmentRequest;
197+
use CodebarAg\Zendesk\Requests\CreateSingleTicketRequest;
198+
use Illuminate\Support\Facades\Storage;
139199

140-
$createTicketResponse = $connector->send(
141-
new CreateSingleTicketRequest(
142-
CreateTicketDTO::fromArray([
143-
"comment" => CommentDTO::fromArray([
144-
"body" => "The smoke is very colorful."
145-
]),
146-
"priority" => TicketPriority::URGENT,
147-
"subject" => "My printer is on fire!"
148-
])
200+
$uploadResponse = $connector->send(
201+
new CreateAttachmentRequest(
202+
fileName: 'someimage.png',
203+
mimeType: Storage::disk('local')->mimeType('public/someimage.png'),
204+
stream: Storage::disk('local')->readStream('public/someimage.png')
149205
)
150206
);
151207

152-
dump($createTicketResponse->dto());
208+
$token = $uploadResponse->dto()->token;
153209

154-
$response = $connector->send(
155-
new CreateAttachmentRequest(
156-
fileName: 'head8.png',
157-
mimeType: Storage::disk('local')->mimeType('public/head8.png'),
158-
stream: Storage::disk('local')->readStream('public/head8.png')
210+
$ticketResponse = $connector->send(
211+
new CreateSingleTicketRequest(
212+
SingleTicketDTO::fromArray([
213+
'comment' => CommentDTO::fromArray([
214+
...
215+
'uploads' => [
216+
$token,
217+
],
218+
]),
219+
])
159220
)
160221
);
161222

162-
dump($response->dto());
223+
$ticket = $ticketResponse->dto();
163224
```
164225

165226
## 🚧 Testing

‎src/Requests/CreateSingleTicketRequest.php

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,14 +22,20 @@ public function resolveEndpoint(): string
2222
}
2323

2424
public function __construct(
25-
readonly protected SingleTicketDTO $createTicketDTO
25+
readonly protected array|SingleTicketDTO $createTicket
2626
) {
2727
}
2828

2929
protected function defaultBody(): array
3030
{
31+
$body = $this->createTicket;
32+
33+
if (! $body instanceof SingleTicketDTO) {
34+
$body = SingleTicketDTO::fromArray($body);
35+
}
36+
3137
return [
32-
'ticket' => $this->createTicketDTO->toArray(),
38+
'ticket' => $body->toArray(),
3339
];
3440
}
3541

0 commit comments

Comments
 (0)