archived-doc-fr/language/types/array.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 3061900171d4ae84d532571bfd6eda823726dad4 Maintainer: yannick Status: ready -->
<!-- Reviewed: no -->
<sect1 xml:id="language.types.array">
 <title>Les tableaux</title>

 <para>
  Pour une liste de toutes les fonctions de tableau, voir le chapitre <link linkend="ref.array">fonctions de tableau</link> dans la documentation.
 </para>

 <para>
  Un tableau en PHP est en fait une carte ordonnée. Une carte est un type
  qui associe des <emphasis>valeurs</emphasis> à des <emphasis>clés</emphasis>.
  Ce type est optimisé pour différentes utilisations ; il peut être considéré
  comme un tableau, une liste, une table de hachage, un dictionnaire, une
  collection, une pile, une file d'attente et probablement plus. On peut avoir,
  comme valeur d'un tableau, d'autres tableaux, multidimensionnels ou non.
 </para>

 <para>
  La structure de ces données dépasse l'objet de ce manuel, mais au moins
  un exemple est fourni pour chacun des cas évoqués. Pour plus d'informations,
  se reporter aux différentes explications sur le sujet que l'on trouve
  sur le web.
 </para>

 <sect2 xml:id="language.types.array.syntax">
  <title>Syntaxe</title>

  <sect3 xml:id="language.types.array.syntax.array-func">
   <title>Syntaxe d'un tableau</title>

   <para>
    Un tableau peut être créé en utilisant la structure de langage
    <function>array</function>. Il prend un nombre illimité de paramètres,
    chacun séparé par une virgule, sous la forme d'une paire
    <literal><replaceable>key</replaceable> =&gt;
    <replaceable>value</replaceable></literal>.
   </para>

   <synopsis>
array(
    <optional><replaceable>key</replaceable>  =&gt; </optional><replaceable>value</replaceable>,
    <optional><replaceable>key2</replaceable> =&gt; </optional><replaceable>value2</replaceable>,
    <optional><replaceable>key3</replaceable> =&gt; </optional><replaceable>value3</replaceable>,
    ...
)</synopsis>
   <!-- Do not fix the whitespace for the synopsis end element. A limitation of PhD prevents proper trimming -->

   <para>
    La virgule après le dernier élément d'un tableau
    est optionnelle et peut ne pas être ajoutée. C'est généralement ce qui
    est fait pour les tableaux sur une seule ligne, i.e.
    <literal>array(1, 2)</literal> est préféré à <literal>array(1, 2, )</literal>.
    Pour les tableaux sur plusieurs lignes, la virgule finale est généralement
    utilisée, car elle permet d'ajouter plus facilement de nouveaux éléments à
    la fin.
   </para>

   <note>
    <para>
     Une syntaxe de tableau courte existe qui remplace
     <literal>array()</literal> par <literal>[]</literal>.
    </para>
   </note>

   <example>
    <title>Un tableau simple</title>
    <programlisting role="php">
<![CDATA[
<?php
$array1 = array(
    "foo" => "bar",
    "bar" => "foo",
);

// Utilisant la syntaxe de tableau courte
$array2 = [
    "foo" => "bar",
    "bar" => "foo",
];
?>
]]>
    </programlisting>
   </example>
   
   <para xml:id="language.types.array.key-casts">
    La clé <replaceable>key</replaceable> peut être soit un <type>int</type>,
    soit une &string;. La valeur <replaceable>value</replaceable> peut être
    de n'importe quel type.
   </para>
   
   <para>
    De plus, les modifications de type suivantes surviendront pour la clé <replaceable>key</replaceable> :
    <itemizedlist>
     <listitem>
      <simpara>
       Les chaînes de caractères contenant un entier valide, sauf si le nombre 
       est précédé d'un signe <literal>+</literal> seront modifiées en un type
       entier. I.e. la clé <literal>"8"</literal> sera actuellement stockée comme
       l'entier <literal>8</literal>. D'un autre côté, <literal>"08"</literal> ne sera
       pas modifié, sachant que ce n'est pas un entier décimal valide.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Les nombres à virgule flottante seront aussi modifiés en entier, ce qui signifie
       que la partie après la virgule sera tronquée. I.e. la clé <literal>8.7</literal>
       sera stockée sous l'entier <literal>8</literal>.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Les booléens seront modifiés en entier également, i.e. la clé
       &true; sera stockée sous l'entier <literal>1</literal>
       et la clé &false; sous l'entier <literal>0</literal>.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       La valeur <type>Null</type> sera modifiée en une chaîne vide, i.e. la clé
       <literal>null</literal> sera stockée sous la chaîne de caractères <literal>""</literal>.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Les tableaux et les objets <emphasis>ne peuvent pas</emphasis> être utilisés comme clé.
       Toute tentative en ce sens émettra l'alerte suivante : <literal>Illegal offset type</literal>.
      </simpara>
     </listitem>
    </itemizedlist>
   </para>
   
   <para>
    Si plusieurs éléments dans la déclaration d'un tableau utilisent la même clé,
    seule la dernière sera utilisée, écrasant ainsi toutes les précédentes.
   </para>
   
   <example>
    <title>Exemple sur la modification de type et l'écrasement</title>
    <programlisting role="php">
