require

L'instruction PHP require

En PHP, require prend le contenu d'un autre fichier PHP, l'insère à l'endroit où require apparaît et l'évalue comme s'il avait été écrit directement à cet emplacement. C'est ainsi que les projets PHP répartissent le code dans plusieurs fichiers : configuration, fonctions utilitaires, définitions de classes et gabarits vivent chacun dans leur propre fichier et sont importés avec require.

La différence essentielle entre require et son équivalent include réside dans la réaction à un fichier manquant. Si le fichier cible est introuvable, require arrête le script avec une erreur fatale, tandis qu'include émet seulement un avertissement et continue l'exécution. require est donc le bon choix pour les fichiers sans lesquels le script ne peut pas fonctionner.

Ce guide couvre la syntaxe, des exemples exécutables, la différence entre require et include, le moment d'utiliser require_once, ainsi que les pièges courants.

Syntaxe

require est une construction de langage, pas une fonction ; vous pouvez donc l'écrire avec ou sans parenthèses :

require '/path/to/file.php';
require('/path/to/file.php'); // also valid, but parentheses are unnecessary

En pratique, vous voudrez presque toujours que les chemins soient relatifs au script courant plutôt qu'au répertoire de travail de PHP. La constante magique __DIR__ contient le répertoire du fichier dans lequel elle apparaît ; construire les chemins à partir d'elle garantit que require fonctionne quelle que soit la localisation depuis laquelle le script est exécuté :

require __DIR__ . '/config.php';

Un exemple exécutable

L'extrait ci-dessous crée un petit fichier utilitaire, l'importe et appelle ensuite la fonction qu'il définit. Vous pouvez le coller dans un seul fichier .php et l'exécuter — le fichier utilitaire est écrit dans le même répertoire au moment de l'exécution, ce qui rend l'exemple autonome.

<?php

// Create a helper file next to this script.
file_put_contents(__DIR__ . '/greet.php', <<<'PHP'
<?php
function greet($name) {
    return "Hello, $name!";
}
PHP);

// Pull the helper in. After this line greet() is available.
require __DIR__ . '/greet.php';

echo greet('Ada'); // Hello, Ada!

Résultat :

Hello, Ada!

Une fois qu'un fichier est importé, tout ce qu'il déclare — fonctions, classes et toutes les variables de premier niveau — devient partie intégrante de la portée courante, exactement comme si vous l'aviez tapé directement.

require vs include

Les deux instructions chargent et évaluent un fichier. La seule différence de comportement concerne ce qui se passe lorsque le fichier est manquant ou illisible :

Utilisez require pour des fichiers comme une connexion à une base de données ou un autoloader, pour lesquels continuer sans eux n'a aucun sens. Recourez à include uniquement quand un fichier manquant doit être toléré — par exemple, une substitution de thème optionnelle.

require_once : éviter de charger deux fois

Importer le même fichier deux fois cause des problèmes : redéclarer une fonction ou une classe est lui-même une erreur fatale. require_once résout ce problème en mémorisant les fichiers déjà chargés et en ignorant toute nouvelle demande.

<?php
require_once __DIR__ . '/User.php'; // loads the file
require_once __DIR__ . '/User.php'; // already loaded — does nothing

En règle générale, utilisez require_once pour les fichiers qui définissent des éléments (classes, bibliothèques de fonctions) et le require simple pour les fichiers que vous exécutez intentionnellement plusieurs fois, comme un gabarit rendu dans une boucle. La même distinction once/non-once existe pour include sous la forme include_once.

Patterns courants

Un fichier de configuration partagé chargé en haut d'un script d'entrée :

<?php
require __DIR__ . '/config.php';

// $dbHost, $dbUser, etc. defined in config.php are now available.
$pdo = new PDO("mysql:host=$dbHost", $dbUser, $dbPass);

Un fichier importé peut aussi return une valeur, que require renvoie. C'est une façon propre de charger un tableau de configuration :

// config.php
<?php
return [
    'host' => 'localhost',
    'port' => 3306,
];

// index.php
<?php
$config = require __DIR__ . '/config.php';
echo $config['port']; // 3306

Pièges courants

• Construisez les chemins depuis __DIR__, pas avec des chaînes relatives. require 'config.php' résout le chemin par rapport au répertoire de travail courant de PHP, qui peut différer de l'emplacement du script et provoquer des erreurs silencieuses selon le serveur web ou l'invocation en CLI.
• require s'exécute à l'endroit où il apparaît. Le placer à l'intérieur d'une fonction (comme dans l'exemple ci-dessus) diffère le chargement jusqu'à l'appel de cette fonction, et limite toutes les variables de premier niveau du fichier à la portée de cette fonction.
• Préférez un autoloader pour les classes. Importer manuellement des dizaines de fichiers de classes est source d'erreurs. Les projets modernes utilisent vendor/autoload.php de Composer (chargé une seule fois avec require) et laissent l'autoloading PSR-4 charger les classes à la demande.

Conclusion

require est le fondement de l'organisation du code en PHP : il découpe un programme en fichiers ciblés et charge ceux dont un script dépend, en échouant bruyamment si l'un d'eux est manquant. Construisez les chemins depuis __DIR__, choisissez require_once pour les définitions afin d'éviter le double chargement, et réservez include uniquement quand un fichier manquant est acceptable. Pour les bibliothèques de classes, un autoloader Composer est le remplacement moderne des listes require écrites à la main.

Pratique