<?xml version="1.0" encoding="utf-8"?>

<!-- $Revision$ -->

<!-- EN-Revision: b91033ba3d6831cfa2ef6745150cd5d6b4af65c9 Maintainer: PhilDaiguille Status: ready -->

<!-- CREDITS: DavidA. -->

<refentry xml:id="function.array-column" xmlns="http://docbook.org/ns/docbook">

<refnamediv>

<refname>array_column</refname>

<refpurpose>Devuelve los valores de una columna de un array de entrada</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> devuelve los valores de una columna de <parameter>array</parameter>, identificada por la clave

<parameter>column_key</parameter>. Opcionalmente, se puede proporcionar

un argumento <parameter>index_key</parameter> para indexar los valores

en el array devuelto por los valores de la columna

<parameter>index_key</parameter> del array de entrada.

</para>

<simpara>

<parameter>array</parameter> se trata como una lista de filas, cada una de las cuales es

a su vez un array o un objeto; una columna es la entrada o propiedad que

<parameter>column_key</parameter> nombra en cada fila.

Las filas que no son ni un array ni un objeto, y las filas en las que dicha entrada

o propiedad está ausente, se omiten sin diagnóstico.

Las claves de <parameter>array</parameter> nunca se conservan.

</simpara>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>array</parameter></term>

<listitem>

<simpara>

Una lista cuyas filas son arrays u objetos, a partir de la cual se extrae

una columna de valores. Si una fila es un objeto, las propiedades públicas

se leen directamente. Para que una propiedad no accesible públicamente sea leída,

la clase debe implementar tanto los métodos mágicos

<link linkend="object.get">__get()</link> como

<link linkend="object.isset">__isset()</link>: sin

<link linkend="object.isset">__isset()</link> la fila se omite, y con

<link linkend="object.isset">__isset()</link> pero sin

<link linkend="object.get">__get()</link> se lanza un

<exceptionname>Error</exceptionname>.

</simpara>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>column_key</parameter></term>

<listitem>

<simpara>

La columna de valores a devolver. Este valor puede ser la clave

entera de la columna a recuperar, o bien el

nombre de la clave para un array asociativo o el nombre de la propiedad.

También puede valer &null; para devolver las filas completas

(esto puede ser útil en conjunción con el argumento

<parameter>index_key</parameter> para reindexar el array).

</simpara>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>index_key</parameter></term>

<listitem>

<para>

La columna a utilizar como índice/clave para el array devuelto.

Este valor puede ser la clave entera de la columna, o el nombre de la clave.

El valor es <link linkend="language.types.array.key-casts">cast</link>

como de costumbre para las claves del array (sin embargo, anterior a PHP 8.0.0,

los objetos que soportan una conversión en string también eran permitidos).

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<simpara>

Devuelve un array de valores que representan una sola columna desde el

array de entrada. Si <parameter>column_key</parameter> es &null;, se devuelven

las propias filas.

</simpara>

</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>

Los objetos en las columnas indicadas por el argumento <parameter>index_key</parameter>

ya no se convertirán en string y lanzarán ahora

una <classname>TypeError</classname> en su lugar.

</entry>

</row>

<row>

<entry>7.1.0</entry>

<entry>

Ahora se respeta la visibilidad de las propiedades. Anteriormente, las propiedades

protegidas y privadas se leían directamente.

</entry>

</row>

<row>

<entry>7.0.0</entry>

<entry>

Las filas de <parameter>array</parameter> ahora también pueden ser objetos,

además de arrays.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>Recupera la columna de los nombres</title>

<programlisting role="php">

<![CDATA[

<?php

// Array que representa un conjunto de registros de una base de datos

$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>

Recupera la columna de los apellidos, indexada por la columna "id"

</title>

<programlisting role="php">

<![CDATA[

<?php

// Utilizando el array del ejemplo #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>

Recupera la columna de los nombres de usuario desde la propiedad pública

"username" de un objeto

</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>

Recupera la columna de nombres desde la propiedad privada "name" de un

objeto utilizando los métodos mágicos <link linkend="object.isset">__isset()</link>

y <link linkend="object.get">__get()</link>

</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 <link linkend="object.isset">__isset()</link> no está definido, el objeto

no contribuye con ninguna entrada al array devuelto.

</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

-->