SDK for PHP V3

Utils
in package

FinalYes

Table of Contents

Methods

asciiToLower()  : string
Converts ASCII uppercase letters in a string to lowercase.
asciiToUpper()  : string
Converts ASCII lowercase letters in a string to uppercase.
asciiUcFirst()  : string
Converts the first character of a string to uppercase when it is an ASCII lowercase letter.
caselessContains()  : bool
Checks whether the haystack contains the needle, comparing ASCII letters case-insensitively and without locale sensitivity.
caselessEquals()  : bool
Checks whether two strings are equal, comparing ASCII letters case-insensitively and without locale sensitivity.
caselessRemove()  : array<string|int, mixed>
Remove the items given by the keys from the data, case-insensitively.
copyToStream()  : int
Copy the contents of a stream into another stream until the given number of bytes have been read, returning the number of bytes copied as an `int`. On 32-bit PHP, an unbounded copy larger than `PHP_INT_MAX` bytes cannot be represented by that return type. 64-bit PHP is not affected.
copyToString()  : string
Copy the contents of a stream into a string until the given number of bytes have been read.
hash()  : string
Calculate a hash of a stream.
modifyRequest()  : RequestInterface
Clone and modify a request with the given changes.
readLine()  : string
Read a line from the stream up to the maximum allowed buffer length.
redactUserInfo()  : UriInterface
Redact the user info part of a URI.
redactUserInfoInString()  : string
Redacts the userinfo of a raw URI string wherever it appears in a subject string.
streamFor()  : StreamInterface
Create a new stream based on the input type.
tryFopen()  : resource
Safely opens a PHP stream resource using a filename.
tryGetContents()  : string
Safely gets the contents of a given stream.
uriFor()  : UriInterface
Returns a `UriInterface` for the given value.

Methods

asciiToLower()

Converts ASCII uppercase letters in a string to lowercase.

public static asciiToLower(string $string) : string

Unlike strtolower(), which honors LC_CTYPE before PHP 8.2, the conversion is locale-independent and leaves every non-ASCII byte unchanged, as HTTP protocol elements require.

Parameters
$string : string
Return values
string

asciiToUpper()

Converts ASCII lowercase letters in a string to uppercase.

public static asciiToUpper(string $string) : string

Unlike strtoupper(), which honors LC_CTYPE before PHP 8.2, the conversion is locale-independent and leaves every non-ASCII byte unchanged, as HTTP protocol elements require.

Parameters
$string : string
Return values
string

asciiUcFirst()

Converts the first character of a string to uppercase when it is an ASCII lowercase letter.

public static asciiUcFirst(string $string) : string

Unlike ucfirst(), which honors LC_CTYPE before PHP 8.2, the conversion is locale-independent and leaves every non-ASCII byte unchanged, as HTTP protocol elements require.

Parameters
$string : string
Return values
string

caselessContains()

Checks whether the haystack contains the needle, comparing ASCII letters case-insensitively and without locale sensitivity.

public static caselessContains(string $haystack, string $needle) : bool
Parameters
$haystack : string
$needle : string
Return values
bool

caselessEquals()

Checks whether two strings are equal, comparing ASCII letters case-insensitively and without locale sensitivity.

public static caselessEquals(string $left, string $right) : bool
Parameters
$left : string
$right : string
Return values
bool

caselessRemove()

Remove the items given by the keys from the data, case-insensitively.

public static caselessRemove(array<string|int, string|int> $keys, array<string|int, mixed> $data) : array<string|int, mixed>
Parameters
$keys : array<string|int, string|int>
$data : array<string|int, mixed>
Return values
array<string|int, mixed>

copyToStream()

Copy the contents of a stream into another stream until the given number of bytes have been read, returning the number of bytes copied as an `int`. On 32-bit PHP, an unbounded copy larger than `PHP_INT_MAX` bytes cannot be represented by that return type. 64-bit PHP is not affected.

public static copyToStream(StreamInterface $source, StreamInterface $dest[, int $maxLen = -1 ]) : int

The destination must accept writes that make positive progress. Streams that return 0 as a backpressure or drop signal (a BufferStream at its high water mark, or a full DroppingStream) will cause this method to throw. For full copies, use a normal writable stream such as a file or php://temp stream.

Throws TimeoutException when PHP-style timeout metadata can be detected after a source read or destination write cannot make progress.

Parameters
$source : StreamInterface

Stream to read from

$dest : StreamInterface

Stream to write to

$maxLen : int = -1

Maximum number of bytes to read. Pass -1 to read the entire stream.

Tags
throws
RuntimeException

on error.

Return values
int

copyToString()

Copy the contents of a stream into a string until the given number of bytes have been read.

public static copyToString(StreamInterface $stream[, int $maxLen = -1 ]) : string

Throws TimeoutException when PHP-style timeout metadata can be detected after a stream read cannot make progress.

Parameters
$stream : StreamInterface

Stream to read

$maxLen : int = -1

Maximum number of bytes to read. Pass -1 to read the entire stream.

Tags
throws
RuntimeException

on error.

Return values
string

hash()

Calculate a hash of a stream.

public static hash(StreamInterface $stream, string $algo[, bool $rawOutput = false ]) : string

This method reads the entire stream to calculate a rolling hash, based on PHP's hash_init functions.

Throws TimeoutException when PHP-style timeout metadata can be detected after a stream read cannot make progress.

Parameters
$stream : StreamInterface

Stream to calculate the hash for

$algo : string

Hash algorithm (e.g. md5, crc32, etc)

$rawOutput : bool = false

Whether or not to use raw output

Tags
throws
RuntimeException

on error.

Return values
string

modifyRequest()

