<?xml version="1.0" encoding="utf-8"?>

<chapter xml:id="language.namespaces" xmlns="http://docbook.org/ns/docbook"

version="1.1">

<title>Les espaces de noms</title>

<sect1 xml:id="language.namespaces.rationale">

<title>Introduction aux espaces de noms</title>

<titleabbrev>Introduction</titleabbrev>

<?phpdoc print-version-for="namespaces"?>

<simpara>

Que sont les espaces de noms ? Dans leur définition la plus large, ils représentent

un moyen d'encapsuler des éléments. Cela peut être conçu comme un concept

abstrait, pour plusieurs raisons. Par exemple, dans un système de fichiers, les

dossiers représentent un groupe de fichiers associés et servent d'espace de noms

pour les fichiers qu'ils contiennent. Un exemple concret est que le fichier

<literal>foo.txt</literal> peut exister dans les deux dossiers

<literal>/home/greg</literal> et <literal>/home/other</literal>, mais que

les deux copies de <literal>foo.txt</literal> ne peuvent pas co-exister

dans le même dossier. De plus, pour accéder au fichier <literal>foo.txt</literal>

depuis l'extérieur du dossier <literal>/home/greg</literal>, il faut préciser

le nom du dossier en utilisant un séparateur de dossier, tel que

<literal>/home/greg/foo.txt</literal>. Le même principe s'applique aux

espaces de noms dans le monde de la programmation.

</simpara>

<simpara>

Dans le monde PHP, les espaces de noms sont conçus pour résoudre deux problèmes

que rencontrent les auteurs de bibliothèques et d'applications lors de la réutilisation

d'éléments tels que des classes ou des bibliothèques de fonctions :

</simpara>

<para>

<orderedlist>

<listitem>

<simpara>

Collisions de noms entre le code créé, les classes, fonctions

ou constantes internes de PHP, ou celles de bibliothèques tierces.

</simpara>

</listitem>

<listitem>

<simpara>

La capacité de faire des alias ou de raccourcir des Noms_Extremement_Long

pour aider à la résolution du premier problème, et améliorer la lisibilité

du code.

</simpara>

</listitem>

</orderedlist>

</para>

<simpara>

Les espaces de noms PHP fournissent un moyen pour regrouper des classes, interfaces,

fonctions ou constantes. Voici un exemple de syntaxe des espaces de noms PHP :

</simpara>

<example>

<title>Exemple de syntaxe des espaces de noms</title>

<titleabbrev>Espaces de noms</titleabbrev>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

<note>

<simpara>

Les noms d'espaces de noms ne sont pas sensibles à la casse.

</simpara>

</note>

<note>

<para>

Les espaces de noms <literal>PHP</literal>, mais aussi les noms composés

commençant par ces noms (comme <literal>PHP\Classes</literal>)

sont réservés pour l'utilisation interne du langage, et ne doivent pas être utilisés

dans le code de l'espace utilisateur.

</para>

</note>

</sect1>

<sect1 xml:id="language.namespaces.definition">

<title>Définition des espaces de noms</title>

<?phpdoc print-version-for="namespaces"?>

<para>

Bien que du code PHP valide puisse être contenu dans un espace de noms,

seuls les types de code suivants peuvent être affectés par les espaces de noms :

les classes (incluant les abstraites, les traits et les enums), les interfaces,

les fonctions et les constantes.

</para>

<para>

Les espaces de noms sont déclarés avec le mot-clé <literal>namespace</literal>.

Un fichier contenant un espace de noms doit déclarer l'espace au début

du fichier, avant tout autre code, avec une seule exception : le mot

clé <xref linkend="control-structures.declare" />.

<example>

<title>Déclaration d'un espace de noms</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

<note>

<simpara>

Les noms complètement qualifiés (c.-à-d. les noms commençant avec un antislash)

ne sont pas autorisés dans les déclarations d'espaces de noms, car de telles

constructions sont interprétées comme des expressions d'espace de noms

relatif.

</simpara>

</note>

Le seul élément autorisé avant la déclaration d'espace de noms est la commande

<literal>declare</literal>, pour définir l'encodage du fichier source. De plus,

aucun code non-PHP ne peut précéder la déclaration d'espace de noms, y compris

des espaces :

<example>

<title>Erreur de déclaration d'un espace de noms</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

</para>

<para>

De plus, contrairement à d'autres structures PHP, le même espace de noms peut

être défini dans plusieurs fichiers, ce qui permet de scinder le contenu d'un

