is_link()

O que a Função is_link() Faz

Um link simbólico (ou symlink) é um arquivo especial que aponta para outro arquivo ou diretório, funcionando como um atalho. A função is_link() é uma função PHP embutida que indica se um determinado caminho é, em si, um link simbólico.

Ela retorna:

• true — se o caminho existir e for um link simbólico.
• false — se o caminho for um arquivo ou diretório comum, não existir ou não puder ser lido.

Um ponto importante que confunde muita gente: is_link() avalia o próprio caminho, não o que o link aponta. Um symlink que aponta para um arquivo regular ainda é reportado como link por is_link(), mesmo que is_file() também retorne true para o mesmo caminho (porque ela segue o link até o destino).

Esta página aborda a sintaxe, um exemplo completo e executável, o erro mais comum (o cache de stat) e como is_link() difere de outras verificações de sistema de arquivos relacionadas.

Sintaxe

is_link(string $filename): bool

$filename é o caminho a ser verificado. A função retorna um booleano.

Um Exemplo Completo e Executável

Como um symlink raramente existe em um caminho fixo, a forma mais confiável de ver is_link() em ação é criar um primeiro com symlink(), verificá-lo e depois limpar:

<?php

$target = tempnam(sys_get_temp_dir(), 'tgt'); // a real regular file
$link   = sys_get_temp_dir() . '/my_symlink';

// Make sure we start clean, then create the symlink.
@unlink($link);
symlink($target, $link);

var_dump(is_link($link));    // bool(true)  — the path is a symlink
var_dump(is_link($target));  // bool(false) — the target is a regular file
var_dump(is_file($link));    // bool(true)  — is_file() follows the link

// Clean up.
unlink($link);
unlink($target);

is_link($link) é true porque o caminho é o symlink, enquanto is_link($target) é false porque o destino é um arquivo comum. Note que is_file($link) é true — ela resolve o link e testa o destino.

O Problema do Cache de Stat

O PHP armazena em cache os resultados de funções de sistema de arquivos como is_link(), is_file() e file_exists() por questões de desempenho. Se você criar, excluir ou substituir um symlink durante a execução do mesmo script e verificá-lo novamente, poderá obter um resultado desatualizado. Chame clearstatcache() para forçar uma nova verificação:

<?php

$link = sys_get_temp_dir() . '/cache_demo';
@unlink($link);
symlink(__FILE__, $link);

var_dump(is_link($link)); // bool(true)

unlink($link);
clearstatcache();          // without this, the next check may still say true
var_dump(is_link($link)); // bool(false)

is_link() vs. Funções Relacionadas

Para inspecionar para onde um link aponta, use readlink(); para resolver um caminho com todos os symlinks expandidos, use realpath().

Quando Usar?

• Scripts de deploy que alternam um symlink current entre diretórios de release e precisam confirmar que é realmente um link antes de substituí-lo.
• Ferramentas de backup ou sincronização que precisam decidir se copiam o próprio link ou o arquivo para o qual ele aponta.
• Verificações de segurança que rejeitam caminhos fornecidos pelo usuário que usam symlinks apontando para fora de um diretório permitido.

Conclusão

is_link() responde a uma pergunta precisa: este caminho é um link simbólico? Ela avalia o próprio caminho em vez de segui-lo, retorna false para caminhos inexistentes e compartilha o cache de stat do PHP — portanto, chame clearstatcache() se você alterar links durante a execução do script. Combine-a com is_file(), readlink() e realpath() quando precisar saber para onde um link aponta.

Prática