php-doc-ru/reference/array/functions/array-column.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 8cdc6621f9826d04abc3e50438c010804d7e8683 Maintainer: rjhdby Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.array-column" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>array_column</refname>
  <refpurpose>Возвращает массив из значений одного столбца входного массива</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>array</type><methodname>array_column</methodname>
   <methodparam><type>array</type><parameter>array</parameter></methodparam>
   <methodparam><type class="union"><type>int</type><type>string</type><type>null</type></type><parameter>column_key</parameter></methodparam>
   <methodparam choice="opt"><type class="union"><type>int</type><type>string</type><type>null</type></type><parameter>index_key</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>array_column</function> возвращает массив из значений столбца массива
   <parameter>array</parameter> с ключом <parameter>column_key</parameter>.
   Опционально можно указать <parameter>index_key</parameter>, чтобы
   индексировать возвращаемый массив значениями из столбца с ключом
   <parameter>index_key</parameter> входного массива.
  </para>
 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>array</parameter></term>
     <listitem>
      <para>
       Многомерный массив или массив объектов, из которого будет производиться выборка
       значений. Если задан массив объектов, то можно выбирать любые его общедоступные
       свойства. Для выборки закрытых или защищённых свойств, объект должен
       реализовывать магические методы <function>__get</function> и <function>__isset</function>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>column_key</parameter></term>
     <listitem>
      <para>
       Ключ столбца, значения которого нужно вернуть. Может содержать как числовой, так и
       строковый ключ для ассоциативных массивов. А также может принимать значение &null;, тогда
       возвращаются не значения определённого столбца, а весь массив (полезно использовать
       вместе с <parameter>index_key</parameter>, чтобы переиндексировать массив).
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>index_key</parameter></term>
     <listitem>
      <para>
       Ключ столбца, значения которого будут использоваться в качестве ключей
       возвращаемого массива. Может быть как целочисленным ключом, так и
       строковым. Тип значения
       <link linkend="language.types.array.key-casts">приводится</link>,
       как обычно для ключей массива (однако до PHP 8.0.0 объекты, поддерживающие
       преобразование к строке, также разрешены).
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Возвращает массив из значений одного столбца входного массива (набора записей).
  </para>
 </refsect1>
 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>8.0.0</entry>
       <entry>
        Объекты в столбцах, обозначенные параметром <parameter>index_key</parameter>,
        больше не будут преобразованы в строку и вместо этого будут выдавать <classname>TypeError</classname>.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Получим столбец с именами из набора записей</title>
    <programlisting role="php">
<![CDATA[
<?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);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen role="php">
<![CDATA[
Array
(
    [0] => John
    [1] => Sally
    [2] => Jane
    [3] => Peter
)
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>
     Получим столбец с фамилиями, а в качестве ключей возвращаемого массива используем значения из столбца "id"
    </title>
    <programlisting role="php">
<![CDATA[
<?php
// Используем массив $records из первого примера
$last_names = array_column($records, 'last_name', 'id');
print_r($last_names);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen role="php">
<![CDATA[
Array
(
    [2135] => Doe
    [3245] => Smith
    [5342] => Jones
    [5623] => Doe
)
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>
     Получим столбец имён пользователей из общедоступного свойства "username" объекта
    </title>
    <programlisting role="php">
<![CDATA[
<?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'));
?>
]]>
    </programlisting>
    &example.outputs;
    <screen role="php">
<![CDATA[
Array
(
    [0] => user 1
    [1] => user 2
    [2] => user 3
)
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>
     Получим столбец имён пользователей из приватного свойства "name" объекта, используя магический
     метод <function>__get</function>.
    </title>
    <programlisting role="php">
<![CDATA[
<?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'));
?>
]]>
    </programlisting>
    &example.outputs;
    <screen role="php">
<![CDATA[
Array
(
    [0] => Fred
    [1] => Jane
    [2] => John
)
]]>
    </screen>
   </example>
   Если в объекте не будет метода <function>__isset</function>, то вернётся пустой массив.
  </para>
 </refsect1>
</refentry><!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->