Introduction to cURL with php

#php #curl #http

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:

Reason for cURL
Implementation of cURL
Sample codes - using POST, GET method and file uploading
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:

cURL is a good way to communicate with third-party API either to download resources or to fetch information from an external website.
cURL is a good library for developing REST API.
cURL is secure and easy to use.
cURL is use instead of file_get_contents because it support POST method.

Getting started with cURL

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.

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.

use curl_exec($curl) - to execute a request or perform a cURL session.
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.

$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
$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