Redirected from /azjezz/psl
PSL - PHP Standard Library

https://github.com/php-standard-library/php-standard-library
Admin
A standard library for PHP, inspired by hhvm/hsl. PSL provides a consistent, centralized, well-typed...
Tokens:40,678
Snippets:688
Trust Score:9.5
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Async Quick Start

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/async/async.md

Quick start example showing the basic structure of an async application using Async\main() and Async\run().

```php
<?php

use Psl\Async;

$result = Async\main(static function (): int {
    $awaitable = Async\run(static function (): string {
        Async\sleep(1.0);
        return 'Hello, World!';
    });

    $value = $awaitable->await();

    echo $value . PHP_EOL;

    return 0;
});

```

--------------------------------

### Write modes example

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/io/file.md

Shows how to use different WriteMode options when opening a file for writing.

```php
@example('io/file-write-modes.php')
```

--------------------------------

### Install PSL via Composer

Source: https://github.com/php-standard-library/php-standard-library/blob/next/README.md

Install the PSL library using Composer. Requires PHP 8.4 or higher.

```shell
composer require php-standard-library/php-standard-library
```

--------------------------------

### File handles example

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/io/file.md

Demonstrates opening a file handle directly for more control, implementing IO handle interfaces and adding getPath(), getSize(), and locking.

```php
@example('io/file-handles.php')
```

--------------------------------

### Multiple source paths

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/tools/detect-packages.md

Pass multiple directories; bare paths default to require. This example scans src/ and lib/ as require, and tests/ as require-dev.

```bash
vendor/bin/psl detect-packages src/ lib/ --dev tests/
```

--------------------------------

### Async iterate()

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/async/async.md

Iterate awaitables in completion order, regardless of the order they were started.

```php
<?php

use Psl\Async;

$awaitables = [
    Async\run(static function (): string { return 'first'; }),
    Async\run(static function (): string { return 'second'; }),
];

foreach (Async\iterate($awaitables) as $awaitable) {
    $result = $awaitable->await();
    // ...
}

```

--------------------------------

### Non-blocking file read with amphp/file

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/io/file.md

Example of using amphp/file for non-blocking file read in an async context, allowing other fibers to run while waiting.

```php
use Amp\File;
use Psl\Async;

Async\main(static function(): int {
    // Non-blocking file read; other fibers can run while this waits
    $content = File\read('/path/to/large-file.dat');

    return 0;
});
```

--------------------------------

### Implementing Custom Writer with WriterConvenienceMethodsTrait

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/text/binary.md

Shows how to implement WriterInterface using WriterConvenienceMethodsTrait to get default implementations of skip() and length-prefixed methods. Only primitive methods need to be implemented.

```php
use Psl\Binary\WriterInterface;
use Psl\Binary\WriterConvenienceMethodsTrait;

final class MyCustomWriter implements WriterInterface
{
    use WriterConvenienceMethodsTrait;

    // Only implement the primitive methods: u8, u16, u32, u64,
    // i8, i16, i32, i64, f32, f64, bytes
    // The prefixed methods come from the trait for free.
}
```

--------------------------------

### Structured concurrency with Psl\Async

Source: https://github.com/php-standard-library/php-standard-library/blob/next/README.md

Run concurrent operations using Async\main and Async\concurrently. Uses fibers for structured concurrency without promises or callbacks. The example connects to two TCP endpoints concurrently and writes an error line.

```php
use Psl\Async;
use Psl\TCP;
use Psl\IO;

Async\main(static function(): int {
    [$a, $b] = Async\concurrently([
        static fn() => TCP\connect('api.example.com', 443),
        static fn() => TCP\connect('db.example.com', 5432),
    ]);

    IO\write_error_line('Both connections ready');

    return 0;
});
```

--------------------------------

### JSON output for composer.json

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/tools/detect-packages.md

Use --composer to get a JSON snippet that can be pasted directly into composer.json. The output includes version constraints (^6.1) for each package.

```bash
vendor/bin/psl detect-packages src/ --dev tests/ --composer
```

```json
{
    "require": {
        "php-standard-library/dict": "^6.1",
        "php-standard-library/str": "^6.1",
        "php-standard-library/vec": "^6.1"
    },
    "require-dev": {
        "php-standard-library/filesystem": "^6.1",
        "php-standard-library/os": "^6.1"
    }
}
```

