|
| 1 | +--- |
| 2 | +group: web-api |
| 3 | +title: Use cURL to run the request |
| 4 | +functional_areas: |
| 5 | + - Integration |
| 6 | +--- |
| 7 | + |
| 8 | +['cURL'](https://curl.haxx.se/) is a command-line tool that lets you transmit HTTP requests and receive responses from the command line or a shell script. It is available for Linux distributions, Mac OS X, and Windows. |
| 9 | + |
| 10 | +To use cURL to run your REST web [API](https://glossary.magento.com/api) call, use the cURL command syntax to construct the command. |
| 11 | + |
| 12 | +To create the endpoint in the call, append the REST URI that you constructed in [Construct a request]({{ page.baseurl }}/get-started/gs-web-api-request.html) to this URL: |
| 13 | + |
| 14 | +`https://<MAGENTO_HOST_OR_IP>/<MAGENTO_BASE_INSTALL_DIR>/rest/` |
| 15 | + |
| 16 | +To pass the customer data object in the POST call payload, specify a JSON or [XML](https://glossary.magento.com/xml) request body on the call. |
| 17 | + |
| 18 | +For a complete list of cURL command options, see [curl.1 the man page](http://curl.haxx.se/docs/manpage.html). |
| 19 | + |
| 20 | +The cURL examples in this guide use the following command-line options: |
| 21 | + |
| 22 | +Option | Description |
| 23 | +--- | --- |
| 24 | +`-d` `-data` | Sends the specified data in a POST request to the HTTP server. Use this option to send a JSON or XML request body to the server. |
| 25 | +`-H` `-header` | Specifies an extra HTTP header in the request. Precede each header with the `-H` option. You can specify any number of extra headers. For a list of common headers used in Magento web API requests, see [HTTP headers]({{ page.baseurl }}/get-started/gs-web-api-request.html#http-headers) |
| 26 | +`-i` `-input` | Includes the HTTP header in the output. |
| 27 | +`-s` `-silent` | Specifies silent or quiet mode, which makes cURL mute. Progress and error messages are suppressed. |
| 28 | +`-T` `-upload-file` | Transfers the specified local file to the remote URL. |
| 29 | +`-X` `-request` | Specifies the request method to use when communicating with the HTTP server. The specified request method is used instead of the default GET method. |
| 30 | + |
| 31 | +## Using cUrl in Magento |
| 32 | + |
| 33 | +Magento provides its own service-wrapper for using cURL instead of using the default PHP cURL. The class ``Magento\Framework\HTTP\Client\Curl`` may be used to work with HTTP protocol using cURL library. |
| 34 | +First, create an instance of `Magento\Framework\HTTP\Client\Curl`. |
| 35 | + |
| 36 | +```php |
| 37 | +/** |
| 38 | +* Constructor. |
| 39 | +* |
| 40 | +* @param Magento\Framework\HTTP\Client\Curl $curl |
| 41 | +*/ |
| 42 | +public function __construct( |
| 43 | + Magento\Framework\HTTP\Client\Curl $curl |
| 44 | +) { |
| 45 | + $this->curl = $curl; |
| 46 | +} |
| 47 | +``` |
| 48 | + |
| 49 | +### Make GET request using cURL |
| 50 | + |
| 51 | +```php |
| 52 | +// get method |
| 53 | +$this->curl->get($url); |
| 54 | + |
| 55 | +// output of curl request |
| 56 | +$result = $this->curl->getBody(); |
| 57 | +``` |
| 58 | + |
| 59 | +where `$url` is the endpoint URL. |
| 60 | + |
| 61 | +### Make POST request using cURL |
| 62 | + |
| 63 | +```php |
| 64 | +// post method |
| 65 | +$this->curl->post($url, $params); |
| 66 | + |
| 67 | +// output of curl requestt |
| 68 | +$result = $this->curl->getBody(); |
| 69 | +``` |
| 70 | + |
| 71 | +where `$url` is the endpoint URL, `$params` is an array of data that is being sent via the POST request. Other parameters may be added in the URL directly. |
| 72 | +A `$params` example: |
| 73 | + |
| 74 | +```php |
| 75 | +$params = [ |
| 76 | + 'user[email]' => $user->getEmail(), |
| 77 | + 'user[cellphone]' => $providerInfo['phone_number'], |
| 78 | + 'user[country_code]' => $providerInfo['country_code'], |
| 79 | +] |
| 80 | +``` |
| 81 | + |
| 82 | +The cURL client can also add headers, basic authorization, additional cURL options, and cookies in the cURL request. The cURL client provides these methods before using `get` or `post` method. |
| 83 | + |
| 84 | +### Set cURL header using addHeader method |
| 85 | + |
| 86 | +The `addHeader` method accepts two parameters. The cURL header name and a cURL header value. |
| 87 | + |
| 88 | +```php |
| 89 | +$this->curl->addHeader("Content-Type", "application/json"); |
| 90 | +$this->curl->addHeader("Content-Length", 200); |
| 91 | +``` |
| 92 | + |
| 93 | +### Set cURL header using setHeaders method |
| 94 | + |
| 95 | +The `setHeaders` method accepts an array as a parameter. |
| 96 | + |
| 97 | +```php |
| 98 | +$headers = ["Content-Type" => "application/json", "Content-Length" => "200"]; |
| 99 | +$this->curl->setHeaders($headers); |
| 100 | +``` |
| 101 | + |
| 102 | +### Set basic authorization in cURL |
| 103 | + |
| 104 | +Set the basic authorization using the `setCredentials` method. |
| 105 | + |
| 106 | +```php |
| 107 | +$userName = "User_Name"; |
| 108 | +$password = "User_Password"; |
| 109 | + |
| 110 | +$this->curl->setCredentials($userName, $password); |
| 111 | +``` |
| 112 | + |
| 113 | +It is equivalent to setting CURLOPT_HTTPHEADER value: |
| 114 | + |
| 115 | +```php |
| 116 | +"Authorization : " . "Basic " . base64_encode($userName . ":" . $password) |
| 117 | +``` |
| 118 | + |
| 119 | +### Set cURL option using setOption method |
| 120 | + |
| 121 | +The `setOption` method accepts two parameters. The cURL option name and the cURL option value. |
| 122 | + |
| 123 | +```php |
| 124 | +$this->curl->setOption(CURLOPT_RETURNTRANSFER, true); |
| 125 | +$this->curl->setOption(CURLOPT_PORT, 8080); |
| 126 | +``` |
| 127 | + |
| 128 | +### Set cURL option using setOptions method |
| 129 | + |
| 130 | +The `setOptions` method accepts an array as a parameter. |
| 131 | + |
| 132 | +```php |
| 133 | +$options = [CURLOPT_RETURNTRANSFER => true, CURLOPT_PORT => 8080]; |
| 134 | + |
| 135 | +$this->curl->setOptions($options); |
| 136 | +``` |
| 137 | + |
| 138 | +### Set cURL cookies using addCookie method |
| 139 | + |
| 140 | +The `addCookie` method accepts an array as a parameter. The cookie name and the cookie value. |
| 141 | + |
| 142 | +```php |
| 143 | +$this->curl->addCookie("cookie-name", "cookie-value"); |
| 144 | +``` |
| 145 | + |
| 146 | +### Set cURL cookies using setCookies method |
| 147 | + |
| 148 | +The ``setCookies`` method accepts an array as a parameter. |
| 149 | + |
| 150 | +```php |
| 151 | +$cookies = ["cookie-name-1" => "cookie-value-1", "cookie-name-2" => "cookie-value-2"]; |
| 152 | +$this->curl->setCookies($cookies); |
| 153 | +``` |
| 154 | + |
| 155 | +### How to use cURL with Magento |
| 156 | + |
| 157 | +For example, the `Magento\Marketplace\Model\Partners` class gets partners info using cURL from the api of Magento connect. |
| 158 | + |
| 159 | +```php |
| 160 | +namespace Magento\Marketplace\Model; |
| 161 | + |
| 162 | +use Magento\Framework\HTTP\Client\Curl; |
| 163 | +use Magento\Marketplace\Helper\Cache; |
| 164 | +use Magento\Backend\Model\UrlInterface; |
| 165 | + |
| 166 | +/** |
| 167 | + * @api |
| 168 | + * @since 100.0.2 |
| 169 | + */ |
| 170 | +class Partners |
| 171 | +{ |
| 172 | + /** |
| 173 | + * @var Curl |
| 174 | + */ |
| 175 | + protected $curlClient; |
| 176 | + |
| 177 | + /** |
| 178 | + * @var string |
| 179 | + */ |
| 180 | + protected $urlPrefix = 'https://'; |
| 181 | + |
| 182 | + /** |
| 183 | + * @var string |
| 184 | + */ |
| 185 | + protected $apiUrl = 'magento.com/magento-connect/platinumpartners/list'; |
| 186 | + |
| 187 | + /** |
| 188 | + * @var \Magento\Marketplace\Helper\Cache |
| 189 | + */ |
| 190 | + protected $cache; |
| 191 | + |
| 192 | + /** |
| 193 | + * @var UrlInterface |
| 194 | + */ |
| 195 | + private $backendUrl; |
| 196 | + |
| 197 | + /** |
| 198 | + * @param Curl $curl |
| 199 | + * @param Cache $cache |
| 200 | + * @param UrlInterface $backendUrl |
| 201 | + */ |
| 202 | + public function __construct(Curl $curl, Cache $cache, UrlInterface $backendUrl) |
| 203 | + { |
| 204 | + $this->curlClient = $curl; |
| 205 | + $this->cache = $cache; |
| 206 | + $this->backendUrl = $backendUrl; |
| 207 | + } |
| 208 | + |
| 209 | + /** |
| 210 | + * @return string |
| 211 | + */ |
| 212 | + public function getApiUrl() |
| 213 | + { |
| 214 | + return $this->urlPrefix . $this->apiUrl; |
| 215 | + } |
| 216 | + |
| 217 | + /** |
| 218 | + * Gets partners json |
| 219 | + * |
| 220 | + * @return array |
| 221 | + */ |
| 222 | + public function getPartners() |
| 223 | + { |
| 224 | + $apiUrl = $this->getApiUrl(); |
| 225 | + try { |
| 226 | + $this->getCurlClient()->post($apiUrl, []); |
| 227 | + $this->getCurlClient()->setOptions( |
| 228 | + [ |
| 229 | + CURLOPT_REFERER => $this->getReferer() |
| 230 | + ] |
| 231 | + ); |
| 232 | + $response = json_decode($this->getCurlClient()->getBody(), true); |
| 233 | + if ($response['partners']) { |
| 234 | + $this->getCache()->savePartnersToCache($response['partners']); |
| 235 | + return $response['partners']; |
| 236 | + } else { |
| 237 | + return $this->getCache()->loadPartnersFromCache(); |
| 238 | + } |
| 239 | + } catch (\Exception $e) { |
| 240 | + return $this->getCache()->loadPartnersFromCache(); |
| 241 | + } |
| 242 | + } |
| 243 | + |
| 244 | + /** |
| 245 | + * @return Curl |
| 246 | + */ |
| 247 | + public function getCurlClient() |
| 248 | + { |
| 249 | + return $this->curlClient; |
| 250 | + } |
| 251 | + |
| 252 | + /** |
| 253 | + * @return cache |
| 254 | + */ |
| 255 | + public function getCache() |
| 256 | + { |
| 257 | + return $this->cache; |
| 258 | + } |
| 259 | + |
| 260 | + /** |
| 261 | + * @return string |
| 262 | + */ |
| 263 | + public function getReferer() |
| 264 | + { |
| 265 | + return \Magento\Framework\App\Request\Http::getUrlNoScript($this->backendUrl->getBaseUrl()) |
| 266 | + . 'admin/marketplace/index/index'; |
| 267 | + } |
| 268 | +} |
| 269 | +``` |
| 270 | + |
| 271 | +First off all the cURL client instance is created in `__construct`. |
| 272 | +Method `getPartners` uses the cURL client makes POST request using cURL, the `post` method takes the first parameter the URL to the api of Magento connect, second parameter is empty array, then the option `CURLOPT_REFERER` added by `setOptions` method of the cURL client. |
| 273 | +As result the script call `getBody` method of the cURL client. |
| 274 | + |
| 275 | +{:.ref-header} |
| 276 | +Related topics |
| 277 | + |
| 278 | +[Status codes and responses]({{ page.baseurl }}/get-started/gs-web-api-response.html) |
0 commit comments