array-column.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 8bf3587d8f70239a65d9aa44d42ced8a696a3e86 Maintainer: yannick Status: ready -->
<!-- Reviewed: no -->
<!-- CREDITS: DavidA. -->
<refentry xml:id="function.array-column" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>array_column</refname>
  <refpurpose>Retourne les valeurs d'une colonne d'un tableau d'entrée</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> retourne les valeurs d'une colonne de <parameter>array</parameter>, identifiée par la clé
   <parameter>column_key</parameter>. Optionnellement, vous pouvez fournir
   un paramètre <parameter>index_key</parameter> pour indexer les valeurs 
   dans le tableau retourné par les valeurs de la colonne 
   <parameter>index_key</parameter> du tableau d'entrée.
  </para>
 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>array</parameter></term>
     <listitem>
      <para>
       Un tableau multidimensionnel ou un tableau d'objets à partir duquel
       on extrait une colonne de valeur. Si un tableau d'objets est fourni, 
       alors les propriétés publiques peuvent être directement extraites. 
       Pour que les propriétés protected ou private soient extraites, 
       la classe doit implémenter les deux méthodes magiques 
       <function>__get</function> et <function>__isset</function>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>column_key</parameter></term>
     <listitem>
      <para>
       La colonne de valeurs à retourner. Cette valeur peut être la clé
       entière de la colonne que vous souhaitez récupérer, ou bien le 
       nom de la clé pour un tableau associatif ou le nom de la propriété.
       Il peut aussi valoir &null; pour retourner le tableau complet ou 
       des objets (ceci peut être utile en conjonction du paramètre
       <parameter>index_key</parameter> pour ré-indexer le tableau).
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>index_key</parameter></term>
     <listitem>
      <para>
       La colonne à utiliser comme index/clé pour le tableau retourné.
       Cette valeur peut être la clé entière de la colonne, ou le nom de la clé.
       La valeur est <link linkend="language.types.array.key-casts">cast</link>
       comme d'habitude pour les clés du tableau (cependant, antérieur à PHP 8.0.0,
       les objects qui supportent une conversion en chaîne de caractère étaient aussi autorisés).
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Retourne un tableau de valeurs représentant une seule colonne depuis le
   tableau d'entrée.
  </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>
        Les objets dans les colonnes indiqué par le paramètre <parameter>index_key</parameter>
        ne seront plus convertie en chaîne de caractères et lanceront désormais
        une <classname>TypeError</classname> à la place.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Récupère la colonne des prénoms</title>
    <programlisting role="php">
<![CDATA[
<?php

// Tableau représentant un jeu d'enregistrements issu d'une base de données
$records = [
    [
        'id' => 2135,
        'first_name' => 'John',
        'last_name' => 'Doe',
    ],
    [
        'id' => 3245,
        'first_name' => 'Sally',
        'last_name' => 'Smith',
    ],
    [
        'id' => 5342,
        'first_name' => 'Jane',
        'last_name' => 'Jones',
    ],
    [
        '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>
     Récupère la colonne des noms, indexé par la colonne "id"
    </title>
    <programlisting role="php">
<![CDATA[
<?php

// En utilisant le tableau de l'exemple #1
$records = [
    [
        'id' => 2135,
        'first_name' => 'John',
        'last_name' => 'Doe',
    ],
    [
        'id' => 3245,
        'first_name' => 'Sally',
        'last_name' => 'Smith',
    ],
    [
        'id' => 5342,
        'first_name' => 'Jane',
        'last_name' => 'Jones',
    ],
    [
        'id' => 5623,
        'first_name' => 'Peter',
        'last_name' => 'Doe',
    ]
];

$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>
     Récupère la colonne des username depuis la propriété publique 
     "username" d'un objet
    </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>
     Récupère la colonne nom depuis la propriété privée "name" d'un 
     objet en utilisant les méthodes magiques <function>__isset</function> et
     <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>
   Si <function>__isset</function> est non défini, alors un tableau 
   vide sera retourné.
  </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
-->