--------------------------------

### Request Body Rules

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/protocols/http-client.md

Describes the rules for request bodies: TRACE requests with a body are rejected, while GET and HEAD requests may carry a body.

```APIDOC
## Request Body Rules

### Description
TRACE requests that include a body are rejected with a `RequestException` per RFC 9110 Section 9.3.8. GET and HEAD requests are allowed to carry a body (useful for Elasticsearch-style query bodies), although this is not recommended per RFC 9110 Section 9.3.1.

### Rules
- **TRACE with body**: Rejected with `RequestException`
- **GET with body**: Allowed, but not recommended
- **HEAD with body**: Allowed, but not recommended

### Example
Refer to the example file `protocols/http-client-body-rules.php`.
```

--------------------------------

### Functional collections with Psl\Vec and Psl\Dict

Source: https://github.com/php-standard-library/php-standard-library/blob/next/README.md

Map, filter, and pull arrays using pure functions. Vec functions return lists, Dict functions return dicts. The example shows uppercase mapping, filtering by string length, and pulling a dict with key-value pairs.

```php
use Psl\Vec;
use Psl\Dict;
use Psl\Str;

$names = ['alice', 'bob', 'charlie'];

Vec\map($names, Str\uppercase(...));
// ['ALICE', 'BOB', 'CHARLIE']

Vec\filter($names, fn($n) => Str\length($n) > 3);
// ['alice', 'charlie']

Dict\pull($names, Str\uppercase(...), fn($n) => $n);
// {alice: 'ALICE', bob: 'BOB', charlie: 'CHARLIE'}
```

--------------------------------

### Basic usage of detect-packages

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/tools/detect-packages.md

Shows the general command syntax for the detect-packages tool. Use this to understand the available options: --src (default), --dev, and --composer.

```bash
vendor/bin/psl detect-packages <path>... [--dev <path>...] [--composer]
```

--------------------------------

### TCP server in 10 lines

Source: https://github.com/php-standard-library/php-standard-library/blob/next/README.md

Create a simple TCP server that listens on port 8080 and responds to each connection with 'Hello!'. Uses Psl\Async, Psl\TCP, and Psl\IO. The server runs indefinitely, accepting connections and handling them asynchronously.

```php
use Psl\Async;
use Psl\TCP;
use Psl\IO;

Async\main(static function(): int {
    $server = TCP\listen('127.0.0.1', 8080);
    IO\write_error_line('Listening on :8080');

    while (true) {
        $conn = $server->accept();
        Async\run(static function() use ($conn) {
            $conn->writeAll("Hello!\n");
            $conn->close();
        })->ignore();
    }
});
```

--------------------------------

### Async main() Entry Point

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/async/async.md

Entry point for async applications. The closure must return an integer exit code.

```php
<?php

use Psl\Async;

$exitCode = Async\main(static function (): int {
    // ...
    return 0;
});

```

--------------------------------

### Integration with IO interfaces

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/io/file.md

Shows how file handles implement IO interfaces and can be used with code that accepts IO\ReadHandleInterface or IO\WriteHandleInterface.

```php
@example('io/file-io-integration.php')
```

--------------------------------

### Async run()

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/async/async.md

Creates a new fiber and returns an Awaitable that resolves to its result.

```php
<?php

use Psl\Async;

$awaitable = Async\run(static function (): string {
    // ...
    return 'result';
});

$result = $awaitable->await();

```

--------------------------------

### Basic scan of a source directory

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/tools/detect-packages.md

Scans the src/ directory and outputs the detected PSL packages under 'require'. The output lists the packages that need to be added to composer.json.

```bash
vendor/bin/psl detect-packages src/
```

```text
Detected PSL packages:

  require:
    php-standard-library/dict
    php-standard-library/foundation
    php-standard-library/str
    php-standard-library/vec
```

--------------------------------

### Quick read and write with File\read() and File\write()

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/io/file.md

Convenience functions that automatically acquire a lock (shared for reads, exclusive for writes) and release it when done.

```php
@example('io/file-read-write.php')
```

--------------------------------

### Async any() and first()

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/async/async.md

any() returns the first successful result. first() returns the first completed result regardless of success or failure.