espace de noms sur plusieurs fichiers.

</para>

</sect1>

<sect1 xml:id="language.namespaces.nested">

<title>Déclaration d'un sous espace de noms</title>

<titleabbrev>Sous espace de noms</titleabbrev>

<?phpdoc print-version-for="namespaces"?>

<para>

Comme pour les fichiers et les dossiers, les espaces de noms sont aussi

capables de spécifier une hiérarchie d'espaces de noms. Ainsi, un nom d'espace

de noms peut être défini avec ses sous-niveaux :

<example>

<title>Déclaration d'un espace de noms avec hiérarchie</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

Dans l'exemple ci-dessus, la constante <literal>MonProjet\Sous\Niveau\CONNEXION_OK</literal>,

la classe <literal>MonProjet\Sous\Niveau\Connexion</literal> et la fonction

<literal>MonProjet\Sous\Niveau\connecte</literal> sont créées.

</para>

</sect1>

<sect1 xml:id="language.namespaces.definitionmultiple">

<title>Définition de plusieurs espaces de noms dans le même fichier</title>

<titleabbrev>Définition de plusieurs espaces de noms dans le même fichier</titleabbrev>

<?phpdoc print-version-for="namespaces"?>

<para>

Plusieurs espaces de noms peuvent aussi être déclarés dans le même fichier.

Il y a deux syntaxes autorisées.

</para>

<para>

<example>

<title>Déclaration de plusieurs espaces de noms, syntaxe à combinaison simple</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

</para>

<para>

Cette syntaxe n'est pas recommandée pour combiner des espaces de noms

dans un seul fichier. Au lieu de cela, il est recommandé d'utiliser

la syntaxe à accolades.

</para>

<para>

<example>

<title>Déclaration de plusieurs espaces de noms, syntaxe à accolades</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

</para>

<para>

Il est fortement recommandé, en tant que pratique de codage, de ne pas mélanger

plusieurs espaces de noms dans le même fichier. L'utilisation recommandée est de

combiner plusieurs scripts PHP dans le même fichier.

</para>

<para>

Pour combiner plusieurs codes sans espaces de noms dans du code avec espace de noms,

seule la syntaxe à accolades est supportée. Le code global doit être encadré par un

espace de noms sans nom, tel que celui-ci :

<example>

<title>Déclaration de plusieurs espaces de noms avec un espace sans nom</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

</para>

<para>

Aucun code PHP ne peut exister hors des accolades du namespace,

sauf pour ouvrir une nouvelle instruction <literal>declare</literal>.

<example>

<title>Déclaration de plusieurs espaces de noms avec un espace sans nom (2)</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

</para>

</sect1>

<sect1 xml:id="language.namespaces.basics">

<title>Utilisation des espaces de noms : introduction</title>

<titleabbrev>Introduction</titleabbrev>

<?phpdoc print-version-for="namespaces"?>

<para>

Avant de discuter de l'utilisation des espaces de noms, il est important de

comprendre comment PHP devine quel espace de noms le code utilise. Une

analogie simple peut être faite entre les espaces de noms de PHP et un système

de fichiers. Il y a trois moyens d'accéder à un fichier dans un système de

fichiers :

<orderedlist>

<listitem>

<simpara>

Un nom relatif de fichier, tel que <literal>foo.txt</literal>. Cela est résolu

en <literal>dossiercourant/foo.txt</literal> où <literal>dossiercourant</literal> est le

dossier de travail. Si le dossier courant est <literal>/home/foo</literal>,

ce nom se résout en <literal>/home/foo/foo.txt</literal>.

</simpara>

</listitem>

<listitem>

<simpara>

Un chemin relatif, tel que <literal>sous-dossier/foo.txt</literal>. Cela se

résout en <literal>dossiercourant/sous-dossier/foo.txt</literal>.

</simpara>

</listitem>

<listitem>

<simpara>

Un chemin absolu, tel que <literal>/main/foo.txt</literal>. Cela se résout

en <literal>/main/foo.txt</literal>.

</simpara>

</listitem>

</orderedlist>

Le même principe peut être appliqué aux espaces de noms de PHP.

Par exemple, on peut faire référence à une classe de trois manières :

<orderedlist>

<listitem>

<simpara>

Un nom sans qualificatif, ou une classe sans préfixe, telle que

<literal>$a = new foo();</literal> ou

<literal>foo::methodestatique();</literal>. Si le namespace courant

est <literal>espacedenomscourant</literal>, ceci se résout en

