array-column.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 8bf3587d8f70239a65d9aa44d42ced8a696a3e86 Maintainer: samesch Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.array-column" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>array_column</refname>
  <refpurpose>Liefert die Werte einer einzelnen Spalte eines Arrays</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> gibt die Werte einer einzelnen Spalte von
   <parameter>array</parameter> zurück, die durch
   <parameter>column_key</parameter> angegeben wird. Optional kann ein
   <parameter>index_key</parameter> angegeben werden, um die Werte im
   zurückgegebenen Array durch die Werte der Spalte
   <parameter>index_key</parameter> des angegebenen Arrays zu indizieren.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>array</parameter></term>
     <listitem>
      <para>
       Ein mehrdimensionales Array oder ein Array von Objekten, aus dem eine
       Spalte von Werten abgerufen werden soll. Wenn ein Array von Objekten
       angegeben wird, können die öffentlichen Eigenschaften direkt abgerufen
       werden. Damit geschützte oder private Eigenschaften abgerufen werden
       können, muss die Klasse die magischen Methoden
       <function>__get</function> und <function>__isset</function>
       implementieren.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>column_key</parameter></term>
     <listitem>
      <para>
       Die Spalte der zurückzugebenden Werte. Dieser Wert kann ein
       Integer-Schlüssel der Spalte sein, die abgerufen werden soll, oder der
       Name eines Zeichenketten-Schlüssels eines assoziativen Arrays oder
       einer Eigenschaft. Er kann auch &null; sein, um komplette Arrays oder
       Objekte zurückzugeben (dies ist in Verbindung mit
       <parameter>index_key</parameter> nützlich, um das Array neu zu
       indizieren).
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>index_key</parameter></term>
     <listitem>
      <para>
       Die Spalte, die als Index/Schlüssel für das zurückgegebene Array
       verwendet werden soll. Dieser Wert kann der Integer-Schlüssel der
       Spalte sein oder der Name des Zeichenketten-Schlüssels. Der Wert wird
       <link linkend="language.types.array.key-casts">konvertiert</link> wie
       für Array-Schlüssel üblich (vor PHP 8.0.0 waren jedoch auch Objekte
       erlaubt, die die Konvertierung in eine Zeichenkette unterstützen).
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Gibt ein Array von Werten zurück, das eine einzelne Spalte aus dem
   angegebenen Array enthält.
  </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>
        Die Objekte der Spalten, die durch den Parameter
        <parameter>index_key</parameter> angegeben werden, werden nicht mehr
        in Zeichenketten umgewandelt, sondern lösen stattdessen einen
        <classname>TypeError</classname> aus.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Auslesen der Spalte der Vornamen aus einem Datensatz</title>
    <programlisting role="php">
<![CDATA[
<?php

// Ein Array, das einen Datensatz enthält, wie er von einer Datenbank
// stammen könnte
$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>
     Abrufen der Spalte der Nachnamen aus einem Datensatz, indiziert durch die
     Spalte "id"
    </title>
    <programlisting role="php">
<![CDATA[
<?php

// Verwenden des Arrays $records aus Beispiel #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>
     Abrufen der Spalte mit den Benutzernamen aus der öffentlichen Eigenschaft
     "username" eines Objekts
    </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>
     Abrufen der Spalte der Namen aus der privaten Eigenschaft "name" eines
     Objekts mit der magischen Methode <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>
   Wenn <function>__isset</function> nicht angegeben wird, wird ein leeres
   Array zurückgegeben.
  </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
-->