symlink()

Introducción

En PHP, la función symlink() crea un enlace simbólico (también llamado symlink o enlace blando) — un archivo especial que actúa como puntero a otro archivo o directorio. En lugar de copiar datos, un enlace simbólico permite que dos rutas se refieran al mismo destino subyacente, de modo que los cambios realizados a través de cualquiera de las rutas afectan al mismo archivo.

Los enlaces simbólicos son útiles cuando necesitas una ruta estable y predecible (por ejemplo, current que siempre apunte al directorio de la última versión), cuando quieres exponer el mismo archivo con varios nombres, o cuando necesitas compartir un archivo de configuración entre proyectos sin duplicarlo.

Este artículo cubre la sintaxis, los parámetros, el valor de retorno, los errores comunes y ejemplos ejecutables.

Cómo funciona un enlace simbólico

Un enlace simbólico almacena una ruta hacia su destino en lugar de una copia de los datos. Esto lo diferencia de un enlace duro (creado con link()), que apunta directamente a los datos del archivo en disco:

• Un symlink puede apuntar a un directorio y puede cruzar límites de sistemas de archivos; si se elimina el destino, el enlace simbólico queda "colgante" (roto).
• Un enlace duro solo funciona para archivos en el mismo sistema de archivos y mantiene los datos activos incluso después de eliminar el nombre original.

Dado que un enlace simbólico solo almacena una ruta, dicha ruta puede ser relativa (resuelta respecto al directorio donde vive el enlace) o absoluta.

Sintaxis

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

symlink() devuelve true en caso de éxito y false en caso de fallo (y emite una advertencia). Falla si $link ya existe, si no tienes permiso de escritura en el directorio del enlace, o si los enlaces simbólicos no están soportados en la plataforma.

Ejemplo 1: Crear y leer un enlace simbólico

Este ejemplo completo crea un archivo, crea un enlace hacia él y luego comprueba que el enlace apunta al 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');

Resultado:

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

Leer example_link.txt devuelve el contenido del destino, is_link() detecta que la ruta es un enlace simbólico y readlink() devuelve la ruta del destino almacenada.

Ejemplo 2: Comprobar el valor de retorno

symlink() devuelve false (con una advertencia) si el enlace ya existe o el directorio no es escribible, por lo que siempre debes verificar el resultado en código real:

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

El @ suprime la advertencia para que puedas gestionar el fallo tú mismo. Una rutina robusta elimina primero un enlace obsoleto y verifica el resultado:

<?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).";
}

Destinos relativos frente a absolutos

Un $target relativo se resuelve respecto al directorio que contiene el enlace, no respecto al directorio de trabajo actual. Esta es una causa frecuente de enlaces rotos:

<?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');

Usa una ruta absoluta cuando el enlace pueda crearse desde un directorio de trabajo diferente, o cuando quieras que siga funcionando sin importar desde dónde se lea el enlace.

Errores comunes

• La ruta del enlace no debe existir ya. Elimina o actualiza un enlace existente con unlink() primero; de lo contrario, symlink() falla.
• Windows requiere privilegios elevados. La creación de enlaces simbólicos necesita privilegios de administrador o el Modo Desarrollador activado.
• Los enlaces rotos (colgantes) apuntan a un destino inexistente. is_link() sigue devolviendo true, pero file_exists() sobre el enlace devuelve false porque sigue el enlace hasta el destino ausente.
• Los permisos se comprueban en el directorio padre del enlace, que debe ser escribible.

Conclusión

La función symlink() proporciona una manera ligera de referenciar archivos y directorios sin copiar datos. Recuerda verificar su valor de retorno, preferir destinos absolutos cuando el directorio de trabajo sea incierto, y tener en cuenta los requisitos de permisos específicos de la plataforma. Combínala con is_link(), readlink() y unlink() para inspeccionar y gestionar enlaces, y consulta la descripción general del Sistema de archivos de PHP para conocer la API de archivos en su totalidad.

Práctica