Inline Code Docs + PHPDoc + Ping Endpoint

Updated inline documentation, for use with PHPDoc, and better dynamic
method handling in IDEs.

Tweaked Static Storage to stop JSON Encoding values (as its not
necessary for static storage), and remove the default behavior to JSON
Decode retrieved tokens from storage in the OAuth Controller (found
this issue out when building out stuff for Portal).

Added Ping & Ping/whattimeisit Endpoints to match v1 functionality.

Added Unit Tests for new functionality, and added test to check for
Requests on all endpoints, since I missed that previously.

.gitignore

@@ -3,3 +3,4 @@
 vendor/
 composer.lock
 coverage/
+docs/

composer.json

@@ -23,7 +23,8 @@
     "michaelj2324/php-rest-client": ">=1.3.0"
   },
   "require-dev": {
-    "phpunit/phpunit": "~4.0|~5.0"
+    "phpunit/phpunit": "~4.0|~5.0",
+    "phpdocumentor/phpdocumentor": "2.*"
   },
   "autoload": {
     "psr-4": {

src/Auth/SugarOAuthController.php

@@ -8,6 +8,14 @@
 use MRussell\REST\Auth\Abstracts\AbstractOAuth2Controller;
 use MRussell\REST\Endpoint\Interfaces\EndpointInterface;
 
+/**
+ * The Authentication Controller for the Sugar 7 REST Client
+ * - Manages authenticating to API
+ * - Manages refreshing API token for continuous access
+ * - Manages logout
+ * - Configures Endpoints that require auth, so that Requests are properly formatted
+ * @package Sugarcrm\REST\Auth
+ */
 class SugarOAuthController extends AbstractOAuth2Controller
 {
     const ACTION_SUGAR_SUDO = 'sudo';
@@ -60,7 +68,6 @@ public function setCredentials(array $credentials)
         if (!empty($this->credentials)){
             $token = $this->getStoredToken($this->credentials);
             if ($token !== NULL){
-                $token = json_decode($token,TRUE);
                 if (is_array($token)){
                     $this->setToken($token);
                 }

src/Client/Sugar7API.php

@@ -6,29 +6,23 @@
 namespace Sugarcrm\REST\Client;
 
 use MRussell\REST\Client\AbstractClient;
-use MRussell\REST\Endpoint\Interfaces\EndpointInterface;
 use Sugarcrm\REST\Helpers\Helper;
 use Sugarcrm\REST\Auth\SugarOAuthController;
 use Sugarcrm\REST\Endpoint\Provider\SugarEndpointProvider;
-use Sugarcrm\REST\Endpoint\Module;
-use Sugarcrm\REST\Endpoint\ModuleFilter;
-use Sugarcrm\REST\Endpoint\Search;
-use Sugarcrm\REST\Endpoint\Metadata;
-use Sugarcrm\REST\Endpoint\Me;
-use Sugarcrm\REST\Endpoint\Enum;
 use Sugarcrm\REST\Storage\SugarStaticStorage;
 
 /**
- * The Abstract Client implementation for Sugar
+ * The default Sugar 7 REST v10 API implementation
  * @package Sugarcrm\REST\Client\Abstracts\AbstractClient
- * @method EndpointInterface ping()
- * @method Module       module(string $module = '',string $record_id = '')
- * @method ModuleFilter list(string $module = '')
- * @method Search       search()
- * @method Metadata     metadata(string $module = '')
- * @method Me           user(string $user_id)
- * @method Enum         enum(string $module,string $field)
-*/
+ * @method \Sugarcrm\REST\Endpoint\Ping             ping()
+ * @method \Sugarcrm\REST\Endpoint\Module           module(string $module = '',string $record_id = '')
+ * @method \Sugarcrm\REST\Endpoint\ModuleFilter     list(string $module = '')
+ * @method \Sugarcrm\REST\Endpoint\Search           search()
+ * @method \Sugarcrm\REST\Endpoint\Metadata         metadata(string $module = '')
+ * @method \Sugarcrm\REST\Endpoint\Me               me()
+ * @method \Sugarcrm\REST\Endpoint\Enum             enum(string $module = '',string $field = '')
+ * @method \Sugarcrm\REST\Endpoint\Bulk             bulk()
+ */
 class Sugar7API extends AbstractClient
 {
     /**

src/Endpoint/Abstracts/AbstractSmartSugarEndpoint.php

@@ -9,7 +9,7 @@
 use Sugarcrm\REST\Endpoint\SugarEndpointInterface;
 
 /**
- * Class AbstractSmartSugarEndpoint
+ * Provide a smarter interface for Endpoints, to better manage passed in data
  * @package Sugarcrm\REST\Endpoint\Abstracts
  */
 class AbstractSmartSugarEndpoint extends SmartEndpoint implements SugarEndpointInterface

src/Endpoint/Abstracts/AbstractSugarBeanCollectionEndpoint.php

@@ -6,7 +6,10 @@
 namespace Sugarcrm\REST\Endpoint\Abstracts;
 
 /**
- * Class AbstractSugarBeanCollectionEndpoint
+ * Abstract implementation of SugarBean Collections for Sugar 7 REST Api
+ * - Works with a single module
+ * - Built in fields tracking
+ * - Built in order by tracking
  * @package Sugarcrm\REST\Endpoint\Abstracts
  */
 abstract class AbstractSugarBeanCollectionEndpoint extends AbstractSugarCollectionEndpoint

src/Endpoint/Abstracts/AbstractSugarBeanEndpoint.php

@@ -8,10 +8,27 @@
 use MRussell\Http\Request\JSON;
 use MRussell\Http\Request\RequestInterface;
 use MRussell\Http\Response\ResponseInterface;
+use MRussell\REST\Endpoint\Data\EndpointData;
 use MRussell\REST\Endpoint\JSON\ModelEndpoint;
 use Sugarcrm\REST\Endpoint\Data\FilterData;
 use Sugarcrm\REST\Endpoint\SugarEndpointInterface;
 
+/**
+ * SugarBean Endpoint acts as a base for any given Module API
+ * - Provides action based interface for accessing stock and custom actions
+ * @package Sugarcrm\REST\Endpoint\Abstracts
+ * @method $this    filterLink(string $link_name = '',string $count = '')
+ * @method $this    massLink(string $link_name)
+ * @method $this    createLink(string $link_name)
+ * @method $this    unlink(string $link_name,string $record_id)
+ * @method $this    favorite()
+ * @method $this    unfavorite()
+ * @method $this    subscribe()
+ * @method $this    unsubscribe()
+ * @method $this    audit()
+ * @method $this    file()
+ * @method $this    downloadFile(string $field)
+ */
 abstract class AbstractSugarBeanEndpoint extends ModelEndpoint implements SugarEndpointInterface
 {
     const MODEL_ACTION_VAR = 'action';
@@ -56,10 +73,10 @@ abstract class AbstractSugarBeanEndpoint extends ModelEndpoint implements SugarE
      * @inheritdoc
      */
     protected static $_DEFAULT_PROPERTIES = array(
-        'auth' => TRUE,
-        'data' => array(
-            'required' => array(),
-            'defaults' => array()
+        self::PROPERTY_AUTH => TRUE,
+        self::PROPERTY_DATA => array(
+            EndpointData::DATA_PROPERTY_REQUIRED => array(),
+            EndpointData::DATA_PROPERTY_DEFAULTS => array()
         )
     );
 
@@ -81,7 +98,7 @@ abstract class AbstractSugarBeanEndpoint extends ModelEndpoint implements SugarE
         self::BEAN_ACTION_UNLINK => JSON::HTTP_DELETE,
         self::BEAN_ACTION_CREATE_RELATED => JSON::HTTP_POST,
         self::BEAN_ACTION_FOLLOW => JSON::HTTP_POST,
-        self::BEAN_ACTION_UNFOLLOW => JSON::HTTP_PUT,
+        self::BEAN_ACTION_UNFOLLOW => JSON::HTTP_DELETE,
         self::BEAN_ACTION_AUDIT => JSON::HTTP_GET,
         self::BEAN_ACTION_FILE => JSON::HTTP_GET,
         self::BEAN_ACTION_DOWNLOAD_FILE => JSON::HTTP_GET,
@@ -305,6 +322,24 @@ protected function updateModel()
         }
     }
 
+    /**
+     * System friendly name for subscribing to a record
+     * @return self
+     */
+    public function follow()
+    {
+        return $this->subscribe();
+    }
+
+    /**
+     * System friendly name for unsubscribing to a record
+     * @return self
+     */
+    public function unfollow()
+    {
+        return $this->unsubscribe();
+    }
+
     /**
      * Human friendly method name for Link action
      * @param string $linkName - Relationship Link Name
@@ -398,6 +433,7 @@ public function attachFile($fileField,$filePath,$deleteOnFail = false,$mimeType
     }
 
     /**
+     * Overloading tempFile dynamic method to provide more functionality
      * @param $fileField
      * @param $filePath
      * @param bool $deleteOnFail

src/Endpoint/Abstracts/AbstractSugarCollectionEndpoint.php

@@ -5,9 +5,15 @@
 
 namespace Sugarcrm\REST\Endpoint\Abstracts;
 
+use MRussell\REST\Endpoint\Data\EndpointData;
 use MRussell\REST\Endpoint\JSON\CollectionEndpoint;
 use Sugarcrm\REST\Endpoint\SugarEndpointInterface;
 
+/**
+ * Provides access to a multi-bean collection retrieved from Sugar 7 REST Api
+ * - Built in pagination functionality
+ * @package Sugarcrm\REST\Endpoint\Abstracts
+ */
 abstract class AbstractSugarCollectionEndpoint extends CollectionEndpoint implements SugarEndpointInterface
 {
     const SUGAR_OFFSET_PROPERTY = 'offset';
@@ -22,10 +28,10 @@ abstract class AbstractSugarCollectionEndpoint extends CollectionEndpoint implem
      * @inehritdoc
      */
     protected static $_DEFAULT_PROPERTIES = array(
-        'auth' => TRUE,
-        'data' => array(
-            'required' => array(),
-            'defaults' => array()
+        self::PROPERTY_AUTH => TRUE,
+        self::PROPERTY_DATA => array(
+            EndpointData::DATA_PROPERTY_REQUIRED => array(),
+            EndpointData::DATA_PROPERTY_DEFAULTS => array()
         )
     );
 

src/Endpoint/Abstracts/AbstractSugarEndpoint.php

@@ -8,6 +8,10 @@
 use MRussell\REST\Endpoint\JSON\Endpoint;
 use Sugarcrm\REST\Endpoint\SugarEndpointInterface;
 
+/**
+ * Base Sugar API Endpoint for the simplest of REST functionality
+ * @package Sugarcrm\REST\Endpoint\Abstracts
+ */
 abstract class AbstractSugarEndpoint extends Endpoint implements SugarEndpointInterface
 {
     /**

src/Endpoint/Bulk.php

@@ -6,10 +6,12 @@
 namespace Sugarcrm\REST\Endpoint;
 
 use MRussell\Http\Request\JSON;
+use MRussell\REST\Endpoint\Data\EndpointData;
 use Sugarcrm\REST\Endpoint\Abstracts\AbstractSmartSugarEndpoint;
 
 /**
- * Class Bulk
+ * Bulk Endpoint allows for submitting multiple REST Requests in a single request
+ * - Consumes other Endpoint Objects for ease of use
  * @package Sugarcrm\REST\Endpoint
  */
 class Bulk extends AbstractSmartSugarEndpoint
@@ -28,13 +30,13 @@ class Bulk extends AbstractSmartSugarEndpoint
      * @var array
      */
     protected static $_DEFAULT_PROPERTIES = array(
-        'auth' => TRUE,
-        'httpMethod' => JSON::HTTP_POST,
-        'data' => array(
-            'required' => array(
+        self::PROPERTY_AUTH => TRUE,
+        self::PROPERTY_HTTP_METHOD => JSON::HTTP_POST,
+        self::PROPERTY_DATA => array(
+            EndpointData::DATA_PROPERTY_REQUIRED => array(
                 'requests' => 'array'
             ),
-            'defaults' => array()
+            EndpointData::DATA_PROPERTY_DEFAULTS => array()
         )
     );
 

src/Endpoint/Enum.php

@@ -8,12 +8,16 @@
 use MRussell\Http\Request\JSON;
 use Sugarcrm\REST\Endpoint\Abstracts\AbstractSugarEndpoint;
 
+/**
+ * Enum Endpoint provides access to the defined Enum values for a given module field
+ * @package Sugarcrm\REST\Endpoint
+ */
 class Enum extends AbstractSugarEndpoint
 {
     protected static $_ENDPOINT_URL = '$module/enum/$field';
 
     protected static $_DEFAULT_PROPERTIES = array(
-        'auth' => true,
-        'httpMethod' => JSON::HTTP_GET
+        self::PROPERTY_AUTH => true,
+        self::PROPERTY_HTTP_METHOD => JSON::HTTP_GET
     );
 }

src/Endpoint/Me.php

@@ -8,6 +8,20 @@
 use MRussell\Http\Request\JSON;
 use MRussell\REST\Endpoint\JSON\ModelEndpoint;
 
+/**
+ * Me Endpoint provides access to current logged in user details
+ * - Can view and update user
+ * - Can view and update user preferences
+ * - Can view followed records
+ * @package Sugarcrm\REST\Endpoint
+ * @method $this    preferences()
+ * @method $this    savePreferences()
+ * @method $this    preference(string $preference)
+ * @method $this    createPreference(string $preference)
+ * @method $this    updatePreference(string $preference)
+ * @method $this    deletePreference(string $preference)
+ * @method $this    following()
+ */
 class Me extends ModelEndpoint implements SugarEndpointInterface
 {
     const MODEL_ACTION_VAR = 'action';
@@ -27,8 +41,8 @@ class Me extends ModelEndpoint implements SugarEndpointInterface
     const USER_ACTION_FOLLOWING = 'following';
 
     protected static $_DEFAULT_PROPERTIES = array(
-        'auth' => true,
-        'httpMethod' => JSON::HTTP_GET
+        self::PROPERTY_AUTH => true,
+        self::PROPERTY_HTTP_METHOD => JSON::HTTP_GET
     );
 
     /**

src/Endpoint/Metadata.php

@@ -9,7 +9,7 @@
 use Sugarcrm\REST\Endpoint\Abstracts\AbstractSugarEndpoint;
 
 /**
- * Class Metadata
+ * Metadata Endpoint provides access to the defined Metadata of the system
  * @package Sugarcrm\REST\Endpoint
  */
 class Metadata extends AbstractSugarEndpoint

src/Endpoint/Module.php

@@ -7,6 +7,10 @@
 
 use Sugarcrm\REST\Endpoint\Abstracts\AbstractSugarBeanEndpoint;
 
+/**
+ * Stock Module Endpoint
+ * @inheritdoc
+ */
 class Module extends AbstractSugarBeanEndpoint
 {
 }

src/Endpoint/ModuleFilter.php

@@ -11,7 +11,11 @@
 use Sugarcrm\REST\Endpoint\Data\FilterData;
 
 /**
- * Class ModuleFilter
+ * Provides access to the Filter API for a given Module
+ * - Also allows for retrieving counts of filters/records
+ * - Works with a single Module Bean type
+ * - Provides access to the Filter API and Filter Query Builder
+ * - Tracks pagination
  * @package Sugarcrm\REST\Endpoint
  */
 class ModuleFilter extends AbstractSugarBeanCollectionEndpoint

src/Endpoint/OAuth2Logout.php

@@ -6,23 +6,24 @@
 namespace Sugarcrm\REST\Endpoint;
 
 use MRussell\Http\Request\Curl;
+use MRussell\REST\Endpoint\Data\EndpointData;
 use Sugarcrm\REST\Endpoint\Abstracts\AbstractSmartSugarEndpoint;
 
 /**
- * Class OAuth2Logout
+ * The OAuth2 Logout Endpoint
  * @package Sugarcrm\REST\Endpoint
  */
 class OAuth2Logout extends AbstractSmartSugarEndpoint
 {
     protected static $_ENDPOINT_URL = 'oauth2/logout';
 
     protected static $_DEFAULT_PROPERTIES = array(
-        'auth' => TRUE,
-        'httpMethod' => Curl::HTTP_POST,
-        'data' => array(
-            'required' => array(
+        self::PROPERTY_AUTH => TRUE,
+        self::PROPERTY_HTTP_METHOD => Curl::HTTP_POST,
+        self::PROPERTY_DATA => array(
+            EndpointData::DATA_PROPERTY_REQUIRED => array(
             ),
-            'defaults' => array(
+            EndpointData::DATA_PROPERTY_DEFAULTS => array(
             )
         )
     );