Table of Contents

PHP RFC: Type casting in array destructuring expressions

Introduction

Adds the possibility to cast values while using array or list destructuring expressions.

Motivation

This proposal aims at type casts when working with data from a untyped source (eg. iterating over a CSV file, XML without a XSD defining the types of the elements). This data can often be handled in an elegant way using the existing capabilities of array destructuring. While simple variable assignments can be casted during the assignment this isn't possible during assignments via array destructuring. This proposal adds a new syntax for casting in array assignments. An example when handling a CSV file may look like:

1,Test,2002
2,Example,2010
3,Demo,2016
$handle = fopen('test.csv', 'r');
while (($data = fgetcsv($handle)) !== false) {
    [(int) $id, (string) $data, (int) $year] = $data;
    // ...
}

Proposal

While a simple variable assignment is able to execute a type cast this possibility isn't present for array or list destructuring expressions. Instead all values are assigned as they are:

// simple assignment with a cast
$now = (int) "2020";
// array destructuring without cast
[$now, $future] = ["2020", "2021"];

If the values stored in $a and $b after the array destructuring shall be casted each value must be casted manually afterwards:

[$now, $future] = ["2020", "2021"];
// either touch each value manually, use array_map or any other implementation approach to cast the values
$now = (int) $now;
$future = (int) $future;

This RFC proposes the possibility to cast the values inside the destructuring expression:

// destructuring and casting of a numeric array
[(int) $now, (int) $future] = ["2020", "2021"];
 
// destructuring and casting of an assiciative array
["now" => (int) $now, "future" => (int) $future] = ["now" => "2020", "future" => "2021"];
 
// destructuring and casting of a nested array
[
    "2020s" => [
        "now" => (int) $now,
        "future" => (int) $future
    ]
] = [
    "2020s" => [
        "now" => "2020",
        "future" => "2021"
    ],
    "2030s" => [
        "far away" => "2039"
    ]
];
 
// destructuring and casting in a foreach loop
$years = [["now", "2020"], ["future", "2021"]];
foreach ($years as [$description, (int) $year]) {
    // ...
}

While examples where all values should be casted to the identical type may be solved reasonably elegant with solutions like array_map it get's more difficult if the casts should cover various types:

// destructuring and casting with various types
["address" => (bool) $hasAddress, "floor" => (int) $floor] = ["address" => "My adress", "floor" => "3"];

All of the examples above also work with the list() syntax.

Backward Incompatible Changes

None

Proposed PHP Version(s)

Next PHP version (target 8.0)

RFC Impact

To SAPIs

None

To Existing Extensions

None

To Opcache

Implementation uses existing functions to compile the code. So existing Opcache implementations for assignments and castings are used.

Open Issues

Discussion

Regular type checks

During the discussion especially the idea of regular type checks instead of castings came up:

$years = ["2020", "2021"];
[int $now, int $future] = $years;

As a regular type check depends on the declare strict_types directive concerning the casting feature (strict_types=0 would result in an implicit cast similar to the proposed feature while strict_types=1 would result in a type error when the provided data doesn't match the type check) a regular type check covers different use cases than the proposed casting feature. (Also see future scopes)

Future Scope

Future scopes may include type casts during reference assignments which lead to a cast of the referenced variable (compare https://wiki.php.net/rfc/list_reference_assignment for reference assignments without casts):

// reference assignment cast
$now = "2020";
$now2 = (int) &$now;
 
// reference assignment cast combined with array destructuring
$years = ["2020", "2021"];
[(int) &$now, (int) &$future] = $years;

Future scopes may include strict type casts which avoid eg. (!int) “No Number String” to be casted to 0:

// strict assignment cast
$now = "2020";
$now2 = (!int) $now;
 
// strict assignment cast combined with array destructuring
$years = ["2020", "2021"];
[(!int) $now, (!int) $future] = $years;

Future scopes may include nullable type casts (compare https://wiki.php.net/rfc/nullable-casting):

// nullable assignment cast
$now = "2020";
$now2 = (?int) $now;
 
// nullable assignment cast combined with array destructuring
$years = ["2020", "2021", null];
[(?int) $now, (?int) $future, (?int) $evenLater] = $years;

Future scopes may include regular type checks which depend on strict_types directive:

$years = ["2020", "2021"];
[int $now, int $future] = $years;

Proposed Voting Choices

Voting starts 2020-04-09 and ends 2020-04-23.

As this is a language change, a 2/3 majority is required. The vote is a straight Yes/No vote for accepting the RFC and merging the patch.

Add type casting in array destructuring expressions
Real name yes no
alcaeus (alcaeus)  
asgrim (asgrim)  
ashnazg (ashnazg)  
brzuchal (brzuchal)  
bwoebi (bwoebi)  
carusogabriel (carusogabriel)  
colinodell (colinodell)  
derick (derick)  
duodraco (duodraco)  
galvao (galvao)  
jasny (jasny)  
jbnahan (jbnahan)  
jhdxr (jhdxr)  
kalle (kalle)  
kguest (kguest)  
kocsismate (kocsismate)  
levim (levim)  
mariano (mariano)  
mike (mike)  
nicolasgrekas (nicolasgrekas)  
nikic (nikic)  
ocramius (ocramius)  
pollita (pollita)  
ramsey (ramsey)  
rasmus (rasmus)  
salathe (salathe)  
sergey (sergey)  
stas (stas)  
svpernova09 (svpernova09)  
trowski (trowski)  
yunosh (yunosh)  
zimt (zimt)  
Final result: 6 26
This poll has been closed.

As the future scopes section of this proposal includes a lot of possible topics an additional poll to see which of these topics may be tackled in the near future:

Choose one or more of the suggested future scopes in which you are interested
Real name reference assignment casts strict casts nullable casts type checks in array destructuring expressions none
ajf (ajf)     
asgrim (asgrim)   
bwoebi (bwoebi)   
carusogabriel (carusogabriel)   
colinodell (colinodell)   
duodraco (duodraco)   
ekin (ekin)   
galvao (galvao)     
jasny (jasny)    
jbnahan (jbnahan)   
jhdxr (jhdxr)     
kelunik (kelunik)    
kguest (kguest)   
kocsismate (kocsismate)     
mariano (mariano)   
mike (mike)    
nicolasgrekas (nicolasgrekas)    
nikic (nikic)   
ocramius (ocramius)   
pollita (pollita)   
ramsey (ramsey)   
seld (seld)     
sergey (sergey)   
svpernova09 (svpernova09)   
trowski (trowski)    
Final result: 0 16 19 25 0
This poll has been closed.

Patches and Tests

The parser is already able to parse the syntax and requires no changes. The patch adds a change in the compile process in zend_compile_list_assign to be able to handle casting AST elements.

https://github.com/php/php-src/pull/5296

Implementation

After the project is implemented, this section should contain

  1. the version(s) it was merged into
  2. a link to the git commit(s)
  3. a link to the PHP manual entry for the feature
  4. a link to the language specification section (if any)

References

Links to external references, discussions or RFCs

Rejected Features

Keep this updated with features that were discussed on the mail lists.