stubbles/peer
Help with socket operations., (*1)
Build status
, (*2)
, (*3)
Installation
stubbles/peer is distributed as Composer
package. To install it as a dependency of your package use the following
command:, (*4)
composer require "stubbles/peer": "^10.0"
Requirements
stubbles/peer requires at least PHP 8.2., (*5)
Working with URIs
Sometimes it's useful to have a URI wrapped into a class which provides methods
to work with this URI. Stubbles Core provides stubbles\peer\Uri for such cases., (*6)
New instances can be created via Uri::fromString('ftp://user@example.net/');.
The following rules apply:, (*7)
- If the supplied uri string is empty no instance will be returned, but
null
instead.
- If the supplied uri string is not a valid URI a
stubbles\peer\MalformedUri
will be thrown.
- For all other cases, an instance of
stubbles\peer\Uri is returned.
- Since release 8.0.0 using passwords in URIs is discouraged, and support for
passwords in URIs will be removed with 9.0.0. Generally, protocols provide
other and better means to transport the password, as using it in URIs is
inherently insecure.
In order for a uri string to be a valid URI it must adhere to the specification
laid out in RFC 3986., (*8)
Please note that hostnames will be normalized, which means if the given hostname
is e.g. eXAMple.net, it will be normalized to example.net and always
returned in normalized form., (*9)
For the methods, the following rules apply:, (*10)
-
hasDnsRecord() returns false if the URI does not contain a host.
-
hasDnsRecord()always returns true for localhost, 127.0.0.1 and [::1].
-
hasDefaultPort() returns false when a port is specified, even if it might
be the default port for the scheme. This method is meant for child classes
which provide additional methods for certain protocols.
URI instances can only be changed regarding their URI parameters. It is not
possible to change the scheme, host, user, password, port, or fragment of the
URI., (*11)
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/peer provides stubbles\peer\http\HttpUri for such cases., (*12)
New instances can be created via HttpUri::fromString('http://example.net/');.
The following rules apply:, (*13)
- 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\MalformedUri
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\MalformedUri., (*14)
Additionally, instances can be created using HttpUri::fromParts($scheme, $host,
$port = null, $path = '/', $queryString = null). (Available since release 4.0.0.), (*15)
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:, (*16)
-
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()., (*17)
Establish connections to HTTP URIs
Additionally, the class provides possibilities to establish connections to the
name HTTP URI:, (*18)
-
openSocket() will create a stubbles\peer\Socket instance to which one can
connect. See section on 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:, (*19)
$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:, (*20)
$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., (*21)
The response can then be read. It provides access to all single details of the
HTTP response., (*22)
Socket operations
Socket operations can be done using stubbles\peer\Socket. A socket can be
created by supplying the host to the constructor, and optionally a port. If no
port is specified it will fall back to port 80., (*23)
On construction only the socket instance is created. To actually open the
connection the connect() method must be called. Optionally a time-out for
establishing the connection can be supplied, if none given its 2 seconds. When
succesfully established, it returns a stubbles\peer\Stream instance which
provides methods to read from and write to the socket., (*24)
Other utility classes
This class provides possibilities to work with headers, mainly parsing a string
which contains headers and maintaining a list of headers., (*25)
This class can parse the accept header
from HTTP and provides access to check if a certain type is accepted, what it's
priority is, and to find the best match if the accept header is compared against
a selection of types. It can cope with Accept, Accept-Charset and
Accept-Encoding., (*26)
stubbles\peer\ParsedUri
Takes a uri string as construction argument and provides access to each part of
the uri. In constrast to stubbles\peer\Uri and stubbles\peer\http\HttpUri no
checks are done on the url string which means you can construct instances from
invalid url strings, which is not possible with both other classes., (*27)
stubbles\peer\QueryString
Takes a query string as construction argument and provides access to all of the
parameters within the query string to modify and remove them or to add other
parameters; and to rebuild a complete query string from this., (*28)
stubbles\peer\IpAddress
Available since release 4.0.0, (*29)
Represents an ip address and possible operations on an ip address., (*30)
Integration with stubbles/values
In case the package stubbles/values is present a recognition for
stubbles\values\Parse to parse http URIs to instances of
stubbles\peer\http\HttpUri will automatically be added., (*31)
Also, some checks are added to stubbles\values\Value (_available since release 7.1.0_):
- isMailAddress()
- isIpAddress()
- isIpV4Address()
- isIpV6Address()
- isHttpUri()
- isExistingHttpUri(), (*32)
Wallogit.com
