# PSL - PHP Standard Library

A standard library for PHP, inspired by [hhvm/hsl](https://github.com/hhvm/hsl). Provides a consistent, centralized, well-typed set of APIs covering async, collections, networking, I/O, cryptography, terminal UI, and more - replacing PHP functions and primitives with safer, async-ready alternatives that error predictably.

## Installation

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

Each component is also available as a standalone package (e.g. `composer require php-standard-library/type`).

## Components

### Basics

- [Dict](dict/index.md) — The Dict component provides functions for creating and transforming associative arrays (array<Tk,...
- [Foundation](foundation/index.md) — The Foundation package provides the base exceptions, Ref, and invariant() utilities used across a...
- [Fun](fun/index.md) — The Fun component provides functional programming utilities for composing, decorating, and contro...
- [Iter](iter/index.md) — The Iter component provides utility functions for inspecting and reducing iterables. Unlike Vec a...
- [Math](math/index.md) — The Math component provides mathematical functions with strict typing and predictable error handl...
- [Str](str/index.md) — The Str component provides Unicode-aware string functions that replace PHP's mb_* and standard st...
- [Vec](vec/index.md) — The Vec component provides functions for creating and transforming sequential, 0-indexed arrays (...

### Types & Error Handling

- [Comparison](comparison/index.md) — The Comparison component provides interfaces and functions for comparing values in a type-safe, c...
- [Default](default/index.md) — The Default component introduces a uniform approach for classes within PSL to provide and utilize...
- [EitherOrBoth](either-or-both/index.md) — Unlike Either (which carries a loose "one vs the other" convention where Right is the happy path)...
- [Either](either/index.md) — The Either component represents a value that is one of two possible types: Left or Right. Unlike ...
- [Option](option/index.md) — The Option component represents a value that may or may not be present. It replaces nullable type...
- [Result](result/index.md) — The Result component represents a computation that either succeeded or failed. Instead of letting...
- [Type](type/index.md) — The Type component provides a set of functions to ensure that a given value is of a specific type...

### Async

- [Async](async/index.md) — The Async component brings concurrency into PHP using cooperative multitasking.
- [Channel](channel/index.md) — The Channel component provides message-passing channels for async communication, inspired by Go's...
- [Promise](promise/index.md) — The Promise component provides a promise interface for deferred computations. A promise represent...

### Collections

- [Collection](collection/index.md) — The Collection component provides generic, object-oriented collection types as an alternative to ...
- [DataStructure](data-structure/index.md) — The DataStructure component provides three classic data structures: Queue (FIFO), Stack (LIFO), a...
- [Graph](graph/index.md) — The Graph component provides immutable graph data structures and algorithms for working with dire...
- [Range](range/index.md) — The Range component provides a way to create a range of integer values.
- [Tree](tree/index.md) — The Tree component provides immutable tree data structures and operations for hierarchical data m...

### Text & Encoding

- [Binary](binary/index.md) — The Binary component provides typed functions and classes for encoding and decoding binary data, ...
- [Encoding](encoding/index.md) — The Encoding component provides functions for encoding and decoding binary data to and from text-...
- [Html](html/index.md) — The Html component provides functions for encoding, decoding, and stripping HTML entities. It wra...
- [Json](json/index.md) — The Json component provides JSON encoding and decoding that throws typed exceptions instead of re...
- [Punycode](punycode/index.md) — The Punycode component provides RFC 3492 Punycode encoding and decoding, the standard algorithm f...
- [Regex](regex/index.md) — The Regex component provides type-safe regular expression functions. PHP's preg_* functions retur...

### I/O

- [compression](compression/index.md) — The Compression component provides streaming compression and decompression abstractions for IO ha...
- [File](file/index.md) — The File component provides typed file handles for reading and writing files. It builds on the IO...
- [Filesystem](filesystem/index.md) — The Filesystem component provides type-safe functions for common file system operations. It repla...
- [IO](io/index.md) — The IO component provides handle-based I/O abstractions. Instead of reaching for global functions...
- [Process](process/index.md) — The Process component provides a typed, non-blocking API for spawning and managing child processe...
- [Shell](shell/index.md) — The Shell component provides a single function, Shell\execute(), for running external commands an...

### Identifiers

- [CIDR](cidr/index.md) — The CIDR component provides utilities for working with CIDR (Classless Inter-Domain Routing) nota...
- [IP](ip/index.md) — The IP component provides an immutable, binary-backed value object for working with IPv4 and IPv6...
- [IRI](iri/index.md) — The IRI component provides RFC 3987 compliant Internationalized Resource Identifier parsing with ...
- [URI](uri/index.md) — The URI component provides RFC 3986 compliant parsing, normalization, reference resolution, and R...
- [URL](url/index.md) — The URL component provides a strict URL type that guarantees a scheme and authority are always pr...

### Networking

- [Network](network/index.md) — The Network component defines the shared interfaces and types used by all networking components (...
- [Socks](socks/index.md) — The Socks component provides a SOCKS5 proxy connector that tunnels TCP connections through a SOCK...
- [TCP](tcp/index.md) — The TCP component provides a non-blocking API for TCP client and server connections, built on top...
- [TLS](tls/index.md) — The TLS component provides a transport-agnostic API for TLS encryption. It operates on Network\St...
- [UDP](udp/index.md) — The UDP component provides a non-blocking API for sending and receiving datagrams over UDP.
- [Unix](unix/index.md) — The Unix component provides a non-blocking API for Unix domain socket connections, built on top o...

### Protocols

- [DNS](dns/index.md) — The DNS component provides async DNS resolution with connection pooling, EDNS0, DNS-over-TLS, DNS...
- [DNSSEC](dnssec/index.md) — The DNSSEC component adds full DNSSEC validation to DNS resolution. It is a standalone package (p...
- [H2](h2/index.md) — The H2 component implements the HTTP/2 binary framing protocol (RFC 9113) on top of PSL's IO hand...
- [HPACK](hpack/index.md) — The HPACK component implements RFC 7541 header compression for HTTP/2. It provides an Encoder and...
- [HTTP Client](http-client/index.md) — The HTTP Client component provides an async HTTP client with connection pooling, HTTP/2 multiplex...
- [HTTP Message](http-message/index.md) — The HTTP Message component provides version-agnostic HTTP message abstractions. Requests, respons...
- [Message](message/index.md) — The Message component implements RFC 5322 Internet Message construction, parsing, and serializati...
- [MIME](mime/index.md) — The MIME component implements the Multipurpose Internet Mail Extensions (RFC 2045-2049) and relat...
- [SMTP](smtp/index.md) — The SMTP component implements an RFC 5321 SMTP client with connection pooling, TLS, authenticatio...

### Terminal

- [Ansi](ansi/index.md) — The Ansi component provides pure functions for constructing ANSI escape sequences -- text styling...
- [Terminal](terminal/index.md) — The Terminal component provides a full-featured TUI (Terminal User Interface) framework built on ...

### Security

- [Crypto](crypto/index.md) — The Crypto component provides a comprehensive cryptography toolkit built on libsodium and OpenSSL...
- [Hash](hash/index.md) — The Hash component provides cryptographic and non-cryptographic hashing through a type-safe API. ...
- [Password](password/index.md) — The Password component provides secure password hashing and verification. It wraps PHP's password...
- [PseudoRandom](pseudo-random/index.md) — The PseudoRandom component provides fast pseudo-random number generation using PHP's Mersenne Twi...
- [RandomSequence](random-sequence/index.md) — The RandomSequence component provides object-oriented random number sequences behind a common Seq...
- [SecureRandom](secure-random/index.md) — The SecureRandom component provides cryptographically secure random data generation. It wraps PHP...

### System

- [DateTime](date-time/index.md) — The DateTime component provides immutable, timezone-aware date and time types. It replaces PHP's ...
- [Env](env/index.md) — The Env component provides functions for inspecting and modifying the process environment. It cov...
- [Locale](locale/index.md) — The Locale component provides a backed enum containing 700+ locale identifiers (such as en_US, fr...
- [OS](os/index.md) — The OS component provides type-safe operating system detection. Instead of comparing raw strings ...
- [Runtime](runtime/index.md) — The Runtime component provides introspection into the PHP runtime environment. It exposes version...

### Other

- [Cache](cache/index.md) — The Cache component provides an async-safe in-memory LRU cache with per-key atomicity. It prevent...
- [Class](class/index.md) — The Class component provides type-safe wrappers around PHP's built-in class reflection and existe...
- [Interface](interface/index.md) — The Interface component provides type-safe wrappers around PHP's built-in interface reflection an...
- [Interoperability](interoperability/index.md) — The Interoperability component provides a set of interfaces for converting between PSL types and ...
- [Observer](observer/index.md) — The Observer component provides two interfaces for the classic Observer design pattern. A subject...
- [Trait](trait/index.md) — The Trait component provides type-safe wrappers around PHP's built-in trait reflection and existe...

### Tools

- [Detect Packages](detect-packages/index.md) — The detect-packages command scans PHP source directories for PSL namespace usage and reports whic...