[doc-en] master: Add earlier hint about array_column supporting objects (#3546)
| From: | Jordi Boggiano via GitHub | Date: | Tue, 01 Sep 2026 13:10:18 +0000 |
| Subject: | [doc-en] master: Add earlier hint about array_column supporting objects (#3546) | ||
| Groups: | php.doc.cvs | ||
| Request: | Send a blank email to doc-cvs+get-23687@lists.php.net to get a copy of this message | ||
Author: Jordi Boggiano (Seldaek)
Committer: GitHub (web-flow)
Pusher: lacatoire
Date: 2026-09-01T15:10:15+02:00
Commit: https://github.com/php/doc-en/commit/b91033ba3d6831cfa2ef6745150cd5d6b4af65c9
Raw diff: https://github.com/php/doc-en/commit/b91033ba3d6831cfa2ef6745150cd5d6b4af65c9.diff
Add earlier hint about array_column supporting objects (#3546)
* Add earlier hint about array_column supporting objects
* array_column: explain what a column is, and correct the object rules
The description never said what a column is in a language without real
multidimensional arrays, nor that a row may be an object, which is what the
one-line refpurpose change was reaching for. Say it where the reviewer asked,
in the description, and leave the summary line short.
Also correct two false statements verified on PHP 8.5.4: a null column_key
returns the rows, not a single column, and a missing __isset() skips the
offending row rather than emptying the result. Document the Error thrown when
__isset() is present without __get(), link the magic methods the way the rest
of the manual does, and record the 7.0 and 7.1 changes in the changelog.
---------
Co-authored-by: Louis-Arnaud <la.catoire@gmail.com>
Changed paths:
M reference/array/functions/array-column.xml
Diff:
diff --git a/reference/array/functions/array-column.xml b/reference/array/functions/array-column.xml
index f7b108d65b06..bf88a4c7e821 100644
--- a/reference/array/functions/array-column.xml
+++ b/reference/array/functions/array-column.xml
@@ -21,6 +21,14 @@
returned array by the values from the <parameter>index_key</parameter>
column of the input array.
</para>
+ <simpara>
+ <parameter>array</parameter> is treated as a list of rows, each of which is
+ itself an array or an object; a column is the entry or property that
+ <parameter>column_key</parameter> names in every row.
+ Rows that are neither an array nor an object, and rows in which that entry
+ or property is absent, are skipped without a diagnostic.
+ The keys of <parameter>array</parameter> are never preserved.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
@@ -29,26 +37,30 @@
<varlistentry>
<term><parameter>array</parameter></term>
<listitem>
- <para>
- A multi-dimensional array or an array of objects from which to pull a
- column of values from. If an array of objects is provided, then public
- properties can be directly pulled. In order for protected or private
- properties to be pulled, the class must implement both the
- <function>__get</function> and <function>__isset</function> magic
- methods.
- </para>
+ <simpara>
+ A list whose rows are arrays or objects, from which a column of values
+ is pulled. If a row is an object, public properties are read directly.
+ For a property that is not publicly accessible to be read, the class
+ must implement both the
+ <link linkend="object.get">__get()</link> and
+ <link linkend="object.isset">__isset()</link> magic methods: without
+ <link linkend="object.isset">__isset()</link> the row is skipped, and
+ with <link linkend="object.isset">__isset()</link> but no
+ <link linkend="object.get">__get()</link> an
+ <exceptionname>Error</exceptionname> is thrown.
+ </simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>column_key</parameter></term>
<listitem>
- <para>
+ <simpara>
The column of values to return. This value may be an integer key of the
- column you wish to retrieve, or it may be a string key name for an
+ column to retrieve, or it may be a string key name for an
associative array or property name. It may also be &null; to return
- complete arrays or objects (this is useful together with
+ complete rows (this is useful together with
<parameter>index_key</parameter> to reindex the array).
- </para>
+ </simpara>
</listitem>
</varlistentry>
<varlistentry>
@@ -68,9 +80,11 @@
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
- Returns an array of values representing a single column from the input array.
- </para>
+ <simpara>
+ Returns an array of values representing a single column from the input
+ array. If <parameter>column_key</parameter> is &null;, the rows themselves
+ are returned.
+ </simpara>
</refsect1>
<refsect1 role="changelog">
&reftitle.changelog;
@@ -91,6 +105,20 @@
will no longer be cast to string and will now throw a
<classname>TypeError</classname> instead.
</entry>
</row>
+ <row>
+ <entry>7.1.0</entry>
+ <entry>
+ Property visibility is now respected. Formerly, protected and private
+ properties were read directly.
+ </entry>
+ </row>
+ <row>
+ <entry>7.0.0</entry>
+ <entry>
+ The rows of <parameter>array</parameter> may now be objects as well as
+ arrays.
+ </entry>
+ </row>
</tbody>
</tgroup>
</informaltable>
@@ -250,7 +278,7 @@ Array
<example>
<title>
Get the column of names from the private "name" property of an object
- using the magic methods <function>__isset</function> and
<function>__get</function>
+ using the magic methods <link linkend="object.isset">__isset()</link>
and <link linkend="object.get">__get()</link>
</title>
<programlisting role="php">
<![CDATA[
@@ -298,8 +326,8 @@ Array
]]>
</screen>
</example>
- If <function>__isset</function> is not provided, then an empty array will be
- returned.
+ If <link linkend="object.isset">__isset()</link> is not provided, the
object
+ contributes no entry to the returned array.
</para>
</refsect1>