====== PHP RFC: Nullable and Non-Nullable Cast Operators ======

  * Version: 1.0
  * Date: 2025-10-??
  * Author: Alexandre Daubois <alexandredaubois@php.net>, Nicolas Grekas <nicolasgrekas@php.net>
  * Status: Draft
  * Target Version: PHP 8.6
  * Implementation: TBD

===== Introduction =====

PHP's type casting operators currently almost always convert values to the target type even if it cannot be represented from the original value.
For example <php>null</php> is evaluated in the following way: <php>(int) null</php> evaluates to <php>0</php>, <php>(string) null</php> evaluates to <php>""</php>, and <php>(bool) null</php> evaluates to <php>false</php>. While this behavior is consistent with PHP's loose typing philosophy, it can mask bugs when <php>null</php> should be treated as a distinct absence of value.

The "almost always" caveat is because non-Stringable objects when being cast to string with <php>(string)</php> will throw a <php>TypeError</php> instead of returning an empty string.

This RFC proposes two new cast operator variants that provide explicit control over null handling **and stricter validation** than traditional casts:

  * **Nullable cast** <php>(?type)</php>: Allows <php>null</php> to pass through unchanged; non-null values are validated and coerced using weak mode rules
  * **Non-null cast** <php>(!type)</php>: Throws <php>TypeError</php> if the value is <php>null</php> or if it fails weak mode validation; valid non-null values are coerced to the target type

Unlike traditional casts that silently truncate malformed values (e.g., <php>(int) "123aze"</php> returns <php>123</php>), these operators reject invalid input while still allowing safe conversions (e.g., <php>(!int) "123"</php> works, but <php>(!int) "123aze"</php> throws).

These operators complement PHP's existing nullable type declarations (<php>?int</php>, <php>?string</php>, etc.) by providing the same semantics at the cast level, with the added benefit of input validation.

===== Current Behavior =====

Currently, PHP casts coerce <php>null</php> to type-specific default values:

<PHP>
<?php
var_dump((int) null);     // int(0)
var_dump((float) null);   // float(0)
var_dump((string) null);  // string(0) ""
var_dump((bool) null);    // bool(false)
var_dump((array) null);   // array(0) {}
?>
</PHP>

This behavior applies regardless of the <php>strict_types</php> declaration:

<PHP>
<?php
declare(strict_types=1);

var_dump((int) null);     // Still int(0)
?>
</PHP>

The <php>strict_types</php> directive only affects function parameter and return type checking, not explicit casts.

===== Proposal =====

This RFC introduces two new cast operator variants:

==== Nullable Cast: (?type) ====

The nullable cast allows <php>null</php> to pass through without coercion. If the value is not <php>null</php>, it is coerced to the specified type using **weak mode function parameter coercion** (stricter than traditional casts).

<PHP>
<?php
(?int) $value      // null -> null, others -> int
(?float) $value    // null -> null, others -> float
(?string) $value   // null -> null, others -> string
(?bool) $value     // null -> null, others -> bool
(?array) $value    // null -> null, others -> array
?>
</PHP>

==== Non-Null Cast: (!type) ====

The non-null cast throws a <php>TypeError</php> in two scenarios:

  * **If the value is null**: Rejected because null is not allowed
  * **If weak mode validation fails**: Rejected for malformed values (e.g., <php>"123aze"</php> cannot be converted to int)

Valid non-null values are coerced to the specified type using **weak mode function parameter coercion** (stricter than traditional casts).

<PHP>
<?php
(!int) $value      // null -> TypeError, "123" -> 123, "123aze" -> TypeError
(!float) $value    // null -> TypeError, "12.5" -> 12.5, "abc" -> TypeError
(!string) $value   // null -> TypeError, 123 -> "123", non-Stringable object -> TypeError
(!bool) $value     // null -> TypeError, valid values -> bool
(!array) $value    // null -> TypeError, valid values -> array
?>
</PHP>

===== Type Coercion Semantics =====

The nullable and non-null cast operators use **weak mode function parameter coercion rules**, not the permissive behavior of traditional explicit casts.

==== Mental Model ====

These operators behave exactly as if passing a value through a typed function parameter **in weak mode** (without <php>strict_types</php>):

<PHP>
<?php
// (!type) $value is equivalent to calling a function
// with typed parameter in weak mode:
function cast(type $v): type { return $v; }
$result = cast($value);  // weak mode behavior

// (?type) $value is equivalent to:
function cast(?type $v): ?type { return $v; }
$result = cast($value);  // weak mode behavior
?>
</PHP>

This means the new operators **always** use weak mode validation rules, even when <php>strict_types=1</php> is declared (see the "Interaction with strict_types" section for details).

**Important:** Weak mode validation can still throw <php>TypeError</php>. The function parameter analogy means both the null handling AND the validation behavior match typed parameters - which means <php>TypeError</php> is thrown for both <php>null</php> (when non-nullable) and invalid values that cannot be coerced.

