<?xml version="1.0" encoding="utf-8"?>
<sect1 xml:id="language.types.type-juggling">
 <title>Type Juggling</title>

 <simpara>
  PHP does not require explicit type definition in variable declaration.
  In this case, the type of a variable is determined by the value it stores.
  That is to say, if a <type>string</type> is assigned to variable
  <varname>$var</varname>, then <varname>$var</varname> is of type
  <type>string</type>. If afterwards an <type>int</type> value is assigned
  to <varname>$var</varname>, it will be of type <type>int</type>.
 </simpara>

 <para>
  PHP may attempt to convert the type of a value to another automatically
  in certain contexts. The different contexts which exist are:
  <itemizedlist>
   <listitem>
    <simpara>Numeric</simpara>
   </listitem>
   <listitem>
    <simpara>String</simpara>
   </listitem>
   <listitem>
    <simpara>Logical</simpara>
   </listitem>
   <listitem>
    <simpara>Integral and string</simpara>
   </listitem>
   <listitem>
    <simpara>Comparative</simpara>
   </listitem>
   <listitem>
    <simpara>Function</simpara>
   </listitem>
  </itemizedlist>
 </para>

 <note>
  <simpara>
   When a value needs to be interpreted as a different type, the value itself
   does <emphasis>not</emphasis> change types.
  </simpara>
 </note>

 <simpara>
  To force a variable to be evaluated as a certain type, see the section on
  <link linkend="language.types.typecasting">Type casting</link>. To change the
  type of a variable, see the <function>settype</function> function.
 </simpara>

 <sect2>
  <title>Numeric contexts</title>

  <simpara>
   This is the context when using an
   <link linkend="language.operators.arithmetic">arithmetical operator</link>.
  </simpara>

  <simpara>
   In this context if either operand is a <type>float</type> (or not
   interpretable as an <type>int</type>), both operands are interpreted as
   <type>float</type>s, and the result will be a <type>float</type>.
   Otherwise, the operands will be interpreted as <type>int</type>s,
   and the result will also be an <type>int</type>.
   As of PHP 8.0.0, if one of the operands cannot be interpreted a
   <classname>TypeError</classname> is thrown.
  </simpara>
 </sect2>

 <sect2>
  <title>String contexts</title>

  <simpara>
   This is the context when using <function>echo</function>,
   <function>print</function>,
   <link linkend="language.types.string.parsing">string interpolation</link>,
   or the string
   <link linkend="language.operators.string">concatenation operator</link>.
  </simpara>

  <simpara>
   In this context the value will be interpreted as <type>string</type>.
   If the value cannot be interpreted a <classname>TypeError</classname> is thrown.
   Prior to PHP 7.4.0, an <constant>E_RECOVERABLE_ERROR</constant> was raised.
  </simpara>
 </sect2>

 <sect2>
  <title>Logical contexts</title>

  <simpara>
   This is the context when using conditional statements, the
   <link linkend="language.operators.comparison.ternary">ternary operator</link>,
   or a <link linkend="language.operators.logical">logical operator</link>.
  </simpara>

  <simpara>
   In this context the value will be interpreted as <type>bool</type>.
  </simpara>
 </sect2>

 <sect2>
  <title>Integral and string contexts</title>

  <simpara>
   This is the context when using
   <link linkend="language.operators.bitwise">bitwise operators</link>.
  </simpara>

  <simpara>
   In this context if all operands are of type <type>string</type> the result
   will also be a <type>string</type>.
   Otherwise, the operands will be interpreted as <type>int</type>s,
   and the result will also be an <type>int</type>.
   As of PHP 8.0.0, if one of the operands cannot be interpreted a
   <classname>TypeError</classname> is thrown.
  </simpara>
 </sect2>

 <sect2>
  <title>Comparative contexts</title>

  <simpara>
   This is the context when using a
   <link linkend="language.operators.comparison">comparison operator</link>.
  </simpara>

  <simpara>
   The type conversions which occur in this context are explained in the
   Comparison with Various Types
   <link linkend="language.operators.comparison.types">table</link>.
  </simpara>
 </sect2>

 <sect2 xml:id="language.types.type-juggling.function">
  <title>Function contexts</title>

  <simpara>
   This is the context when a value is passed to a typed parameter, property,
   or returned from a function which declares a return type.
  </simpara>

  <para>
   In this context the value must be a value of the type.
   Two exceptions exist, the first one is: if the value is of type
   <type>int</type> and the declared type is <type>float</type>, then the
   integer is converted to a floating point number.
   The second one is: if the declared type is a <emphasis>scalar</emphasis>
   <!-- e.g. An object that implements __toString will pass a string type -->
   type, the value is convertable to a scalar type,
   and the coercive typing mode is active
   (the default), the value may be converted to an accepted scalar value.
   See below for a description of this behaviour.
  </para>

  <warning>
   <simpara>
    <link linkend="functions.internal">Internal functions</link>
    automatically coerce &null; to scalar types,
    this behaviour is <emphasis>DEPRECATED</emphasis> as of PHP 8.1.0.
   </simpara>
  </warning>

  <sect3 xml:id="language.types.type-juggling.function.simple">
   <title>Coercive typing with simple type declarations</title>
   <itemizedlist>
    <listitem>
     <simpara>
      <type>bool</type> type declaration: value is interpreted as <type>bool</type>.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <type>int</type> type declaration: value is interpreted as <type>int</type>
      if the conversion is well-defined. For example the string is
      <link linkend="language.types.numeric-strings">numeric</link>.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <type>float</type> type declaration: value is interpreted as <type>float</type>
      if the conversion is well-defined. For example the string is
      <link linkend="language.types.numeric-strings">numeric</link>.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <type>string</type> type declaration: value is interpreted as <type>string</type>.
     </simpara>
    </listitem>
   </itemizedlist>
  </sect3>

  <sect3 xml:id="language.types.type-juggling.function.union">
   <title>Coercive typing with union types</title>
   <para>
    When <literal>strict_types</literal> is not enabled, scalar type declarations
    are subject to limited implicit type coercions.
    If the exact type of the value is not part of the union, then the target type
    is chosen in the following order of preference:

    <orderedlist>
     <listitem>
      <simpara>
       <type>int</type>
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <type>float</type>
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <type>string</type>
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <type>bool</type>
      </simpara>
     </listitem>
    </orderedlist>

    If the type exists in the union and the value can be coerced to the
    type under PHP's existing type-checking semantics, then the type is chosen.
    Otherwise, the next type is tried.
   </para>

   <caution>
    <para>
     As an exception, if the value is a string and both int and float are part
     of the union, the preferred type is determined by the existing
     <link linkend="language.types.numeric-strings">numeric string</link>
     semantics.
     For example, for <literal>"42"</literal> <type>int</type> is chosen,
     while for <literal>"42.0"</literal> <type>float</type> is chosen.
    </para>
   </caution>

   <note>
    <para>
     Types that are not part of the above preference list are not eligible
     targets for implicit coercion. In particular no implicit coercions to
     the <type>null</type>, <type>false</type>, and <type>true</type>
     types occur.
    </para>
   </note>

   <example>
    <title>Example of types being coerced into a type part of the union</title>
    <programlisting role="php">
