Http

Working with HTTP URIs

While the basic implementation for Uris already provides useful help when working with URIs, sometimes one needs slightly better support for HTTP URIs. Stubbles Core provides stubbles\peer\http\HttpUri for such cases.

New instances can be created via HttpUri::fromString('http://example.net/');. The following rules apply:

• If the supplied uri string is empty no instance will be returned, but null instead.
• If the supplied uri string is not a valid HTTP URI a stubbles\peer\MalformedUriException will be thrown.
• For all other cases, an instance of stubbles\peer\http\HttpUri is returned.

In order for a uri string to be a valid URI it must adhere to the specification laid out in RFC 7230. Any uri strings with other schemes than http or https are rejected and lead to a thrown stubbles\peer\MalformedUriException.

Additionally, instances can be created using HttpUri::fromParts($scheme, $host, $port = null, $path = '/', $queryString = null). (Available since release 4.0.0.)

Rules for specific methods

• hasDefaultPort() returns true if the scheme is http and the port is 80. In case no port was originally supplied, port 80 is assumed. The method also returns true if the scheme is https and the port is 443. In case no port was originally supplied, port 443 is assumed. In any other case the method returns false.
• port() will return the port if it was originally supplied. If it was not supplied and scheme is http return value will be 80, and if scheme is https return value will be 443.

Changing portions of the HTTP URI

Instances of HttpUri can only be changed regarding their URI parameters. It is not possible to change the host, user, password, port, or fragment of the URI. Additionally it is possible to change the scheme, but this will return a new instance:

• toHttp(): If the scheme is http the same instance will be returned. If the scheme is https a new instance with the same URI but scheme http will be returned.
• toHttps(): If the scheme is https the same instance will be returned. If the scheme is http a new instance with the same URI but scheme https will be returned.

The current scheme can be checked with isHttp() and isHttps().

Establish connections to HTTP URIs

Additionally, the class provides possibilities to establish connections to the name HTTP URI:

• openSocket() will create a stubbles\peer\Socket instance to which one can connect. See Sockets for more details.
• connect() provides higher level access with a full HTTP connection. The method can optionally take an instance of stubbles\peer\HeaderList from which headers will be applied to the request.

Establishing a HTTP connection

A HTTP request to the target URI can be done in the following way:

$response = $httpUri->connect()->asUserAgent('Not Mozilla')
                               ->timeout(5)
                               ->usingHeader('X-Money', 'Euro')
                               ->get();

Please note that the call to connect() does not open the connection, but establishes it locally only. Rather, it can be used to add some more headers to the request: user agent, referer, cookies or any other header. Only the last method really opens the connection. Currently, GET, HEAD, POST, PUT and DELETE requests are supported:

$response = $httpUri->connect()->get();
$response = $httpUri->connect()->head();
$response = $httpUri->connect()->post($postBody);
$response = $httpUri->connect()->put($putBody);
$response = $httpUri->connect()->delete();

For POST and PUT there is one required parameter which should contain the post/put body. For POST alternatively an associative array can be supplied which will be transformed into form post values, which will lead to an automatically added Content-type: application/x-www-form-urlencoded header to the request.

The response can then be read. It provides access to all single details of the HTTP response.