PHP/iterable

إن المتغير التكراري Iterable هو شبه نوع (نوع زائف، pseudo-type) عُرِّفَ في الإصدار 7.1 من PHP وهو يقبل أية مصفوفة أو كائن يستخدم واجهة Traversable (أي Traversable interface)، كلا النوعين يمكن تكراره باستخدام حلقة foreach ويمكن أن يُستخدم مع تعبير yield داخل دالة مولِّدة (generator).

استخدام Iterables

يمكن استخدام Iterable كنوع لمعاملات الدالة (function parameter type) للإشارة إلى الدالة تتطلب مجموعةً من القيم، لكن دون أن تهتم لصيغة القيمة لأنها ستُستخدَم مع حلقة foreach، إذا لم تكن القيم مصفوفة أو مبنيةً على واجهة Traversable، فسيُرمى خطأٌ من النوع TypeError.

مثال 1: نوع معامل iterable

<?php

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

?>

يمكن للمعاملات المعرّفة كنوع البيانات iterable أن تستخدم القيمة NULL أو مصفوفة (array) كقيمة افتراضية لها.

المثال 2: قيم افتراضية لمعامل iterable

<?php

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

?>

يمكن استخدام iterable كنوع للقيمة المُعادة للإشارة إلى أنَّ الدالة ستُعيد قيمةً تكراريةً، وسيظهر خطأ من نوع TypeError إذا كانت القيمة المُعادة ليست مصفوفةً أو مبنيةً على Traversable.

المثال 3: نوع القيمة المُعادة هو تكراري

<?php

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

?>

الدوال التي عُرِّف نوع القيمة المُعادة فيها كتكرارية iterable يمكن أن تكون دوالًا مولِّدةً (generators).

المثال 4: نوع القيمة المُعادة هو تكراري والدالة هي دالة مولِّدة

<?php

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

?>

تباين النوع التكراري

يمكن توسيع (broaden) الدوال (methods) في الأصناف (classes) التي تستخدم مصفوفة أو قيمة مبنية على Traversable كنوع معامل؛ أو تضييق مجال أنواع القيم المُعادة من تكراري (iterable) إلى مصفوفة أو Traversable.

مثال 5: تباين النوع التكراري

<?php

interface Example {
    public function method(array $array): iterable;
}

class ExampleImplementation implements Example {
    public function method(iterable $iterable): array {
        // تم توسيع المعاملات وتضييق نوع القيم المعادة
    }
}

?>

مصادر

• صفحة Types iterable في توثيق PHP الرسمي.