ftp_mdtm()

Cos'è ftp_mdtm()?

La funzione ftp_mdtm() è una funzione built-in di PHP che recupera il tempo dell'ultima modifica di un singolo file su un server FTP. "mdtm" sta per modification time — corrisponde direttamente al comando MDTM del protocollo FTP.

È particolarmente utile quando si desidera sincronizzare file, rilevare modifiche, o decidere se riscaricare qualcosa: invece di scaricare l'intero file solo per verificare se è più recente della copia locale, si chiede al server il suo timestamp.

Accetta due parametri:

1. ftp — l'identificatore di connessione restituito da ftp_connect().
2. remote_file — il percorso del file sul server.

La funzione restituisce l'ora dell'ultima modifica come timestamp Unix (secondi dal 1970-01-01 UTC). In caso di errore — il file non esiste, il percorso punta a una directory, oppure la connessione non è valida — restituisce -1.

ftp_mdtm() funziona solo con file regolari. Molti server rifiutano MDTM per le directory, quindi chiamarla su una cartella restituisce tipicamente -1.

Sintassi di ftp_mdtm()

ftp_mdtm(resource|FTP\Connection $ftp, string $remote_file): int

Il tipo resource era utilizzato fino a PHP 7. A partire da PHP 8.1, le connessioni FTP sono oggetti (FTP\Connection), quindi il primo argomento è un'istanza di FTP\Connection — ma si passa comunque ciò che ftp_connect() ha restituito, così il codice esistente continua a funzionare senza modifiche.

Questa funzione richiede una connessione FTP attiva. Non attiva automaticamente la modalità passiva; se la rete è protetta da un firewall o NAT, chiamare ftp_pasv($ftp, true) dopo il login e prima di richiedere il timestamp.

Utilizzo di base

Per usare ftp_mdtm(), connettersi prima con ftp_connect() e autenticarsi con ftp_login():

<?php

// Set up an FTP connection
$conn = ftp_connect('ftp.example.com');

// Log in with your FTP credentials
ftp_login($conn, 'username', 'password');

// Enable passive mode (often required behind a firewall)
ftp_pasv($conn, true);

// Get the last modified time of the remote file (a Unix timestamp)
$last_modified = ftp_mdtm($conn, '/path/to/remote/file.txt');

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

Convertire il timestamp in una data leggibile

Poiché ftp_mdtm() restituisce un timestamp Unix grezzo, è quasi sempre necessario formattarlo con date() prima di mostrarlo a un utente. La conversione è puro PHP, quindi funziona ovunque — nessun server FTP necessario:

<?php

// Pretend ftp_mdtm() returned this timestamp
$last_modified = 1718000000;

echo "Raw timestamp: $last_modified\n";
echo "Formatted (UTC): " . gmdate('Y-m-d H:i:s', $last_modified) . " UTC\n";
echo "Year only: " . gmdate('Y', $last_modified) . "\n";

Output:

Raw timestamp: 1718000000
Formatted (UTC): 2024-06-10 06:13:20 UTC
Year only: 2024

MDTM restituisce l'ora in UTC. Usare gmdate() (o impostare esplicitamente il fuso orario) in modo che l'ora visualizzata non venga silenziosamente spostata dal fuso orario locale del server. Vedere date() per l'elenco completo dei caratteri di formato.

Gestione degli errori in ftp_mdtm()

Poiché la funzione restituisce -1 in caso di errore, verificare tale valore con l'operatore di confronto stretto ===. Un confronto generico == corrisponderebbe anche a false e altri valori falsy, nascondendo risultati reali:

<?php

$last_modified = ftp_mdtm($conn, '/path/to/remote/file.txt');

if ($last_modified === -1) {
    echo "Failed to retrieve the last modified time.\n";
} else {
    echo "Last modified: " . gmdate('Y-m-d H:i:s', $last_modified) . " UTC\n";
}

Caso d'uso comune: scarica solo se più recente

Il motivo tipico per chiamare ftp_mdtm() è evitare di riscaricare un file invariato. Confrontare il timestamp remoto con il tempo di modifica del file locale:

<?php

$remote = '/path/to/remote/file.txt';
$local  = 'file.txt';

$remoteTime = ftp_mdtm($conn, $remote);

if ($remoteTime === -1) {
    echo "Could not read remote timestamp.\n";
} elseif (!file_exists($local) || $remoteTime > filemtime($local)) {
    echo "Remote file is newer — downloading.\n";
    ftp_get($conn, $local, $remote, FTP_BINARY);
} else {
    echo "Local copy is up to date — skipping download.\n";
}

Questo schema mantiene efficienti mirror e backup: i byte vengono trasferiti solo quando la copia del server è effettivamente più recente.

Avvertenze

• Il supporto del server varia. MDTM non fa parte dello standard FTP originale, quindi alcuni server più vecchi o con restrizioni non lo implementano e restituiscono sempre -1, anche per file esistenti.
• Le directory restituiscono -1. Usare ftp_nlist() per elencare il contenuto delle directory.
• Fuso orario. I timestamp sono in UTC; formattare con gmdate() per evitare offset inattesi.
• Serve anche la dimensione del file? Abbinarlo a ftp_size().

Conclusione

ftp_mdtm() recupera il timestamp Unix dell'ultima modifica di un file su un server FTP, rendendolo il componente fondamentale per il rilevamento delle modifiche e la sincronizzazione incrementale. Ricordare di verificare il valore di errore -1 con ===, formattare il risultato con date() o gmdate(), e abilitare la modalità passiva quando la rete lo richiede.

Esercizio