Download the PHP package aura/http without Composer

Aura HTTP

The Aura HTTP package provides objects to build and send HTTP requests and responses, including multipart/form-data requests, with streaming of file resources when using the curl adapter.

This package is compliant with PSR-0, PSR-1, and PSR-2. If you notice compliance oversights, please send a patch via pull request.

Getting Started

Instantiation

The easiest way to get started is to use the scripts/instance.php script to instantiate an HTTP Manager object.

You can then create new Request and Response objects, and send them via the Manager.

HTTP Responses

Instantiation

Use the Manager to create a new HTTP response.

Setting And Getting Content

To set the content of the Response, use setContent().

Instead of a string, the content may be a file resource; when the response is sent, the file will be streamed out via fread().

To get the content, use getContent() or access the $content property.

Setting And Getting Headers

To set headers, access the $headers property, and use its set() method.

You can also set all the headers at once by passing an array of key-value pairs where the key is the header label and the value is one or more header values.

N.b.: Header labels are sanitized and normalized, so if you enter a label header_foo it will be converted to Header-Foo.

To get the headers, use getHeaders() or access the $headers property and use the get() method.

Setting and Getting Cookies

To set cookies, access the $cookies property . Pass the cookie name and an array of information about the cookie (including its value).

The information array keys mimic the setcookies() parameter names. You only need to provide the parts of the array that you need; the remainder will be filled in with null defaults for you.

You can also set all the cookies at once by passing an array of key-value pairs, where the key is the cookie name and the value is a cookie information array.

To get cookies, use getCookies() or access the $cookies property and use the get() method.

Setting and Getting the Status

To set the HTTP response status, use setStatusCode() and setStatusText(). The setStatusCode() method automatically sets the text for known codes.

N.b.: By default, a new Response starts with a status of '200 OK'.

To get the response status, use getStatusCode() and getStatusText().

Sending the Response

Once you have set the content, headers, cookies, and status, you can send the response using the HTTP Manager object.

This will send all the headers using header() and all the cookies using setcookie().

If the content is a string, it will be echo-ed; if the content is a file resource, it will be streamed out with fread().

N.b.: You can only send the Response once. If you try to send it again, or if you try to send another response of any sort with headers on it, you will get a HeadersSent exception.

HTTP Requests

Instantiation

Use the Manager to create a new HTTP request.

Setting and Getting Headers and Cookies

You can set and get headers and cookies just as with a Response object, described above.

Setting and Getting Content

You can set and get content just as with a Response object, described above.

N.b.: Content will be sent only if the request method is POST or PUT.

If the Request content is a string, it will be sent as-is.

If the Request content is a file resource, it will be read from disk and sent.

If the content is an array, it will be converted to x-www-form-urlencoded or multipart/form-data. The array may specify files to be uploaded by prefixing the array value with @.

WARNING: Be sure to sanitize user data to make sure only values intended as file uploads begin with @.

Setting URL and Method

To set the URL and method, do the following:

(By default, all requests use a Aura\Http\Message\Request::METHOD_GET method to begin with.)

Setting Authentication

To set authentication credentials, pick the authentication type, then set a username and password.

Available authentication types are Aura\Http\Message\Request::AUTH_BASIC and Aura\Http\Message\Request::AUTH_DIGEST.

Sending the Request

You can send the request via the Manager object; it returns a ResponseStack.

The $stack is an Aura\Http\Message\Response\Stack containing all the responses, including redirects. The stack order is last in first out. Each item in the stack is an Aura\Http\Message\Response object.

Further Examples

Making a GET request to the Github API to list Aura's repositories:

Making a custom POST request:

Saving the response content to a file:

HTTP Transport and Adapters

The HTTP Manager uses a Transport object to send requests. You can specify various options for the transport.

The transport uses an Adapter to handle the actual sending of requests. There are two adapters available:

• Aura\Http\Request\Adapter\Curl, which is used automatically when the curl extension is loaded. This adapter will stream file resources directly to and from disk, without loading the entire file into memory.

• Aura\Http\Request\Adapter\Stream, which is the fallback if curl is not loaded. This adapter is not suitable for sending or receiving large files. Each file will loaded into memory. This is a limitation in PHP HTTP streams.