<![CDATA[
<?php
$array = array(
    1    => "a",
    "1"  => "b",
    1.5  => "c",
    true => "d",
);
var_dump($array);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
array(1) {
  [1]=>
  string(1) "d"
}
]]>
    </screen>
    <para>
     Vu que toutes les clés de l'exemple ci-dessus sont modifiées en l'entier
     <literal>1</literal>, la valeur sera écrasée sur chaque nouvel élément,
     et seul le dernier dont la valeur assignée est <literal>"d"</literal> sera
     conservé.
    </para>
   </example>
   
   <para>
    Les tableaux PHP peuvent contenir des clés de type 
    <type>int</type> et <type>string</type> en même temps,
    vu que PHP ne distingue pas les tableaux indexés et les tableaux associatifs.
   </para>

   <example>
    <title>Exemple avec des clés de type <type>int</type> et <type>string</type></title>
    <programlisting role="php">
<![CDATA[
<?php
$array = array(
    "foo" => "bar",
    "bar" => "foo",
    100   => -100,
    -100  => 100,
);
var_dump($array);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
array(4) {
  ["foo"]=>
  string(3) "bar"
  ["bar"]=>
  string(3) "foo"
  [100]=>
  int(-100)
  [-100]=>
  int(100)
}
]]>
    </screen>
   </example>
   
   <para>
    La clé <replaceable>key</replaceable> est optionnelle. Si elle n'est
    pas spécifiée, PHP utilisera un incrément de la dernière clé entière utilisée.
   </para>
   
   <example>
    <title>Tableaux indexés sans clé</title>
    <programlisting role="php">
<![CDATA[
<?php
$array = array("foo", "bar", "hello", "world");
var_dump($array);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
array(4) {
  [0]=>
  string(3) "foo"
  [1]=>
  string(3) "bar"
  [2]=>
  string(5) "hello"
  [3]=>
  string(5) "world"
}
]]>
    </screen>
   </example>
   
   <para>
    Il est possible de spécifier la clé seulement pour quelques éléments
    et ne pas la fournir pour d'autres :
   </para>
   
   <example>
    <title>Exemple avec des clés seulement pour quelques éléments</title>
    <programlisting role="php">
<![CDATA[
<?php
$array = array(
         "a",
         "b",
    6 => "c",
         "d",
);
var_dump($array);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
array(4) {
  [0]=>
  string(1) "a"
  [1]=>
  string(1) "b"
  [6]=>
  string(1) "c"
  [7]=>
  string(1) "d"
}
]]>
    </screen>
    <para>
     Comme on peut le voir, la dernière valeur <literal>"d"</literal>
     a été assignée à la clé <literal>7</literal>. Ceci est dû au fait que
     la dernière clé entière la plus grande utilisée auparavant était <literal>6</literal>.
    </para>
   </example>

   <example>
    <title>Exemple complexe sur la modification de type et l'écrasement</title>
    <para>
     Cet exemple inclut toutes les variations de modification de type de clés
     et écrasements des éléments.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
$array = array(
    1    => 'a',
    '1'  => 'b', // la valeur "a" sera écrasée par "b"
    1.5  => 'c', // la valeur "b" sera écrasée par "c"
    -1 => 'd',
    '01'  => 'e', // comme ceci n'est pas une chaîne de caractères entière elle n'écrasera PAS la clé pour 1
    '1.5' => 'f', // comme ceci n'est pas une chaîne de caractères entière elle n'écrasera pas la clé pour 1
    true => 'g', // la valeur "c" sera écrasée par "g"
    false => 'h',
    '' => 'i',
    null => 'j', // la valeur "i" sera écrasée par "j"
    'k', // la valeur "k" est assignée à la clé 2. Ceci est dû au fait que la dernière clé entière la plus grande utilisée auparavant était 1
    2 => 'l', // la valeur "k" sera écrasée par "l"
);
var_dump($array);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
array(7) {
  [1]=>
  string(1) "g"
  [-1]=>
  string(1) "d"
  ["01"]=>
  string(1) "e"
  ["1.5"]=>
  string(1) "f"
  [0]=>
  string(1) "h"
  [""]=>
  string(1) "j"
  [2]=>
  string(1) "l"
}
]]>
    </screen>
   </example>
   <example>
    <title>Exemple d'index négatif</title>
    <simpara>
     Lorsqu'une clé entière négative <literal>n</literal> est assignée, PHP prendra soin
     d'assigner la clé suivante à <literal>n+1</literal>.
    </simpara>
    <programlisting role="php">
<![CDATA[
<?php
$array = [];

$array[-5] = 1;
$array[] = 2;

var_dump($array);
?>
]]>
    </programlisting>
     &example.outputs;
    <screen>
<![CDATA[
array(2) {
  [-5]=>
  int(1)
  [-4]=>
  int(2)
}
]]>
    </screen>

    <warning>
     <simpara>
      Avant PHP 8.3.0, l'assignation d'une clé entière négative <literal>n</literal>
      assignait la clé suivante à <literal>0</literal>. L'exemple précédent aurait
      donc produit :
     </simpara>
     <informalexample>
      <screen>
<![CDATA[
array(2) {
  [-5]=>
  int(1)
  [0]=>
  int(2)
}
]]>
      </screen>
     </informalexample>
    </warning>
   </example>
  </sect3>
  
  <sect3 xml:id="language.types.array.syntax.accessing">
   <title>Accès aux éléments d'un tableau en utilisant la syntaxe à base
    de crochets</title>
   
   <para>
    Les éléments d'un tableau peuvent être accédés en utilisant
    la syntaxe <literal>array[key]</literal>.
   </para>
   
   <example>
    <title>Accès aux éléments d'un tableau</title>
    <programlisting role="php">
