Download the PHP package nidux/niduxrest-php without Composer

NiduxRest for PHP 8.1+ (based on Unirest from Kong)

This is a fork from Unirest that I try to keep it updated as possible. The main idea is to continue with the idea of something quick and simple as originally made by Mashape.

For PHP versions like 8.0 and below, keep using v1.0.5.

Notable changes

• PHP 8.1 support
• Optimization
• Breaking changes See below

Breaking changes

• I did remove access to properties directly, trying to follow some Object-oriented best practices, so use the proper GET methods instead.
• I did rename setters to a proper naming convention
• There was an unnecesary return on some setters, these were completely removed on v2
• Changeing methods from interface to enum

Requirements

• cURL
• PHP 8.1+

Documentation

I will keep most of the original documentation for simplicity, I will update the example as I begin making improvements

Installation

Using Composer

To install unirest-php with Composer, just add the following to your composer.json file:

or by running the following command:

Usage

Creating a Request

So you're probably wondering how using Niduxrest makes creating requests in PHP easier, let's look at a working example:

PAY ATTENTION HERE: You cannot access the properties directly anymore

JSON Requests (application/json)

A JSON Request can be constructed using the Niduxrest\Request\Body::prepareJson helper:

Notes:

• Content-Type headers will be automatically set to application/json
• the data variable will be processed through json_encode with default values for arguments.
• an error will be thrown if the JSON Extension is not available.

Form Requests (application/x-www-form-urlencoded)

A typical Form Request can be constructed using the Niduxrest\Request\Body::prepareForm helper:

Notes:

• Content-Type headers will be automatically set to application/x-www-form-urlencoded
• the final data array will be processed through http_build_query with default values for arguments.

Multipart Requests (multipart/form-data)

A Multipart Request can be constructed using the Niduxrest\Request\Body::prepareMultiPart helper:

Notes:

• Content-Type headers will be automatically set to multipart/form-data.
• an auto-generated --boundary will be set.

Multipart File Upload

simply add an array of files as the second argument to to the prepareMultiPart helper:

If you wish to further customize the properties of files uploaded you can do so with the Niduxrest\Request\Body::prepareFile helper:

Note: we did not use the Niduxrest\Request\Body::multipart helper in this example, it is not needed when manually adding files.

Custom Body

Sending a custom body such rather than using the Niduxrest\Request\Body helpers is also possible, for example, using a serialize body string with a custom Content-Type:

Authentication examples

Bearer token authentication

For simplicity, there is a new method to set a bearer token to the Request

Basic authentication

Using the mashape key for their services (you need to get the key first)

The third parameter, which is a bitmask, will Niduxrest which HTTP authentication method(s) you want it to use for your proxy authentication.

If more than one bit is set, Niduxrest (at PHP's libcurl level) will first query the site to see what authentication methods it supports and then pick the best one you allow it to use. For some methods, this will induce an extra network round-trip.

Supported Methods

Previous versions of Niduxrest support Basic Authentication by providing the username and password arguments:

This has been deprecated, and will be completely removed in v.2.0 please use the Niduxrest\Request::auth() method instead

Cookies

Set a cookie string to specify the contents of a cookie header. Multiple cookies are separated with a semicolon followed by a space (e.g., "fruit=apple; colour=red")

Set a cookie file path for enabling cookie reading and storing cookies across multiple sequence of requests.

$cookieFile must be a correct path with write permission.

Request Object

• url - Endpoint, address, or uri to be acted upon and requested information from.
• headers - Request Headers as associative array or object
• body - Request Body as associative array or object

You can send a request with any standard or custom HTTP Method present on the Method enum:

Response Object

Upon recieving a response, Niduxrest returns a Response Object, this object will have the following getters available.

• getCode() - HTTP Response Status Code (Example 200)
• getHeaders() - HTTP Response Headers
• getBody() - Parsed response body where applicable, for example JSON responses are parsed to Objects / Associative Arrays.
• getRawBody() - Un-parsed response body

Advanced Configuration

You can set some advanced configuration to tune Niduxrest-PHP:

Custom JSON Decode Flags

Niduxrest uses PHP's JSON Extension for automatically decoding JSON responses. sometime you may want to return associative arrays, limit the depth of recursion, or use any of the customization flags.

To do so, simply set the desired options using the setJsonOpts request method:

Timeout

You can set a custom timeout value (in seconds):

Proxy

Set the proxy to use for the upcoming request.

you can also set the proxy type to be one of CURLPROXY_HTTP, CURLPROXY_HTTP_1_0, CURLPROXY_SOCKS4 , CURLPROXY_SOCKS5, CURLPROXY_SOCKS4A, and CURLPROXY_SOCKS5_HOSTNAME.

check the cURL docs for more info.

Proxy Authenticaton

Passing a username, password (optional), defaults to Basic Authentication:

The third parameter, which is a bitmask, will Niduxrest which HTTP authentication method(s) you want it to use for your proxy authentication.

If more than one bit is set, Niduxrest (at PHP's libcurl level) will first query the site to see what authentication methods it supports and then pick the best one you allow it to use. For some methods, this will induce an extra network round-trip.

See Authentication for more details on methods supported.

Default Request Headers

You can set default headers that will be sent on every request:

You can set default headers in bulk by passing an array:

You can clear the default headers anytime with:

Default cURL Options

You can set default cURL options that will be sent on every request:

You can set options bulk by passing an array:

You can clear the default options anytime with:

SSL validation

You can explicitly enable or disable SSL certificate validation when consuming an SSL protected endpoint:

By default is true.

Utility Methods