<literal>espacedenomscourant\foo</literal>. Si le namespace est

global, soit encore le namespace sans nom, cela devient <literal>foo</literal>.

</simpara>

<simpara>

Une mise en garde : les noms sans qualificatif pour les fonctions et les

constantes vont être pris dans le namespace global, si la fonction

n'est pas définie dans le namespace courant. Voir

<link linkend="language.namespaces.fallback">Utilisation des espaces de noms :

retour au namespace global pour les fonctions et les constantes</link> pour

plus de détails.

</simpara>

</listitem>

<listitem>

<simpara>

Un nom qualifié, ou une classe préfixée telle que

<literal>$a = new sousespacedenoms\foo();</literal> ou

<literal>sousespacedenoms\foo::methodestatique();</literal>. Si le namespace courant

est <literal>espacedenomscourant</literal>, cela devient

<literal>espacedenomscourant\sousespacedenoms\foo</literal>. Si

le code est global, c'est-à-dire le namespace sans nom,

cela devient <literal>sousespacedenoms\foo</literal>.

</simpara>

</listitem>

<listitem>

<simpara>

Un nom absolu, ou un nom préfixé avec un opérateur global tel que

<literal>$a = new \espacedenomscourant\foo();</literal> ou

<literal>\espacedenomscourant\foo::methodestatique();</literal>. Cela fait toujours

référence au nom littéral spécifié dans le code : <literal>espacedenomscourant\foo</literal>.

</simpara>

</listitem>

</orderedlist>

</para>

<para>

Voici un exemple des trois syntaxes, dans du code réel :

<informalexample>

<simpara>file1.php</simpara>

<programlisting role="php">

