====== PHP RFC: Improve Type Conversion Inconsistencies ======

  * Version: 1.0
  * Date: 2025-10-28
  * Author: Alexandre Daubois <alexandredaubois@php.net>, Nicolas Grekas <nicolasgrekas@php.net>
  * Status: Under discussion
  * Target Version: PHP 8.6 (deprecation), PHP 9.0 (TypeError and Stringable support)
  * Implementation: TBD

===== Introduction =====

PHP's type conversion system contains inconsistencies that make behavior unpredictable across different mechanisms. This RFC addresses two related issues:

**Issue 1: Fuzzy Casts**

PHP's explicit type casting operators (<php>(int)</php>, <php>(float)</php>, <php>(bool)</php>, <php>(string)</php>, <php>(array)</php>, <php>(object)</php>) have historically been maximally permissive, performing lossy conversions when the input value cannot be fully represented in the target type. Fuzzy casts are conversions where information is lost or transformed in unexpected ways:

<PHP>
<?php
// Partial string conversions - only a portion of the string is used
(int) "123abc";      // Returns 123 (discards "abc")
(float) "12.34foo";  // Returns 12.34 (discards "foo")

// Scalar to object casts - creates arbitrary structure
(object) 42;         // Returns stdClass Object ( [scalar] => 42 )
(object) "hello";    // Returns stdClass Object ( [scalar] => "hello" )
?>
</PHP>

**Issue 2: Stringable Objects in Strict Mode**

Another inconsistency exists with Stringable objects and string parameters in strict mode:

<PHP>
<?php
// Non-strict mode
function process(string $value): void { }

$obj = new class implements Stringable {
    public function __toString(): string { return "hello"; }
};

process($obj);  // Works

// Strict mode
declare(strict_types=1);
process($obj);  // TypeError: Argument must be of type string, object given
?>
</PHP>

The <php>Stringable</php> interface was introduced in PHP 8.0 to explicitly declare that an object can be safely converted to a string. Strict mode rejecting this explicit contract is inconsistent with its purpose.

**Proposed Changes**

This RFC proposes:
1. Deprecate fuzzy casts in PHP 8.6 and make them throw <php>TypeError</php> in PHP 9.0, aligning explicit cast behavior with the validation rules already used for typed function parameters in non-strict mode
2. Allow Stringable objects for string parameters in strict mode starting in PHP 9.0, respecting the explicit conversion contract

**Important:** For fuzzy casts, this RFC specifically targets **partial string conversions** and **scalar-to-object casts**. Well-formed numeric strings (e.g., <php>"123"</php>, <php>"12.5"</php>) will continue to work as expected.

===== Motivation =====

==== Fuzzy Casts ====

Since PHP 7.0, the language has supported type declarations and <php>TypeError</php> exceptions, yet explicit cast operators have retained their legacy permissive behavior from PHP 3/4. This creates a significant inconsistency:

<PHP>
<?php
// Function parameter - rejects fuzzy conversions
function process(int $value): void { }
process("123abc");  // TypeError

// Explicit cast - silently truncates
$result = (int) "123abc";  // 123 (no error)
?>
</PHP>

This inconsistency is problematic because:

  * **Silent data loss**: Corrupted values like <php>"19.99corrupted"</php> are silently accepted, masking bugs
  * **Unexpected behavior**: Developers expect either full conversion or failure, not partial conversion
  * **Inconsistent validation**: Function parameters and casts should follow the same rules

==== Stringable Objects in Strict Mode ====

The <php>Stringable</php> interface provides an explicit contract for safe string conversion. However, strict mode rejects these explicitly declared safe conversions (see Introduction for example).

This is inconsistent because:

  * The explicit contracts are ignored
  * Strict mode is misaligned as it should reject *unsafe* conversions, not explicitly declared safe ones
  * Non-strict mode works, this creates confusion

===== Proposal =====

This RFC proposes two changes to improve type conversion consistency:

==== Fuzzy Scalar Casts ====

=== Phase 1: PHP 8.6 - Deprecation Notice ===

In PHP 8.6, fuzzy casts will emit an <php>E_DEPRECATED</php> notice when a string value can only be **partially** converted to the target scalar type, or when a scalar is cast to <php>(object)</php>:

<PHP>
<?php
// PHP 8.6 behavior

// Valid conversions - no change
(int) "123";       // 123 (no notice)
(int) "  42  ";    // 42 (whitespace is acceptable)
(float) "12.5";    // 12.5 (no notice)
(float) "1e3";     // 1000.0 (scientific notation is acceptable)

// Fuzzy casts - emit E_DEPRECATED
(int) "123abc";    // Deprecated: Partial string conversion from "123abc" to int
                   // Returns: 123

(float) "12.5foo"; // Deprecated: Partial string conversion from "12.5foo" to float
                   // Returns: 12.5

// Scalar to object casts - emit E_DEPRECATED (fuzzy cast)
(object) 42;       // Deprecated: Conversion from int to object is deprecated
                   // Returns: stdClass Object ( [scalar] => 42 )