<![CDATA[
<?php
$array = array(
    "foo" => "bar",
    42    => 24,
    "multi" => array(
         "dimensional" => array(
             "array" => "foo"
         )
    )
);

var_dump($array["foo"]);
var_dump($array[42]);
var_dump($array["multi"]["dimensional"]["array"]);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
string(3) "bar"
int(24)
string(3) "foo"
]]>
    </screen>
   </example>

   <note>
    <para>
     Avant PHP 8.0.0, les crochets et accolades pouvaient être utilisés de
     façon interchangeable pour accéder aux éléments d'un tableau (e.g.
     <literal>$array[42]</literal> et <literal>$array{42}</literal> feraient
     tous deux la même chose dans l'exemple ci-dessus).
     La syntaxe avec les accolades a été rendue obsolète en PHP 7.4.0 et n'est
     plus supportée à partir de PHP 8.0.0.
    </para>
   </note>

   <example>
    <title>Faire référence à un tableau à la sortie d'une fonction ou d'une méthode</title>
    <programlisting role="php">
<![CDATA[
<?php
function getArray() {
    return array(1, 2, 3);
}

$secondElement = getArray()[1];

var_dump($secondElement);
?>
]]>
    </programlisting>
   </example>
   
   <note>
    <para>
     Une tentative d'accès à une clé d'un tableau qui n'a pas été définie
     revient à tenter d'accéder à une variable non définie : une alerte de
     niveau <constant>E_WARNING</constant> sera émise (E_NOTICE avant PHP 8.0.0),
     et le résultat vaudra &null;.
    </para>
   </note>
   <note>
    <para>
     Faire référence à un tableau à la sortie d'une fonction ou d'une méthode 
     d'une valeur scalaire qui n'est pas une &string; génère &null;.
     Avant PHP 7.4.0, ceci ne générait pas de message d'erreur.
     À partir de PHP 7.4.0, ceci émet une <constant>E_NOTICE</constant> ;
     À partir de PHP 8.0.0, ceci émet une <constant>E_WARNING</constant>.
    </para>
   </note>
  </sect3>

  <sect3 xml:id="language.types.array.syntax.modifying">
   <title>Création/modification avec des crochets</title>

   <para>
    Un tableau existant peut être modifié en y assignant explicitement des valeurs.
   </para>

   <para>
    L'assignation d'une valeur dans un tableau est effectué en spécifiant
    la clé, entre crochets. La clé peut également ne pas être renseignée, sous
    la forme : <literal>[]</literal>.
   </para>

   <synopsis>
$arr[<replaceable>clé</replaceable>] = <replaceable>valeur</replaceable>;
$arr[] = <replaceable>valeur</replaceable>;
// <replaceable>clé</replaceable> peut être un &integer; ou une &string;
// <replaceable>valeur</replaceable> peut être n'importe quel type</synopsis>

   <para>
    Si lors de l'assignation <varname>$arr</varname> n'existe pas ou est défini
    à &null; ou &false;, il sera créé ; c'est ainsi une façon détournée de créer un tableau.
    Cette pratique est cependant découragée car si <varname>$arr</varname>
    contient déjà quelques valeurs (i.e. <type>string</type> depuis la variable demandée)
    alors cette valeur restera en place et <literal>[]</literal> peut attendre
    un <link linkend="language.types.string.substr">opérateur d'accès
    sur une chaîne</link>. C'est toujours un meilleur choix que d'initialiser
    une variable par affectation directe.
   </para>
   <note>
    <simpara>
     À partir de PHP 7.1.0, l'application de l'opérateur d'index vide sur une 
     chaîne lève une erreur fatale. Auparavant, la chaîne aurait été convertie 
     silencieusement en tableau.
    </simpara>
   </note>
   <note>
    <simpara>
     À partir de PHP 8.1.0, créer un nouveau tableau à partir de &false; est obsolète.
     Créer un nouveau tableau depuis &null; et les valeurs indéfinies est toujours autorisé.
    </simpara>
   </note>

   <para>
    Pour modifier une valeur en particulier, il convient d'assigner une valeur en spécifiant
    sa clé. Pour effacer une paire clé/valeur, il convient d'appeler la fonction
    <function>unset</function> sur la clé désirée.
   </para>

   <example>
    <title>Utilisation des crochets avec les tableaux</title>
    <programlisting role="php">
<![CDATA[
<?php
$arr = array(5 => 1, 12 => 2);

$arr[] = 56;    // Identique à $arr[13] = 56;
                // à cet endroit du script

$arr["x"] = 42; // Ceci ajoute un nouvel élément au
                // tableau avec la clé "x"

var_dump($arr);

unset($arr[5]); // Ceci efface l'élément du tableau

unset($arr);    // Ceci efface complètement le tableau

var_dump($arr);
?>
]]> 
    </programlisting>
   </example>

   <note>
    <para>
     Comme dit plus haut, si aucune clé n'est spécifiée, l'indice maximal
     existant est repris, et la nouvelle clé sera ce nombre, plus 1 (mais au moins 0).
     Si aucun indice entier n'existe, la clé sera <literal>0</literal> (zéro).
    </para>

    <para>
     Il est à noter que la clé entière maximale pour cette opération <emphasis>n'a
     pas besoin d'exister dans le tableau au moment de la manipulation</emphasis>.
     Elle doit seulement avoir existé dans le tableau à un moment ou un autre
     depuis la dernière fois où le tableau a été ré-indexé.
     Voici un exemple qui illustre ce principe :
    </para>

    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
