تابع is_iterable() در PHP

تابع is_iterable() یکی از توابع کاربردی در PHP است که در نسخهٔ 7.1 معرفی شد. این تابع بررسی می‌کند که آیا یک مقدار قابل استفاده در حلقهٔ foreach هست یا خیر. به عبارت دیگر، آیا مقدار مورد نظر از نوع iterable است یا نه — یعنی آرایه است یا شیئی که رابط Traversable (مثلاً Iterator یا IteratorAggregate) را پیاده‌سازی کرده است.

ساختار تابع

امضای تابع به‌صورت زیر است:

bool is_iterable ( mixed $var )

خروجی بولین است: true وقتی مقدار قابل پیمایش باشد و false در غیر این صورت.

مثال‌های پایه

<?php
var_dump(is_iterable([1,2,3]));           // true
var_dump(is_iterable(new ArrayIterator([1,2,3]))); // true
var_dump(is_iterable("string"));          // false
var_dump(is_iterable(null));              // false
?>

در این مثال، آرایه و نمونهٔ ArrayIterator که رابط Iterator را پیاده‌سازی می‌کند، قابل پیمایش هستند؛ اما رشته و مقدار null قابل پیمایش نیستند.

مثال با Generator

<?php
function gen() {
    yield 1;
    yield 2;
}
$g = gen();
var_dump(is_iterable($g)); // true
?>

جنریتورها (Generator) نمونه‌هایی از Iterator هستند، بنابراین با is_iterable() به‌درستی true برمی‌گردانند.

کاربردهای عملی و الگوهای رایج

• ایمن‌سازی پیمایش: قبل از اجرای foreach از is_iterable() استفاده کنید تا از هشدارها و خطاها جلوگیری شود.
• اعتبارسنجی پارامترها: وقتی تابع یا متدی انتظار یک مجموعه را دارد، با is_iterable() می‌توان ورودی را قبل از پردازش بررسی کرد.
• پشتیبانی از انواع مختلف: با این تابع می‌توان هم آرایه‌ها و هم اشیاء قابل پیمایش را به‌طور یکپارچه مدیریت کرد.

نمونه: پیمایش ایمن

<?php
function process_items($items) {
    if (!is_iterable($items)) {
        // می‌توانیم خطا بدهیم یا مقدار خالی جایگزین کنیم
        $items = [];
    }
    foreach ($items as $k => $v) {
        // پردازش هر عنصر
    }
}
?>

در این کد اگر پارامتر ورودی قابل پیمایش نباشد، به‌جای تولید هشدار، یک آرایهٔ خالی جایگزین می‌شود و حلقه بدون مشکل اجرا می‌گردد.

تفاوت is_iterable با is_array و instanceof Traversable

ممکن است با توابع و عملگرهای دیگری برای تشخیص نوع مواجه شوید؛ مقایسهٔ سریع:

یعنی is_iterable() عملاً ترکیبی از is_array() و instanceof Traversable است و کاربردش زمانی است که بخواهیم هر دو حالت را یکجا بررسی کنیم.

نکات و موارد لبه‌ای (Edge Cases)

• رشته‌ها (strings) قابل پیمایش نیستند؛ استفاده از رشته در foreach باعث هشدار می‌شود.
• منابع (resources) قابل پیمایش نیستند.
• نمی‌توان Traversable را مستقیماً در سطح کاربر پیاده‌سازی کرد؛ به‌جای آن باید Iterator یا IteratorAggregate پیاده‌سازی شود.
• عملکرد: این تابع یک تابع داخلی است و هزینهٔ بسیار کمی دارد؛ مناسب برای بررسی‌های کوتاه پیش از حلقه.

پلی‌فیل برای نسخه‌های قدیمی PHP

اگر پروژه‌تان روی نسخه‌ای از PHP اجرا می‌شود که قبل از 7.1 است، می‌توانید یک پلی‌فیل ساده تعریف کنید:

<?php
if (!function_exists('is_iterable')) {
    function is_iterable($var) {
        return is_array($var) || $var instanceof Traversable;
    }
}
?>

این تابع قبل از تعریف، بررسی می‌کند که آیا is_iterable از قبل وجود دارد یا نه، سپس در صورت عدم وجود نسخهٔ مشابهی را تعریف می‌کند. این روش برای سازگاری بازگشتی با کدهای جدید مفید است.

بهترین شیوه‌ها و توصیه‌های حرفه‌ای

• به جای بررسی‌های تودرتو و شروط پیچیده، از is_iterable() برای خوانایی بهتر کد استفاده کنید.
• در APIها زمانی که پارامتر می‌تواند آرایه یا اشیاء قابل پیمایش باشد، با استفاده از iterable در امضا (PHP 7.1+) و/یا is_iterable() در زمان اجرا، هم نوع‌ها را مشخص و هم ایمن‌سازی کنید.
• برای تبدیل مقادیر غیرقابل پیمایش به مجموعه، از الگوهای واضح استفاده کنید (مثلاً بازگشت آرایهٔ خالی یا بومی‌سازی مقدار در آرایه).

نمونه پیشرفته: تابعی که ورودی متنوع را همسان‌سازی می‌کند

<?php
function normalize_to_iterable($value) {
    if (is_iterable($value)) {
        return $value;
    }
    // اگر بخواهیم رشته‌ها یا اسکالرها را هم تبدیل کنیم:
    if ($value === null) {
        return [];
    }
    return [$value];
}

// استفاده:
foreach (normalize_to_iterable($maybeItem) as $item) {
    // امن و ساده
}
?>

در این نمونه، هر مقدار به یک مجموعه قابل پیمایش تبدیل می‌شود تا کد بالای foreach ساده و از خطا مصون باشد.

جمع‌بندی

is_iterable() همراهی ساده و قدرتمند برای برنامه‌نویس PHP است تا بدون پیچیدگی تشخیص دهد آیا مقداری قابل پیمایش هست یا خیر. این تابع مخصوصاً در ورودی‌زدایی، APIها و کدهایی که باید با آرایه‌ها و اشیاء قابل پیمایش کار کنند، کاربرد فراوانی دارد. با بهره‌گیری از این تابع و رعایت بهترین شیوه‌ها، کدهای خواناتر، ایمن‌تر و سازگار‌تری خواهید داشت.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال