{"id":18656642,"url":"https://github.com/zendesk/zendesk_api_client_php","last_synced_at":"2025-05-13T22:12:14.882Z","repository":{"id":14115911,"uuid":"16820767","full_name":"zendesk/zendesk_api_client_php","owner":"zendesk","description":"Official Zendesk API v2 client library for PHP","archived":false,"fork":false,"pushed_at":"2025-01-16T04:48:31.000Z","size":2055,"stargazers_count":343,"open_issues_count":6,"forks_count":259,"subscribers_count":435,"default_branch":"master","last_synced_at":"2025-04-30T14:16:01.917Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zendesk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-02-13T23:21:28.000Z","updated_at":"2025-04-15T21:35:08.000Z","dependencies_parsed_at":"2023-12-22T03:18:22.825Z","dependency_job_id":"8614c1ba-149c-48d2-ad5c-52ba3b04aa7b","html_url":"https://github.com/zendesk/zendesk_api_client_php","commit_stats":{"total_commits":668,"total_committers":89,"mean_commits":7.50561797752809,"dds":0.7395209580838323,"last_synced_commit":"d1da1a7f1548dc5218e864cdf213532b0768d8c1"},"previous_names":[],"tags_count":56,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zendesk%2Fzendesk_api_client_php","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zendesk%2Fzendesk_api_client_php/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zendesk%2Fzendesk_api_client_php/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zendesk%2Fzendesk_api_client_php/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zendesk","download_url":"https://codeload.github.com/zendesk/zendesk_api_client_php/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254036843,"owners_count":22003654,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T07:24:32.536Z","updated_at":"2025-05-13T22:12:14.755Z","avatar_url":"https://github.com/zendesk.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Zendesk PHP API Client Library\n\n![CI](https://github.com/zendesk/zendesk_api_client_php/actions/workflows/ci.yaml/badge.svg)\n[![Latest Stable Version](https://poser.pugx.org/zendesk/zendesk_api_client_php/v/stable)](https://packagist.org/packages/zendesk/zendesk_api_client_php)\n[![Total Downloads](https://poser.pugx.org/zendesk/zendesk_api_client_php/downloads)](https://packagist.org/packages/zendesk/zendesk_api_client_php)\n[![Code Climate](https://codeclimate.com/github/zendesk/zendesk_api_client_php/badges/gpa.svg)](https://codeclimate.com/github/zendesk/zendesk_api_client_php)\n[![License](https://poser.pugx.org/zendesk/zendesk_api_client_php/license)](https://packagist.org/packages/zendesk/zendesk_api_client_php)\n\n## API Client Version\n\nThis is the second version of our PHP API client. The previous version of the API client can be found on the [v1 branch](https://github.com/zendesk/zendesk_api_client_php/tree/v1).\n\n## API version support\n\nThis client **only** supports Zendesk's API v2.  Please see our [API documentation](http://developer.zendesk.com) for more information.\n\n## Requirements\n\n* PHP 8.2+\n\n## Installation\n\nThe Zendesk PHP API client can be installed using [Composer](https://packagist.org/packages/zendesk/zendesk_api_client_php).\n\n### Composer\n\nTo install run `composer require zendesk/zendesk_api_client_php`\n\n### Upgrading from V1 to V2\n\nIf you are upgrading from [v1](https://github.com/zendesk/zendesk_api_client_php/tree/v1) of the client, we've written an [upgrade guide](https://github.com/zendesk/zendesk_api_client_php/wiki/Upgrading-from-v1-to-v2) to highlight some of the key differences.\n\n## Configuration\n\nConfiguration is done through an instance of `Zendesk\\API\\HttpClient`.\nThe block is mandatory and if not passed, an error will be thrown.\n\n``` php\n// load Composer\nrequire 'vendor/autoload.php';\n\nuse Zendesk\\API\\HttpClient as ZendeskAPI;\n\n$subdomain = \"subdomain\";\n$username  = \"email@example.com\"; // replace this with your registered email\n$token     = \"6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv\"; // replace this with your token\n\n$client = new ZendeskAPI($subdomain);\n$client-\u003esetAuth('basic', ['username' =\u003e $username, 'token' =\u003e $token]);\n```\n\n## Usage\n\n### Basic Operations\n\n``` php\n// Get all tickets\n$tickets = $client-\u003etickets()-\u003efindAll();\nprint_r($tickets);\n\n// Get all tickets regarding a specific user.\n$tickets = $client-\u003eusers($requesterId)-\u003etickets()-\u003erequested();\nprint_r($tickets);\n\n// Create a new ticket\n$newTicket = $client-\u003etickets()-\u003ecreate([\n    'subject'  =\u003e 'The quick brown fox jumps over the lazy dog',\n    'comment'  =\u003e [\n        'body' =\u003e 'Lorem ipsum dolor sit amet, consectetur adipisicing elit, ' .\n                  'sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.'\n    ],\n    'priority' =\u003e 'normal'\n]);\nprint_r($newTicket);\n\n// Update a ticket\n$client-\u003etickets()-\u003eupdate(123,[\n    'priority' =\u003e 'high'\n]);\n\n// Delete a ticket\n$client-\u003etickets()-\u003edelete(123);\n\n// Get all users\n$users = $client-\u003eusers()-\u003efindAll();\nprint_r($users);\n```\n\n### Attachments\n\n``` php\n$attachment = $client-\u003eattachments()-\u003eupload([\n    'file' =\u003e getcwd().'/tests/assets/UK.png',\n    'type' =\u003e 'image/png',\n    'name' =\u003e 'UK.png' // Optional parameter, will default to filename.ext\n]);\n```\n\nAttaching files to comments\n\n``` php\n$ticket = $client-\u003etickets()-\u003ecreate([\n    'subject' =\u003e 'The quick brown fox jumps over the lazy dog',\n    'comment' =\u003e [\n        'body' =\u003e 'Lorem ipsum dolor sit amet, consectetur adipisicing elit, ' .\n                  'sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.',\n        'uploads'   =\u003e [$attachment-\u003eupload-\u003etoken]\n    ]\n]);\n```\n\n### Side-loading\n\nSide-loading allows you to retrieve related records as part of a single request. See [the documentation] for more information. (https://developer.zendesk.com/rest_api/docs/core/side_loading).\n\nAn example of sideloading with the client is shown below.\n\n``` php\n$tickets = $client-\u003etickets()-\u003esideload(['users', 'groups'])-\u003efindAll();\n```\n\n### Pagination\n\nMethods like `findAll()` call the API without any pagination parameter. If an endpoint supports pagination, only the first page will be returned. To fetch all resources, you need to make multiple API calls.\n\n#### Iterator (recommended)\n\nThe use of the correct type of pagination is encapsulated using an iterator, which allows you to retrieve all resources in all pages, making multiple API calls, without having to worry about pagination at all:\n\n```php\n$iterator = $client-\u003etickets()-\u003eiterator();\n\nforeach ($iterator as $ticket) {\n    echo($ticket-\u003eid . \" \");\n}\n```\n\nIf you want a specific sort order, please refer to the sorting section in the documentation ([Tickets, for example](https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/#sorting)).\n\n##### Iterator with params example\n\n```php\n$params = ['my' =\u003e 'param1', 'extra' =\u003e 'param2'];\n$iterator = $client-\u003etickets()-\u003eiterator($params);\n\nforeach ($iterator as $ticket) {\n    echo($ticket-\u003eid . \" \");\n}\n```\n\n* Change page size with: `$params = ['page[size]' =\u003e 5];`\n* Change sorting with: `$params = ['sort' =\u003e '-updated_at'];`\n  * Refer to the docs for details, including allowed sort fields\n* Combine everything: `$params = ['page[size]' =\u003e 2, 'sort' =\u003e 'updated_at', 'extra' =\u003e 'param'];`\n\n**Note**:\n\n* Refer to the documentation for the correct params for sorting with the pagination type you're using\n* The helper method `iterator_to_array` doesn't work with this implementation\n\n##### Iterator API call response\n\nThe latest response is exposed in the iterator at `$iterator-\u003elatestResponse()`. This could come handy for debugging.\n\n##### Custom iterators\n\nIf you want to use the iterator for custom methods, as opposed to the default `findAll()`, you can create an iterator for your collection:\n\n```php\n$strategy = new CbpStrategy( // Or ObpStrategy or SinglePageStrategy\n    \"resources_key\", // The root key with resources in the response, usually plural and in underscore\n    [], // Extra params for your call\n);\n$iterator = PaginationIterator($client-\u003etickets(), $strategy);\nforeach ($ticketsIterator as $ticket) {\n    // Use as normal\n}\n```\n\nThis can be useful for filter endpoints like [active automations](https://developer.zendesk.com/api-reference/ticketing/business-rules/automations/#list-active-automations). However, in this common case where you only need to change the method from `findAll()` to `findActive()` there's a better shortcut:\n\n```php\n$iterator = $client-\u003eautomations()-\u003eiterator($params, 'findActive');\n```\n\nWhich is analogous to:\n\n```php\nuse Zendesk\\API\\Traits\\Utility\\Pagination\\PaginationIterator;\nuse Zendesk\\API\\Traits\\Utility\\Pagination\\CbpStrategy;\n$strategy = new CbpStrategy('automations', $params);\n$iterator = new PaginationIterator(\n    $client-\u003eautomations(),\n    $strategy,\n    'findActive'\n);\n```\n\nSee how the [Pagination Trait](src/Zendesk/API/Traits/Resource/Pagination.php) is used if you need more custom implementations.\n\n##### Catching API errors\n\nThis doesn't change too much:\n\n```php\ntry {\n    foreach ($iterator as $ticket) {\n        // your code\n    }\n} catch (ApiResponseException $e) {\n    $errorMessage = $e-\u003egetMessage();\n    $errorDetails = $e=\u003egetErrorDetails();\n}\n```\n\nIf you need to know at what point you got the error, you can store the required information inside the loop in your code.\n\n#### FindAll using CBP (fine)\n\nIf you still want use `findAll()`, until CBP becomes the default API response, you must explicitly request CBP responses by using the param `page[size]`.\n\n``` php\n// CBP: /path?page[size]=100\n$response = $client-\u003etickets()-\u003efindAll(['page[size]' =\u003e 100]);\nprocess($response-\u003etickets); // Your implementation\ndo {\n    if ($response-\u003emeta-\u003ehas_more) {\n        // CBP: /path?page[after]=cursor\n        $response = $client-\u003etickets()-\u003efindAll(['page[after]' =\u003e $response-\u003emeta-\u003eafter_cursor]);\n        process($response-\u003etickets);\n    }\n} while ($response-\u003emeta-\u003ehas_more);\n```\n\n**Process data _immediately_ upon fetching**. This optimizes memory usage, enables real-time processing, and helps adhere to API rate limits, enhancing efficiency and user experience.\n\n#### Find All using OBP (only recommended if the endpoint doesn't support CBP)\n\nIf CBP is not available, this is how you can fetch one page at a time:\n\n```php\n$pageSize = 100;\n$pageNumber = 1;\ndo {\n    // OBP: /path?per_page=100\u0026page=2\n    $response = $client-\u003etickets()-\u003efindAll(['per_page' =\u003e $pageSize, 'page' =\u003e $pageNumber]);\n    process($response-\u003etickets); // Your implementation\n    $pageNumber++;\n} while (count($response-\u003etickets) == $pageSize);\n```\n\n**Process data _immediately_ upon fetching**. This optimizes memory usage, enables real-time processing, and helps adhere to API rate limits, enhancing efficiency and user experience.\n\n### Retrying Requests\n\nAdd the `RetryHandler` middleware on the `HandlerStack` of your `GuzzleHttp\\Client` instance. By default `Zendesk\\Api\\HttpClient`\nretries:\n\n* timeout requests\n* those that throw `Psr\\Http\\Message\\RequestInterface\\ConnectException:class`\n* and those that throw `Psr\\Http\\Message\\RequestInterface\\RequestException:class` that are identified as ssl issue.\n\n#### Available options\n\nOptions are passed on `RetryHandler` as an array of values.\n\n* max = 2 _limit of retries_\n* interval = 300 _base delay between retries in milliseconds_\n* max_interval = 20000 _maximum delay value_\n* backoff_factor = 1 _backoff factor_\n* exceptions = [ConnectException::class] _Exceptions to retry without checking retry_if_\n* retry_if = null _callable function that can decide whether to retry the request or not_\n\n## Contributing\n\nPull Requests are always welcome but before you send one please read our [contribution guidelines](#CONTRIBUTING.md). It would\nspeed up the process and would make sure that everybody follows the community's standard.\n\n### Debugging\n\n#### REPL\n\nTo help would be contributors, we've added a REPL tool. It is a simple wrapper for [psysh](http://psysh.org) and symfony's console.\nOn your terminal, run `bin/console \u003csubdomain\u003e \u003cemail\u003e \u003capi token\u003e`. This would automatically create an instance of `Zendesk\\API\\HttpClient` on $client variable.\nAfter that you would be able to enter any valid php statement. The goal of the tool is to speed up the process in which developers\ncan experiment on the code base.\n\n#### HTTP client print API calls\n\nYou can print a line with details about every API call with:\n\n```php\n$client = new ZendeskAPI($subdomain);\n$client-\u003elog_api_calls = true;\n```\n\n#### HTTP client debug\n\nYou can inspect this object for info about requests and responses:\n\n```php\n$client-\u003egetDebug();\n```\n\n## Copyright and license\n\nCopyright 2013-present Zendesk\n\nLicensed under the Apache License, Version 2.0 (the \"License\"); you may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\nhttp://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzendesk%2Fzendesk_api_client_php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzendesk%2Fzendesk_api_client_php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzendesk%2Fzendesk_api_client_php/lists"}