stubbles / peer
Help with socket operations.
Installs: 1 031
Dependents: 2
Suggesters: 1
Security: 0
Stars: 0
Watchers: 3
Forks: 0
Open Issues: 2
Requires
- php: ^8.2
- ext-ctype: *
- ext-filter: *
Requires (Dev)
- bovigo/assert: ^8.0
- bovigo/callmap: ^8.0
- mikey179/vfsstream: ^1.6.11
- phpunit/phpunit: ^10.5
- stubbles/values: ^11.0
Suggests
- stubbles/values: Will automatically add http uri parsing to stubbles\values\Parse
README
Help with socket operations.
Build status
Installation
stubbles/peer is distributed as Composer package. To install it as a dependency of your package use the following command:
composer require "stubbles/peer": "^10.0"
Requirements
stubbles/peer requires at least PHP 8.2.
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.
New instances can be created via Uri::fromString('ftp://user@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 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.
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.
For the methods, the following rules apply:
hasDnsRecord()
returnsfalse
if the URI does not contain a host.hasDnsRecord()
always returns true for localhost, 127.0.0.1 and [::1].hasDefaultPort()
returnsfalse
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.
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.
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\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
.
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()
returnstrue
if the scheme is http and the port is 80. In case no port was originally supplied, port 80 is assumed. The method also returnstrue
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 returnsfalse
.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 astubbles\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 ofstubbles\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.
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.
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.
Other utility classes
stubbles\peer\HeaderList
This class provides possibilities to work with headers, mainly parsing a string which contains headers and maintaining a list of headers.
stubbles\peer\http\AcceptHeader
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.
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.
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.
stubbles\peer\IpAddress
Available since release 4.0.0
Represents an ip address and possible operations on an ip address.
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.
Also, some checks are added to stubbles\values\Value
(available since release 7.1.0):
isMailAddress()
isIpAddress()
isIpV4Address()
isIpV6Address()
isHttpUri()
isExistingHttpUri()