Skip to content
Fetching contributors…
Cannot retrieve contributors at this time
163 lines (118 sloc) 6.04 KB
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "../../Developer_Manual.ent">
%BOOK_ENTITIES;
]>
<section id="chap-Joomla_Platform_Manual-JHttp">
<title>JHttp</title>
<para>The JHttp class provides methods for making RESTful requests.</para>
<section>
<title>Construction</title>
<para>Construction of JHttp object is generally done using the JHttpFactory class. However, JHttp is not abstract and can be
instantiated directly passing an optional JRegistry object of options and an optional JHttpTransport object. If the transport
is omitted, the default transport will be used. The default is determined by looking up the transports folder and selecting
the first transport that is supported (this will usually be the "curl" transport).</para>
<example>
<title>Creating a JHttp object</title>
<programlisting>// Create an instance of a default JHttp object.
$http = new JHttp;
$options = new JRegistry;
$transport = new JHttpTransportStream($options);
// Create a 'stream' transport.
$http = new JHttp($options, $transport);</programlisting>
</example>
</section>
<section>
<title>Making a HEAD request</title>
<para>An HTTP HEAD request can be made using the head method passing a URL and an optional key-value array of header
variables. The method will return a JHttpResponse object.</para>
<example>
<title>Making a HEAD request</title>
<programlisting>// Create an instance of a default JHttp object.
$http = JHttpFactory::getHttp();
// Invoke the HEAD request.
$response = $http-&gt;head('http://example.com');
// The response code is included in the "code" property.
// See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
var_dump($response-&gt;code);
// The response headers are included as an associative array in the "headers" property.
var_dump($response-&gt;headers);
// The body of the response (not applicable for the HEAD method) is included in the "body" property.
var_dump($response-&gt;body);</programlisting>
</example>
</section>
<section>
<title>Making a GET request</title>
<para>An HTTP GET request can be made using the get method passing a URL, an optional key-value array of header variables and
an optional timeout value. In RESTful terms, a GET request is sent to read data from the server.</para>
<example>
<title>Making a GET request</title>
<programlisting>// Invoke the GET request.
$response = $http-&gt;get('http://api.example.com/cars');</programlisting>
</example>
</section>
<section>
<title>Making a POST request</title>
<para>An HTTP POST request can be made using the post method passing a URL, a data variable, an optional key-value array of
header variables and an optional timeout value. The data can be either an associative array of POST variables, or a string to
be sent with the request. In RESTful terms, a POST request is sent to create new data on the server.</para>
<example>
<title>Making a POST request</title>
<programlisting>// Prepare the update data.
$data = array('make' =&gt; 'Holden', model =&gt; 'EJ-Special');
// Invoke the GET request.
$response = $http-&gt;post('http://api.example.com/cars/1', $data);</programlisting>
</example>
</section>
<section>
<title>Making a PUT request</title>
<para>An HTTP POST request can be made using the post method passing a URL, a data variable, an optional key-value array of
header variables and an optional timeout value. The data can be either an associative array of POST variables, or a string to
be sent with the request. In RESTful terms, a PUT request is typically sent to update existing data on the server.</para>
<example>
<title>Making a PUT request</title>
<programlisting>// Prepare the update data.
$data = array('description' =&gt; 'My first car.', 'color' =&gt; 'gray');
// Invoke the GET request.
$response = $http-&gt;put('http://api.example.com/cars/1', $data);</programlisting>
</example>
</section>
<section>
<title>Making a DELETE request</title>
<para>An HTTP DELETE request can be made using the delete method passing a URL, an optional key-value array of header
variables and an optional timeout value. In RESTful terms, a DELETE request is typically sent to delete existing data on the
server.</para>
<example>
<title>Making a DELETE request</title>
<programlisting>// Invoke the DELETE request.
$response = $http-&gt;delete('http://api.example.com/cars/1');</programlisting>
</example>
</section>
<section>
<title>Making a TRACE request</title>
<para>An HTTP TRACE request can be made using the trace method passing a URL and an optional key-value array of header
variables. In RESTful terms, a TRACE request is to echo data back to the client for debugging or testing purposes.</para>
</section>
<section>
<title>Working with options</title>
<para>Customs headers can be pased into each REST request, but they can also be set globally in the constructor options where
the registry path starts with "headers.". In the case where a request method passes additional headers, those will override
the headers set in the options.</para>
<example>
<title>Setting custom request headers</title>
<programlisting>// Create the options.
$options = new JRegistry;
// Configure a custom Accept header for all requests.
$options-&gt;set('headers.Accept', 'application/vnd.github.html+json');
// Make the request, knowing the custom Accept header will be used.
$pull = $http-&gt;get('https://api.github.com/repos/joomla/joomla-platform/pulls/1');
// Set up custom headers for a single request.
$headers = array(
'Accept' =&gt; 'application/foo',
);
// In this case, the Accept header in $headers will override the options header.
$pull = $http-&gt;get('https://api.github.com/repos/joomla/joomla-platform/pulls/1', $headers);</programlisting>
</example>
</section>
</section>
Jump to Line
Something went wrong with that request. Please try again.