[doc-en] master: settype(): document that it always returns true and can throw TypeError (#5916)

Author: Zotis Angelis (angeliszotis) Committer: GitHub (web-flow) Pusher: lacatoire Date: 2026-10-07T12:27:50+02:00 Commit: https://github.com/php/doc-en/commit/dafe5520d24185756b98d021c52e2df65c523e31 Raw diff: https://github.com/php/doc-en/commit/dafe5520d24185756b98d021c52e2df65c523e31.diff settype(): document that it always returns true and can throw TypeError (#5916) * settype(): document that it always returns true and can throw TypeError The return values section used return.success, which says the function returns false on failure. It cannot return false. I tried an invalid type name, an array, an object and a resource, and a reference to a typed property, and it either returned true or threw. Switched to return.true.always, the entity already used by openlog(), closelog() and syslog() for the same situation. The errors section only documented the ValueError for an invalid type name. A TypeError is also thrown when var is a reference to a typed property and the converted value cannot be assigned back to the declared type. Tested on PHP 8.4.26: declare(strict_types=1); class Foo { public int $value = 123; } $foo = new Foo; $ref = &$foo->value; settype($ref, "string"); // TypeError: Cannot assign string to reference held by property // Foo::$value of type int I wrote it as "cannot be assigned under the active typing mode" instead of listing the cases, because widening still works in strict mode. With strict_types a float property set to "integer" returns true and ends up as float(1), while an int property set to "float" throws. Added a note for the coercive case, where the converted value is assigned back and gets coerced to the declared type, so the property keeps its type and the call still returns true. That is the behaviour reported in the issue that looked like a bug. Fixes #2677 * settype(): use simpara and refine the typed property note Apply @lacatoire's wording suggestion for the note and switch the three inline-only para blocks to simpara, which the DocBook style check flagged. Changed paths: M reference/var/functions/settype.xml Diff: diff --git a/reference/var/functions/settype.xml b/reference/var/functions/settype.xml index 0cf24423dc77..5fcce3378b79 100644 --- a/reference/var/functions/settype.xml +++ b/reference/var/functions/settype.xml @@ -82,9 +82,9 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; - <para> - &return.success; - </para> + <simpara> + &return.true.always; + </simpara> </refsect1> <refsect1 role="errors"> @@ -95,6 +95,14 @@ Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted and &false; was returned. </para> + <simpara> + Throws a <exceptionname>TypeError</exceptionname> if + <parameter>var</parameter> is a reference to a + <link linkend="language.oop5.properties">typed property</link> and the + converted value cannot be assigned to the declared type of that property + under the active + <link linkend="language.types.declarations.strict">typing mode</link>. + </simpara> </refsect1> <refsect1 role="changelog"> @@ -151,6 +159,17 @@ var_dump($foo, $bar); Maximum value for "int" is <constant>PHP_INT_MAX</constant>. </para> </note> + <note> + <simpara> + The converted value is assigned back to <parameter>var</parameter>, so the + usual assignment rules apply. When <parameter>var</parameter> is a + reference to a typed property and coercive typing is in effect, the + converted value is coerced back to the declared type of the property when + possible, so the type of the property does not change and + <function>settype</function> returns &true;. Otherwise a + <exceptionname>TypeError</exceptionname> is thrown. + </simpara> + </note> </refsect1> <refsect1 role="seealso">