// Création d'un tableau simple.
$array = array(1, 2, 3, 4, 5);
print_r($array);

// Maintenant, on efface tous les éléments, mais on conserve le tableau :
foreach ($array as $i => $value) {
    unset($array[$i]);
}
print_r($array);

// Ajout d'un élément (notez que la nouvelle clé est 5, et non 0).
$array[] = 6;
print_r($array);

// Ré-indexation :
$array = array_values($array);
$array[] = 7;
print_r($array);
?>
]]> 
     </programlisting>
     &example.outputs;
     <screen>
<![CDATA[
Array
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)
Array
(
)
Array
(
    [5] => 6
)
Array
(
    [0] => 6
    [1] => 7
)
]]>
     </screen>
    </informalexample>

   </note>

  </sect3>

  <sect3 xml:id="language.types.array.syntax.destructuring">
   <title>Déstructuration de tableau</title>

   <para>
    Les tableaux peuvent être déstructurés en utilisant <literal>[]</literal>
    (à partir de PHP 7.1.0) ou <function>list</function>.
    Ces constructions peuvent être utilisées pour déstructurer un tableau en variables distinctes.
   </para>

   <example>
    <title>Déstructuration de tableau</title>
    <programlisting role="php">
<![CDATA[
<?php
$tableau_source = ['foo', 'bar', 'baz'];

[$foo, $bar, $baz] = $tableau_source;

echo $foo, PHP_EOL;    // affiche "foo"
echo $bar, PHP_EOL;    // affiche "bar"
echo $baz, PHP_EOL;    // affiche "baz"
?>
]]>
    </programlisting>
   </example>

   <para>
    La déstructuration de tableau peut être utilisée dans un &foreach;
    pour déstructurer un tableau multidimensionnel tout en itérant sur celui-ci.
   </para>

   <example>
    <title>Déstructuration de tableau dans un foreach</title>
    <programlisting role="php">
<![CDATA[
<?php
$tableau_source = [
    [1, 'John'],
    [2, 'Jane'],
];

foreach ($tableau_source as [$id, $name]) {
    echo "{$id}: '{$name}'\n";
}
?>
]]>
    </programlisting>
   </example>

   <para>
    Les éléments du tableau seront ignorés si la variable n'est pas fournie.
    Le tableau commence toujours à l'index <literal>0</literal>.
   </para>

   <example>
    <title>Ignorer des éléments</title>
    <programlisting role="php">
<![CDATA[
<?php
$tableau_source = ['foo', 'bar', 'baz'];

// Assigne l'élément situé à l'indice 2 à la variable $baz 
[, , $baz] = $tableau_source;

echo $baz;    // Affiche "baz"
?>
]]>
    </programlisting>
   </example>

   <para>
    A partir de PHP 7.1.0, les tableaux associatifs peuvent aussi être déstructurés.
    Cela permet de sélectionner plus facilement le bon élément dans les tableaux
    à indexation numérique, car l'index peut être explicitement spécifié.
   </para>

   <example>
    <title>Déstructuration de tableau associatif</title>
    <programlisting role="php">
<![CDATA[
<?php
$tableau_source = ['foo' => 1, 'bar' => 2, 'baz' => 3];

// Assigne l'élément situé à l'indice 'baz' à la variable $three
['baz' => $three] = $tableau_source;

echo $three, PHP_EOL;    // Affiche "3"

$tableau_source = ['foo', 'bar', 'baz'];

// Assigne l'élément situé à l'indice 2 à la variable $baz
[2 => $baz] = $tableau_source;

echo $baz, PHP_EOL;    // Affiche "baz"
?>
]]>
    </programlisting>
   </example>

   <para>
    La déstructuration de tableau peut être utilisée pour permuter facilement
    deux variables.
   </para>

   <example>
    <title>Permuter deux variables</title>
    <programlisting role="php">
<![CDATA[
<?php
$a = 1;
$b = 2;

[$b, $a] = [$a, $b];

echo $a, PHP_EOL;    // Affiche 2
echo $b, PHP_EOL;    // Affiche 1
?>
]]>
    </programlisting>
   </example>

   <note>
    <para>
     L'opérateur de décomposition (<literal>...</literal>) n'est pas
     supporté dans les assignations.
    </para>
   </note>

   <note>
    <para>
     Une tentative d'accès à une clé d'un tableau qui n'a pas été définie
     revient à tenter d'accéder à une variable non définie : une alerte de
     niveau <constant>E_WARNING</constant> sera émise (E_NOTICE avant PHP 8.0.0),
     et le résultat vaudra &null;.
    </para>
   </note>
   <note>
    <para>
     La déstructuration d’une valeur scalaire affecte &null; à toutes les variables.
    </para>
   </note>
  </sect3>

 </sect2><!-- end syntax -->

 <sect2 xml:id="language.types.array.useful-funcs">
  <title>Fonctions utiles</title>

  <para>
   Il y a beaucoup de fonctions utiles pour travailler avec les tableaux.
   Il est recommandé de lire la section de ce manuel sur les
   <link linkend="ref.array">fonctions</link> en rapport avec les tableaux.
  </para>

  <note>
   <para>
    La fonction <function>unset</function> permet d'effacer les clés d'un tableau.
    Soyez attentif sur le fait que le tableau ne sera <emphasis>pas</emphasis>
    ré-indexé. Pour réaliser un effacement complet et une ré-indexation
    du tableau, il faut utiliser la fonction
    <function>array_values</function>.
   </para>

   <example>
    <title>Effacer des éléments intermédiaires</title>
    <programlisting role="php">
