symlink()

Introdução

Em PHP, a função symlink() cria um link simbólico (também chamado de symlink ou soft link) — um arquivo especial que funciona como um ponteiro para outro arquivo ou diretório. Em vez de copiar dados, um symlink permite que dois caminhos se refiram ao mesmo destino subjacente, de modo que as alterações feitas por qualquer um dos caminhos afetam o mesmo arquivo.

Os symlinks são úteis quando você precisa de um caminho estável e previsível (por exemplo, current sempre apontando para o diretório da versão mais recente), quando deseja expor o mesmo arquivo com vários nomes, ou quando precisa compartilhar um arquivo de configuração entre projetos sem duplicá-lo.

Este artigo aborda a sintaxe, os parâmetros, o valor de retorno, armadilhas comuns e exemplos executáveis.

Como um Link Simbólico Funciona

Um link simbólico armazena um caminho para seu destino em vez de uma cópia dos dados. Isso difere de um hard link (criado com link()), que aponta diretamente para os dados do arquivo no disco:

• Um symlink pode apontar para um diretório e pode cruzar limites de sistemas de arquivos; se o destino for excluído, o symlink se torna "pendente" (quebrado).
• Um hard link só funciona para arquivos no mesmo sistema de arquivos e mantém os dados vivos mesmo após o nome original ser removido.

Como um symlink armazena apenas um caminho, esse caminho pode ser relativo (resolvido em relação ao diretório onde o link reside) ou absoluto.

Sintaxe

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

symlink() retorna true em caso de sucesso e false em caso de falha (e emite um aviso). Ela falha se $link já existir, se você não tiver permissão de escrita no diretório do link, ou se os symlinks não forem suportados na plataforma.

Exemplo 1: Criando e Lendo um Link Simbólico

Este exemplo completo cria um arquivo, cria um link para ele e depois confirma que o link aponta de volta para o 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');

Saída:

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

Ler example_link.txt retorna o conteúdo do destino, is_link() detecta que o caminho é um symlink, e readlink() retorna o caminho de destino armazenado.

Exemplo 2: Verificando o Valor de Retorno

symlink() retorna false (com um aviso) se o link já existir ou se o diretório não for gravável, então sempre verifique o resultado em código real:

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

O @ suprime o aviso para que você possa tratar a falha por conta própria. Uma rotina robusta remove um link obsoleto primeiro e verifica o 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 vs. Absolutos

Um $target relativo é resolvido em relação ao diretório que contém o link, não em relação ao diretório de trabalho atual. Essa é uma fonte comum de links quebrados:

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

Use um caminho absoluto quando o link puder ser criado a partir de um diretório de trabalho diferente, ou quando você quiser que ele continue funcionando independentemente de onde o link for lido.

Armadilhas Comuns

• O caminho do link não pode já existir. Exclua ou atualize um link existente com unlink() primeiro; caso contrário, symlink() falhará.
• O Windows exige privilégios elevados. A criação de symlinks requer privilégios de administrador ou o Modo de Desenvolvedor habilitado.
• Links quebrados (pendentes) apontam para um destino ausente. is_link() ainda retorna true, mas file_exists() no link retorna false porque segue o link até o destino ausente.
• As permissões são verificadas no diretório pai do link, que deve ter permissão de escrita.

Conclusão

A função symlink() fornece uma maneira leve de referenciar arquivos e diretórios sem copiar dados. Lembre-se de verificar seu valor de retorno, prefira destinos absolutos quando o diretório de trabalho for incerto e considere os requisitos de permissão específicos da plataforma. Use-a junto com is_link(), readlink() e unlink() para inspecionar e gerenciar links, e consulte a visão geral do Sistema de Arquivos PHP para a API de arquivos mais ampla.

Prática