symlink()

Введение

В PHP функция symlink() создаёт символическую ссылку (также называемую симлинком или мягкой ссылкой) — специальный файл, который действует как указатель на другой файл или директорию. Вместо копирования данных симлинк позволяет двум путям ссылаться на один и тот же целевой объект, поэтому изменения, внесённые через любой из путей, затрагивают один и тот же файл.

Симлинки удобны, когда нужен стабильный, предсказуемый путь (например, current всегда указывает на директорию последнего релиза), когда требуется открыть доступ к одному файлу под несколькими именами или когда нужно использовать один конфигурационный файл в нескольких проектах без его дублирования.

В этой статье рассматриваются синтаксис, параметры, возвращаемое значение, распространённые подводные камни и запускаемые примеры.

Как работает символическая ссылка

Символическая ссылка хранит путь к целевому объекту, а не копию данных. Это отличает её от жёсткой ссылки (создаваемой с помощью link()), которая указывает непосредственно на данные файла на диске:

• Симлинк может указывать на директорию и пересекать границы файловых систем; если цель удалена, симлинк становится «оборванным» (неработающим).
• Жёсткая ссылка работает только для файлов на одной файловой системе и сохраняет данные даже после удаления исходного имени.

Поскольку симлинк хранит только путь, этот путь может быть относительным (разрешается относительно директории, в которой находится ссылка) или абсолютным.

Синтаксис

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

symlink() возвращает true при успехе и false при ошибке (с выдачей предупреждения). Функция завершается с ошибкой, если $link уже существует, если нет прав на запись в директорию ссылки или если платформа не поддерживает симлинки.

Пример 1: создание и чтение символической ссылки

Этот полный пример создаёт файл, создаёт на него ссылку, а затем проверяет, что ссылка указывает на исходный файл:

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

Вывод:

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

Чтение example_link.txt возвращает содержимое целевого файла, is_link() определяет, что путь является симлинком, а readlink() возвращает сохранённый целевой путь.

Пример 2: проверка возвращаемого значения

symlink() возвращает false (с предупреждением), если ссылка уже существует или директория недоступна для записи, поэтому в реальном коде всегда проверяйте результат:

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

@ подавляет предупреждение, позволяя самостоятельно обработать сбой. Надёжная реализация сначала удаляет устаревшую ссылку и проверяет результат:

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

Относительные и абсолютные цели

Относительный $target разрешается относительно директории содержащей ссылку, а не текущей рабочей директории. Это распространённая причина появления оборванных ссылок:

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

Используйте абсолютный путь, если ссылка может создаваться из другой рабочей директории или если нужно, чтобы она работала независимо от того, откуда читается.

Распространённые подводные камни

• Путь ссылки не должен существовать. Удалите или обновите существующую ссылку с помощью unlink() перед вызовом; иначе symlink() завершится с ошибкой.
• Windows требует повышенных прав. Для создания симлинков необходимы права администратора или включённый режим разработчика.
• Оборванные ссылки указывают на несуществующий целевой объект. is_link() по-прежнему возвращает true, но file_exists() для ссылки возвращает false, поскольку следует по ссылке к отсутствующей цели.
• Права доступа проверяются для родительской директории ссылки, которая должна быть доступна для записи.

Заключение

Функция symlink() предоставляет лёгкий способ ссылаться на файлы и директории без копирования данных. Не забывайте проверять возвращаемое значение, предпочитайте абсолютные пути при неопределённой рабочей директории и учитывайте требования к правам доступа на разных платформах. Используйте её совместно с is_link(), readlink() и unlink() для проверки ссылок и управления ими, а обзор файловой системы PHP читайте в разделе PHP Filesystem.

Практика