array_column()‎

(PHP 5 >= 5.5.0, PHP 7)

تعيد الدالة array_column()‎ القيم المتواجدة بعمود واحد للمصفوفة التي تُمرَّر كمعامل للدالة. 

الوصف

array array_column ( array $input , mixed $column_key [, mixed $index_key = NULL ] )

تعيد الدالة array_column()‎ القيم من عمود واحد في المصفوفة ‎$input، هذه القيم مسجلة بالمفتاح المحدد بالمعامل ‎$column_key. اختياريًا، يمكن تحديد عمود آخر لتستخدمه الدالة كمفتاح للمصفوفة التي تعيدها عن طريق المعامل ‎$index_key.

المعاملات

input

مصفوفة متعددة الأبعاد أو مصفوفة من الكائنات تستخرج هذه الدالة القيم منها. يمكن استعمال الخصائص عامة الوصول مباشرةً في حالة استخدام مصفوفة من الكائنات. يجب أن يوفر الصنف (class) تعريفًا للدوال السحرية ‎__get()‎ و ‎__isset()‎ حتى يمكن استعمال الخصائص المحمية أو خاصة الوصول.

column_key

عمود القيم الذي ستعيده الدالة. يمكن أن تكون هذه القيمة عددًا صحيحًا يمثل مفتاح العامود الذي ستعيده الدالة، أو مفتاحًا نصيًا في حالة المصفوفات الترابطية، أو اسم إحدى خصائص الكائنات. إذا تساوت قيمة هذا المعامل مع NULL فستعيد الدالة المصفوفة أو الكائنات كاملة (هذه الميزة مفيدة في حالة استخدامها مع المعامل ‎$index_key بقصد إعادة فهرسة المصفوفة).

index_key

يحدد هذا المعامل العمود الذي سيُستخدَم كمفتاح للمصفوفة التي ستعيدها الدالة. قد تكون قيمة مفتاح الفهرسة عددًا صحيحًا يمثل مفتاح العمود، أو مفتاحًا نصيًا. 

القيم المعادة

تعيد هذه الدالة مصفوفةً من القيم تمثل عمودًا واحدًا من المصفوفة التي ستُعالَج. 

سجل التغيرات

الإصدار	الوصف
PHP 7.0.0	أضافت إمكانية تمرير المعامل ‎$input كمصفوفة من الكائنات.

أمثلة

المثال 1: الحصول على عمود «الاسم الأول» من مصفوفة فيها سجلات

<?php
$records = array(
    array(
        'id' => 2135,
        'first_name' => 'John',
        'last_name' => 'Doe',
    ),
    array(
        'id' => 3245,
        'first_name' => 'Sally',
        'last_name' => 'Smith',
    ),
    array(
        'id' => 5342,
        'first_name' => 'Jane',
        'last_name' => 'Jones',
    ),
    array(
        'id' => 5623,
        'first_name' => 'Peter',
        'last_name' => 'Doe',
    )
);
 
$first_names = array_column($records, 'first_name');
print_r($first_names);
?>

نتيجة المثال السابق:

Array
(
    [0] => John
    [1] => Sally
    [2] => Jane
    [3] => Peter
)

المثال 2: الحصول على عمود «الاسم الأخير» من المصفوفة التي تحتوي على السجلات، مع فهرسته باستخدام عمود id

<?php
// سنستخدم نفس المصفوفة الموجودة في المثال السابق
$last_names = array_column($records, 'last_name', 'id');
print_r($last_names);
?>

نتيجة المثال السابق:

Array
(
    [2135] => Doe
    [3245] => Smith
    [5342] => Jones
    [5623] => Doe
)

المثال 3: الحصول على عمود أسماء المستخدمين من الخاصية العامة username التابعة لأحد الكائنات

<?php

class User
{
    public $username;

    public function __construct(string $username)
    {
        $this->username = $username;
    }
}

$users = [
    new User('user 1'),
    new User('user 2'),
    new User('user 3'),
];

print_r(array_column($users, 'username'));
?>

نتيجة المثال السابق:

Array
(
    [0] => user 1
    [1] => user 2
    [2] => user 3
)

المثال رقم 4: الحصول على عمود الأسماء من الخاصية الخاصة name لأحد الكائنات باستخدام الدالة السحرية ‎__get()‎

<?php

class Person
{
    private $name;

    public function __construct(string $name)
    {
        $this->name = $name;
    }

    public function __get($prop)
    {
        return $this->$prop;
    }

    public function __isset($prop) : bool
    {
        return isset($this->$prop);
    }
}

$people = [
    new Person('Fred'),
    new Person('Jane'),
    new Person('John'),
];

print_r(array_column($people, 'name'));
?>

نتيجة المثال السابق:

Array
(
    [0] => Fred
    [1] => Jane
    [2] => John
)

إذا لم تتواجد الدالة ‎__‎isset()‎ فستعيد الدالة array_column()‎ مصفوفة فارغة.

مصادر

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