(object) "hello";  // Deprecated: Conversion from string to object is deprecated
                   // Returns: stdClass Object ( [scalar] => "hello" )
?>
</PHP>

The deprecation notice will clearly indicate the original value, the target type, and the nature of the problematic conversion, and that these conversions will become errors in PHP 9.0.

=== Phase 2: PHP 9.0 - TypeError ===

In PHP 9.0, fuzzy casts will throw a <php>TypeError</php> instead of performing conversion:

<PHP>
<?php
// PHP 9.0 behavior

// Valid conversions - no change
(int) "123";       // 123
(float) "12.5";    // 12.5

// Fuzzy casts - throw TypeError
(int) "123abc";    // TypeError: Cannot convert string "123abc" to int: trailing data
(float) "12.5foo"; // TypeError: Cannot convert string "12.5foo" to float: trailing data
(object) 42;       // TypeError: Cannot convert int to object
(object) "hello";  // TypeError: Cannot convert string to object
?>
</PHP>

This aligns explicit cast behavior with the validation rules already used for typed function parameters in non-strict mode.

==== Stringable Objects in Strict Mode ====

=== PHP 8.6 ===

No changes to Stringable behavior. Strict mode continues to throw <php>TypeError</php> when Stringable objects are passed to string parameters.

=== PHP 9.0 ===

Strict mode will accept Stringable objects for string parameters, converting them via <php>__toString()</php> just like in non-strict mode:

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

function greet(string $name): string {
    return "Hello, $name!";
}

$user = new class implements Stringable {
    public function __toString(): string { return "John"; }
};

// PHP 8.x: TypeError
// PHP 9.0: Works - returns "Hello, John!"
greet($user);
?>
</PHP>

===== Scope and Affected Cases =====

**Important:** Apart from <php>Stringable</php>, the proposed behavior aligns with the **existing validation rules** used by typed function parameters in **non-strict mode**. This RFC does not introduce new rules—it applies the same well-established rules that have been used for function parameters since PHP 7.0.

A fuzzy cast occurs when:

  - **Partial string conversions**: The input is a **string** containing a valid numeric prefix **followed by non-numeric/non-whitespace characters**, and the cast operator uses only the valid prefix and discards the trailing data
  - **Scalar to object casts**: A scalar value (<php>int</php>, <php>float</php>, <php>string</php>, or <php>bool</php>) is cast to <php>(object)</php>, creating a <php>stdClass</php> with an arbitrary <php>scalar</php> property

^ Input Type ^ Cast ^ Current Behavior ^ PHP 8.6 ^ PHP 9.0 ^
| String (fully numeric) | <php>(int) "123"</php> | 123 | 123 | 123 |
| String (whitespace + numeric) | <php>(int) "  42  "</php> | 42 | 42 | 42 |
| String (fuzzy) | <php>(int) "123abc"</php> | 123 | E_DEPRECATED + 123 | TypeError |
| String (fuzzy) | <php>(float) "12.5foo"</php> | 12.5 | E_DEPRECATED + 12.5 | TypeError |
| String (non-numeric) | <php>(int) "abc"</php> | 0 | E_DEPRECATED + 0 | TypeError |
| Scalar (fuzzy) | <php>(object) 42</php> | <php>stdClass</php> with <php>scalar</php> property | E_DEPRECATED + <php>stdClass</php> | TypeError |
| Scalar (fuzzy) | <php>(object) "hello"</php> | <php>stdClass</php> with <php>scalar</php> property | E_DEPRECATED + <php>stdClass</php> | TypeError |
| Array | <php>(object) ['a' => 1]</php> | <php>stdClass</php> with properties | <php>stdClass</php> (not affected) | <php>stdClass</php> (not affected) |
| Non-string | <php>(int) 12.5</php> | 12 | 12 (E_DEPRECATED for precision loss) | 12 (may throw in future) |
| Boolean string | <php>(bool) "false"</php> | true | true (not affected) | true (not affected) |
| Stringable (non-strict) | <php>function(string $s)</php> with Stringable | Accepts (converts via <php>__toString</php>) | Accepts (converts) | Accepts (converts) |
| Stringable (strict) | <php>function(string $s)</php> with Stringable in strict mode | TypeError | TypeError | Accepts (converts via <php>__toString</php>) |

**Note on boolean casts:** Boolean casts are not affected by this RFC. They use truthiness rules rather than numeric parsing, so they evaluate the entire value rather than performing partial conversion.

Developers are encouraged to use explicit comparisons for clarity:

<PHP>
<?php
// Instead of this:
$enabled = (bool) $value;

// Prefer explicit comparison:
$enabled = $value !== "" && $value !== "0" && $value !== false && $value !== null;

// Or for boolean strings:
$enabled = filter_var($value, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE);
?>
</PHP>

===== Backward Compatibility Impact =====

