[doc-en] master: Add earlier hint about array_column supporting objects (#3546)

From: 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>

« previous php.doc.cvs (#23687) next »