```php
<?php

use Psl\Async;

$awaitables = [
    Async\run(static function (): string { return 'a'; }),
    Async\run(static function (): string { return 'b'; }),
];

$first = Async\any($awaitables);
$firstCompleted = Async\first($awaitables);

```

--------------------------------

### Accept a connection with ListenerInterface

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/networking/network.md

Accepts an incoming connection on a listener, blocking until a connection arrives. Returns a StreamInterface instance.

```php
$connection = $listener->accept(); // blocks until a connection arrives
```

--------------------------------

### Callbacks for Connection and Protocol Events

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/protocols/http-client.md

Configure per-request callbacks for observing connection and informational responses, plus a client-level callback for informational responses.

```APIDOC
## Callbacks

### Description
`SendConfiguration` provides two per-request callbacks for observing connection and protocol events. `ClientConfiguration` also accepts an `onInformationalResponse` callback that applies to all requests.

### Callbacks
- **onConnection(ConnectionMetadata): void** - Fires immediately after a connection is acquired (fresh or pooled), before the HTTP exchange. Use it to inspect the peer IP, local address, and TLS negotiation state.
- **onInformationalResponse(Response): void** - Fires for each 1xx response as it arrives (100 Continue, 103 Early Hints, etc.).

### Client-Level Callback
- **ClientConfiguration::onInformationalResponse** - Applies to all requests. When both client-level and per-request callbacks are set, the client-level callback fires first, followed by the per-request callback.

### Example
Refer to the example file `protocols/http-client-callbacks.php`.
```

--------------------------------

### Async sleep() with Cancellation

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/async/async.md

sleep() accepts a CancellationTokenInterface to wake early, useful for interruptible retry delays.

```php
<?php

use Psl\Async;
use Psl\Cancellation\CancellationTokenInterface;

$token = ...; // obtain a cancellation token
Async\sleep(1.0, $token);

```

--------------------------------

### Basic Shell execute() usage

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/io/shell.md

Runs an external command and captures its output. The command and arguments are escaped automatically. Use this when you need a simple command execution without advanced process management.

```php
@example('io/shell-execute.php')
```

--------------------------------

### Crypto\Hkdf\extract() and Crypto\Hkdf\expand()

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/security/crypto.md

Two-step API for HKDF. Useful when deriving multiple keys from the same source material, as extraction cost is paid only once.

```APIDOC
## Crypto\Hkdf\extract() and Crypto\Hkdf\expand()

### Description
The two-step API (`Hkdf\extract()` + `Hkdf\expand()`) is useful when you need to derive multiple keys from the same source material, as you only pay the extraction cost once.

### Usage
Refer to the example file `security/crypto-hkdf-derive.php` for a complete usage example.
```

--------------------------------

### Async series()

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/async/async.md

Runs closures one after another. If any throws, execution stops.

```php
<?php

use Psl\Async;

$results = Async\series([
    static function (): string { return 'a'; },
    static function (): string { return 'b'; },
]);

```

--------------------------------

### tryLock() throwing AlreadyLockedException

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/io/file.md

tryLock() acquires the lock immediately or throws AlreadyLockedException.

```php
@example('io/file-try-lock.php')
```

--------------------------------

### Async all()

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/async/async.md

Waits for all Awaitables to complete. If multiple fail, throws CompositeException.

```php
<?php

use Psl\Async;

$awaitables = [
    Async\run(static function (): string { return 'a'; }),
    Async\run(static function (): string { return 'b'; }),
];

$results = Async\all($awaitables);

```

--------------------------------

### Async reflect()

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/async/async.md

Use Psl\Result\reflect(...) to continue execution even when individual tasks fail.

```php
<?php

use Psl\Async;
use Psl\Result;

$results = Async\concurrently([
    static function (): string { return 'a'; },
    static function (): string { throw new \Exception('fail'); },
], reflect: true);

```

--------------------------------

### File locking with lock() and tryLock()

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/io/file.md

Shows advisory locking via lock() and tryLock(). The returned Lock object is released by calling release() or when garbage collected.

```php
@example('io/file-locking.php')
```

--------------------------------

### Mago configuration for psl plugin

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/types/type.md

