الدالة array_push() في PHP: إضافة عناصر إلى مصفوفة

تضيف array_push($arr, $value) قيمة إلى نهاية مصفوفة. ولقيمة واحدة، يؤدي الاختصار $arr[] = $value; المهمة نفسها دون استدعاء دالة، وهو ما تستخدمه معظم شيفرات PHP. كلاهما يغيّر المصفوفة في مكانها.

<?php
$colors = ['red', 'green'];

$colors[] = 'blue';                    // shorthand, one value
array_push($colors, 'yellow', 'pink'); // several values at once

print_r($colors);

تأخذ array_push() المصفوفة بالمرجع، لذا تعدّل المتغير الذي تمرره. وتعيد العدد الجديد للعناصر، ويمكنك تجاهله.

array_push مقابل $arr[] =

استخدم $arr[] = $value لقيمة واحدة: فهي أقصر وتتجنب استدعاء دالة، وهذا يتراكم داخل حلقة كبيرة. واستخدم array_push() عندما تكون لديك عدة قيم تضيفها في جملة واحدة، أو قائمة من القيم تريد بسطها.

<?php
$log = [];
for ($i = 1; $i <= 3; $i++) {
    $log[] = "step $i";
}

$more = ['step 4', 'step 5'];
$count = array_push($log, ...$more);   // spread a list in

print_r($log);
echo "Now $count entries\n";

تعمل $arr[] = أيضًا على متغير غير موجود بعد: تنشئ PHP المصفوفة. أما array_push() فتحتاج إلى مصفوفة موجودة: على متغير غير معرّف ترمي TypeError: array_push(): Argument #1 ($array) must be of type array, null given.

إضافة مفتاح وقيمة

لا تلحق array_push() القيم إلا بالمفتاح الصحيح التالي. لإضافة مفتاح مسمى، أسند إليه. ولإضافة عدة أزواج معًا، استخدم += (تُبقي المفاتيح الموجودة) أو array_merge() (تجعل القيم الجديدة تفوز).

<?php
$user = ['name' => 'Ada'];

$user['email'] = 'ada@example.com';             // one key and value
$user += ['role' => 'admin', 'name' => 'X'];    // adds role; name already exists, kept

print_r($user);

array_push($user, 'oops');                      // gets key 0, not a name
print_r($user);

الفرق بين + وarray_merge() عند تصادم المفاتيح مشروح في صفحة array_merge.

الإضافة إلى البداية: array_unshift

تُدرج array_unshift($arr, $value) في البداية. يُعاد ترقيم المفاتيح الصحيحة لتحصل القيمة الجديدة على الفهرس 0؛ وتبقى المفاتيح النصية كما هي. ومثل array_push()، تقبل عدة قيم وتعيد العدد الجديد.

<?php
$queue = ['Linus', 'Grace'];
array_unshift($queue, 'Ada');
print_r($queue);

$menu = ['home' => '/', 'about' => '/about'];
array_unshift($menu, '/login');      // string keys are kept, the new value gets key 0
print_r($menu);

لوضع زوج مسمى أولًا، ابنِ مصفوفة جديدة: $menu = ['login' => '/login'] + $menu;.

الإدراج في موضع محدد

تُدرج array_splice($arr, $offset, 0, $values) دون حذف أي شيء: تبدأ عند $offset، وتحذف 0 من العناصر، وتضع القيم الجديدة هناك. ويُعاد ترقيم المفاتيح الصحيحة بعد نقطة الإدراج.

<?php
$letters = ['a', 'b', 'd', 'e'];

array_splice($letters, 2, 0, 'c');           // insert 'c' at index 2
print_r($letters);

array_splice($letters, 1, 0, ['x', 'y']);    // insert two values at index 1
echo implode(' ', $letters), "\n";

تستطيع array_splice() أيضًا حذف العناصر واستبدالها؛ وتعرض صفحة حذف العناصر هذه الصيغ.

إلحاق مصفوفة أخرى

تضيف array_push($a, $b) المصفوفة $b عنصرًا متداخلًا واحدًا، ونادرًا ما يكون هذا ما تريده. لإضافة قيم $b واحدة واحدة، ابسطها، أو ابنِ مصفوفة جديدة بصيغة البسط أو بـ array_merge().

<?php
$a = [1, 2];
$b = [3, 4];

$nested = $a;
array_push($nested, $b);       // [1, 2, [3, 4]]
echo json_encode($nested), "\n";

$flat = $a;
array_push($flat, ...$b);      // [1, 2, 3, 4]
echo json_encode($flat), "\n";

echo json_encode([...$a, ...$b]), "\n";

خطأ شائع: إسناد القيمة المعادة

تعيد array_push() عددًا، هو العدد الجديد للعناصر. وإسناده مرة أخرى إلى متغير المصفوفة يستبدل مصفوفتك بعدد صحيح، فترمي array_push() التالية عليه TypeError.

<?php
$items = ['pen', 'book'];

$result = array_push($items, 'lamp');
var_dump($result);    // the count, not the array

// Wrong: $items = array_push($items, 'mug');  turns $items into int(4)
array_push($items, 'mug');   // right: call it on its own line
print_r($items);

ينطبق الأمر نفسه على array_unshift() وعلى sort()، التي تعيد true. الدوال التي تغيّر مصفوفة في مكانها تعيد حالة، لا المصفوفة.