<![CDATA[

</programlisting>

<simpara>file2.php</simpara>

<programlisting role="php">

<![CDATA[

</programlisting>

</informalexample>

</para>

<para>

Il est à noter que pour accéder à n'importe quelle classe, fonction ou constante

globale, un nom absolu peut être utilisé, tel que

<function>\strlen</function> ou <classname>\Exception</classname> ou

\<constant>INI_ALL</constant>.

<example>

<title>Accès aux classes, fonctions et constantes globales depuis un espace de noms</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

</para>

</sect1>

<sect1 xml:id="language.namespaces.dynamic">

<title>Espaces de noms et langage dynamique</title>

<titleabbrev>Espaces de noms et langage dynamique</titleabbrev>

<?phpdoc print-version-for="namespaces"?>

<para>

L'implémentation des espaces de noms de PHP est influencée par sa nature dynamique

de langage de programmation. Par conséquent, pour convertir du code tel que le code

de l'exemple suivant, en un espace de noms :

<example>

<title>Accès dynamique aux éléments</title>

<simpara>example1.php:</simpara>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

Il faut utiliser un nom absolu (le nom de la classe, avec son préfixe d'espace

de noms). Il est à noter qu'il n'y a pas de différence entre un nom absolu et un nom qualifié

dans un nom de classe, de fonction ou de constante dynamique, ce qui fait que l'antislash

initial n'est pas nécessaire.

<example>

<title>Accès dynamique à des espaces de noms</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

</para>

<para>

Il est recommandé de lire la <link linkend="language.namespaces.faq.quote">note au sujet

de la protection des espaces de noms dans les chaînes</link>.

</para>

</sect1>

<sect1 xml:id="language.namespaces.nsconstants">

<title>La commande namespace et la constante __NAMESPACE__</title>

<titleabbrev>Commande namespace et __NAMESPACE__</titleabbrev>

<?phpdoc print-version-for="namespaces"?>

<para>

PHP supporte deux moyens pour accéder de manière abstraite aux éléments

dans l'espace de noms courant, à savoir la constante magique

<constant>__NAMESPACE__</constant> et la commande <literal>namespace</literal>.

</para>

<para>

La valeur de <constant>__NAMESPACE__</constant> est une chaîne qui contient le nom

du namespace courant. Dans l'espace global, sans nom, elle contient

une chaîne vide.

<example>

<title>Exemple avec __NAMESPACE__, dans un code avec espace de noms</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

<example>

<title>Exemple avec __NAMESPACE__, dans un code avec espace de noms global</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

La constante <constant>__NAMESPACE__</constant> est utile pour construire

dynamiquement des noms, tels que :

<example>

<title>Utilisation de __NAMESPACE__ pour une construction dynamique de noms</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

</para>

<para>

La commande <literal>namespace</literal> peut aussi être utilisée pour

demander explicitement un élément du namespace courant, ou d'un

sous-espace. C'est l'équivalent pour les espaces de noms de l'opérateur

<literal>self</literal> des classes.

<example>

<title>l'opérateur namespace, dans un espace de noms</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

<example>

<title>l'opérateur namespace, dans le namespace global</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

</para>

</sect1>

<sect1 xml:id="language.namespaces.importing">

<?phpdoc print-version-for="namespaces"?>

<title>Utilisation des espaces de noms : importation et alias</title>

<titleabbrev>Importation et alias</titleabbrev>

<para>

La capacité de faire référence à un nom absolu avec un alias ou en important

un espace de noms est stratégique. C'est un avantage similaire aux liens

symboliques dans un système de fichiers.

</para>

<para>

PHP peut aliaser(/importer) les constantes, fonctions, classes, interfaces,

traits, énumérations et les espaces de noms.

</para>

<para>

Un alias est créé avec l'opérateur <literal>use</literal>.

Voici un exemple qui présente les cinq types d'importation :

<example>

<title>importation et alias avec l'opérateur use</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

Il est à noter que pour les noms avec chemin (les noms absolus contenant des

séparateurs d'espaces, tels que <literal>Foo\Bar</literal>, par comparaison avec

les noms globaux, tels que <literal>FooBar</literal>, qui n'en contiennent pas),

l'antislash initial n'est pas nécessaire et n'est pas recommandé, car les noms importés

doivent être absolus et ne sont pas résolus relativement au namespace courant.

</para>

<para>

De plus, PHP supporte des raccourcis pratiques, tels que les commandes use multiples.

<example>

<title>importation et alias multiples avec l'opérateur use</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

</para>

<para>

L'importation est réalisée à la compilation, ce qui fait que cela n'affecte pas

les classes, fonctions et constantes dynamiques.

<example>

<title>Importation et noms d'espaces dynamiques</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

</para>

<para>

De plus, l'importation n'affecte que les noms sans qualification. Les noms

absolus restent absolus, et inchangés par un import.

<example>

<title>Importation et noms d'espaces absolus</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

</para>

<sect2 xml:id="language.namespaces.importing.scope">

<title>Règles de contextes pour l'importation</title>

<para>

Le mot-clé <literal>use</literal> doit être déclaré dans le contexte le plus

externe d'un fichier (le contexte global) ou alors dans les déclarations d'espace

de noms. Ceci car l'importation est effectuée à la compilation et non durant

l'exécution, donc on ne peut empiler les contextes. L'exemple qui suit montre des

utilisations incorrectes du mot-clé <literal>use</literal>:

</para>

<para>

<example>

<title>Règles d'importation incorrectes</title>

<programlisting role="php">

</programlisting>

</example>

</para>

<note>

<para>

Les règles d'importation sont basées sur les fichiers, ce qui signifie que les fichiers

inclus n'hériteront <emphasis>PAS</emphasis> des règles d'importation du fichier parent.

</para>

</note>

</sect2>

<sect2 xml:id="language.namespaces.importing.group">

<title>Déclaration du groupe <literal>use</literal></title>

<para>

Les classes, fonctions et constantes importées depuis

le même &namespace; peuvent être regroupées dans une

seule instruction &use.namespace;.

</para>

<informalexample>

<programlisting role="php">

</programlisting>

</informalexample>

</sect2>

</sect1>

<sect1 xml:id="language.namespaces.global">

<title>Espace de noms global</title>

<titleabbrev>Global</titleabbrev>

<?phpdoc print-version-for="namespaces"?>

<para>

Sans aucune définition d'espace de noms, toutes les classes et les fonctions

sont placées dans le namespace global : comme en PHP avant que les espaces

de noms aient été introduits. En préfixant un nom avec un antislash

<literal>\</literal>, on peut demander l'utilisation du namespace

global, même dans un contexte d'espace de noms spécifique.

<example>

<title>Spécification d'espace de noms global</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

</para>

</sect1>

<sect1 xml:id="language.namespaces.fallback">

<title>Utilisation des espaces de noms : retour sur l'espace global pour les fonctions et les constantes</title>

<titleabbrev>Retour sur l'espace global</titleabbrev>

<?phpdoc print-version-for="namespaces"?>

<para>

Dans un espace de noms, lorsque PHP rencontre un nom sans qualification,

que ce soit une classe, une fonction ou une constante, il le résout avec différentes

priorités. Les noms de classes sont toujours résolus avec le namespace courant.

Pour accéder à des classes internes ou à des classes qui ne sont pas dans

un espace de noms, il faut les représenter avec leur nom absolu, tel que :

<example>

<title>Accès aux classes globales depuis un espace de noms</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

</para>

<para>

Pour les fonctions et constantes, PHP va aller les chercher dans l'espace

global s'il ne peut les trouver dans le namespace courant.

<example>

<title>Accès aux fonctions et constantes globales dans un espace de noms</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

</para>

</sect1>

<sect1 xml:id="language.namespaces.rules">

<title>Règles de résolution de noms</title>

<titleabbrev>Règles de résolution de noms</titleabbrev>

<?phpdoc print-version-for="namespaces"?>

<para>

Dans le cadre des règles de résolution, il y a plusieurs définitions importantes :

<variablelist>

<title>Définitions pour les espaces de noms</title>

<varlistentry>

<term>nom non qualifié</term>

<listitem>

<para>

Ceci est un identifiant ne contenant pas un séparateur d'espace de noms.

Par exemple : <literal>Foo</literal>

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>nom qualifié</term>

<listitem>

<para>

Ceci est un identifiant contenant un séparateur d'espace de noms.

Par exemple : <literal>Foo\Bar</literal>

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Nom absolu</term>

<listitem>

<para>

Ceci est un identifiant qui commence par un séparateur d'espace de noms.

Par exemple : <literal>\Foo\Bar</literal>. le namespace <literal>Foo</literal>

est aussi un nom absolu.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Nom Relatif</term>

<listitem>

<para>

C'est un identifiant commençant par <literal>namespace</literal>, tel que

<literal>namespace\Foo\Bar</literal>.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

<para>

Les noms sont résolus en suivant les règles suivantes :

<orderedlist>

<listitem>

<simpara>

Les noms absolus sont toujours résolus en le nom sans le séparateur de namespace initial.

Par exemple, <literal>\A\B</literal> est résolu en <literal>A\B</literal>.

</simpara>

</listitem>

<listitem>

<simpara>

Les noms relatifs sont toujours résolus en remplaçant

<literal>namespace</literal> par le namespace courant.

Si le nom apparaît dans le namespace global, le préfixe

<literal>namespace\</literal> est retiré. Par exemple, <literal>namespace\A</literal>

dans le namespace <literal>X\Y</literal> est résolu en <literal>X\Y\A</literal>.

Le même nom dans le namespace global est résolu en <literal>A</literal>.

</simpara>

</listitem>

<listitem>

<simpara>

Pour les noms qualifiés, le premier segment est traduit

en accord avec la table d'importation des class/namespace.

Par exemple, si le namespace <literal>A\B\C</literal> est importé comme <literal>C</literal>, le nom <literal>C\D\E</literal> est traduit par <literal>A\B\C\D\E</literal>.

</simpara>

</listitem>

<listitem>

<simpara>

Pour les noms qualifiés, si aucune règle d'import ne

s'applique, le namespace courant est préfixé au nom.

Par exemple le nom <literal>C\D\E</literal> dans le namespace <literal>A\B</literal>,

est traduit par <literal>A\B\C\D\E</literal>.

</simpara>

</listitem>

<listitem>

<simpara>

Pour les noms non qualifiés, le nom est traduit en lien avec la table courante d'importation pour le type de symbole respectif.

Cela signifie qu'un nom ressemblant à une classe est traduit en accord avec la table d'importation des

class/namespace, les noms de fonctions en utilisant la

table d'importation des fonctions, et les constantes en

utilisant la table d'importation des constantes.

Par exemple, après

<literal>use A\B\C;</literal> un usage tel que <literal>new C()</literal> correspond au nom

<literal>A\B\C()</literal>. De la même manière, après <literal>use function A\B\foo;</literal> un usage

tel que <literal>foo()</literal> correspond au nom <literal>A\B\foo</literal>.

</simpara>

</listitem>

<listitem>

<simpara>

Pour les noms non qualifiés, si aucune règle ne s'applique, et que le nom

fait référence à une classe, le namespace courant sert de préfixe.

Par exemple <literal>new C()</literal> dans le namespace

<literal>A\B</literal> correspond au nom <literal>A\B\C</literal>.

</simpara>

</listitem>

<listitem>

<simpara>

Pour les noms non qualifiés, si aucune règle ne s'applique, et que le nom

fait référence à une fonction ou une constante, et que le code est en

dehors du namespace global, le nom est résolu à l'exécution.