Using cURL to run requests

'cURL' 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.

To use cURL to run your REST web API call, use the cURL command syntax to construct the command.

To create the endpoint in the call, append the REST URI that you constructed in Construct a request to this URL:

https://<HOST_OR_IP>/<BASE_INSTALL_DIR>/rest/

To pass the customer data object in the POST call payload, specify a JSON or XML request body on the call.

For a complete list of cURL command options, see curl.1 the man page.

The cURL examples in this guide use the following command-line options:

Option	Description
`-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.
`-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 web API requests, see HTTP headers
`-i` `-input`	Includes the HTTP header in the output.
`-s` `-silent`	Specifies silent or quiet mode, which makes cURL mute. Progress and error messages are suppressed.
`-T` `-upload-file`	Transfers the specified local file to the remote URL.
`-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.

Using cUrl

Adobe Commerce and Magento Open Source provide a 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. First, create an instance of Magento\Framework\HTTP\Client\Curl.

/**
* Constructor.
*
* @param Magento\Framework\HTTP\Client\Curl $curl
*/
public function __construct(
   Magento\Framework\HTTP\Client\Curl $curl
) {
   $this->curl = $curl;
}
Copied to your clipboard
/**
* Constructor.
*
* @param Magento\Framework\HTTP\Client\Curl $curl
*/
public function __construct(
   Magento\Framework\HTTP\Client\Curl $curl
) {
   $this->curl = $curl;
}

Make GET request using cURL

// get method
$this->curl->get($url);

// output of curl request
$result = $this->curl->getBody();
Copied to your clipboard
// get method
$this->curl->get($url);

// output of curl request
$result = $this->curl->getBody();

where $url is the endpoint URL.

Make POST request using cURL

// post method
$this->curl->post($url, $params);

// output of curl requestt
$result = $this->curl->getBody();
Copied to your clipboard
// post method
$this->curl->post($url, $params);

// output of curl requestt
$result = $this->curl->getBody();

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. A $params example:

$params = [
  'user[email]' => $user->getEmail(),
  'user[cellphone]' => $providerInfo['phone_number'],
  'user[country_code]' => $providerInfo['country_code'],
]
Copied to your clipboard
$params = [
  'user[email]' => $user->getEmail(),
  'user[cellphone]' => $providerInfo['phone_number'],
  'user[country_code]' => $providerInfo['country_code'],
]

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.

Set cURL header using addHeader method

The addHeader method accepts two parameters. The cURL header name and a cURL header value.

$this->curl->addHeader("Content-Type", "application/json");
$this->curl->addHeader("Content-Length", 200);
Copied to your clipboard
$this->curl->addHeader("Content-Type", "application/json");
$this->curl->addHeader("Content-Length", 200);

Set cURL header using setHeaders method

The setHeaders method accepts an array as a parameter.

$headers = ["Content-Type" => "application/json", "Content-Length" => "200"];
$this->curl->setHeaders($headers);
Copied to your clipboard
$headers = ["Content-Type" => "application/json", "Content-Length" => "200"];
$this->curl->setHeaders($headers);

Set basic authorization in cURL

Set the basic authorization using the setCredentials method.

$userName = "User_Name";
$password = "User_Password";

$this->curl->setCredentials($userName, $password);
Copied to your clipboard
$userName = "User_Name";
$password = "User_Password";

$this->curl->setCredentials($userName, $password);

It is equivalent to setting CURLOPT_HTTPHEADER value:

"Authorization : " . "Basic " . base64_encode($userName . ":" . $password)
Copied to your clipboard
"Authorization : " . "Basic " . base64_encode($userName . ":" . $password)

Set cURL option using setOption method

The setOption method accepts two parameters. The cURL option name and the cURL option value.

$this->curl->setOption(CURLOPT_RETURNTRANSFER, true);
$this->curl->setOption(CURLOPT_PORT, 8080);
Copied to your clipboard
$this->curl->setOption(CURLOPT_RETURNTRANSFER, true);
$this->curl->setOption(CURLOPT_PORT, 8080);

Set cURL option using setOptions method

The setOptions method accepts an array as a parameter.

$options = [CURLOPT_RETURNTRANSFER => true, CURLOPT_PORT => 8080];

$this->curl->setOptions($options);
Copied to your clipboard
$options = [CURLOPT_RETURNTRANSFER => true, CURLOPT_PORT => 8080];

$this->curl->setOptions($options);

Set cURL cookies using addCookie method

The addCookie method accepts an array as a parameter. The cookie name and the cookie value.

$this->curl->addCookie("cookie-name", "cookie-value");
Copied to your clipboard
$this->curl->addCookie("cookie-name", "cookie-value");

Set cURL cookies using setCookies method

The setCookies method accepts an array as a parameter.

$cookies = ["cookie-name-1" => "cookie-value-1", "cookie-name-2" => "cookie-value-2"];
$this->curl->setCookies($cookies);
Copied to your clipboard
$cookies = ["cookie-name-1" => "cookie-value-1", "cookie-name-2" => "cookie-value-2"];
$this->curl->setCookies($cookies);

Example usage

For example, the Magento\Marketplace\Model\Partners class gets partners info using cURL from the API of Magento connect.

namespace Magento\Marketplace\Model;

use Magento\Framework\HTTP\Client\Curl;
use Magento\Marketplace\Helper\Cache;
use Magento\Backend\Model\UrlInterface;

/**
 * @api
 * @since 100.0.2
 */
class Partners
{
    /**
     * @var Curl
     */
    protected $curlClient;

    /**
     * @var string
     */
    protected $urlPrefix = 'https://';

    /**
     * @var string
     */
    protected $apiUrl = 'magento.com/magento-connect/platinumpartners/list';

    /**
     * @var \Magento\Marketplace\Helper\Cache
     */
    protected $cache;

    /**
     * @var UrlInterface
     */
    private $backendUrl;

    /**
     * @param Curl $curl
     * @param Cache $cache
     * @param UrlInterface $backendUrl
     */
    public function __construct(Curl $curl, Cache $cache, UrlInterface $backendUrl)
    {
        $this->curlClient = $curl;
        $this->cache = $cache;
        $this->backendUrl = $backendUrl;
    }

    /**
     * @return string
     */
    public function getApiUrl()
    {
        return $this->urlPrefix . $this->apiUrl;
    }

    /**
     * Gets partners json
     *
     * @return array
     */
    public function getPartners()
    {
        $apiUrl = $this->getApiUrl();
        try {
            $this->getCurlClient()->post($apiUrl, []);
            $this->getCurlClient()->setOptions(
                [
                    CURLOPT_REFERER => $this->getReferer()
                ]
            );
            $response = json_decode($this->getCurlClient()->getBody(), true);
            if ($response['partners']) {
                $this->getCache()->savePartnersToCache($response['partners']);
                return $response['partners'];
            } else {
                return $this->getCache()->loadPartnersFromCache();
            }
        } catch (\Exception $e) {
            return $this->getCache()->loadPartnersFromCache();
        }
    }

    /**
     * @return Curl
     */
    public function getCurlClient()
    {
        return $this->curlClient;
    }

    /**
     * @return cache
     */
    public function getCache()
    {
        return $this->cache;
    }

    /**
     * @return string
     */
    public function getReferer()
    {
        return \Magento\Framework\App\Request\Http::getUrlNoScript($this->backendUrl->getBaseUrl())
        . 'admin/marketplace/index/index';
    }
}
Copied to your clipboard
namespace Magento\Marketplace\Model;

use Magento\Framework\HTTP\Client\Curl;
use Magento\Marketplace\Helper\Cache;
use Magento\Backend\Model\UrlInterface;

/**
 * @api
 * @since 100.0.2
 */
class Partners
{
    /**
     * @var Curl
     */
    protected $curlClient;

    /**
     * @var string
     */
    protected $urlPrefix = 'https://';

    /**
     * @var string
     */
    protected $apiUrl = 'magento.com/magento-connect/platinumpartners/list';

    /**
     * @var \Magento\Marketplace\Helper\Cache
     */
    protected $cache;

    /**
     * @var UrlInterface
     */
    private $backendUrl;

    /**
     * @param Curl $curl
     * @param Cache $cache
     * @param UrlInterface $backendUrl
     */
    public function __construct(Curl $curl, Cache $cache, UrlInterface $backendUrl)
    {
        $this->curlClient = $curl;
        $this->cache = $cache;
        $this->backendUrl = $backendUrl;
    }

    /**
     * @return string
     */
    public function getApiUrl()
    {
        return $this->urlPrefix . $this->apiUrl;
    }

    /**
     * Gets partners json
     *
     * @return array
     */
    public function getPartners()
    {
        $apiUrl = $this->getApiUrl();
        try {
            $this->getCurlClient()->post($apiUrl, []);
            $this->getCurlClient()->setOptions(
                [
                    CURLOPT_REFERER => $this->getReferer()
                ]
            );
            $response = json_decode($this->getCurlClient()->getBody(), true);
            if ($response['partners']) {
                $this->getCache()->savePartnersToCache($response['partners']);
                return $response['partners'];
            } else {
                return $this->getCache()->loadPartnersFromCache();
            }
        } catch (\Exception $e) {
            return $this->getCache()->loadPartnersFromCache();
        }
    }

    /**
     * @return Curl
     */
    public function getCurlClient()
    {
        return $this->curlClient;
    }

    /**
     * @return cache
     */
    public function getCache()
    {
        return $this->cache;
    }

    /**
     * @return string
     */
    public function getReferer()
    {
        return \Magento\Framework\App\Request\Http::getUrlNoScript($this->backendUrl->getBaseUrl())
        . 'admin/marketplace/index/index';
    }
}

First off all the cURL client instance is created in __construct. 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. As result the script call getBody method of the cURL client.

Status codes and responses

Construct a request

Status codes and responses