الدالة array_map() في PHP: تطبيق دالة على كل عنصر

تستدعي array_map($callback, $array) الدالة $callback على كل عنصر في $array وتعيد مصفوفة جديدة بالنتائج. دالة الاستدعاء أولًا، والمصفوفة ثانيًا، وتبقى المصفوفة الأصلية دون تغيير.

<?php
$prices = [10, 25, 40];

$withTax = array_map(fn($p) => $p * 1.2, $prices);

print_r($withTax);
print_r($prices); // unchanged

fn($p) => $p * 1.2 دالة سهمية: دالة من تعبير واحد تعيد نتيجته. ويعمل أي شيء قابل للاستدعاء مكانها.

استخدام دالة مدمجة دالةَ استدعاء

مرّر اسم دالة مدمجة نصًا. هذه أقصر طريقة لتنظيف مصفوفة كاملة: تشذيب كل قيمة، أو تحويل النصوص إلى أعداد صحيحة، أو تغيير حالة الأحرف.

<?php
$raw = ["  apple ", "Banana  ", " cherry"];
print_r(array_map('trim', $raw));

$ids = ["4", "15", "42"];
var_dump(array_map('intval', $ids));

$names = ["ada", "grace", "linus"];
print_r(array_map('ucfirst', $names));

array_map('intval', ...) هي الطريقة المعتادة لتحويل النصوص القادمة من نموذج أو من explode() إلى أعداد صحيحة حقيقية. ويمكنك أيضًا كتابة intval(...)، صيغة الاستدعاء من الدرجة الأولى منذ PHP 8.1، التي يستطيع محررك إكمالها تلقائيًا وفحصها.

استخدام دالة مغلقة مع متغيرات خارجية

ترى الدالة السهمية المتغيرات المحيطة بها تلقائيًا. أما function الكلاسيكية فتحتاج إلى use لإدخالها. كلتاهما مشروحة في صفحة الدوال المجهولة.

<?php
$rate = 0.15;
$amounts = [100, 250, 80];

// Arrow function: $rate is captured automatically
$tips = array_map(fn($a) => round($a * $rate, 2), $amounts);
print_r($tips);

// Classic closure: $rate must be listed in use()
$tips2 = array_map(function ($a) use ($rate) {
    return round($a * $rate, 2);
}, $amounts);
print_r($tips2);

array_map مع المفاتيح

مع مصفوفة واحدة، تحتفظ array_map بالمفاتيح، بما فيها المفاتيح النصية. لكن دالة الاستدعاء لا تتلقى إلا القيمة. وللحصول على المفتاح أيضًا، مرّر array_keys($array) مصفوفةً ثانية: عندها تُستدعى الدالة بعنصر واحد من كل مصفوفة.

<?php
$stock = ["apples" => 12, "pears" => 0, "plums" => 7];

// Keys are kept
print_r(array_map(fn($n) => $n * 2, $stock));

// Key and value in the callback
$lines = array_map(
    fn($name, $count) => "$name: $count",
    array_keys($stock),
    $stock
);
print_r($lines);

// Same, with the original keys put back
print_r(array_combine(array_keys($stock), $lines));

لاحظ النتيجة الثانية: حالما تمرر أكثر من مصفوفة، تُستبدل المفاتيح بـ 0, 1, 2. لهذا يستخدم السطر الأخير array_combine() لإعادة بنائها.

المرور على عدة مصفوفات معًا

تصبح كل مصفوفة إضافية وسيطًا إضافيًا لدالة الاستدعاء، مطابقًا حسب الموضع. وإذا اختلفت أطوال المصفوفات، تُكمَّل الأقصر بـ null.

<?php
$first = ["Ada", "Grace", "Linus"];
$last  = ["Lovelace", "Hopper", "Torvalds"];

print_r(array_map(fn($f, $l) => "$f $l", $first, $last));

// Different lengths: missing values arrive as null
$a = [1, 2, 3];
$b = [10, 20];
print_r(array_map(fn($x, $y) => $x + ($y ?? 0), $a, $b));

تمرير null دالةَ استدعاء يتخطى الدالة ويضم المصفوفات أزواجًا:

<?php
$names = ["Ada", "Grace"];
$years = [1815, 1906];

print_r(array_map(null, $names, $years));

array_map مقابل array_walk مقابل foreach

تبني array_map مصفوفة جديدة. وتغيّر array_walk المصفوفة التي تمررها، عبر مرجع، وتعطي دالة الاستدعاء المفتاح وسيطًا ثانيًا. وتفعل foreach أيًّا منهما، وتستطيع أيضًا تخطي عناصر أو التوقف مبكرًا بـ break.

<?php
$tags = [" php ", " arrays", "map "];

// New array, input untouched
$clean = array_map('trim', $tags);

// Change in place: note the & before $value
array_walk($tags, function (&$value, $key) {
    $value = "#$key " . trim($value);
});

print_r($clean);
print_r($tags);

استخدم array_map عندما يتحول كل عنصر إلى عنصر جديد واحد بالضبط. وإذا احتجت أيضًا إلى إسقاط بعض العناصر، فاجمعها مع array_filter، أو اكتب foreach.

خطأ شائع: ترتيب الوسائط

تأخذ array_map دالة الاستدعاء أولًا والمصفوفة ثانيًا. وجارتها array_filter تأخذهما بالترتيب المعاكس، فيسهل الخلط بينهما:

array_map($callback, $array);     // callback first
array_filter($array, $callback);  // array first

تبديلهما يجعل PHP 8 ترمي TypeError، لأن المصفوفة العادية ليست دالة استدعاء صالحة:

<?php
// This throws a TypeError on purpose: the arguments are swapped
$numbers = [1, 2, 3];
$doubled = array_map($numbers, fn($n) => $n * 2);

تتوقف PHP مع:

PHP Fatal error:  Uncaught TypeError: array_map(): Argument #1 ($callback) must be a valid callback or null, array callback must have exactly two members in /home/index.php:4

أعد الوسيطين إلى مكانيهما فتعمل الكتلة.