symlink()

Introduction

En PHP, la fonction symlink() crée un lien symbolique (aussi appelé symlink ou lien souple) — un fichier spécial qui agit comme un pointeur vers un autre fichier ou répertoire. Au lieu de copier les données, un symlink permet à deux chemins de faire référence à la même cible sous-jacente, de sorte que les modifications effectuées via l'un ou l'autre chemin affectent le même fichier.

Les liens symboliques sont pratiques lorsque vous avez besoin d'un chemin stable et prévisible (par exemple current pointant toujours vers le dernier répertoire de version), que vous souhaitez exposer le même fichier sous plusieurs noms, ou que vous devez partager un fichier de configuration entre plusieurs projets sans le dupliquer.

Cet article couvre la syntaxe, les paramètres, la valeur de retour, les pièges courants et des exemples exécutables.

Fonctionnement d'un lien symbolique

Un lien symbolique stocke un chemin vers sa cible plutôt qu'une copie des données. Cela diffère d'un lien physique (créé avec link()), qui pointe directement vers les données du fichier sur le disque :

• Un symlink peut pointer vers un répertoire et peut traverser les frontières de systèmes de fichiers ; si la cible est supprimée, le symlink devient « pendant » (cassé).
• Un lien physique ne fonctionne que pour les fichiers sur le même système de fichiers et maintient les données actives même après la suppression du nom d'origine.

Comme un symlink ne contient qu'un chemin, ce chemin peut être relatif (résolu par rapport au répertoire où se trouve le lien) ou absolu.

Syntaxe

symlink(string $target, string $link): bool

symlink() retourne true en cas de succès et false en cas d'échec (et émet un avertissement). Elle échoue si $link existe déjà, si vous n'avez pas la permission d'écriture dans le répertoire du lien, ou si les liens symboliques ne sont pas pris en charge sur la plateforme.

Exemple 1 : Créer et lire un lien symbolique

Cet exemple complet crée un fichier, y crée un lien, puis vérifie que le lien pointe bien vers l'original :

<?php
// Create the real file.
file_put_contents('example.txt', 'Hello from the target file');

// Create a symbolic link to it.
symlink('example.txt', 'example_link.txt');

// Reading through the link reads the target's contents.
echo file_get_contents('example_link.txt'), PHP_EOL;

// is_link() confirms the path is a symlink, readlink() reveals its target.
echo (is_link('example_link.txt') ? 'It is a link' : 'Not a link'), PHP_EOL;
echo 'Points to: ', readlink('example_link.txt'), PHP_EOL;

// Clean up: unlink() removes the link, not the target.
unlink('example_link.txt');
unlink('example.txt');

Sortie :

Hello from the target file
It is a link
Points to: example.txt

La lecture de example_link.txt retourne le contenu de la cible, is_link() détecte que le chemin est un symlink, et readlink() retourne le chemin cible stocké.

Exemple 2 : Vérifier la valeur de retour

symlink() retourne false (avec un avertissement) si le lien existe déjà ou si le répertoire n'est pas accessible en écriture, donc vérifiez toujours le résultat dans votre code :

<?php
if (@symlink('target.txt', 'link.txt')) {
    echo 'Symbolic link created successfully.';
} else {
    echo 'Failed to create symbolic link.';
}

Le @ supprime l'avertissement afin que vous puissiez gérer l'échec vous-même. Une routine robuste supprime d'abord un lien obsolète et vérifie le résultat :

<?php
$target = 'config.php';
$link   = 'current-config.php';

if (is_link($link)) {
    unlink($link); // remove the old link before re-pointing it
}

if (symlink($target, $link)) {
    echo "Linked $link -> " . readlink($link);
} else {
    echo "Could not create link (check permissions).";
}

Cibles relatives vs. absolues

Un $target relatif est résolu par rapport au répertoire contenant le lien, et non par rapport au répertoire de travail courant. C'est une source courante de liens cassés :

<?php
// If the link lives in /var/www/app, this resolves to /var/www/shared/db.php
symlink('../shared/db.php', '/var/www/app/db.php');

// Absolute targets avoid the ambiguity entirely.
symlink('/var/www/shared/db.php', '/var/www/app/db.php');

Utilisez un chemin absolu lorsque le lien peut être créé depuis un répertoire de travail différent, ou lorsque vous souhaitez qu'il continue de fonctionner peu importe l'endroit où il est lu.

Pièges courants

• Le chemin du lien ne doit pas déjà exister. Supprimez ou mettez à jour un lien existant avec unlink() d'abord ; sinon symlink() échoue.
• Windows nécessite des droits élevés. La création de liens symboliques nécessite des privilèges d'administrateur ou le mode développeur activé.
• Les liens cassés (pendants) pointent vers une cible manquante. is_link() retourne toujours true, mais file_exists() sur le lien retourne false car il suit le lien vers la cible absente.
• Les permissions sont vérifiées sur le répertoire parent du lien, qui doit être accessible en écriture.

Conclusion

La fonction symlink() offre un moyen léger de référencer des fichiers et des répertoires sans copier les données. N'oubliez pas de vérifier sa valeur de retour, préférez les cibles absolues lorsque le répertoire de travail est incertain, et tenez compte des exigences de permissions spécifiques à la plateforme. Associez-la avec is_link(), readlink() et unlink() pour inspecter et gérer les liens, et consultez la vue d'ensemble du système de fichiers PHP pour l'API de fichiers complète.

Pratique