ftp_site()

Comprendere la funzione PHP ftp_site()

La funzione ftp_site() è una funzione PHP integrata che invia un comando SITE a un server FTP. SITE è un comando FTP generico per istruzioni che esulano dal protocollo FTP standard — cose che ogni fornitore di server implementa a modo suo, come la modifica dei permessi dei file, la regolazione dei timeout di inattività o l'esecuzione di attività di manutenzione specifiche del server.

Poiché il significato di un comando SITE è definito interamente dal server remoto, ftp_site() è la valvola di sfogo a cui si ricorre quando non esiste una funzione PHP FTP dedicata per ciò di cui si ha bisogno. Questo articolo spiega cosa fa la funzione, quando usarla (e quando non usarla) e come gestire il risultato in modo sicuro.

Per utilizzarla è necessario prima aprire una connessione con ftp_connect() e autenticarsi con ftp_login(). Consulta la panoramica PHP FTP per la famiglia completa di funzioni.

Cos'è ftp_site()?

La funzione accetta due parametri:

1. ftp — La connessione FTP restituita da ftp_connect() (o ftp_ssl_connect()).
2. command — La stringa del comando SITE grezzo da inviare, senza la parola chiave SITE iniziale (PHP la aggiunge automaticamente).

Restituisce true se il server ha accettato il comando e false in caso di errore. Un risultato true significa solo che il server ha accettato il comando — non garantisce che l'azione sottostante (ad esempio, il cambiamento dei permessi) sia riuscita, poiché il comportamento di SITE è definito dal server.

Sintassi di ftp_site()

La sintassi della funzione ftp_site() è la seguente:

Sintassi di ftp_site()

ftp_site(FTP\Connection $ftp, string $command): bool

A partire da PHP 8.1 il primo argomento è un oggetto FTP\Connection (nelle versioni precedenti era una risorsa). L'argomento command è l'istruzione SITE da inviare — ad esempio CHMOD 644 file.txt. Si passa solo la parte dopo SITE; PHP antepone la parola chiave automaticamente.

Utilizzo di ftp_site()

Per utilizzare la funzione ftp_site(), è necessario prima stabilire una connessione al server FTP utilizzando la funzione ftp_connect(). Ecco un esempio:

Utilizzo di ftp_site()

<?php

// Set up an FTP connection
$conn = @ftp_connect('ftp.example.com');
if (!$conn) {
    die('Could not connect to server.');
}

// Login with your FTP credentials
if (!ftp_login($conn, 'username', 'password')) {
    die('Login failed.');
}

// Send the SITE command
ftp_site($conn, 'CHMOD 755 /public_html/index.php');

// Close the FTP connection
ftp_close($conn);

In questo esempio, ci connettiamo con ftp_connect(), ci autentichiamo con ftp_login(), inviamo SITE CHMOD 755 per cambiare i permessi di index.php, e infine chiudiamo la connessione con ftp_close().

Nota: I comandi SITE sono specifici del server. SITE CHMOD non è supportato universalmente da tutti i server FTP. Per le modifiche standard ai permessi dei file, è preferibile usare la funzione dedicata ftp_chmod(), che è portabile e restituisce il nuovo valore dei permessi. Ricorrere a ftp_site() solo per azioni che non hanno una funzione FTP dedicata.

Comandi SITE comuni

L'insieme esatto dei comandi supportati dipende dal software del server (ProFTPD, vsftpd, Pure-FTPd, ecc.), ma alcuni sono ampiamente disponibili:

In caso di dubbio, eseguire SITE HELP per scoprire cosa accetta un determinato server:

Scoprire i comandi SITE supportati

<?php

$conn = ftp_connect('ftp.example.com');
ftp_login($conn, 'username', 'password');

if (ftp_site($conn, 'HELP')) {
    echo "Server accepted the SITE HELP command.\n";
}

ftp_close($conn);

Gestione degli errori in ftp_site()

È importante gestire correttamente gli errori quando si utilizza la funzione ftp_site(). Se la funzione restituisce false, significa che l'operazione non è riuscita. Ecco un esempio di come gestire gli errori:

Gestione degli errori in ftp_site()

<?php

if (!ftp_site($conn, 'CHMOD 755 /public_html/index.php')) {
    echo "Failed to send SITE command.\n";
}

ftp_close($conn);

Controllando il valore restituito, si evita di continuare silenziosamente dopo un comando rifiutato dal server. Si noti che ftp_site() restituisce false sia quando la connessione è interrotta sia quando il server semplicemente non riconosce il comando — quindi un risultato false è il segnale per ricorrere a una funzione dedicata o a un approccio diverso.

ftp_site() vs. ftp_raw() e ftp_exec()

ftp_site() è strettamente correlata ad altre due funzioni "invia un'istruzione grezza", ed è utile sapere quando scegliere ciascuna:

• ftp_site() — invia un singolo comando SITE e restituisce un boolean. Usarla per azioni specifiche del server come CHMOD o UMASK.
• ftp_raw() — invia qualsiasi comando FTP grezzo (non solo SITE) e restituisce la risposta completa del server come array, in modo da poter leggere il codice di stato. Usarla quando si ha bisogno di esaminare la risposta.
• ftp_exec() — esegue un programma sul server tramite SITE EXEC, dove supportato. Usarla solo su server che si controlla e di cui ci si fida.

Per le operazioni quotidiane (caricamento, scaricamento, elenco, ridenominazione) preferire le funzioni appositamente costruite illustrate nella panoramica PHP FTP; sono più portabili dei comandi SITE costruiti manualmente.

Conclusione

La funzione ftp_site() consente di inviare comandi SITE specifici del server quando nessuna funzione PHP FTP dedicata è adatta allo scopo. Controllare sempre il valore restituito, ricordare che un invio riuscito non equivale a un'azione riuscita, e preferire funzioni portabili come ftp_chmod() ogni volta che ne esiste una.

Pratica