<![CDATA[
<?php
$a = array(1 => 'one', 2 => 'two', 3 => 'three');

/* produira un tableau comme ceci
   $a = array(1 => 'one', 3 => 'three');
   et NON un tableau comme ceci
   $a = array(1 => 'one', 2 =>'three');
*/
unset($a[2]);
var_dump($a);

$b = array_values($a);
// Maintenant, $b vaut array(0 => 'one', 1 =>'three')
var_dump($b);
?>
]]>
    </programlisting>
   </example>
  </note>

  <para>
   La structure de contrôle &foreach; existe tout spécialement 
   pour les tableaux. Elle fournit une manière pratique
   de parcourir un tableau.
  </para>
 </sect2>

 <sect2 xml:id="language.types.array.donts">
  <title>Ce qu'il est possible de faire ou non avec un tableau</title>

  <sect3 xml:id="language.types.array.foo-bar">
   <title>Pourquoi <literal>$foo[bar]</literal> est incorrect ?</title>

   <para>
    Utiliser toujours des guillemets autour d'un index littéral. Par exemple,
    <literal>$foo['bar']</literal> est correct, alors que
    <literal>$foo[bar]</literal> ne l'est pas. Mais pourquoi ? il est courant
    de rencontrer ce genre de syntaxe dans d'anciens scripts :
   </para>

   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
$foo[bar] = 'enemy';
echo $foo[bar];
// etc
?>
]]>
    </programlisting>
   </informalexample>

   <para>
    C'est incorrect, mais ça fonctionne. La raison est que ce code a une constante
    indéfinie (<literal>bar</literal>) plutôt qu'une &string;
    (<literal>'bar'</literal> - notez les guillemets).
    Cela fonctionne car PHP convertit automatiquement une <emphasis>chaîne nue</emphasis>
    (une chaîne sans guillemets qui ne correspond à aucun symbole connu) en une chaîne
    qui la contient. Actuellement, s'il n'y a aucune constante nommée <constant>bar</constant>,
    alors PHP substituera <literal>'bar'</literal> dans la chaîne et l'utilisera.
   </para>
   
   <warning>
    <simpara>
     La solution de recours qui considère une constante non-définie comme une
     chaîne de caractères nu est une erreur de niveau <constant>E_NOTICE</constant>.
     Ceci est obsolète à partir de PHP 7.2.0, et émet une erreur de niveau
     <constant>E_WARNING</constant>.
     À partir de PHP 8.0.0, ceci a été retiré et lance une exception
     <classname>Error</classname>.
    </simpara>
   </warning>

   <simpara>
    Ceci ne signifie pas qu'il faut <emphasis>toujours</emphasis> mettre la clé entre guillemets.
    N'utilisez pas de guillemets avec les clés qui sont des
    <link linkend="language.constants">constantes</link> ou des
    <link linkend="language.variables">variables</link>, car cela empêcherait PHP de
    les interpréter.
   </simpara>

   <example>
    <title>Clé entre guillemets</title>
    <programlisting role="php">
<![CDATA[
<?php
error_reporting(E_ALL);
ini_set('display_errors', true);
ini_set('html_errors', false);

// Tableau simple :
$array = array(1, 2);
$count = count($array);

for ($i = 0; $i < $count; $i++) {
    echo "\nVérification de $i : \n";
    echo "Mauvais : " . $array['$i'] . "\n";
    echo "Bon : " . $array[$i] . "\n";
    echo "Mauvais : {$array['$i']}\n";
    echo "Bon : {$array[$i]}\n";
}
?>
]]>
     </programlisting>
    </example>
    &example.outputs;
    <screen>
<![CDATA[
Vérification de 0 :
Notice: Undefined index:  $i in /path/to/script.html on line 9
Mauvais :
Bon : 1
Notice: Undefined index:  $i in /path/to/script.html on line 11
Mauvais :
Bon : 1

Vérification de 1 :
Notice: Undefined index:  $i in /path/to/script.html on line 9
Mauvais :
Bon : 2
Notice: Undefined index:  $i in /path/to/script.html on line 11
Mauvais :
Bon : 2
]]>
   </screen>

   <para>
    Plus d'exemples pour expliquer ce comportement :
   </para>

   <example>
    <title>Plus d'exemples</title>
    <programlisting role="php">
<![CDATA[
<?php
// Affichons toutes les erreurs
error_reporting(E_ALL);

$arr = array('fruit' => 'apple', 'veggie' => 'carrot');

// Correct
echo $arr['fruit'], PHP_EOL;  // apple
echo $arr['veggie'], PHP_EOL; // carrot

// Incorrect. Ceci ne fonctionne pas et lance une erreur PHP
// on utilise la constante nommée fruit qui est indéfinie
// 
// Error: Undefined constant "fruit"
try {
    echo $arr[fruit];
} catch (Error $e) {
    echo get_class($e), ': ', $e->getMessage(), PHP_EOL;
}

// Ceci définit une constante pour expliquer ce qu'il ne va pas. La valeur 'veggie'
// est assignée à la constante nommée fruit.
define('fruit', 'veggie');

// Noter la différence maintenant
echo $arr['fruit'], PHP_EOL;  // apple
echo $arr[fruit], PHP_EOL;    // carrot

// Ce qui suit est correct, car c'est dans une chaîne. Les constantes ne sont pas recherchées
// dans les chaînes, et donc, aucune erreur ne sera émise
echo "Hello $arr[fruit], PHP_EOL";      // Hello apple

// Avec une exception : les parenthèses autour d'un tableau dans une chaîne permettent
// aux constantes d'être interprétées
echo "Hello {$arr[fruit]}", PHP_EOL;    // Hello carrot
echo "Hello {$arr['fruit']}", PHP_EOL;  // Hello apple

// La concaténation est une autre solution
echo "Hello " . $arr['fruit'], PHP_EOL; // Hello apple
?>
]]>
    </programlisting>
   </example>

   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
