Introduction to cURL with php
Tags: php, curl, http
Published: 2021-10-09 21:44:00

Client URL (cURL) is a PHP library for transferring data using various network protocols. cURL allows data to be transfer over HTTP using either the GET/POST method.

In this article we'll discus briefly on cURL under the following:
1. Reason for cURL
2. Implementation of cURL
3. Sample codes - using POST, GET method and file uploading
4. some cURL functions


> cURL is supported with PHP version 4 and above.
> file can be upload using cURL.


Some of the reasons you might want to use cURL compared to other options like `file_get_contents()` includes:

1. cURL is a good way to communicate with third-party API  either to download resources or to fetch information from an external website.
2. cURL is a good library for developing REST API.

3. cURL is secure and easy to use.

4. cURL is use instead of `file_get_contents` because it support POST method.


## Getting started with cURL

1. First you will need to initialize a new curl session using the `curl_init()` function.

> You should note this function must come first before all other curl related functions.


2. Afterwards, we use `curl_setopt()` to define other various options like setting the request type, adding request data, etc. for our curl request.

>  most of the cURL request settings are done using `curl_setopt()` function.
This function takes three parameters - `curl_setopt($curl, CURLOPT_*,Value)` where:
   * $curl - the initializeed curl session variable
   * CURLOPT_* - the option to set e.g `CURLOPT_POST`
   * Value - this is the value to set for a specified CURLOPT_* option.

And, on sending our request, the following options are required:



a. `curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE)` - setting the `CURLOPT_RETURNTRANSFER` option to `TRUE` will prevent the response to be displayed directly on the screen.

b. `curl_setopt($curl, CURLOPT_URL, $url)` - use CURLOPT_URL option to set the request URL to **thewebsite.com**

c. `curl_setopt($curl, CURLOPT_POST, TRUE)` - the `CURLOPT_POST` option to `TRUE` to set the request method to HTTP POST

d. curl_setopt($curl, CURLOPT_POSTFIELDS, $fields_string_array) - use `CURLOPT_POSTFIELDS` option to set the `POST` data to submit along with the request.

e. `curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json')` - this inform the API server that we are sending JSON data.

3. use `curl_exec($curl)` - to execute a request or perform a cURL session.
4. use `curl_close($curl)` - to close the curl session.

### curl in action
The code below is a sample of cURL POST method request to be submit, along with required datas.

```php
$curl = curl_init();
$post_method = array( "userName" => "example1",
"email" => "email@example.com",
"password" => "password");

$url = 'https://www.thewebsite.com';
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $post_method);
curl_setopt($curl, CURLOPT_HEADER, false);

$Response = curl_exec($curl);

curl_close($curl);

```
### Upload file with cURL
To upload a file with  cURL we need to use `curl_file_create` to create the `CURLFile` object, we'll  set `CURLOPT_HTTPHEADER` to `multipart/form-data`


````php
<?php
$url = '{POST_REST_ENDPOINT}';

$curl = curl_init();

if (function_exists('curl_file_create')) {
  $fileAttachment = curl_file_create('/file/path/');
} else {
  $fileAttachment = '@' . realpath('/file/path/');
}

$fields = array(
    'username' => 'Value',
    'password' => 'Value',
    'uploaded_file' => $fileAttachment
);

curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_POST, TRUE);
curl_setopt($curl, CURLOPT_POSTFIELDS, $fields);
curl_setopt($curl, CURLOPT_RETURNTRANSFER,1);
curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:multipart/form-data')
$response = curl_exec($curl);

curl_close($curl);
?>
````

### List of some cURL functions.

`curl_escape` — it encode a given URL string
`curl_unescape` — it decodes a given URL encoded string
`curl_errno` — it return the last error number, when error is encounter
`curl_error` — it return a string description containing the last error for the current session
`curl_getinfo` — Get information about a specific transfer
`curl_setopt_array` — for Setting multiple options for a cURL transfer(in array format).
`curl_pause` — it Pause and unpause a connection
`curl_reset` — it Reset all options of a cURL session handle
`curl_version` — Gets cURL version information