Enable the 'psl' plugin in your mago.toml file to let Mago's static analyzer understand types from this component. The snippet shows the required [analyzer] section with the plugins list.

```toml
[analyzer]
plugins = ["psl"]
...
```

--------------------------------

### Encryptor Class for Sealed-Box Encryption

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/security/crypto.md

Implements Crypto\EncryptorInterface for sealed-box encryption, useful for dependency injection.

```php
@example('security/crypto-asymmetric-encryptor.php')
```

--------------------------------

### Async concurrently()

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/async/async.md

Runs all closures concurrently and returns their results in the original order. Warning: only for I/O functions, not CPU-bound code.

```php
<?php

use Psl\Async;

$results = Async\concurrently([
    static function (): string { return 'a'; },
    static function (): string { return 'b'; },
]);

```

--------------------------------

### Async catch() Error Handling

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/async/async.md

Error handling with catch() works naturally with awaitables.

```php
<?php

use Psl\Async;

try {
    $result = $awaitable->await();
} catch (\Throwable $e) {
    // handle error
}

```

--------------------------------

### Hash\Context

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/security/hash.md

Provides incremental hashing and HMAC support through an immutable context.

```APIDOC
## Hash\Context

### Description
Provides incremental hashing by feeding data in chunks. The context is immutable; each update() returns a new context.

### Methods
- **update(data: string): Context** - Returns a new context with the data added.
- **hmac(key: string): Context** - Creates an HMAC context with the given key.

### Parameters
- **data** (string) - Required - The data chunk to add.
- **key** (string) - Required - The secret key for HMAC.

### Request Example
N/A

### Response
#### Success Response
- **Context** - A new context instance.

#### Response Example
N/A
```

--------------------------------

### Awaitable await()

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/async/async.md

Awaitables are promise-like objects. The await() method accepts an optional CancellationTokenInterface to cancel the wait.

```php
<?php

use Psl\Async;

$awaitable = Async\run(static function (): string {
    return 'value';
});

$value = $awaitable->await();

```

--------------------------------

### Verifier Class

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/security/crypto.md

Wraps the verification logic, needing only the public key. Useful for dependency injection to separate verification from signing.

```APIDOC
## Verifier Class

### Description
Wraps the verification logic, needing only the public key. Useful for dependency injection to separate verification from signing.

### Methods
- **verify(signature, message)** - Verifies a signature against a message and returns a boolean.

### Example
```php
$verifier = new Verifier($publicKey);
$valid = $verifier->verify($signature, $message);
```
```

--------------------------------

### Crypto\Hkdf\derive()

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/security/crypto.md

Implements the full HKDF construction from RFC 5869. It takes raw input keying material and produces cryptographically strong key material.

```APIDOC
## Crypto\Hkdf\derive()

### Description
Implements the full HKDF construction from RFC 5869. It takes raw input keying material (such as a shared secret from key exchange) and produces cryptographically strong key material.

### Usage
Refer to the example file `security/crypto-hkdf-derive.php` for a complete usage example.
```

--------------------------------

### HTTP Proxy Configuration

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/protocols/http-client.md

Configure the HTTP client to route requests through an HTTP proxy using ProxyConfiguration. Supports CONNECT tunneling for HTTPS and forward proxying for HTTP.

```APIDOC
## HTTP Proxy Configuration

### Description
Use `$proxyConfiguration` to route requests through an HTTP proxy. Configure the proxy URL, authentication, and bypass rules via `ProxyConfiguration`. HTTPS targets use CONNECT tunneling while plain HTTP targets use forward proxying with absolute-form request targets.

### Configuration
- **proxyConfiguration** (ProxyConfiguration) - Required - The proxy configuration object containing proxy URL, authentication, and bypass rules.

### Behavior
- HTTPS targets: CONNECT tunneling
- HTTP targets: Forward proxying with absolute-form request targets

### Example
Refer to the example file `protocols/http-client-tunnel.php`.
```

--------------------------------

### Cancellation with TimeoutCancellationToken

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/io/shell.md

Pass a CancellationTokenInterface to cancel a running command. Use TimeoutCancellationToken to enforce a time limit.

```php
@example('io/shell-timeout.php')
```

--------------------------------

### Separating require and require-dev

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/tools/detect-packages.md