// Ceci ne fonctionnera pas, et en résultera une erreur d'analyse, comme ceci :
// Parse error: parse error, expecting T_STRING' or T_VARIABLE' or T_NUM_STRING'
// Ceci arrive lors de l'utilisation d'une superglobales dans les chaînes
print "Hello $arr['fruit']";
print "Hello $_GET['foo']";
?>
]]>
    </programlisting>
   </informalexample>

   <para>
    Comme vu dans la section "<link linkend="language.types.array.syntax">syntaxe</link>",
    ce qui se trouve entre crochets ('<literal>[</literal>' et
    '<literal>]</literal>') doit être une expression. Ceci signifie que le code ci-dessous
    fonctionne :
   </para>

   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
echo $arr[somefunc($bar)];
?>
]]>
    </programlisting>
   </informalexample>

   <para>
    C'est un exemple d'utilisation d'une fonction retournant une valeur qui sera
    la clé du tableau. PHP comprend également les constantes :
   </para>

   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
$error_descriptions[E_ERROR]   = "A fatal error has occurred";
$error_descriptions[E_WARNING] = "PHP issued a warning";
$error_descriptions[E_NOTICE]  = "This is just an informal notice";
?>
]]>
    </programlisting>
   </informalexample>

   <para>
    Noter que <constant>E_ERROR</constant> est également un identifiant valide,
    tout comme <literal>bar</literal> dans le premier exemple. Mais le dernier
    exemple est finalement le même que celui-ci :
   </para>

   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
$error_descriptions[1] = "A fatal error has occurred";
$error_descriptions[2] = "PHP issued a warning";
$error_descriptions[8] = "This is just an informal notice";
?>
]]>
    </programlisting>
   </informalexample>
   
   <para>
    car <constant>E_ERROR</constant> vaut <literal>1</literal>, etc.
   </para>

   <sect4 xml:id="language.types.array.foo-bar.why">
    <title>Alors, pourquoi est-ce une mauvaise pratique ?</title>

    <para>
     Dans le futur, les développeurs PHP peuvent vouloir ajouter une autre
     constante ou un autre mot clé, ou bien une constante dans une autre partie
     du code qui peut interférer. Par exemple, il est toujours incorrect d'utiliser
     le mot <literal>empty</literal> et <literal>default</literal>, sachant que ce sont
     des <link linkend="reserved">mots réservés</link>.
    </para>

    <note>
     <simpara>
      Pour être plus clair, dans une chaîne entourée de guillemets doubles,
      il est valide de ne pas entourer les index d'un tableau avec des
      guillemets, et donc, <literal>"$foo[bar]"</literal> est valide. Voir
      les exemples ci-dessous pour plus de détails mais aussi la section sur
      l'<link linkend="language.types.string.parsing">analyse des variables
      dans les chaînes</link>.
     </simpara>
    </note>

   </sect4>
  </sect3>
 </sect2>

 <sect2 xml:id="language.types.array.casting">
  <title>Conversion en un tableau</title>

  <para>
   Pour tous les types &integer;, &float;, &string;, &boolean; et &resource;,
   le fait de convertir une valeur en un tableau résulte en un tableau contenant
   un seul élément dont l'indexe vaut zéro et la valeur, une valeur scalaire convertie.
   En d'autres termes, <code>(array) $scalarValue</code> est exactement la
   même chose que <literal>array($scalarValue)</literal>.
  </para>

  <para>
   Si un objet est converti en un tableau, le résultat sera un tableau dont les
   éléments sont les propriétés de l'objet. Les clés sont les noms des membres,
   avec une légère exception : les variables ayant un nom sous forme d'entier sont
   inaccessibles ; les variables privées auront le nom de la classe
   ajouté au nom de la variable ; les variables protégées auront un '*' ajouté
   au nom de la variable.
   Ces valeurs préfixées ont des octets <literal>NUL</literal> des deux côtés.
   Les <link linkend="language.oop5.properties.typed-properties">propriétés typées</link>
   non-initialisées sont silencieusement écartées.
  </para>

  <example>
   <title>Conversion en tableau</title>
   <programlisting role="php">
<![CDATA[
<?php
class A {
    private $B;
    protected $C;
    public $D;
    function __construct()
    {
        $this->{1} = null;
    }
}
var_export((array) new A());
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
array (
  '' . "\0" . 'A' . "\0" . 'B' => NULL,
  '' . "\0" . '*' . "\0" . 'C' => NULL,
  'D' => NULL,
  1 => NULL,
)
]]>
   </screen>
  </example>

  <para>
   Ces octets <literal>NUL</literal> peuvent amener à des résultats inattendus :
  </para>

  <example>
   <title>Conversion d'un objet en tableau</title>
   <programlisting role="php">