==== Key Difference from Traditional Casts ====

Traditional casts like <php>(int)</php> are **maximally permissive** and perform lossy conversions:

<PHP>
<?php
// Traditional cast - silently truncates
(int) "123aze";  // 123 (no error, data loss)

// Function parameter in weak mode - validates input
function test(int $i): int { return $i; }
test("123aze");  // TypeError: Cannot convert string to int

// New non-null cast - matches function parameter behavior
(!int) "123aze";  // TypeError: Cannot convert string to int
?>
</PHP>

==== Validation Behavior ====

The new operators validate inputs according to weak mode type juggling rules:

<PHP>
<?php
// Valid numeric strings - accepted
(!int) "123";      // 123
(!float) "12.5";   // 12.5

// Malformed numeric strings - rejected
(!int) "123aze";   // TypeError
(!int) "abc";      // TypeError

// null handling
(!int) null;       // TypeError
(?int) null;       // null

// Nullable cast still validates non-null values
(?int) "123";      // 123
(?int) "123aze";   // TypeError (validates when non-null)
?>
</PHP>

This behavior ensures that the new cast operators are **stricter** and **safer** than traditional casts while remaining **more convenient** than manual validation.

===== Syntax and Examples =====

==== Nullable Cast Examples ====

<PHP>
<?php
// Database value that might be NULL
$age = (?int) $row['age'];  // null stays null, "25" becomes 25

// Optional query parameter
$limit = (?int) ($_GET['limit'] ?? null);  // null if not set
?>
</PHP>

==== Non-Null Cast Examples ====

<PHP>
<?php
// Required field that must not be null
$userId = (!int) $data['user_id'];  // Throws if null or malformed

// API response validation
$response = json_decode($json, true);
$id = (!int) $response['id'];  // Throws if null or malformed
?>
</PHP>

==== Comparison with Current Behavior ====

<PHP>
<?php
// ===== NULL HANDLING =====

$value = null;
$result = (int) $value;  // 0 - may hide a bug

// Nullable cast - null stays null
$result = (?int) $value;  // null - preserves absence

// Non-null cast - null throws
$result = (!int) $value;  // TypeError - fails fast

// ===== MALFORMED STRING HANDLING =====

// Traditional cast - silently truncates (lossy)
$value = "123aze";
$result = (int) $value;  // 123 - data loss, no error

// New operators - reject invalid input (safe)
$result = (!int) $value;  // TypeError - cannot convert
$result = (?int) $value;  // TypeError - validates even when nullable

// ===== VALID STRING HANDLING =====

// All three work the same for valid numeric strings
$value = "123";
$result = (int) $value;   // 123
$result = (!int) $value;  // 123
$result = (?int) $value;  // 123
?>
</PHP>

The key difference: traditional casts are **maximally permissive** (silent data loss), while the new operators use **weak mode validation** (reject malformed input).

==== Behavior Comparison Table ====

^ Input Value ^ <php>(int)</php> ^ <php>(!int)</php> ^ <php>(?int)</php> ^ Function param <php>int</php> (weak mode) ^
| <php>"123"</php> | <php>123</php> | <php>123</php> | <php>123</php> | <php>123</php> |
| <php>"123aze"</php> | <php>123</php> ⚠️ | TypeError | TypeError | TypeError |
| <php>"abc"</php> | <php>0</php> ⚠️ | TypeError | TypeError | TypeError |
| <php>null</php> | <php>0</php> ⚠️ | TypeError | <php>null</php> | TypeError |
| <php>123</php> | <php>123</php> | <php>123</php> | <php>123</php> | <php>123</php> |

⚠️ = potentially unsafe (silent coercion/data loss)

The new operators (<php>!type</php> and <php>?type</php>) align with function parameter behavior, providing safer and more predictable type coercion.

===== Interaction with strict_types =====

These cast operators **always use weak mode coercion rules**, regardless of the <php>strict_types</php> setting:

<PHP>
<?php
declare(strict_types=1);

// Valid numeric strings - coerced in both strict and weak modes
(?int) "123";      // 123 (allowed)
(!int) "123";      // 123 (allowed)

// Malformed strings - rejected in both strict and weak modes
(?int) "123aze";   // TypeError (rejected)
(!int) "123aze";   // TypeError (rejected)

// null handling - consistent in both modes
(?int) null;       // null (allowed)
(!int) null;       // TypeError (rejected)
?>
</PHP>

The behavior is uniform because these operators **always use weak mode coercion rules**, even when <php>strict_types=1</php> is declared.

This differs from function parameters, which **do** respect <php>strict_types</php>:

<PHP>
<?php
declare(strict_types=1);

// Function parameter - respects strict_types (rejects string)
function test(int $i): int { return $i; }
test("123");       // TypeError in strict mode, allowed in weak mode

// New operators - always use weak mode rules (allows valid strings)
(!int) "123";      // 123 (allowed regardless of strict_types)
(!int) "123aze";   // TypeError (rejected regardless of strict_types)
?>
</PHP>