Scans src/ as require and tests/ as require-dev. Packages found in both are placed only in require. The output shows the separation.

```bash
vendor/bin/psl detect-packages src/ --dev tests/
```

```text
Detected PSL packages:

  require:
    php-standard-library/dict
    php-standard-library/foundation
    php-standard-library/str
    php-standard-library/vec

  require-dev:
    php-standard-library/filesystem
    php-standard-library/os
```

--------------------------------

### Error handling with specific exceptions

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/io/shell.md

execute() throws FailedExecutionException, PossibleAttackException, CancelledException, or RuntimeException depending on the failure. FailedExecutionException provides getCommand(), getOutput(), and getErrorOutput().

```php
@example('io/shell-error-handling.php')
```

--------------------------------

### Async sleep()

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/async/async.md

Non-blocking sleep. Multiple concurrent sleeps run in parallel.

```php
<?php

use Psl\Async;

Async\sleep(1.0);

```

--------------------------------

### Crypto\Kdf\derive()

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/security/crypto.md

Derives deterministic subkeys from a master key. Each subkey is identified by a numeric ID and an 8-byte context string.

```APIDOC
## Crypto\Kdf\derive()

### Description
Produces deterministic subkeys from a master key. Each subkey is identified by a numeric ID and an 8-byte context string.

### Usage
Refer to the example file `security/crypto-kdf-derive.php` for a complete usage example.

This is useful when you need multiple keys for different purposes (encryption, signing, tokens) but want to store and manage only a single master key.
```

--------------------------------

### Crypto\KeyExchange

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/security/crypto.md

Provides X25519 Diffie-Hellman key agreement. Two parties can combine their own secret key with the other's public key to arrive at the same shared secret.

```APIDOC
## Crypto\KeyExchange

### Description
Provides X25519 Diffie-Hellman key agreement. Two parties can each combine their own secret key with the other's public key to arrive at the same shared secret, without ever transmitting the secret itself.

### Usage
Refer to the example file `security/crypto-key-exchange.php` for a complete usage example.

The shared secret can then be used as input keying material for key derivation to produce session keys.
```

--------------------------------

### Connection Timeout Configuration

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/protocols/http-client.md

Set the maximum duration for establishing a connection using SendConfiguration::$connectionTimeout. The connector's cancellation token is linked with a timeout token.

```APIDOC
## Connection Timeout

### Description
`SendConfiguration::$connectionTimeout` sets the maximum duration for establishing a connection (TCP handshake + TLS handshake) on a per-request basis. When set, the connector's cancellation token is linked with a timeout token scoped to this duration. The overall request cancellation token still applies independently.

### Configuration
- **connectionTimeout** (Duration) - Optional - Maximum duration for connection establishment.

### Behavior
- Applies per request
- Links connector's cancellation token with a timeout token
- Overall request cancellation token still applies independently

### Example
Refer to the example file `protocols/http-client-connection-timeout.php`.
```

--------------------------------

### Signing\verify()

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/security/crypto.md

Verifies a detached Ed25519 signature against the original message using a public key.

```APIDOC
## Signing\verify()

### Description
Verifies a detached Ed25519 signature against the original message using a public key.

### Method
verify

### Parameters
- **signature** (string) - Required - The signature to verify.
- **message** (string) - Required - The original message.
- **publicKey** (string) - Required - The public key used for verification.

### Returns
- **bool** - True if the signature is valid, false otherwise.

### Example
```php
$valid = Signing\verify($signature, $message, $publicKey);
```
```

--------------------------------

### Hash\equals()

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/security/hash.md

Compares two hashes in constant time to prevent timing attacks.

```APIDOC
## Hash\equals()

### Description
Compares two hashes in constant time to prevent timing attacks.

### Method
N/A (function)

### Endpoint
N/A (function)

### Parameters
- **known_string** (string) - Required - The known hash string.
- **user_string** (string) - Required - The user-provided hash string.

### Request Example
N/A

### Response
#### Success Response
- **bool** - True if the hashes are equal, false otherwise.

#### Response Example
N/A
```

--------------------------------

### Generate a pseudo-random float between 0.0 and 1.0

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/security/pseudo-random.md

Use this snippet to generate a pseudo-random float between 0.0 and 1.0. It is suitable for simulations or Monte Carlo methods.