<![CDATA[
<?php

class A {
    private $A; // Ceci devient '\0A\0A'
}

class B extends A {
    private $A; // Ceci devient '\0B\0A'
    public $AA; // Ceci devient 'AA'
}

var_dump((array) new B());
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
array(3) {
  ["BA"]=>
  NULL
  ["AA"]=>
  NULL
  ["AA"]=>
  NULL
}
]]>
   </screen>
  </example>

  <para>
   Ici, on pourrait penser qu'il y a 2 clés nommées 'AA', alors qu'une est
   actuellement nommée '\0A\0A'.
  </para>

  <para>
   La conversion de &null; en un tableau résultat en un tableau vide.
  </para>
 </sect2>

 <sect2 xml:id="language.types.array.comparing">
  <title>Comparaison</title>

  <para>
   Il est possible de comparer plusieurs tableaux avec la fonction
   <function>array_diff</function> ainsi qu'avec les
   <link linkend="language.operators.array">opérateurs de tableaux</link>.
  </para>
 </sect2>

 <sect2 xml:id="language.types.array.unpacking">
  <title>Déballage des tableaux</title>

  <para>
   Un tableau préfixé par <code>...</code> sera déballé sur place lors de la définition du tableau.
   Seuls les tableaux et les objets qui implémentent <interfacename>Traversable</interfacename> peuvent être déballés.
   Le déballage de tableau avec <code>...</code> est disponible à partir de PHP 7.4.0. C'est aussi appelé l'opérateur de décomposition.
  </para>

  <para>
   Il est possible de déballer plusieurs fois, et d'ajouter des éléments
   normaux avant et après l'opérateur <code>...</code> :

   <example>
    <title>Déballage simple de tableau</title>
    <programlisting role="php">
<![CDATA[
<?php
// Utilisation de la syntaxe de tableau courte.
// Fonctionne avec array() aussi.
$arr1 = [1, 2, 3];
$arr2 = [...$arr1]; // [1, 2, 3]
$arr3 = [0, ...$arr1]; // [0, 1, 2, 3]
$arr4 = [...$arr1, ...$arr2, 111]; // [1, 2, 3, 1, 2, 3, 111]
$arr5 = [...$arr1, ...$arr1]; // [1, 2, 3, 1, 2, 3]

function getArr() {
  return ['a', 'b'];
}
$arr6 = [...getArr(), 'c' => 'd']; // ['a', 'b', 'c' => 'd']

var_dump($arr1, $arr2, $arr3, $arr4, $arr5, $arr6);
?>
]]>
    </programlisting>
   </example>
  </para>

  <para>
   Déballer un tableau avec l'opérateur <code>...</code> suit les sémantiques de la fonction <function>array_merge</function>.
   C'est-à-dire, que les clés ultérieures écrasent les valeurs antérieures
   et les clés numériques sont renumérotées :

   <example>
    <title>Déballage de tableau avec clé dupliqué</title>
    <programlisting role="php">
<![CDATA[
<?php
// string key
$arr1 = ["a" => 1];
$arr2 = ["a" => 2];
$arr3 = ["a" => 0, ...$arr1, ...$arr2];
var_dump($arr3); // ["a" => 2]

// integer key
$arr4 = [1, 2, 3];
$arr5 = [4, 5, 6];
$arr6 = [...$arr4, ...$arr5];
var_dump($arr6); // [1, 2, 3, 4, 5, 6]
// Which is [0 => 1, 1 => 2, 2 => 3, 3 => 4, 4 => 5, 5 => 6]
// where the original integer keys have not been retained.
?>
]]>
    </programlisting>
   </example>
  </para>

  <note>
   <para>
    Les clés qui ne sont ni des entiers, ni des chaînes lancent une <classname>TypeError</classname>.
    De telles clés peuvent uniquement être générées par un objet <interfacename>Traversable</interfacename>.
   </para>
  </note>
  <note>
   <para>
    Avant PHP 8.1, le déballage de tableau qui avait une clé sous forme de chaîne n'est pas supporté :
   </para>
   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php

$arr1 = [1, 2, 3];
$arr2 = ['a' => 4];
$arr3 = [...$arr1, ...$arr2];
// Fatal error: Uncaught Error: Cannot unpack array with string keys in example.php:5

$arr4 = [1, 2, 3];
$arr5 = [4, 5];
$arr6 = [...$arr4, ...$arr5]; // works. [1, 2, 3, 4, 5]
?>
]]>
    </programlisting>
   </informalexample>
  </note>

 </sect2>

 <sect2 xml:id="language.types.array.examples">
  <title>Exemples</title>

  <para>
   Le type tableau en PHP est vraiment polyvalent. Voici quelques exemples :
  </para>

  <example>
   <title>Versatilité d'un tableau</title>
   <programlisting role="php">
<![CDATA[
<?php
// Ceci
$a = array( 'color' => 'red',
            'taste' => 'sweet',
            'shape' => 'round',
            'name'  => 'apple',
             4        // la clé sera 0
          );
      
$b = array('a', 'b', 'c');

var_dump($a, $b);

// est strictement équivalent à
$a = array();
$a['color'] = 'red';
$a['taste'] = 'sweet';
$a['shape'] = 'round';
$a['name']  = 'apple';
$a[]        = 4;        // la clé sera 0

$b = array();
$b[] = 'a';
$b[] = 'b';
$b[] = 'c';

// Après exécution du code ci-dessus, $a sera le tableau
// array('color' => 'red', 'taste' => 'sweet', 'shape' => 'round', 
// 'name' => 'apple', 0 => 4), et $b sera le tableau
// array(0 => 'a', 1 => 'b', 2 => 'c'), ou simplement array('a', 'b', 'c').
var_dump($a, $b);
?>
]]>
   </programlisting>
  </example>

  <example>
   <title>Utilisation de array()</title>
   <programlisting role="php">
