Creating a cURL Request

When making external HTTP requests, there are two primary options: leveraging PHP’s built-in curl_* functions or utilizing the curlRequest method provided by the system.

The curlRequest method serves as a secure and standardized wrapper around PHP’s native cURL functionality. It enforces the use of the application/x-www-form-urlencoded content type and automatically URL-encodes parameters. In addition, it simplifies configuration by supporting various HTTP methods, custom headers, cookies, and request parameters, while also enforcing locked cURL options to mitigate potential security risks.

For scenarios requiring lower-level cURL control, direct usage of PHP’s cURL functions is supported, but must be executed through $this->curlExec() instead of curl_exec(), which is restricted in Custom Logic. The curlExec method ensures safe execution by applying locked options and returning consistent response structures.

In general, curlRequest is recommended for most use cases requiring reliable and secure HTTP communication, while $this->curlExec() is available for more advanced or custom cURL handling.

curlRequest

PHP

array curlRequest(
  array $url,
  array $requestOptions,
  bool $closeCurl = true,
  bool $debug = false
)

Parameters

$url The target URL for the HTTP request
$requestOptions Configuration options including HTTP method, headers, cookies, params
$closeCurl Whether to close the cURL handle after execution (defaults to true)
$debug Whether to include debug information in the response (defaults to false)

Return Values

Returns an array of standardized data from the request.

Purpose and Usage

The curlRequest method provides a wrapper around PHP's cURL functionality with several important features:

Standardized HTTP Request Handling:
- Supports different HTTP methods (GET, POST, and custom methods)
- Properly formats headers, cookies, and request parameters
- Handles request execution and response processing
Security Enforcement:
- Uses the curlExec method which enforces lockedCurlOptions to prevent potentially dangerous behavior
- The locked options restrict cURL to only HTTP/HTTPS protocols
- Ensures proper response handling to prevent data leakage
Structured Response:
- Returns a consistent array format with success status
- Includes error messages when failures occur
- Provides HTTP response data when successful
Debugging Support:
- When the debug flag is set, includes detailed information about cURL options and execution

curlExec

PHP

string|false curlExec(CurlHandle $handle)

curl_exec cannot be used within Custom Logic, use $this->curlExec() instead.

Examples

This example shows all the options available in the $requestOptions parameter.

CODE

$requestOptions = [
    // GET, POST, custom (anything not GET or POST is custom)
    'httpMethod' => 'POST',
    
    // Parameters to pass in the query string (GET) or CURLOPT_POSTFIELDS (POST/custom)
    // For GET: Value assigned using $url .= '?' . http_build_query($requestOptions['params'] ?? []);
    // For POST/custom: Value assigned using $curlOptions[CURLOPT_POSTFIELDS] = http_build_query($requestOptions['params'] ?? []);
    'params' => [
        // Modify as appropriate for your API call
        'FOO' => 'BAR',
    	'BAZ' => 'BAT',
    ],
    
    // Cookies to pass in CURLOPT_COOKIE
    // Assigned as $curlOptions[CURLOPT_COOKIE] = http_build_query($requestOptions['cookies'], '', '; ');
    'cookies' => [
    	'c1' => 'cv1',
    	'c2' => 'cv2'
	],
	
    // Additional headers to pass in CURLOPT_HTTPHEADER
    'headers' => [
    	// 'Content-Type' headers will be ignored by curlRequest in deference to 'Content-Type' => 'application/x-www-form-urlencoded'
		'Content-Type' => 'Content-Type-Should-Be-Ignored',
    	'X-some-header-1' => 'X-some-header-1-value',
    	'X-some-header-2' => 'X-some-header-2-value',
	],
	
    // Additional CURLOPT_* options
    // curlRequest will use curlExec, which will force the following locked curl options:
    // CURLOPT_PROTOCOLS =>  CURLPROTO_HTTP | CURLPROTO_HTTPS
    // CURLOPT_RETURNTRANSFER => true
    'curl' => [
    	CURLOPT_TIMEOUT => 10,
    	CURLOPT_VERBOSE => true
	],
];

$results = $this->curlRequest('https://api.url.com', $requestOptions, true, true);

In the above example $results will look something like this:

CODE

{
  "success": true,
  "response": ...,  // response body from the webservice
  "curlHandle": {}, // only present when the $closeCurl parameter is false
  "debug": {        // only present when the $debug parameter is true
    "curlOptions": {
      "13 [CURLOPT_TIMEOUT]": 10,
      "41 [CURLOPT_VERBOSE]": true,
      "10022 [CURLOPT_COOKIE]": "c1=cv1; c2=cv2",
      "10023 [CURLOPT_HTTPHEADER]": [
        "Content-Type: application\/x-www-form-urlencoded",
        "X-some-header-1: X-some-header-1-value",
        "X-some-header-2: X-some-header-2-value"
      ],
      "47 [CURLOPT_POST]": true,
      "10015 [CURLOPT_POSTFIELDS]": "FOO=BAR&BAZ=BAT",
      "10002 [CURLOPT_URL]": "https://api.url.com"
    },
    "lockedCurlOptions": {
      "181 [CURLOPT_PROTOCOLS]": 3,
      "19913 [CURLOPT_RETURNTRANSFER]": true
    },
    "curlInfo": {
      "url": "https://api.url.com",
      "content_type": "application\/json", // whatever content-type returned
      "http_code": 200,
      "header_size": 469,
      "request_size": 292,
      "filetime": -1,
      "ssl_verify_result": 0,
      "redirect_count": 0,
      "total_time": 0.022522,
      "namelookup_time": 0.001116,
      "connect_time": 0.00122,
      "pretransfer_time": 0.001272,
      "size_upload": 15,
      "size_download": 406,
      "speed_download": 18026,
      "speed_upload": 666,
      "download_content_length": -1,
      "upload_content_length": 15,
      "starttransfer_time": 0.022476,
      "redirect_time": 0,
      "redirect_url": "",
      "primary_ip": "0.0.0.0",
      "certinfo": [],
      "primary_port": 80,
      "local_ip": "0.0.0.0",
      "local_port": 33844,
      "http_version": 2,
      "protocol": 1,
      "ssl_verifyresult": 0,
      "scheme": "HTTP",
      "appconnect_time_us": 0,
      "connect_time_us": 1220,
      "namelookup_time_us": 1116,
      "pretransfer_time_us": 1272,
      "redirect_time_us": 0,
      "starttransfer_time_us": 22476,
      "total_time_us": 22522,
      "effective_method": "POST"
    }
  }
}

Example

This example uses the built-in PHP functions and then calls curlExec to Validate a GLA on an external webservice.

PHP

    $valGLNumber = $glNumber;
    $address = "https://gla-validator.someurl.com/?gla=";

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $address . $valGLNumber);
    curl_setopt($ch, CURLOPT_HEADER, false);

    // this will not work!!!
    // $response = curl_exec($ch)
    if (false === ($response = $this->curlExec($ch))) {
        // do something with the response
    }
    curl_close($ch);