Download the PHP package ctw/ctw-cast without Composer

Package "ctw/ctw-cast"

Type-safe, exception-free casting utility for PHP 8.5+ applications.

Introduction

Why This Library Exists

Modern PHP development with strict types (declare(strict_types=1)) demands precise type handling. However, many data sources in PHP return mixed or loosely-typed values:

• Superglobals ($_GET, $_POST, $_SERVER, $_ENV, $_COOKIE, $_SESSION) return mixed
• Environment variables via getenv() return string|false
• Legacy libraries often return untyped or loosely-typed data
• Database results may return strings for numeric columns
• Configuration files (JSON, XML, YAML, INI) parse to mixed arrays
• External APIs return decoded JSON with uncertain types

PHP's native type casting ((int), (string), etc.) is permissive and can silently produce unexpected results:

This library provides predictable, exception-free type conversions. When a value cannot be cast, a safe default is returned instead of throwing an exception, making it ideal for use in hot paths, middleware, and defensive code where unexpected input must never interrupt execution.

Default Return Values

When a value cannot be cast to the target type, the following defaults are returned:

Problems This Library Solves

1. Silent data corruption: Native casts convert invalid values in unpredictable ways; this library uses clear, documented rules
2. Inconsistent boolean handling: PHP treats "false", "no", "off" as true; this library treats them as false
3. Missing validation: No built-in way to reject non-numeric strings for number conversion
4. Overflow handling: Native (int) silently wraps on overflow; this library returns 0
5. Type ambiguity: Superglobals and legacy code return mixed, breaking strict typing

Accessing Data from Superglobals

When working with $_GET, $_POST, $_SERVER, $_ENV, and other superglobals, values are always mixed. This library ensures type-safe access:

Working with Legacy Libraries

Many older PHP libraries return untyped data. This library bridges the gap between legacy code and modern strict-typed applications:

Where to Use This Library

• Controllers: Cast request parameters to expected types
• Service layers: Ensure type safety when processing external data
• CLI commands: Parse command-line arguments and environment variables
• Data mappers: Convert database results to typed domain objects
• API handlers: Decode incoming JSON payloads
• Configuration loaders: Parse config values
• Queue workers: Process messages with mixed payloads
• Middleware: Normalize request/response data

Design Goals

1. Never throw: Every method returns a safe default when a value cannot be cast
2. Explicit behavior: Every conversion rule is documented and predictable
3. No silent corruption: Ambiguous values produce the documented default, not a guess
4. PHPStan/Psalm friendly: Return types are precise, enabling static analysis
5. Zero dependencies: No external packages required

Requirements

• PHP 8.5 or higher
• strict_types enabled

Installation

Install by adding the package as a Composer requirement:

Usage Examples

Cast::toString(mixed $value): string

Converts values to string representation with explicit, predictable rules. Returns '' for values that cannot be cast.

Cast::toInt(mixed $value): int

Converts values to integers with rounding for floats. Returns 0 for values that cannot be cast.

Cast::toFloat(mixed $value): float

Converts values to floating-point numbers. Returns 0.0 for values that cannot be cast.

Cast::toBool(mixed $value): bool

Strict boolean conversion with explicit allowed values. Returns false for values that cannot be interpreted unambiguously.

Cast::toArray(mixed $value): array

Intelligent array conversion with multiple strategies for different types. Returns [] for values that cannot be cast.

Cast::toJson(mixed $value, int $flags = ..., int $depth = 512): string

Type-safe JSON encoding. Returns '{}' when encoding fails (INF/NAN, invalid UTF-8, depth exceeded, resources, etc.).

Default flags: JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE

Error Handling

This library never throws exceptions. When a value cannot be cast to the target type, a documented default value is returned instead:

Because no exceptions are thrown, there is no need for try/catch blocks around cast calls.