symlink()

Introduzione

In PHP, la funzione symlink() crea un collegamento simbolico (detto anche symlink o soft link) — un file speciale che funge da puntatore a un altro file o directory. Invece di copiare i dati, un symlink consente a due percorsi di fare riferimento allo stesso target sottostante, così le modifiche apportate tramite uno dei due percorsi influenzano lo stesso file.

I symlink sono utili quando si ha bisogno di un percorso stabile e prevedibile (ad esempio current che punta sempre alla directory dell'ultima release), si vuole esporre lo stesso file con più nomi, oppure si desidera condividere un file di configurazione tra progetti senza duplicarlo.

Questo articolo tratta la sintassi, i parametri, il valore restituito, le insidie comuni e gli esempi eseguibili.

Come funziona un collegamento simbolico

Un collegamento simbolico memorizza un percorso verso il suo target anziché una copia dei dati. Questo differisce da un hard link (creato con link()), che punta direttamente ai dati del file su disco:

• Un symlink può puntare a una directory e può attraversare i confini del filesystem; se il target viene eliminato, il symlink diventa "pendente" (broken).
• Un hard link funziona solo per file sullo stesso filesystem e mantiene i dati in vita anche dopo che il nome originale è stato rimosso.

Poiché un symlink memorizza solo un percorso, tale percorso può essere relativo (risolto rispetto alla directory in cui si trova il link) o assoluto.

Sintassi

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

symlink() restituisce true in caso di successo e false in caso di fallimento (ed emette un avviso). Fallisce se $link esiste già, se non si dispone dei permessi di scrittura nella directory del link, oppure se i symlink non sono supportati sulla piattaforma.

Esempio 1: Creazione e lettura di un collegamento simbolico

Questo esempio completo crea un file, lo collega, poi dimostra che il link punta al file originale:

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

Output:

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

La lettura di example_link.txt restituisce il contenuto del target, is_link() rileva che il percorso è un symlink e readlink() restituisce il percorso del target memorizzato.

Esempio 2: Verifica del valore restituito

symlink() restituisce false (con un avviso) se il link esiste già o la directory non è scrivibile, quindi verifica sempre il risultato nel codice reale:

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

Il @ sopprime l'avviso in modo da poter gestire l'errore autonomamente. Una routine robusta rimuove prima un link obsoleto e verifica il risultato:

<?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 relativi e assoluti

Un $target relativo viene risolto rispetto alla directory contenente il link, non rispetto alla directory di lavoro corrente. Questa è una fonte comune di link non funzionanti:

<?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 un percorso assoluto quando il link potrebbe essere creato da una directory di lavoro diversa, o quando vuoi che continui a funzionare indipendentemente da dove il link viene letto.

Insidie comuni

• Il percorso del link non deve esistere già. Elimina o aggiorna un link esistente con unlink() prima; altrimenti symlink() fallisce.
• Windows richiede privilegi elevati. La creazione di symlink richiede i privilegi di amministratore o la modalità sviluppatore abilitata.
• I link pendenti (dangling) puntano a un target mancante. is_link() restituisce comunque true, ma file_exists() sul link restituisce false perché segue il link fino al target assente.
• I permessi vengono verificati sulla directory padre del link, che deve essere scrivibile.

Conclusione

La funzione symlink() offre un modo leggero per fare riferimento a file e directory senza copiare i dati. Ricorda di verificare il suo valore restituito, preferisci i target assoluti quando la directory di lavoro è incerta e considera i requisiti di permesso specifici della piattaforma. Abbinala a is_link(), readlink() e unlink() per ispezionare e gestire i link, e consulta la panoramica sul Filesystem PHP per l'API dei file più completa.

Esercitazione