Various feature updates

CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All Notable changes to `ixudra/curl` will be documented in this file
+
+## 6.12.0 - 2017-08-06
+### Added
+- File uploads by path
+- `returnResponseArray()` method
+- `enableXDebug()` method for easy xDebug integration
+- CHANGELOG file
+
+### Updated
+- README
+
+

README.md

@@ -308,20 +308,25 @@ Sending custom headers is easy with the `withcontentType()` method. Multiple cal
 
 ### Sending files via Curl
 
-For sending files via a POST request, you can use the `containsFile` method to correctly format a request before sending:
+For sending files via a POST request, you can use the `withFile` method to correctly format a request before sending:
 
 ```php
 
     use Ixudra\Curl\Facades\Curl;
 
-    $response = Curl::to('http://foo.com/bar.png')
-        ->withContentType('multipart/form-data')
-        ->withData( array( 'foz' => 'baz' ) )
-        ->containsFile()
+    $response = Curl::to('http://foo.com/bar')
+        ->withData( array( 'Foo' => 'Bar' ) )
+        ->withFile( 'image_1', '/path/to/dir/image1.png', 'image/png', 'imageName1.png' )
+        ->withFile( 'image_2', '/path/to/dir/image2.png', 'image/png', 'imageName2.png' )
         ->post();
 
 ```
 
+You can add as many files to the request as you want. A couple of things to keep in mind:
+
+- When submitting files, the `asJson()` method and `asJsonRequest()` method cannot be used. If you do, the files will not be transferred correctly
+- The files are added to the data that was provided in the `withData()` method using the first parameter of the `withFile()` method. If this key already exists, it will be overridden.
+
 
 ### Downloading files
 
@@ -405,6 +410,7 @@ any validation on the cURL options. Additional information about available cURL
 | withHeader()          |  array()          | Add an HTTP header to the request                                 |
 | withHeaders()         |  array()          | Add multiple HTTP headers to the request                          |
 | withContentType()     |  none             | Set the content type of the response                              |
+| withFile()            |  none             | Add a file to the form data to be sent                            |
 | containsFile()        |  false            | Should be used to submit files through forms                      |
 | withData()            |  array()          | Add an array of data to sent with the request (GET or POST)       |
 | setCookieFile()       |  none             | Set a file to store cookies in                                    |

composer.json