<![CDATA[
<?php
// Tableau comme carte de propriétés
$map = array( 'version'    => 4,
              'OS'         => 'Linux',
              'lang'       => 'english',
              'short_tags' => true
            );
var_dump($map);

// clés numériques strictes
// est identique à array(0 => 7, 1 => 8, ...)
$array = array( 7,
                8,
                0,
                156,
                -10
              );
var_dump($array);

$switching = array(         10, // clé = 0
                    5    =>  6,
                    3    =>  7, 
                    'a'  =>  4,
                            11, // clé = 6 (l'indice entier maximal est 5)
                    '8'  =>  2, // clé = 8 (entier !)
                    '02' => 77, // clé = '02'
                    0    => 12  // la valeur 10 sera écrasée par la valeur 12
                  );
var_dump($switching);

// tableau vide
$empty = array();
var_dump($empty);
?>
]]>
   </programlisting>
  </example>

  <example xml:id="language.types.array.examples.loop">
   <title>Collection</title>
   <programlisting role="php">
<![CDATA[
<?php
$colors = array('rouge', 'bleu', 'verte', 'jaune');

foreach ($colors as $color) {
    echo "Aimez-vous la couleur $color ?\n";
}

?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
Aimez-vous la couleur rouge ?
Aimez-vous la couleur bleu ?
Aimez-vous la couleur verte ?
Aimez-vous la couleur jaune ?
]]>
   </screen>
  </example>

  <para>
   La modification directe de valeurs d'un <type>array</type> est possible
   en le passant par référence.
  </para>

  <example xml:id="language.types.array.examples.changeloop">
   <title>Modification d'un élément dans la boucle</title>
   <programlisting role="php">
<![CDATA[
<?php
foreach ($colors as &$color) {
    $color = mb_strtoupper($color);
}
unset($color); /* On s'assure que les écritures suivantes
sur $color ne modifie pas le dernier élément du tableau */

print_r($colors);
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
Array
(
    [0] => ROUGE
    [1] => BLEU
    [2] => VERTE
    [3] => JAUNE
)
]]>
   </screen>
  </example>

  <para>
   Cet exemple crée un tableau, dont l'indexation commence à 1.
  </para>

  <example>
   <title>Indexation commençant à 1</title>
   <programlisting role="php">
<![CDATA[
<?php
$firstquarter = array(1 => 'Janvier', 'Février', 'Mars');
print_r($firstquarter);
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
Array 
(
    [1] => Janvier
    [2] => Février
    [3] => Mars
)
]]>
   </screen>
  </example>

  <example>
   <title>Remplissage d'un tableau</title>
   <programlisting role="php">
<![CDATA[
<?php
// Remplit un tableau avec tous les éléments d'un dossier
$handle = opendir('.');
while (false !== ($file = readdir($handle))) {
    $files[] = $file;
}
closedir($handle); 
var_dump($files);
?>
]]>
   </programlisting>
  </example>

  <para>
   Les tableaux sont ordonnés. L'ordre peut être modifié en utilisant plusieurs
   fonctions. Voir la section sur les <link linkend="ref.array">fonctions sur les
   tableaux</link> pour plus d'informations. La fonction <function>count</function>
   peut être utilisée pour compter le nombre d'éléments d'un tableau.
  </para>

  <example>
   <title>Tri d'un tableau</title>
   <programlisting role="php" annotations="non-interactive">
<![CDATA[
<?php
sort($files);
print_r($files);
?>
]]>
   </programlisting>
  </example>

  <para>
   Sachant que la valeur d'un tableau peut être n'importe quoi, elle peut
   aussi être un autre tableau. Ceci permet la création de tableaux récursifs
   et de tableaux multidimensionnels.
  </para>

  <example>
   <title>Tableaux récursifs et multidimensionnels</title>
   <programlisting role="php">
<![CDATA[
<?php
$fruits = array ( "fruits"  => array ( "a" => "orange",
                                       "b" => "banana",
                                       "c" => "apple"
                                     ),
                  "numbers" => array ( 1,
                                       2,
                                       3,
                                       4,
                                       5,
                                       6
                                     ),
                  "holes"   => array (      "first",
                                       5 => "second",
                                            "third"
                                     )
                );
var_dump($fruits);

// Quelques exemples pour retrouver les valeurs dans le tableau ci-dessus 
echo $fruits["holes"][5];    // affiche "second"
echo $fruits["fruits"]["a"]; // affiche "orange"
unset($fruits["holes"][0]);  // efface "first"

// Création d'un tableau multidimensionnel
$juices["apple"]["green"] = "good"; 
var_dump($juices);
?>
]]>
   </programlisting>
  </example>

  <para>
   L'assignation d'un tableau induit toujours la copie des valeurs.
   Utilisez l'<link linkend="language.operators">opérateur de référence</link>
   pour copier un tableau par référence.
  </para>

  <example>
   <title>Copier des tableaux</title>
   <programlisting role="php">
<![CDATA[
<?php
$arr1 = array(2, 3);
$arr2 = $arr1;
$arr2[] = 4; // $arr2 est modifié,
             // $arr1 vaut toujours array(2, 3)

$arr3 = &$arr1;
$arr3[] = 4; // maintenant, $arr1 et $arr3 sont identiques

var_dump($arr1, $arr2, $arr3);
?>
]]>
   </programlisting>
  </example>

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