The new operators provide a **middle ground**: stricter than traditional casts (validate input), but more permissive than strict mode (allow valid numeric strings).

==== Comparison with Traditional Casts ====

Traditional casts like <php>(int)</php> are always **maximally permissive** regardless of <php>strict_types</php>:

<PHP>
<?php
declare(strict_types=1);

// Traditional cast - always permissive, even with strict_types
(int) "123aze";    // 123 (no error, data loss)

// New operators - always validate, regardless of strict_types
(!int) "123aze";   // TypeError (rejects malformed input)
?>
</PHP>

===== Use Cases =====

==== 1. Database NULL Handling ====

<PHP>
<?php
// Traditional approach - ambiguous
$age = (int) $row['age'];  // NULL becomes 0, but 0 might be valid

// With nullable cast - explicit
$age = (?int) $row['age'];  // NULL stays null, distinguishable from 0
if ($age === null) {
    echo "Age not provided";
} else {
    echo "Age: $age";
}
?>
</PHP>

==== 2. API Response Processing ====

<PHP>
<?php
$json = '{"count": null, "total": 100}';
$data = json_decode($json, true);

// Non-null cast for required fields
$total = (!int) $data['total'];  // 100

// Nullable cast for optional fields
$count = (?int) $data['count'];  // null
$count = $count ?? 0;  // Default to 0 if null
?>
</PHP>

==== 3. Form Input Validation ====

<PHP>
<?php
// Required field
$quantity = (!int) ($_POST['quantity'] ?? null);  // Throws TypeError if missing

// Optional field
$discount = (?float) ($_POST['discount'] ?? null);  // null if missing
$discount = $discount ?? 0.0;  // Apply default
?>
</PHP>

==== 4. Type-Safe Wrapper Functions ====

<PHP>
<?php
function getConfigInt(string $key): ?int {
    $value = getenv($key);  // Returns string|false
    if ($value === false) {
        return null;  // Config not set
    }
    return (!int) $value;  // Validate and convert to int
}

function requireConfigInt(string $key): int {
    $value = getenv($key);  // Returns string|false
    if ($value === false) {
        throw new RuntimeException("Missing config: $key");
    }
    return (!int) $value;  // Validate and convert to int
}
?>
</PHP>

==== 5. Reducing Boilerplate ====

<PHP>
<?php
// Before - verbose null checking
$value = $input['value'] ?? null;
if ($value !== null) {
    $value = (int) $value;  // Permissive, may silently truncate
}

// After - concise and validates input
$value = (?int) ($input['value'] ?? null);
?>
</PHP>

===== Comparison Table =====

^ Cast Type ^ Syntax ^ <php>null</php> Input ^ Valid String (<php>"123"</php>) ^ Malformed String (<php>"123aze"</php>) ^
| Current cast | <php>(int) $value</php> | <php>0</php> ⚠️ | <php>123</php> | <php>123</php> ⚠️ (silently truncates) |
| Nullable cast | <php>(?int) $value</php> | <php>null</php> | <php>123</php> | TypeError (validates input) |
| Non-null cast | <php>(!int) $value</php> | TypeError | <php>123</php> | TypeError (validates input) |

**Key differences:**
  * **Current casts**: Maximally permissive - never throw, may lose data
  * **New operators**: Validate input using weak mode rules - reject malformed values while accepting valid conversions

===== Supported Types =====

Both <php>?</php> and <php>!</php> operators support all existing cast types:

  * <php>(?int)</php> / <php>(!int)</php> - Integer cast
  * <php>(?float)</php> / <php>(!float)</php> - Float cast
  * <php>(?string)</php> / <php>(!string)</php> - String cast
  * <php>(?bool)</php> / <php>(!bool)</php> - Boolean cast
  * <php>(?array)</php> / <php>(!array)</php> - Array cast
  * <php>(?object)</php> / <php>(!object)</php> - Object cast

===== Backward Incompatible Changes =====

This proposal introduces new syntax and has **no backward compatibility issues**:

  * The syntax <php>(?type)</php> and <php>(!type)</php> are currently parse errors
  * No existing code uses these patterns
  * No changes to existing cast behavior
  * No impact on <php>strict_types</php> semantics

===== Proposed PHP Version =====

PHP 8.6

===== Voting Choices =====

This is a simple yes/no vote requiring a 2/3 majority.

<doodle title="Accept nullable and non-nullable cast operators for PHP 8.6?" voteType="single" closed="false">
   * Yes
   * No
</doodle>

Vote will start on [TBD] and end on [TBD].

===== References =====

  * PHP Type Declarations: https://www.php.net/manual/en/language.types.declarations.php
  * RFC: Null Coercion Consistency: https://wiki.php.net/rfc/null_coercion_consistency
  * RFC: Nullable Types: https://wiki.php.net/rfc/nullable_types
  * RFC: Safe Casting Functions (declined): https://wiki.php.net/rfc/safe_cast
  * Discussion thread: [TBD]