```php
@example('security/pseudo-random-float.php')
```

--------------------------------

### Signer Class

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/security/crypto.md

Wraps the signing logic, holding the secret key. Useful for dependency injection to separate the signing side from verification.

```APIDOC
## Signer Class

### Description
Wraps the signing logic, holding the secret key. Useful for dependency injection to separate the signing side from verification.

### Methods
- **sign(message)** - Signs a message and returns the signature.

### Example
```php
$signer = new Signer($secretKey);
$signature = $signer->sign($message);
```
```

--------------------------------

### Hash\hash()

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/security/hash.md

Computes a message digest for the given data and algorithm.

```APIDOC
## Hash\hash()

### Description
Computes a message digest for the given data and algorithm.

### Method
N/A (function)

### Endpoint
N/A (function)

### Parameters
- **data** (string) - Required - The data to hash.
- **algorithm** (Algorithm) - Required - The hashing algorithm to use.

### Request Example
N/A

### Response
#### Success Response
- **string** - The computed message digest.

#### Response Example
N/A
```

--------------------------------

### Authenticated Encryption with Asymmetric\encrypt()

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/security/crypto.md

Authenticated encryption when both parties have key pairs. Recipient can verify sender. A random nonce is generated and prepended to ciphertext automatically.

```php
@example('security/crypto-asymmetric-encrypt.php')
```

--------------------------------

### Custom conversion pipeline with converted()

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/types/type.md

Use `converted()` to build a custom conversion pipeline from a source type to a target type with a converter function. Error messages indicate the failing stage, e.g., 'coerce_input(int): string' or 'coerce_output(string): class-string<stdClass>'.

```php
@example('types/type-converted.php')
```

--------------------------------

### Signing\sign()

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/security/crypto.md

Creates a detached Ed25519 digital signature for a message using a secret key.

```APIDOC
## Signing\sign()

### Description
Creates a detached Ed25519 digital signature for a given message using a secret key.

### Method
sign

### Parameters
- **message** (string) - Required - The message to sign.
- **secretKey** (string) - Required - The secret key used for signing.

### Returns
- **string** - The detached signature.

### Example
```php
$signature = Signing\sign($message, $secretKey);
```
```

--------------------------------

### Symmetric Encryption with Crypto\Symmetric

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/security/crypto.md

Authenticated encryption using XChaCha20-Poly1305. A single shared key encrypts and decrypts. Nonces are managed automatically.

```php
@example('security/crypto-symmetric-seal.php')
```

--------------------------------

### Additional Authenticated Data (AAD) for Symmetric Encryption

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/security/crypto.md

Binds extra context to ciphertext. AAD is not encrypted, but decryption fails if it does not match exactly.

```php
@example('security/crypto-symmetric-aad.php')
```

--------------------------------

### HTTP/2 over Plaintext (h2c)

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/protocols/http-client.md

Configure the client to use HTTP/2 without TLS by setting protocolVersions to only ProtocolVersion::V20. The client uses prior-knowledge mode per RFC 9113 Section 3.4.

```APIDOC
## HTTP/2 over Plaintext (h2c)

### Description
For servers that support HTTP/2 without TLS, set `protocolVersions` to only `ProtocolVersion::V20`. The client uses prior-knowledge mode per RFC 9113 Section 3.4 - it sends the HTTP/2 connection preface directly on the TCP connection, skipping TLS and ALPN negotiation entirely.

### Configuration
- **protocolVersions** (array of ProtocolVersion) - Required - Set to only `ProtocolVersion::V20` to enable h2c.

### Behavior
- Sends HTTP/2 connection preface directly on TCP connection
- Skips TLS and ALPN negotiation

### Example
Refer to the example file `protocols/http-client-h2c.php`.
```

--------------------------------

### Hash\hmac()

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/security/hash.md

Computes an HMAC using a secret key for data integrity and authenticity.

```APIDOC
## Hash\hmac()

### Description
Computes an HMAC (Hash-based Message Authentication Code) using a secret key.

### Method
N/A (function)

### Endpoint
N/A (function)

### Parameters
- **data** (string) - Required - The data to authenticate.
- **key** (string) - Required - The secret key.
- **algorithm** (Algorithm) - Required - The hashing algorithm to use.

### Request Example
N/A

### Response
#### Success Response
- **string** - The HMAC digest.

#### Response Example
N/A
```

