Iterable pseudo-type #1941

trowski · 2016-06-10T23:10:09Z

It is common for a function to accept or return either an array or an object implementing Traversable to be used with foreach. However, because array is a primitive type and Traversable is an interface, there currently is no way to use a type declaration on a parameter or return type to indicate that the value is iterable.

This PR proposes a new iterable pseduo-type. This type is analogous to callable, accepting multiple types instead of one single type.

iterable accepts any array or object implementing Traversable. Both of these types are iterable using foreach and can be used with yield from within a generator.

iterable can be used as a parameter type to indicate that a function requires a set of values, but does not care about the form of the value set (array, Iterator, Generator, etc.) since it will be used with foreach. If a value is not an array or instance of Traversable, a TypeError will be thrown.

function foo(iterable $iterable) {
    foreach ($iterable as $value) {
        // ...
    }
}

iterable can also be used as a return type to indicate a function will return an iterable value. If the returned value is not an array or instance of Traversable, a TypeError will be thrown.

function bar(): iterable {
    return [1, 2, 3];
}

Parameters declared as iterable may use null or an array as a default value.

function foo(iterable $iterable = []) {
    // ...
}

Functions declaring iterable as a return type may also be generators.

function gen(): iterable {
    yield 1;
    yield 2;
    yield 3;
}

This proposal also adds a function is_iterable() that returns a boolean: true if a value is iterable and will be accepted by the iterable pseudo-type, false for other values.

var_dump(is_iterable([1, 2, 3])); // bool(true)
var_dump(is_iterable(new ArrayIterator([1, 2, 3]))); // bool(true)
var_dump(is_iterable((function () { yield 1; })())); // bool(true)
var_dump(is_iterable(1)); // bool(false)
var_dump(is_iterable(new stdClass())); // bool(false)

RFC: https://wiki.php.net/rfc/iterable

mokeev1995 · 2016-06-12T23:08:59Z

so... what about strings? are they iterable? if no, why?
@trowski @nikic

codedokode · 2016-06-13T13:18:29Z

@mokeev1995 PHP cannot iterate strings by characters anyway (only by bytes which makes little sence with multibyte encodings). And you cannot pass a sting to foreach.

Fleshgrinder · 2016-06-13T16:41:59Z

Strings cannot become iterables, the fact that you are able to iterate them byte by byte does not qualify them for this pseudo compound type. Especially because you cannot use them in a foreach and the iterable is all about that; you cannot use a Generator in a for. 😉

mokeev1995 · 2016-06-13T22:11:12Z

ok, thanks)

Majkl578 · 2016-06-18T19:50:25Z

I'm afraid this would be a serious BC break in minor version. It would be perfectly fine for 7.0 (at least as part of reserved types RFC), but since it's already out, the only reasonable version to target is 8.0.
See GH results for:
class Iterable
interface iterable

Danack · 2016-06-18T23:01:57Z

@Majkl578 From the first page of your first link, there are 10 entries. 8 have extra words (e.g. class IterableFilterIterator) and so wouldn't be affected. 1 of the others is in a namespace and so wouldn't be affected. Which leaves 1 example.

I'm afraid this would be a serious BC break in minor version.

Most people don't consider adding new classes to be a BC break. It's only changing behaviour of existing classes/functions, or removing stuff that is a 'real' BC break.

Majkl578 · 2016-06-18T23:24:00Z

Which leaves 1 example.

Which is still more than 0. And we are not even considering all the private code out there.

1 of the others is in a namespace and so wouldn't be affected

Not true, real-world applications typically import classes with use which implies breaking the usage of such classes/interfaces.

Most people don't consider adding new classes to be a BC break.

This proposal is not to add new class, but a pseudotype that would break all code using typehint for interface/class named Iterable. And that is a real BC break.

trowski · 2016-06-19T04:34:14Z

@Majkl578 Behavioral changes are considered serious BC breaks, while this would only cause a BC break due to naming, which can easily be fixed with simple find-and-replace. Yes, it is technically a BC break, but one that can be fixed in a matter of minutes without actually examining any code.

dstogov · 2016-06-20T07:06:55Z

Zend/zend_inheritance.c

+
+	if (arg_info->class_name && zend_string_equals_literal_ci(arg_info->class_name, "Traversable")) {
+		return 1;
+	}


