Merge pull request #33 from MichaelJ2324/2.0

ME Endpoint Fix

.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

@@ -6,9 +6,23 @@
 namespace Sugarcrm\REST\Endpoint;
 
 use MRussell\Http\Request\JSON;
-use MRussell\REST\Endpoint\Abstracts\AbstractModelEndpoint;
+use MRussell\REST\Endpoint\JSON\ModelEndpoint;
 
-class Me extends AbstractModelEndpoint
+/**
+ * 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';
 
@@ -26,6 +40,11 @@ class Me extends AbstractModelEndpoint
 
     const USER_ACTION_FOLLOWING = 'following';
 
+    protected static $_DEFAULT_PROPERTIES = array(
+        self::PROPERTY_AUTH => true,
+        self::PROPERTY_HTTP_METHOD => JSON::HTTP_GET
+    );
+
     /**
      * @inheritdoc
      */
@@ -52,6 +71,14 @@ public function __construct(array $options = array(), array $properties = array(
         }
     }
 
+    /**
+     * @inheritdoc
+     * @codeCoverageIgnore
+     */
+    public function compileRequest(){
+        return $this->configureRequest($this->getRequest());
+    }
+
     /**
      * Redefine some Actions to another Action, for use in URL
      * @inheritdoc

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(
             )
         )
     );