--------------------------------

### Strict mode with always_assert()

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/types/type.md

Use `always_assert()` to create a type that rejects any value not already matching, even during coercion. This is useful when you want to enforce strict type checking.

```php
@example('types/type-always-assert.php')
```

--------------------------------

### encode()

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/text/html.md

Converts all applicable characters to HTML entities. Accepts an optional double encoding flag and an Encoding enum for character set selection.

```APIDOC
## encode()

### Description
Converts all applicable characters to HTML entities. Use this when you need to encode all characters, but prefer encode_special_characters() for user input to prevent XSS.

### Method
Function

### Signature
`encode(string $string, bool $double_encoding = true, Encoding $encoding = Encoding::UTF_8): string`

### Parameters
- **$string** (string) - Required - The input string to encode.
- **$double_encoding** (bool) - Optional - Whether to encode existing HTML entities. Defaults to true.
- **$encoding** (Encoding) - Optional - The character set to use. Defaults to UTF-8.

### Example
```php
use Psl\Html;

$encoded = Html\encode('<p>Hello & welcome</p>');
// Output: &lt;p&gt;Hello &amp; welcome&lt;/p&gt;
```

### Notes
- Wraps PHP's htmlentities function.
- To avoid double encoding, set $double_encoding to false.
```

--------------------------------

### Async later()

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/async/async.md

Reschedules the current fiber, allowing other pending callbacks to execute.

```php
<?php

use Psl\Async;

Async\later();

```

--------------------------------

### Sealed Boxes (Anonymous Sender) with Crypto\Asymmetric

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/security/crypto.md

Encrypts a message for a recipient using only their public key. The sender remains anonymous. Use when sender identity does not need verification.

```php
@example('security/crypto-asymmetric-seal.php')
```

--------------------------------

### Generate a pseudo-random integer within a range

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/security/pseudo-random.md

Use this snippet to generate a pseudo-random integer within a specified range. It is suitable for non-security contexts like dice rolls, shuffling, or sampling.

```php
@example('security/pseudo-random-int.php')
```

--------------------------------

### Stream Encryption with StreamEncryptor

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/security/crypto.md

Streaming encryption for large data or files. Processes data in chunks to keep memory usage constant. Uses XChaCha20-Poly1305 secretstream, authenticating each chunk and detecting reordering or truncation.

```php
@example('security/crypto-symmetric-stream.php')
```

--------------------------------

### Aead\Algorithm Enum

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/security/crypto.md

Enum supporting three AEAD constructions: XChaCha20Poly1305, ChaCha20Poly1305, and Aes256Gcm.

```APIDOC
## Aead\Algorithm Enum

### Description
Enum supporting three AEAD constructions: XChaCha20Poly1305, ChaCha20Poly1305, and Aes256Gcm.

### Values
- **XChaCha20Poly1305** - Nonce size: 24 bytes. Recommended. Large nonce makes accidental reuse unlikely.
- **ChaCha20Poly1305** - Nonce size: 8 bytes. IETF standard. Smaller nonce requires careful management.
- **Aes256Gcm** - Nonce size: 12 bytes. Hardware-accelerated on supported CPUs. Not available everywhere.
```

--------------------------------

### decode()

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/text/html.md

Decodes HTML entities back to their corresponding characters. Accepts an optional Encoding enum for character set selection.

```APIDOC
## decode()

### Description
Decodes HTML entities back to their corresponding characters. Use this to convert encoded strings back to plain text.

### Method
Function

### Signature
`decode(string $string, Encoding $encoding = Encoding::UTF_8): string`

### Parameters
- **$string** (string) - Required - The input string containing HTML entities.
- **$encoding** (Encoding) - Optional - The character set to use. Defaults to UTF-8.

### Example
```php
use Psl\Html;

$decoded = Html\decode('&lt;p&gt;Hello &amp; welcome&lt;/p&gt;');
// Output: <p>Hello & welcome</p>
```

### Notes
- Wraps PHP's html_entity_decode function.
```

--------------------------------

### Encoding enum

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/text/html.md