why do we need these special compatibility rules? why not just check for IS_ITERABLE?

Allows a degree of co/contravariance in extending/implementing classes. Parameter types of array or Traversable can be broadened to iterable or return types declaring iterable can be restricted to either array or Traversable.

brutuscat · 2016-07-29T16:12:22Z

It would be pretty cool if, somehow (I have no idea if this is possible), after this pseudo type has been added, we could start using the array_* functions indiscriminately across all the iterable types.
Is there any discussion going on regarding this that I could read/join?

This PR was merged into the 1.12 branch. Discussion ---------- PhpdocTypesFixer - support iterable type PHP 7.1 will have the `iterable` type. We should treat it like the other types we normalize. Refs: * https://wiki.php.net/rfc/iterable * php/php-src#1941 * https://github.com/php/php-src/blob/php-7.1.0RC2/UPGRADING#L25-L27 Commits ------- 0d8da6e Added support for the new iterable type

trowski added 11 commits June 3, 2016 17:42

Add iterable pseudo-type

72692e9

Add is_iterable() function

0e221cb

Add iterable to zend_get_type_by_const()

340a000

Fix default argument check

bf6a659

Fix error message

8146c47

Add iterable tests

bea9df5

Covariance on inheriting classes with iterable

4da3e77

Fix generator test; add covariance tests

c2266c3

Fix abort too early

cf0290c

Limit covariance to array and Traversable

277d89c

Add iterable type to opcache

0dc772c

smalyshev added the RFC label Jun 14, 2016

dstogov reviewed Jun 20, 2016
View reviewed changes

trowski added 2 commits June 29, 2016 09:36

Swap type check order

583386d

Merge branch 'master' into iterable

d9a9cf8

php-pulls merged commit d9a9cf8 into php:master Jul 4, 2016

zonuexe mentioned this pull request Aug 18, 2016

Add iterable and void keyword emacs-php/php-mode#317

Merged

GrahamCampbell mentioned this pull request Sep 23, 2016

PhpdocTypesFixer - support iterable type PHP-CS-Fixer/PHP-CS-Fixer#2196

Merged

hollodotme mentioned this pull request Nov 4, 2016

Add iterable return type to getReadRoutes() and getWriteRoutes() icehawk/icehawk#19

Open

carusogabriel mentioned this pull request Oct 26, 2018

Add is_iterable to opcache Optimizer #3637

Closed

trowski deleted the iterable branch May 6, 2021 15:57

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Iterable pseudo-type #1941

Iterable pseudo-type #1941

Uh oh!

trowski commented Jun 10, 2016 •

edited

Loading

Uh oh!

mokeev1995 commented Jun 12, 2016

Uh oh!

codedokode commented Jun 13, 2016

Uh oh!

Fleshgrinder commented Jun 13, 2016

Uh oh!

mokeev1995 commented Jun 13, 2016

Uh oh!

Majkl578 commented Jun 18, 2016

Uh oh!

Danack commented Jun 18, 2016

Uh oh!

Majkl578 commented Jun 18, 2016

Uh oh!

trowski commented Jun 19, 2016

Uh oh!

dstogov Jun 20, 2016

Uh oh!

trowski Jun 20, 2016

Uh oh!

brutuscat commented Jul 29, 2016

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

11 participants

Iterable pseudo-type #1941

Iterable pseudo-type #1941

Uh oh!

Conversation

trowski commented Jun 10, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mokeev1995 commented Jun 12, 2016

Uh oh!

codedokode commented Jun 13, 2016

Uh oh!

Fleshgrinder commented Jun 13, 2016

Uh oh!

mokeev1995 commented Jun 13, 2016

Uh oh!

Majkl578 commented Jun 18, 2016

Uh oh!

Danack commented Jun 18, 2016

Uh oh!

Majkl578 commented Jun 18, 2016

Uh oh!

trowski commented Jun 19, 2016

Uh oh!

dstogov Jun 20, 2016

Choose a reason for hiding this comment

Uh oh!

trowski Jun 20, 2016

Choose a reason for hiding this comment

Uh oh!

brutuscat commented Jul 29, 2016

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

11 participants

trowski commented Jun 10, 2016 •

edited

Loading