<![CDATA[
<?php
// int|string
42    --> 42          // exact type
"42"  --> "42"        // exact type
new ObjectWithToString --> "Result of __toString()"
                      // object never compatible with int, fall back to string
42.0  --> 42          // float compatible with int
42.1  --> 42          // float compatible with int
1e100 --> "1.0E+100"  // float too large for int type, fall back to string
INF   --> "INF"       // float too large for int type, fall back to string
true  --> 1           // bool compatible with int
[]    --> TypeError   // array not compatible with int or string

// int|float|bool
"45"    --> 45        // int numeric string
"45.0"  --> 45.0      // float numeric string

"45X"   --> true      // not numeric string, fall back to bool
""      --> false     // not numeric string, fall back to bool
"X"     --> true      // not numeric string, fall back to bool
[]      --> TypeError // array not compatible with int, float or bool
?>
]]>
    </programlisting>
   </example>
  </sect3>

 </sect2>

 <sect2 xml:id="language.types.typecasting">
  <title>Type Casting</title>

  <simpara>
   Type casting converts the value to a chosen type by writing the type within
   parentheses before the value to convert.
  </simpara>

  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
$foo = 10;   // $foo is an integer
$bar = (bool) $foo;   // $bar is a boolean
?>
]]>
   </programlisting>
  </informalexample>

  <simpara>
   The casts allowed are:
  </simpara>

  <simplelist>
   <member><literal>(int)</literal> - cast to <type>int</type></member>
   <member><literal>(bool)</literal> - cast to <type>bool</type></member>
   <member><literal>(float)</literal> - cast to <type>float</type></member>
   <member><literal>(string)</literal> - cast to <type>string</type></member>
   <member><literal>(array)</literal> - cast to <type>array</type></member>
   <member><literal>(object)</literal> - cast to <type>object</type></member>
   <member><literal>(unset)</literal> - cast to <type>NULL</type></member>
  </simplelist>

  <note>
   <para>
    <literal>(integer)</literal> is an alias of the <literal>(int)</literal> cast.
    <literal>(boolean)</literal> is an alias of the <literal>(bool)</literal> cast.
    <literal>(binary)</literal> is an alias of the <literal>(string)</literal> cast.
    <literal>(double)</literal> and <literal>(real)</literal> are aliases of
    the <literal>(float)</literal> cast.
    These casts do not use the canonical type name and are not recommended.
   </para>
  </note>

  <warning>
   <simpara>
    The <literal>(real)</literal> cast alias has been deprecated as of PHP 8.0.0.
   </simpara>
  </warning>

  <warning>
   <simpara>
    The <literal>(unset)</literal> cast has been deprecated as of PHP 7.2.0.
    Note that the <literal>(unset)</literal> cast is the same as assigning the
    value <type>NULL</type> to the variable or call.
    The <literal>(unset)</literal> cast is removed as of PHP 8.0.0.
   </simpara>
  </warning>

  <caution>
   <simpara>
    The <literal>(binary)</literal> cast and <literal>b</literal> prefix exists
    for forward support. Currently <literal>(binary)</literal> and
    <literal>(string)</literal> are identical, however this may change and
    should not be relied upon.
   </simpara>
  </caution>

  <note>
   <para>
    Whitespaces are ignored within the parentheses of a cast.
    Therefore, the following two casts are equivalent:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
