Merge pull request #99 from zendesk/v2

V2 - Rewrite of the PHP API Client

.travis.yml

@@ -1,7 +1,11 @@
 language: php
 php:
+  - 5.6
   - 5.5
   # - 5.4
   # - hhvm
-before_script: composer self-update && composer install
-script: phpunit --testsuite "Zendesk API Unit Test Suites"
+install:
+  - travis_retry composer self-update && composer install
+script:
+  - vendor/bin/phpunit --testsuite "Zendesk API Unit Test Suites"
+  - vendor/bin/phpcs --extensions=php --standard=PSR2 --report=summary -np src/ tests/

CHANGELOG

@@ -0,0 +1,30 @@
+Changed:
+
+* on tickets, can no longer do $client->tickets(["organization_id" -> 1231])->findAll(), etc. (also user_id)
+* separate findMany method
+* change interface of find to just take ID, then params
+* added updateMany method, support both ways of updating
+* change update so that it takes ID as first param
+* change delete so that it takes id
+* add deleteMany method to tickets
+* Add property chained properties to store all previous chained calls
+* Removed setting of last ID on instantiation of Resource
+* Allowed pattern `$client->ticket(id)->find()` for consistency with chaining pattern
+* Make $id in delete and update optional to allow passing of the id via chaining pattern
+
+Topics
+* removed Topics::create() - was implementing lastId
+* remove Topics::findAll() - can no longer do $client->users(123)->topics()->findAll()
+
+UserFields
+* remove CRUD methods
+
+Forums
+* remove CRUD methods - (most methods)
+* no unique case so test is empty
+
+Tickets
+* markAsSpam method now only accepts an int value for an ID or an array of ID's
+
+Users
+* Remove tickets, identities, and other relational methods

README.md