@@ -1,7 +1,7 @@
 {
     "name": "ixudra/curl",
     "description": "Custom PHP Curl library for the Laravel 5 framework - developed by Ixudra",
-    "version": "6.11.0",
+    "version": "6.12.0",
     "keywords": ["Ixudra", "Laravel", "Curl"],
     "homepage": "http://ixudra.be",
     "license": "MIT",

src/Builder.php

@@ -25,11 +25,14 @@ class Builder {
     /** @var array $packageOptions      Array with options that are not specific to cURL but are used by the package */
     protected $packageOptions = array(
         'data'                  => array(),
+        'files'                 => array(),
         'asJsonRequest'         => false,
         'asJsonResponse'        => false,
         'returnAsArray'         => false,
         'responseObject'        => false,
+        'responseArray'         => false,
         'enableDebug'           => false,
+        'xDebugSessionName'     => '',
         'containsFile'          => false,
         'debugFile'             => '',
         'saveFile'              => '',
@@ -69,6 +72,29 @@ class Builder {
         return $this->withPackageOption( 'data', $data );
     }
 
+    /**
+     * Add a file to the request
+     *
+     * @param   string $key          Identifier of the file (how it will be referenced by the server in the $_FILES array)
+     * @param   string $path         Full path to the file you want to send
+     * @param   string $mimeType     Mime type of the file
+     * @param   string $postFileName Name of the file when sent. Defaults to file name
+     *
+     * @return Builder
+     */
+    public function withFile($key, $path, $mimeType = '', $postFileName = '')
+    {
+        $fileData = array(
+            'fileName'     => $path,
+            'mimeType'     => $mimeType,
+            'postFileName' => $postFileName,
+        );
+
+        $this->packageOptions[ 'files' ][ $key ] = $fileData;
+
+        return $this->containsFile();
+    }
+
     /**
      * Allow for redirects in the request
      *
@@ -235,6 +261,16 @@ class Builder {
         return $this->withPackageOption( 'responseObject', true );
     }
 
+    /**
+     * Return a full response array with HTTP status and headers instead of only the content
+     *
+     * @return Builder
+     */
+    public function returnResponseArray()
+    {
+        return $this->withPackageOption( 'responseArray', true );
+    }
+
     /**
      * Enable debug mode for the cURL request
      *
@@ -258,6 +294,19 @@ class Builder {
         return $this->withPackageOption( 'containsFile', true );
     }
 
+    /**
+     * Add the XDebug session name to the request to allow for easy debugging
+     *
+     * @param  string $sessionName
+     * @return Builder
+     */
+    public function enableXDebug($sessionName = 'session_1')
+    {
+        $this->packageOptions[ 'xDebugSessionName' ] = $sessionName;
+
+        return $this;
+    }
+
     /**
      * Send a GET request to a URL using the specified cURL options
      *
@@ -303,6 +352,12 @@ class Builder {
         $this->curlOptions[ 'POST' ] = true;
 
         $parameters = $this->packageOptions[ 'data' ];
+        if( !empty($this->packageOptions[ 'files' ]) ) {
+            foreach( $this->packageOptions[ 'files' ] as $key => $file ) {
+                $parameters[ $key ] = $this->getCurlFileValue( $file[ 'fileName' ], $file[ 'mimeType' ], $file[ 'postFileName'] );
+            }
+        }
+
         if( $this->packageOptions[ 'asJsonRequest' ] ) {
             $parameters = json_encode($parameters);
         }
@@ -310,6 +365,22 @@ class Builder {
         $this->curlOptions[ 'POSTFIELDS' ] = $parameters;
     }
 
+    protected function getCurlFileValue($filename, $mimeType, $postFileName)
+    {
+        // PHP 5 >= 5.5.0, PHP 7
+        if( function_exists('curl_file_create') ) {
+            return curl_file_create($filename, $mimeType, $postFileName);
+        }
+
+        // Use the old style if using an older version of PHP
+        $value = "@{$filename};filename=" . $postFileName;
+        if( $mimeType ) {
+            $value .= ';type=' . $mimeType;
+        }
+
+        return $value;
+    }
+
     /**
      * Send a PUT request to a URL using the specified cURL options
      *
@@ -376,7 +447,7 @@ class Builder {
 
         // Capture additional request information if needed
         $responseData = array();
-        if( $this->packageOptions[ 'responseObject' ] ) {
+        if( $this->packageOptions[ 'responseObject' ] || $this->packageOptions[ 'responseArray' ] ) {
             $responseData = curl_getinfo( $this->curlObject );
 
             if( curl_errno($this->curlObject) ) {
@@ -407,14 +478,10 @@ class Builder {
     /**
      * @param   mixed $content          Content of the request
      * @param   array $responseData     Additional response information
-     * @return stdClass
+     * @return mixed
      */
     protected function returnResponse($content, array $responseData = array())
     {
-        if( !$this->packageOptions[ 'responseObject' ] ) {
-            return $content;
-        }
-
         $object = new stdClass();
         $object->content = $content;
         $object->status = $responseData[ 'http_code' ];
@@ -422,7 +489,15 @@ class Builder {
             $object->error = $responseData[ 'errorMessage' ];
         }
 
-        return $object;
+        if( $this->packageOptions[ 'responseObject' ] ) {
+            return $object;
+        }
+
+        if( $this->packageOptions[ 'responseArray' ] ) {
+            return (array) $object;
+        }
+
+        return $content;
     }
 
     /**
@@ -443,6 +518,13 @@ class Builder {
             }
         }
 
+        if( !empty($this->packageOptions[ 'xDebugSessionName' ]) ) {
+            $char = strpos($this->curlOptions[ 'URL' ], '?') ? '&' : '?';
+            $this->curlOptions[ 'URL' ] .= $char . 'XDEBUG_SESSION_START='. $this->packageOptions[ 'xDebugSessionName' ];
+        }
+
+        dd( $this->curlOptions );
+
         return $results;
     }