This RFC proposes a syntax to add to improve type-hinting, allowing an array of that hinted type to be passed as an argument, thus improving readability of code, improving expectations of passed items, reducing boilerplate code required to check the contents of an array and offering minor performance improvements.

Under this proposal, a new syntax is introduced:

function test ( SplFileObject [ ] $files ) { var_dump ( $files ) ; }

The square brackets allow type-hinting for an array where each value is of a specific type. This is handy when simply type-hinting with “array” is just not clear enough what the content should be. It improves readability and self-documentation of the signature, and avoids asking users to foreach through the argument to verify if each item is of the expected type.

Default values can still be used:

function test ( SplFileObject [ ] $files = null ) { var_dump ( $files ) ; } test ( ) ; // Outputs: null

Interfaces and instances work in the same way as expected for existing type-hints:

interface Face { } class One implements Face { } class Two extends One { } class Other { } function test ( Face [ ] $objects ) { var_dump ( $objects ) ; } test ( 'stuff' ) ; // Catchable fatal error: Argument 1 passed to test() must be an array of Face, string given test ( [ new One , new Other ] ) ; // Catchable fatal error: Argument 1 passed to test() must be an array of Face, Other found test ( [ new One , new Two ] ) ; // Success

While this may look like it contains similarities to the variadic syntax, it is not intended for the same use-case. Variadics hint against the type of multiple parameters, this proposed syntax hints against the type of the contents in one.

Variadic syntax can be used to provide an alternative interface for function usage, or combined to accept an unlimited number of arrays, of which the content will be of a specific type.

function testArrayOf ( Face [ ] $objects ) { var_dump ( $objects ) ; } testArrayOf ( [ new One , new Two ] ) ; // array(2) { // [0]=> // object(One)#1 (0) { // } // [1]=> // object(Two)#2 (0) { // } // } function testVariadics ( Face ... $objects ) { var_dump ( $objects ) ; } testVariadics ( new One , new Two ) ; // array(2) { // [0]=> // object(One)#2 (0) { // } // [1]=> // object(Two)#1 (0) { // } // } function testVariadicArrays ( Face [ ] ... $objects ) { var_dump ( $objects ) ; } testVariadicArrays ( [ new One , new Two ] , [ new Two ] ) ; // array(2) { // [0]=> // array(2) { // [0]=> // object(One)#2 (0) { // } // [1]=> // object(Two)#1 (0) { // } // } // [1]=> // array(1) { // [0]=> // object(Two)#3 (0) { // } // } // }

The two are by no means mutually exclusive.

A limitation of the variadics feature is that they can only go at the end of a function signature, and there can only be on variadic argument per signature, whilst the “array of” syntax can be used multiple times at any location in the signature.