An enum for character set selection used by all encoding/decoding functions. Supports UTF-8, ISO-8859-1, ISO-8859-15, Windows-1251, Windows-1252, Big5, GB2312, Shift_JIS, EUC-JP, KOI8-R, and several other character sets.

```APIDOC
## Encoding enum

### Description
An enum for character set selection used by all encoding/decoding functions. The default is UTF-8.

### Supported Values
- UTF-8
- ISO-8859-1
- ISO-8859-15
- Windows-1251
- Windows-1252
- Big5
- GB2312
- Shift_JIS
- EUC-JP
- KOI8-R
- and several other character sets

### Usage
```php
use Psl\Html;

$encoded = Html\encode('café', encoding: Html\Encoding::ISO_8859_1);
```

### Notes
- See `src/Psl/Html/` for the full API.
```

--------------------------------

### strip_tags()

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/text/html.md

Removes HTML and PHP tags from a string, optionally keeping specific tags. Useful for sanitizing user input.

```APIDOC
## strip_tags()

### Description
Removes HTML and PHP tags from a string, optionally keeping specific tags. Use this to strip unwanted markup from user input.

### Method
Function

### Signature
`strip_tags(string $string, array $allowed_tags = []): string`

### Parameters
- **$string** (string) - Required - The input string to strip tags from.
- **$allowed_tags** (array) - Optional - An array of tag names to keep. Defaults to empty (strip all tags).

### Example
```php
use Psl\Html;

$stripped = Html\strip_tags('<p>Hello <b>world</b></p>', ['b']);
// Output: Hello <b>world</b>
```

### Notes
- Wraps PHP's strip_tags function.
```

--------------------------------

### encode_special_characters()

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/text/html.md

Converts only the special characters (&, ", ', <, >) to HTML entities. This is the safer default for preventing XSS while keeping non-special characters readable.

```APIDOC
## encode_special_characters()

### Description
Converts only the special characters (&, ", ', <, >) to HTML entities. Use this when building HTML output from user input to prevent XSS.

### Method
Function

### Signature
`encode_special_characters(string $string, bool $double_encoding = true, Encoding $encoding = Encoding::UTF_8): string`

### Parameters
- **$string** (string) - Required - The input string to encode.
- **$double_encoding** (bool) - Optional - Whether to encode existing HTML entities. Defaults to true.
- **$encoding** (Encoding) - Optional - The character set to use. Defaults to UTF-8.

### Example
```php
use Psl\Html;

$encoded = Html\encode_special_characters('<p>Hello & welcome</p>');
// Output: &lt;p&gt;Hello &amp; welcome&lt;/p&gt;
```

### Notes
- Wraps PHP's htmlspecialchars function.
- Recommended for user input to prevent XSS.
```

--------------------------------

### Error paths for nested validation failures

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/types/type.md

When validation fails on nested structures, the error message includes the exact path to the failing value. This makes debugging validation failures in deeply nested data structures straightforward.

```php
@example('types/type-error-paths.php')
```

--------------------------------

### Handling error output with ErrorOutputBehavior

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/io/shell.md

By default, stderr is discarded. The ErrorOutputBehavior enum controls how stderr is handled relative to stdout.

```php
@example('io/shell-error-output.php')
```

--------------------------------

### Type-safe data validation with Psl\Type

Source: https://github.com/php-standard-library/php-standard-library/blob/next/README.md

Define a shape type to validate and coerce untrusted data. Uses composable type combinators like shape, non_empty_string, positive_int, and vec. The coerce method returns a typed array.

```php
use Psl\Type;

$userType = Type\shape([
    'name' => Type\non_empty_string(),
    'age'  => Type\positive_int(),
    'tags' => Type\vec(Type\string()),
]);

$user = $userType->coerce($untrustedInput);
// array{name: non-empty-string, age: positive-int, tags: list<string>}
```

--------------------------------

### JSON decoding with json_decoded()

Source: https://github.com/php-standard-library/php-standard-library/blob/next/docs/content/types/type.md

Use `json_decoded()` to handle fields that may contain JSON-encoded strings. If the value already matches the inner type, it passes through; if it's a string, it's JSON-decoded and coerced through the inner type. Useful for database columns storing JSON.

```php
@example('types/type-json-decoded.php')
```
Tokens:
Raw