bradfeehan / desk-php
PHP client for Desk.com v2 API based on Guzzle
Installs: 80 331
Dependents: 0
Suggesters: 0
Security: 0
Stars: 21
Watchers: 3
Forks: 27
Open Issues: 6
Requires
- php: >=5.3
- bradfeehan/guzzle-modular-service-descriptions: ~1.1,>=1.1.1
- guzzle/guzzle: ~3.9
Requires (Dev)
- mockery/mockery: dev-master#3bd6f1712642838b4c0524d3a47359940df72e80
- phpunit/phpunit: ~4.1
- satooshi/php-coveralls: ~0.6
- seld/jsonlint: ~1.1
- squizlabs/php_codesniffer: ~1.5
This package is not auto-updated.
Last update: 2024-11-19 02:30:38 UTC
README
PHP client for Desk.com v2 API, based on Guzzle
This project is still under development and things may change quickly. It'll attempt to adhere to Semantic Versioning to minimise any issues.
Here's a summary of what's implemented:
- Main resource operations (ListCases, etc)
- Sub-item operations (ListCaseNotes, etc)
- Data type filtering
Dates- Custom fields?
- Resource property lists (e.g. customer email addresses, etc)
- Resource relationships (links/embedding)
Links to other resources return commandsEmbedded resources return modelsEmbedded model data type filtering
Project Aims
- Support all API operations documented by Desk
- Consumption of the API's provided relationship
functionality
- Resources link to other related resources
- These can be embedded to reduce the number of requests
- PHP-friendly data types (dates represented using DateTime objects, etc)
- 100% unit test coverage (using PHPUnit)
- Additional "use-case" tests for every individual operation, which use documented responses as mock responses
Installation
To get this library in to an existing project, the best way is to use Composer.
-
Add
bradfeehan/desk-php
as a Composer dependency in your project'scomposer.json
file:{ "require": { "bradfeehan/desk-php": "dev-master" } }
-
If you haven't already, download and install Composer:
$ curl -sS https://getcomposer.org/installer | php
-
Install your Composer dependencies:
$ php composer.phar install
-
Set up Composer's autoloader:
require_once 'vendor/autoload.php';
You're done! Now the Desk
namespace should exist and contain
everything you need to consume the Desk.com API.
Super Quick Run-down
use Desk\Client; $client = Client::factory(array( 'subdomain' => 'foo', 'username' => 'myuser', 'password' => 'secret', )); foreach ($client->getIterator("ListUsers") as $user) { // do things with $user $casesForCurrentUser = $user->getLink("cases")->execute(); }
Basic Usage
The main point of entry for your app will usually be the Desk\Client
class:
$client = \Desk\Client::factory(array( 'subdomain' => 'foo', 'username' => 'myuser', 'password' => 'secret', ));
.. or with API keys:
$client = \Desk\Client::factory(array( 'subdomain' => 'foo' 'consumer_key' => 'key', 'consumer_secret' => 'secret', 'token' => 'key', 'token_secret' => 'secret', ));
Individual commands can be retrieved from the client and executed:
$command = $client->getCommand('ShowUser'); $command->set('id', 1); $user = $command->execute(); print $user->get('name'); // => 'John Doe'
There are some shortcuts which can be taken. The above is equivalent to:
$command = $client->getCommand('ShowUser', array('id' => 1)); $user = $command->execute(); print $user->get('name'); // => 'John Doe'
...which again is the same as:
$user = $client->ShowUser(array('id' => 1)); print $user->get('name'); // => 'John Doe'
Complex data types are (generally) converted to/from easier to use
formats. For example, dates are represented as strings over the wire
when communicating with the Desk API, but these will be converted to
PHP DateTime
objects upon retrieval:
$customer = $client->ShowCustomer(array('id' => 1)); var_dump($customer->get('created_at')); // => object(DateTime)#209 (3) { ...
Command names
The names of commands follow a strict naming convention. The type of operation is first; this is usually one of Show, List, Create, Update, Delete, or Search. This is combined with the resource name (CamelCase if it's more than one word) -- for example, Article, Company, CustomField etc. List and Search operations will have a pluralised version of the resource name (e.g. ListCompanies, SearchArticles, etc). while the other operations will have the singular form (e.g. ShowCompany, CreateArticle, etc). The complete list is in the service description file, desk.json, although it might be a bit hard to use for this purpose due to its length.
Relationships
In version 2 of the Desk API, there exists the concept of relationships between resources. For example, a Case resource now links to the Customer resource which created the case. This is fully supported by this library.
Links
A link from one resource to another is represented by a pre-configured
command object which is ready to retrieve the target of the link. To
retrieve a command representing a link, call the getLink()
method on
the model:
$case = $client->ShowCase(array('id' => 1)); $command = $case->getLink('customer'); print $command->getName(); // => 'ShowCustomer' print $command->get('id'); // => 1 $customer = $command->execute(); // or, more useful: $customer = $case->getLink('customer')->execute();
Embedded Resources
The example above would require two requests -- one for the case, and another for the customer. If, at the time of the first request, you know that you will (or might) need to access a related resource, you can request that the related resource be embedded into the first response. As an example, to improve on the performance of the previous example:
$case = $client->ShowCase(array('id' => 1, 'embed' => array('customer'))); $customer = $case->getEmbedded('customer'); // no second request necessary
The call to getEmbedded()
would throw an exception if we hadn't
requested the "customer" relation to be embedded at the time of the
original request to retrieve the case.
Contributing
Contributions are most welcome! At this early stage of development, I'm working hard on the items at the top of this README. At any time I'm probably halfway through implementing (or re-implementing) something on that list, so keep that in mind if you're planning to start working on something -- I may already be on it.
Here's a few guidelines when coding on this project:
- I'm trying to use best practices everywhere in this project. Hacky solutions are generally rejected in favor of "doing it right" (in general).
- Stick to PSR-2 coding style. This involves many things I wasn't aware of when starting out! (e.g. one argument per line in multi-line function definitions)
- Try and stick to 72/80 characters where possible (except in
.json
files if necessary).
With that being said, I feel like even if you have some code in a fork which doesn't adhere to these guidelines, it could certainly still be useful, so feel free to open a pull request anyway.