Merge pull request #43 from djagya/42-fix-namespaces-clean-code

Fixed namespaces, cleaned code/comments - closes #42

Author: jasonrhodes

.gitignore

@@ -4,3 +4,4 @@
 .buildpath
 test/output/
 examples/example-config.json
+.idea

composer.json

@@ -2,7 +2,7 @@
     "name": "sparkpost/php-sparkpost",
     "description": "Client library for interfacing with the SparkPost API.",
     "license": "Apache 2.0",
-    "version": "1.0.1",
+    "version": "1.0.2",
     "authors": [
       {
         "name": "Message Systems, Inc."

lib/SendGridCompatibility/Email.php

@@ -4,19 +4,18 @@
 class Email {
   public $model;
 
-
   /**
-   * @desc Sets up the model for saving the configuration
+   * Sets up the model for saving the configuration
    */
   public function __construct() {
     $this->model = array();
   }
 
   /**
-   * @desc adds addresses as recipients
+   * adds addresses as recipients
    * @param string $address
    * @param string $name optional
-   * @return \SparkPost\SendGridCompatibility\Email
+   * @return $this
    */
    public function addTo($address, $name = null) {
     if (!isset($this->model['recipients'])) {
@@ -34,28 +33,30 @@ public function addTo($address, $name = null) {
   }
 
   /**
-  * @desc explicitly sets a list of addresses
+  * explicitly sets a list of addresses
   * @param array $addresses
-  * @return \SparkPost\SendGridCompatibility\Email
+  * @return $this
   */
   public function setTos(array $addresses) {
     $this->model['recipients'] = $addresses;
     return $this;
   }
 
   /**
-   * @desc sets the from address
+   * sets the from address
    * @param string $address
-   * @return \MessageSystems\SendGridCompatibility\Email
+   * @return $this
    */
   public function setFrom($address) {
     $this->model['from'] = array('email' => $address);
     return $this;
   }
 
   /**
-   * @desc sets the name for the from address
+   * Sets the name for the from address
    * @param string $name
+   * @return $this
+   * @throws \Exception
    */
   public function setFromName($name) {
     if(!isset($this->model['from'])){
@@ -66,58 +67,57 @@ public function setFromName($name) {
   }
 
   /**
-   * @desc sets the reply to field
+   * sets the reply to field
    * @param string $address
-   * @return \MessageSystems\SendGridCompatibility\Email
+   * @return $this
    */
   public function setReplyTo ($address) {
     $this->model['replyTo'] = $address;
     return $this;
   }
 
   /**
-   * @desc throws an error because bcc fields are not yet implemented.
+   * throws an error because bcc fields are not yet implemented.
    * @throws \Exception
    * @param string $address
-   * @return \MessageSystems\SendGridCompatibility\Email
+   * @return $this
    */
   public function addBcc($address) {
     throw new \Exception('Adding bcc recipients is not yet supported, try adding them as a \'to\' address');
   }
 
   /**
-   * @desc sets the subject header
+   * sets the subject header
    * @param string $subject
-   * @return \SparkPost\SendGridCompatibility\Email
+   * @return $this
    */
   public function setSubject($subject) {
     $this->model['subject'] = $subject;
     return $this;
   }
 
   /**
-   * @desc sets the text body
+   * sets the text body
    * @param string $text
-   * @return \SparkPost\SendGridCompatibility\Email
+   * @return $this
    */
   public function setText($text) {
     $this->model['text'] = $text;
     return $this;
   }
 
   /**
-   * @desc sets the html body
+   * sets the html body
    * @param string $html
-   * @return \SparkPost\SendGridCompatibility\Email
+   * @return $this
    */
   public function setHtml($html) {
     $this->model['html'] = $html;
     return $this;
   }
 
   /**
-   * @desc Throws an exception since adding categories is not yet supported
-   * @throws \Exception
+   * Throws an exception since adding categories is not yet supported
    * @param string $category
    * @throws \Exception
    */
@@ -126,19 +126,19 @@ public function addCategory($category) {
   }
 
   /**
-   * @desc Throws an exception since adding attachments is not yet supported
-   * @throws Exception
+   * Throws an exception since adding attachments is not yet supported
+   * @throws \Exception
    * @param mixed $attachment
    */
   public function addAttachment($attachment) {
     throw new \Exception('Adding attachments is not yet supported');
   }
 
   /**
-   * @desc Adds transmission level substitution data
+   * Adds transmission level substitution data
    * @param string $name
    * @param mixed $values
-   * @return \SparkPost\SendGridCompatibility\Email
+   * @return $this
    */
   public function addSubstitution($name, $values) {
     if (!isset($this->model['substitutionData'])) {
@@ -150,7 +150,7 @@ public function addSubstitution($name, $values) {
   }
 
   /**
-   * @desc Adds transmission level substitution data
+   * Adds transmission level substitution data
    * @param string $name
    * @param mixed $values
    */
@@ -159,25 +159,25 @@ public function addSection($name, $values) {
   }
 
   /**
-   * @desc Throws an exception because arguments for third party systems is not supported
-   * @throws Exception
+   * Throws an exception because arguments for third party systems is not supported
+   * @throws \Exception
    * @param mixed $value
    */
   public function addUniqueArg($key, $value) {
     throw new \Exception('Adding Unique Arguments is not yet supported');
   }
 
   /**
-   * @desc Throws an exception because arguments for third party systems is not supported
-   * @throws Exception
+   * Throws an exception because arguments for third party systems is not supported
+   * @throws \Exception
    * @param mixed $values
    */
   public function setUniqueArgs(array $values) {
     throw new \Exception('Setting Unique Arguments is not yet supported');
   }
 
   /**
-   * @desc Adds custom headers to the email header
+   * Adds custom headers to the email header
    * @param string $name
    * @param string $value
    */
@@ -189,7 +189,7 @@ public function addHeader($name, $value) {
   }
 
   /**
-   * @desc converts this object to a configuration for a SparkPost transmission
+   * converts this object to a configuration for a SparkPost transmission
    * @return array
    */
   public function toSparkPostTransmission() {

lib/SendGridCompatibility/SendGrid.php

@@ -2,7 +2,6 @@
 namespace SparkPost\SendGridCompatibility;
 
 use SparkPost\SparkPost;
-use SparkPost\SendGridCompatibility\Email;
 
 class SendGrid{
   private $sparky;

lib/SparkPost/APIResource.php

@@ -1,50 +1,46 @@
 <?php
 namespace SparkPost;
-use Ivory\HttpAdapter\HttpAdapterException;
-use SparkPost\SparkPost;
-
-
 
 /**
- * @desc SDK interface for managing SparkPost API endpoints
+ * SDK interface for managing SparkPost API endpoints
  */
 class APIResource {
 
   /**
-   * @desc name of the API endpoint, mainly used for URL construction.
+   * name of the API endpoint, mainly used for URL construction.
    * This is public to provide an interface
    *
    * @var string
    */
   public $endpoint;
 
   /**
-   * @desc Mapping for values passed into the send method to the values needed for the respective API
+   * Mapping for values passed into the send method to the values needed for the respective API
    * @var array
    */
   protected static $parameterMappings = [];
 
   /**
-   * @desc Sets up default structure and default values for the model that is acceptable by the API
+   * Sets up default structure and default values for the model that is acceptable by the API
    * @var array
    */
   protected static $structure = [];
 
   /**
-   * @desc SparkPost reference for httpAdapters and configs
+   * SparkPost reference for httpAdapters and configs
    */
   protected $sparkpost;
 
   /**
-   * @desc Initializes config and httpAdapter for use later.
-   * @param $sparkpost SparkPost\SparkPost provides api configuration information
+   * Initializes config and httpAdapter for use later.
+   * @param $sparkpost \SparkPost\SparkPost provides api configuration information
    */
   public function __construct(SparkPost $sparkpost) {
     $this->sparkpost = $sparkpost;
   }
 
   /**
-   * @desc Private Method helper to reference parameter mappings and set the right value for the right parameter
+   * Private Method helper to reference parameter mappings and set the right value for the right parameter
    *
    * @param array $model (pass by reference) the set of values to map
    * @param string $mapKey a dot syntax path determining which value to set
@@ -76,9 +72,9 @@ protected function setMappedValue(&$model, $mapKey, $value) {
   }
 
   /**
-   * @desc maps values from the passed in model to those needed for the request
-   * @param $requestConfig the passed in model
-   * @param $model the set of defaults
+   * maps values from the passed in model to those needed for the request
+   * @param array $requestConfig the passed in model
+   * @param array $model the set of defaults
    * @return array A model ready for the body of a request
    */
   protected function buildRequestModel(Array $requestConfig, Array $model=[] ) {
@@ -89,39 +85,41 @@ protected function buildRequestModel(Array $requestConfig, Array $model=[] ) {
   }
 
   /**
-   * @desc posts to the api with a supplied body
-   * @param body post body for the request
+   * posts to the api with a supplied body
+   * @param array $body post body for the request
    * @return array Result of the request
    */
   public function create(Array $body=[]) {
     return $this->callResource( 'post', null, ['body'=>$body]);
   }
 
   /**
-   * @desc Makes a put request to the api with a supplied body
-   * @param body Put body for the request
+   * Makes a put request to the api with a supplied body
+   * @param $resourcePath
+   * @param array $body Put body for the request
    * @return array Result of the request
+   * @throws APIResponseException
    */
   public function update( $resourcePath, Array $body=[]) {
     return $this->callResource( 'put', $resourcePath, ['body'=>$body]);
   }
 
   /**
-   * @desc Wrapper method for issuing GET request to current API endpoint
+   * Wrapper method for issuing GET request to current API endpoint
    *
    * @param string $resourcePath (optional) string resource path of specific resource
-   * @param array $options (optional) query string parameters
+   * @param array $query (optional) query string parameters
    * @return array Result of the request
    */
   public function get( $resourcePath=null, Array $query=[] ) {
     return $this->callResource( 'get', $resourcePath, ['query'=>$query] );
   }
 
   /**
-   * @desc Wrapper method for issuing DELETE request to current API endpoint
+   * Wrapper method for issuing DELETE request to current API endpoint
    *
    * @param string $resourcePath (optional) string resource path of specific resource
-   * @param array $options (optional) query string parameters
+   * @param array $query (optional) query string parameters
    * @return array Result of the request
    */
   public function delete( $resourcePath=null, Array $query=[] ) {
@@ -130,13 +128,13 @@ public function delete( $resourcePath=null, Array $query=[] ) {
 
 
   /**
-   * @desc assembles a URL for a request
+   * assembles a URL for a request
    * @param string $resourcePath path after the initial endpoint
-   * @param array options array with an optional value of query with values to build a querystring from.
+   * @param array $options array with an optional value of query with values to build a querystring from.
    * @return string the assembled URL
    */
   private function buildUrl($resourcePath, $options) {
-    $url = join(['/', $this->endpoint, '/']);
+    $url = "/{$this->endpoint}/";
     if (!is_null($resourcePath)){
       $url .= $resourcePath;
     }
@@ -151,8 +149,8 @@ private function buildUrl($resourcePath, $options) {
 
 
   /**
-   * @desc Prepares a body for put and post requests
-   * @param array options array with an optional value of body with values to build a request body from.
+   * Prepares a body for put and post requests
+   * @param array $options array with an optional value of body with values to build a request body from.
    * @return string|null A json encoded string or null if no body was provided
    */
   private function buildBody($options) {
@@ -165,9 +163,8 @@ private function buildBody($options) {
     return $body;
   }
 
-
   /**
-   * @desc Private Method for issuing GET and DELETE request to current API endpoint
+   * Private Method for issuing GET and DELETE request to current API endpoint
    *
    *  This method is responsible for getting the collection _and_
    *  a specific entity from the API endpoint
@@ -178,6 +175,7 @@ private function buildBody($options) {
    * @param string $resourcePath (optional) string resource path of specific resource
    * @param array $options (optional) query string parameters
    * @return array Result set of action performed on resource
+   * @throws APIResponseException
    */
   private function callResource( $action, $resourcePath=null, $options=[] ) {
     $action = strtoupper($action); // normalize