@@ -2,10 +2,17 @@
 
 [![Build Status](https://travis-ci.org/zendesk/zendesk_api_client_php.svg?branch=master)](https://travis-ci.org/zendesk/zendesk_api_client_php)
 
+## API Client Version
+
+This is the second version of our PHP API client and it is **currently in BETA**. The previous version of the API client can be found on the [v1 branch](https://github.com/zendesk/zendesk_api_client_php/tree/v1).
+
 ## API version support
 
 This client **only** supports Zendesk's API v2.  Please see our [API documentation](http://developer.zendesk.com) for more information.
 
+## Requirements
+* PHP 5.5+
+
 ## Installation
 
 The Zendesk PHP API client can be installed using [Composer](https://packagist.org/packages/zendesk/zendesk_api_client_php).
@@ -27,7 +34,7 @@ Inside of `composer.json` specify the following:
 Configuration is done through an instance of `Zendesk\API\Client`.
 The block is mandatory and if not passed, an error will be thrown.
 
-```php
+```
 use Zendesk\API\Client as ZendeskAPI;
 
 $subdomain = "subdomain";
@@ -43,54 +50,203 @@ $client->setAuth('token', $token); // set either token or password
 
 ### Basic Operations
 
-```php
+```
 // Get all tickets
 $tickets = $client->tickets()->findAll();
 print_r($tickets);
 
 // Create a new ticket
-$newTicket = $client->tickets()->create(array(
-  'subject' => 'The quick brown fox jumps over the lazy dog',
-  'comment' => array (
-      'body' => 'Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.'
-  ),
-  'priority' => 'normal'
-));
+$newTicket = $client->tickets()->create([
+    'subject'  => 'The quick brown fox jumps over the lazy dog',
+    'comment'  => [
+        'body' => 'Lorem ipsum dolor sit amet, consectetur adipisicing elit, '
+                  . 'sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.'
+    ],
+    'priority' => 'normal'
+]);
 print_r($newTicket);
 
 // Update multiple tickets
-$client->ticket(array (123, 456))->update(array (
-  'status' => 'urgent'
-));
+$client->ticket([123, 456])->update([
+    'status' => 'urgent'
+]);
 
 // Delete a ticket
 $client->ticket(123)->delete();
 ```
 
 ### Attachments
 
-```php
-$attachment = $client->attachments()->upload(array(
+```
+$attachment = $client->attachments()->upload([
     'file' => getcwd().'/tests/assets/UK.png',
     'type' => 'image/png',
     'name' => 'UK.png'    // Optional parameter, will default to filename.ext
-));
+]);
 ```
 
 ### Test suite
 
 The test suite is run via phpunit. Note that these are all live tests that must be run targeted at a real Zendesk instance. Credentials can be provided by setting the environment variables in phpunit.xml; a sample is provided at phpunit.xml.dist.
 
+To run the unit tests: `vendor/bin/phpunit --testsuite "Zendesk API Unit Test Suites"`
+
+To run the live tests: `vendor/bin/phpunit --testsuite "Zendesk API Live Test Suites"`
+
+
 ### Side-loading
 
+```
+$tickets = $this->client->tickets()->sideload(['users', 'groups'])->findAll();
+```
+
+
+
+## Coding Standard
+This project strictly follows the [PSR-2](http://www.php-fig.org/psr/psr-2/) coding standard. 
+
+[PHP Codesniffer](https://github.com/squizlabs/PHP_CodeSniffer) is used to verify that the standard is being followed.
+
+In addition to the PSR2 standard which we try to follow the following rules as much as possible:
+
+### PHPDoc
+
+All Classes, Class Methods and Properties should have docblocs.
+
+#### Classes
+
+Class docblocks should contain:
+* A short description of the class
+* Any methods available that are called via magic method with what that method returns.
+
+A good example is
+```
+/**
+ * Client class, base level access
+ *
+ * @method Debug debug()
+ * @method Tickets ticket()
+ * @method Views views()
+ */
+```
+
+
+#### Methods
+
+Method docblocks should contain:
+* A short description of what the method does.
+* The parameters passed with what type to expect.
+* Description of the parameters passed with examples(optional).
+* The type of the return.
+* All the possible exceptions the method may throw.
+
+A good example of this is
+
+```
+/**
+ * Find a specific ticket by id or series of ids
+ *
+ * @param integer|null $id
+ * @param array        $queryParams
+ *
+ * @return Array
+ *
+ * @throws MissingParametersException
+ * @throws \Exception
+ */
+```
+
+#### Properties
+
+Class properties docblocs should contain:
+* A short description of the property (optional)
+* The var type
+
+A good example of this
+
+```
+/**
+ * This contains the Auth object to be used for authenticating with the Client
+ *
+ * @var Zendesk\API\Utilities\Auth
+ */
+```
+
+### Arrays
+The short notations for declaring arrays (`[]`) is preferred over the longer `array()`.
+
+Align `=>`s following the longest key to make the arrays easier to read.
+
+```
+[
+    'findAll'             => "users/{userId}/{$this->resourceName}.json",
+    'find'                => "users/{userId}/{$this->resourceName}/{id}.json",
+    'update'              => "users/{userId}/{$this->resourceName}/{id}.json",
+    'makePrimary'         => "users/{userId}/{$this->resourceName}/{id}/make_primary.json",
+    'verify'              => "users/{userId}/{$this->resourceName}/{id}/verify.json",
+    'requestVerification' => "users/{userId}/{$this->resourceName}/{id}/request_verification.json",
+    'delete'              => "users/{userId}/{$this->resourceName}/{id}.json",
+    'create'              => "users/{userId}/{$this->resourceName}.json",
+    'createAsEndUser'     => "end_users/{userId}/{$this->resourceName}.json",
+]
+```
+
+### Grouped assignment statements
+
+Align the `=` for grouped assignment statements.
+
+```
+$headers             = 'sample';
+$lastRequestBody     = 'example';
+$lastResponseCode    = 'something';
+$lastResponseHeaders = 'test';
+$lastResponseError   = 'test2';
+
+```
+
+
+### Traits
+
+#### Declaration
+
+* Traits are added after class constants and arranged alphabetically when declared. 
+* Group traits accordingly by adding a new line after each group.
+* Groups are ordered as follows:
+1. Instantiator 
+2. Single resource
+3. Bulk traits
+
+#### Resource Traits
+
+When adding a resource, use traits to define available API calls. Resource traits are namespaced under `Zendesk\API\Traits\Resource`.
+
+**Single Resource**
+* Create
+* Delete
+* Find
+* FindAll
+* Update
+* Defaults - this adds **Find**, **FindAll**, **Create**, **Update**, and **Delete**
+
+**Bulk traits**
+* CreateMany
+* DeleteMany
+* FindMany
+* UpdateMany
+
+#### Utility Traits
+
+Use `Zendesk\API\Traits\Utility\InstantiatorTrait` when you want a resource to be chainable to other resources. See `Zendesk/API/Resources/Tickets.php`.
+
 ```php
-$tickets = $this->client->tickets()->sideload(array('users', 'groups'))->findAll();
+$this->client->tickets()->comments()->findAll();
 ```
 
 ## Note on Patches/Pull Requests
 1. Fork the project.
 2. Make your feature addition or bug fix.
 3. Add tests for it. This is important so that we don't break your improvement in a future version unintentionally.
+4. Please follow the [coding standard described above](#coding-standard).
 4. Commit and do not mess with version or history. (If you want to have
    your own version, that is fine but bump version in a commit by itself I can
    ignore when we pull)

composer.json

@@ -1,20 +1,23 @@
 {
-    "name": "zendesk/zendesk_api_client_php",
-    "description": "PHP Client for Zendesk REST API. See http://developer.zendesk.com/api-docs",
-    "license": "Apache License Version 2.0",
-    "homepage": "https://github.com/zendesk/zendesk_api_client_php",
-    "require": {
-		"php": ">=5.3.1"
-    },
-	"require-dev": {
-        "phpunit/phpunit": "4.5.*",
-        "squizlabs/php_codesniffer": "2.*",
-        "phpmd/phpmd" : "@stable",
-        "internations/http-mock": "dev-master"
-    },
-	"autoload": {
-        "psr-0": {
-            "Zendesk\\API\\": "src/"
-        }
+  "name": "zendesk/zendesk_api_client_php",
+  "description": "PHP Client for Zendesk REST API. See http://developer.zendesk.com/api-docs",
+  "license": "Apache License Version 2.0",
+  "version": "2.0.0-beta",
+  "homepage": "https://github.com/zendesk/zendesk_api_client_php",
+  "require": {
+    "php": ">=5.3.1",
+    "guzzlehttp/guzzle": "~6.0",
+    "mmucklo/inflect": "0.3.*"
+  },
+  "require-dev": {
+    "phpunit/phpunit": "4.5.*",
+    "squizlabs/php_codesniffer": "2.*",
+    "phpmd/phpmd": "@stable",
+    "fzaninotto/faker": ">=1.5.0"
+  },
+  "autoload": {
+    "psr-0": {
+      "Zendesk\\API\\": "src/"
     }
+  }
 }