Clone and modify a request with the given changes.

public static modifyRequest(RequestInterface $request, array<string|int, mixed> $changes) : RequestInterface

This method is useful for reducing the number of clones needed to mutate a message.

The changes can be one of:

  • method: (string) Changes the HTTP method.
  • set_headers: (array) Sets the given headers. Values must be strings or non-empty arrays of strings.
  • remove_headers: (array) Remove the given headers. Values may be strings or integers.
  • body: (mixed) Sets the given body. Present non-null values are converted with self::streamFor(), including resources, streams, iterators, callable arrays, closures, invokable objects, and stringable objects. String inputs remain literal bodies.
  • uri: (UriInterface) Set the URI. When the URI contains a host, the Host header is updated from it, and combining this with an explicit Host entry in set_headers throws an InvalidArgumentException. Apply an intentional Host override separately with withHeader() afterwards.
  • query: (string) Set the query string value of the URI.
  • version: (string) Set the protocol version.
Parameters
$request : RequestInterface

Request to clone and modify.

$changes : array<string|int, mixed>
Return values
RequestInterface

readLine()

Read a line from the stream up to the maximum allowed buffer length.

public static readLine(StreamInterface $stream[, int|null $maxLength = null ]) : string

Throws TimeoutException when PHP-style timeout metadata can be detected after a stream read cannot make progress.

Parameters
$stream : StreamInterface

Stream to read from

$maxLength : int|null = null

Maximum buffer length

Return values
string

redactUserInfo()

Redact the user info part of a URI.

public static redactUserInfo(UriInterface $uri) : UriInterface

Returns the URI with the whole userinfo component replaced by "***" when one is present, so neither the username nor the password survives into logs and diagnostics. A URI without userinfo is returned unchanged.

Parameters
$uri : UriInterface
Return values
UriInterface

redactUserInfoInString()

Redacts the userinfo of a raw URI string wherever it appears in a subject string.

public static redactUserInfoInString(string $subject, string $uri) : string

The needle is taken verbatim from the raw URI rather than from parsed components, so credentials that URI normalization would rewrite, such as raw control bytes or unencoded reserved characters, are still found in text that embeds the URI exactly as given, for example transport error messages. A URI without "://" is treated as authority-form: a host and port with optional userinfo.

A URI that does not parse has no trustworthy authority boundary, so everything between any scheme and its last "@" is redacted as a safe-side fallback.

Parameters
$subject : string

Text that may embed the URI

$uri : string

Raw URI whose userinfo is redacted in the text

Return values
string

streamFor()

Create a new stream based on the input type.

public static streamFor([resource|string|StreamInterface|callable|Iterator|Stringable|null $resource = '' ][, array{size?: int, metadata?: array} $options = [] ]) : StreamInterface

Options are provided as an associative array that can contain the following keys:

  • metadata: Array of custom metadata.
  • size: Size of the stream.

This method accepts the following $resource types:

  • Psr\Http\Message\StreamInterface: Returns the value as-is.
  • string: Creates a stream object that uses the given string as the contents.
  • resource: Creates a stream object that wraps the given PHP stream resource.
  • Iterator: If the provided value implements Iterator, then a read-only stream object will be created that wraps the given iterable. Each time the stream is read from, data from the iterator will fill a buffer and will be continuously called until the buffer is equal to the requested read size. Yielded strings, integers, finite floats, booleans, null, and stringable objects are converted to string chunks; non-finite floats and other values throw UnexpectedValueException when the stream is read. Values that stringify to an empty string are skipped while the iterator advances. Subsequent read calls will first read from the buffer and then call next on the underlying iterator until it is exhausted.
  • object with __toString(): If the object has the __toString() method, the object will be cast to a string and then a stream will be returned that uses the string value.
  • NULL: When null is passed, an empty stream object is returned.
  • callable: When a callable array, closure, or invokable object is passed and no earlier resource or object rule applies, a read-only stream object will be created that invokes the given callable. The callable is invoked with the suggested number of bytes to read. The callable can return fewer or more bytes than requested, but MUST return a non-empty string to provide data and MUST return false or null when there is no more data to return. Any additional bytes will be buffered and used in subsequent reads. String inputs are always treated as string bodies, even when they name callable functions.
Parameters
$resource : resource|string|StreamInterface|callable|Iterator|Stringable|null = ''

Entity body data

$options : array{size?: int, metadata?: array} = []

Additional options

Tags
throws
InvalidArgumentException

if the $resource arg is not valid.

Return values
StreamInterface

tryFopen()

Safely opens a PHP stream resource using a filename.

public static tryFopen(string $filename, string $mode) : resource

When fopen() fails, PHP normally raises a warning. This function adds an error handler that checks for errors and throws an exception instead.

Parameters
$filename : string

File to open

$mode : string

Mode used to open the file

Tags
throws
RuntimeException

if the file cannot be opened

Return values
resource

tryGetContents()

Safely gets the contents of a given stream.

public static tryGetContents(resource $stream) : string

When stream_get_contents() fails, PHP normally raises a warning. This function adds an error handler that checks for errors and throws an exception instead.

Throws TimeoutException when PHP-style timeout metadata can be detected after a stream read cannot make progress.

Parameters
$stream : resource
Tags
throws
RuntimeException

if the stream cannot be read

Return values
string

uriFor()

Returns a `UriInterface` for the given value.

public static uriFor(string|UriInterface $uri) : UriInterface

This function accepts a string or UriInterface and returns a UriInterface for the given value. If the value is already a UriInterface, it is returned as-is.

Parameters
$uri : string|UriInterface
Tags
throws
InvalidArgumentException
Return values
UriInterface
<-- modeled_exceptions -->
On this page