$foo = (int) $bar;
$foo = ( int ) $bar;
?>
]]>
     </programlisting>
    </informalexample>
   </para>
  </note>

  <informalexample>
   <simpara>
    Casting literal <type>string</type>s and variables to binary
    <type>string</type>s:
   </simpara>

   <programlisting role="php">
<![CDATA[
<?php
$binary = (binary) $string;
$binary = b"binary string";
?>
]]>
   </programlisting>
  </informalexample>

  <!-- TODO Remove or move into string context section? -->
  <note>
   <simpara>
    Instead of casting a variable to a <type>string</type>, it is also possible
    to enclose the variable in double quotes.
   </simpara>

   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
$foo = 10;            // $foo is an integer
$str = "$foo";        // $str is a string
$fst = (string) $foo; // $fst is also a string

// This prints out that "they are the same"
if ($fst === $str) {
    echo "they are the same";
}
?>
]]>
    </programlisting>
   </informalexample>
  </note>
   
  <para>
   It may not be obvious exactly what will happen when casting between certain
   types. For more information, see these sections:
   <simplelist>
    <member><link linkend="language.types.boolean.casting">Converting to boolean</link></member>
    <member><link linkend="language.types.integer.casting">Converting to integer</link></member>
    <member><link linkend="language.types.float.casting">Converting to float</link></member>
    <member><link linkend="language.types.string.casting">Converting to string</link></member>
    <member><link linkend="language.types.array.casting">Converting to array</link></member>
    <member><link linkend="language.types.object.casting">Converting to object</link></member>
    <member><link linkend="language.types.resource.casting">Converting to resource</link></member>
    <member><link linkend="language.types.null.casting">Converting to NULL</link></member>
    <member><link linkend="types.comparisons">The type comparison tables</link></member>
   </simplelist>
  </para>

  <note>
   <simpara>
    Because PHP supports indexing into <type>string</type>s via offsets
    using the same syntax as <type>array</type> indexing, the following example
    holds true for all PHP versions:
   </simpara>

   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
$a    = 'car'; // $a is a string
$a[0] = 'b';   // $a is still a string
echo $a;       // bar
?>
]]>
    </programlisting>
   </informalexample>

   <simpara>
    See the section titled <link linkend="language.types.string.substr">String
    access by character</link> for more information.
   </simpara>
  </note>
 </sect2>

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