This RFC introduces **backward incompatible changes** that will affect existing code relying on fuzzy cast behavior and implicit use of <php>Stringable</php> for string parameters in strict mode.

==== Fuzzy Casts ====

=== Potential Impact ===

Code that currently relies on fuzzy casts will need to be updated. Common patterns that will be affected include:

<PHP>
<?php
// Database/API responses with trailing whitespace or corruption
$age = (int) $row['age'];  // If $row['age'] is "25\0" or "25 years"

// User input with mixed content
$quantity = (int) $_POST['quantity'];  // If input is "10 items"

// Configuration values with units
$timeout = (int) $config['timeout'];  // If config is "30s" or "30 seconds"

// Scalar to object wrapping
$wrapped = (object) $someScalar;  // Creates stdClass with 'scalar' property
?>
</PHP>

=== Migration Path ===

Developers have several options to migrate away from fuzzy casts:

**Option 1: Validate before casting**

<PHP>
<?php
// Explicit validation using is_numeric()
if (!is_numeric($value)) {
    throw new ValueError("Invalid numeric value: $value");
}
$result = (int) $value;
?>
</PHP>

**Option 2: Use filter functions**

<PHP>
<?php
// Validate and convert
$result = filter_var($value, FILTER_VALIDATE_INT);
if ($result === false) {
    throw new ValueError("Invalid integer: $value");
}

// Sanitize before converting (explicit intent)
$sanitized = filter_var($value, FILTER_SANITIZE_NUMBER_INT);
$result = (int) $sanitized;
?>
</PHP>

**Option 3: For scalar to object casts**

Create a proper object structure or use an array:

<PHP>
<?php
// Instead of:
$obj = (object) 42;

// Option A: Create proper object structure
$obj = new stdClass();
$obj->value = 42;

// Option B: Or create a proper class
class ValueWrapper {
    public function __construct(public mixed $value) {}
}
$obj = new ValueWrapper(42);

// Option C: Use an array if you need a key-value structure
$data = ['value' => 42];
// Or if object is required:
$obj = (object) ['value' => 42];

// Option D: Question whether object wrapping is necessary
// Often, the scalar value can be used directly
processValue(42);  // Instead of processObject((object) 42)
?>
</PHP>

=== Detection and Tooling ===

To help developers identify fuzzy casts in their codebase:

  * **PHP 8.6**: The deprecation notices will appear in error logs, making it easy to find affected code
  * **Static analysis tools**: Tools like PHPStan and Psalm can be updated to detect potential fuzzy casts
  * **Code review**: Search for cast patterns like <php>(int)</php>, <php>(float)</php>, <php>(object)</php> applied to variables that may contain malformed data

==== Stringable Objects in Strict Mode ====

When using strict mode, code relying on the fact that providing a <php>Stringable</php> to a string parameter without the <php>(string)</php> explicit cast will throw won't be working as expected.

===== Rationale =====

Both changes in this RFC address the same fundamental issue: **PHP's type conversion behavior is inconsistent across different mechanisms**.

**Fuzzy casts** are more permissive than function parameter validation, silently accepting malformed data that would be rejected as function arguments. This violates the principle of least surprise and can mask bugs.

**Stringable in strict mode** demonstrates the opposite problem: strict mode rejects explicitly declared safe conversions. The <php>Stringable</php> interface exists specifically to declare that an object can be safely converted to a string, yet strict mode ignores this contract.

Together, these changes move PHP toward **consistent, predictable type conversion**.

This RFC uses <php>TypeError</php> for consistency with function parameter type checking, which already uses <php>TypeError</php> for invalid conversions.

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

  * **PHP 8.6**: Emit <php>E_DEPRECATED</php> for fuzzy casts (Stringable behavior unchanged)
  * **PHP 9.0**: Throw <php>TypeError</php> for fuzzy casts, accept Stringable objects in strict mode for string parameters

===== RFC Impact =====

==== To the Ecosystem ====

A first patch has been created to php-src to test the new rules against the Symfony codebase. Only a few dozens of deprecations were raised across the whole codebase of components, built-in bundles and bridges.

Symfony doesn't use strict types in its codebase, so no impact is expected from the Stringable change in this project.

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

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

<doodle title="Accept type conversion consistency improvements (fuzzy cast deprecation + Stringable in strict mode) for PHP 8.6/9.0?" voteType="single" closed="false">
   * Yes
   * No
   * Abstain
</doodle>

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

===== References =====

  * RFC: Null Coercion Consistency: https://wiki.php.net/rfc/null_coercion_consistency
  * PHP Type Juggling Documentation: https://www.php.net/manual/en/language.types.type-juggling.php
  * PHP Type Declarations: https://www.php.net/manual/en/language.types.declarations.php
  * PHP filter_var() Documentation: https://www.php.net/manual/en/function.filter-var.php
  * RFC: Deprecate implicit float to int conversions: https://wiki.php.net/rfc/implicit-float-int-deprecate
  * Discussion thread: [TBD]