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

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:

(int) "42abc";     // 42 (silently ignores "abc")
(int) [];          // 0 (arrays become 0 or 1)
(bool) "false";    // true (non-empty string)
(float) "invalid"; // 0.0 (no error)

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.

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

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

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

use Ctw\Cast\Cast;

// Environment variables
$debug    = Cast::toBool($_ENV['DEBUG'] ?? 'false');
$port     = Cast::toInt($_ENV['DB_PORT'] ?? '3306');
$timeout  = Cast::toFloat($_ENV['TIMEOUT'] ?? '30.0');
$appName  = Cast::toString($_ENV['APP_NAME'] ?? '');

// GET/POST parameters
$page     = Cast::toInt($_GET['page'] ?? '1');
$limit    = Cast::toInt($_GET['limit'] ?? '10');
$active   = Cast::toBool($_POST['active'] ?? 'false');
$tags     = Cast::toArray($_POST['tags'] ?? '[]');

// Server variables
$port     = Cast::toInt($_SERVER['SERVER_PORT'] ?? '80');
$https    = Cast::toBool($_SERVER['HTTPS'] ?? 'off');

// Session data
$userId   = Cast::toInt($_SESSION['user_id'] ?? '0');
$prefs    = Cast::toArray($_SESSION['preferences'] ?? '{}');

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

use Ctw\Cast\Cast;

// Legacy database result (returns strings for all columns)
$row    = $legacyDb->fetchRow("SELECT id, price, active FROM products");
$id     = Cast::toInt($row['id']);
$price  = Cast::toFloat($row['price']);
$active = Cast::toBool($row['active']);

// Legacy configuration loader
$config     = $legacyLoader->load('app.ini');
$maxSize    = Cast::toInt($config['upload_max_size']);
$debugMode  = Cast::toBool($config['debug']);
$allowedIps = Cast::toArray($config['allowed_ips']);

// Legacy API client
$response = $legacyClient->get('/api/users');
$users    = Cast::toArray($response);
$jsonOut  = Cast::toJson($users);

// Untyped function returns
$result = some_legacy_function();
$count  = Cast::toInt($result);

• 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

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

• PHP 8.5 or higher
• strict_types enabled

Install by adding the package as a Composer requirement:

composer require ctw/ctw-cast

use Ctw\Cast\Cast;

$string = Cast::toString($value);
$int    = Cast::toInt($value);
$float  = Cast::toFloat($value);
$bool   = Cast::toBool($value);
$array  = Cast::toArray($value);
$json   = Cast::toJson($value);

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

Cast::toString(42);           // "42"
Cast::toString(true);         // "1"
Cast::toString(null);         // ""
Cast::toString([1, 2, 3]);    // ""

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

Cast::toInt("42");        // 42
Cast::toInt(3.7);         // 4 (rounded)
Cast::toInt(null);        // 0
Cast::toInt("hello");     // 0
Cast::toInt(INF);         // 0

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

Cast::toFloat("3.14");    // 3.14
Cast::toFloat(42);        // 42.0
Cast::toFloat(true);      // 1.0
Cast::toFloat("hello");   // 0.0

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

Cast::toBool("yes");   // true
Cast::toBool(0);       // false
Cast::toBool(null);    // false
Cast::toBool("maybe"); // false
Cast::toBool(42);      // false

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

Cast::toArray('{"a":1}');   // ["a" => 1]
Cast::toArray(42);          // [42]
Cast::toArray(null);        // []

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

Cast::toJson(['name' => 'John']);   // '{"name":"John"}'
Cast::toJson(true);                 // 'true'
Cast::toJson(null);                 // 'null'
Cast::toJson(INF);                  // '{}'

Default flags: JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE

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

use Ctw\Cast\Cast;

$int   = Cast::toInt($userInput);   // 0 if not castable
$str   = Cast::toString($userInput); // '' if not castable
$bool  = Cast::toBool($userInput);   // false if not castable
$float = Cast::toFloat($userInput);  // 0.0 if not castable
$arr   = Cast::toArray($userInput);  // [] if not castable
$json  = Cast::toJson($userInput);   // '{}' if not castable

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