Lorsque l'option de configuration session.upload_progress.enabled est active, PHP sera capable de traquer la progression d'un fichier en cours de téléchargement. Cette information n'est pas particulièrement utile pour la requête de téléchargement en tant que tel, mais pendant le téléchargement, une application peut envoyer une requête POST séparée (via XHR par exemple) pour vérifier le statut de ce téléchargement.
La progression de téléchargement sera disponible dans la variable super-global $_SESSION lorsque le téléchargement est en cours, et lors d'un envoi en méthode POST d'une variable du même nom que celui définit dans l'option de configuration INI session.upload_progress.name. Lorsque PHP détecte une requête POST de ce type, il remplira un tableau dans $_SESSION, où l'index est une valeur concaténée des options de configuration session.upload_progress.prefix et session.upload_progress.name. La clé est typiquement récupérée en lisant ces configurations INI, i.e.
<?php
$key = ini_get("session.upload_progress.prefix") . $_POST[ini_get("session.upload_progress.name")];
var_dump($_SESSION[$key]);
?>
Il est également possible d'annuler le téléchargement courant
en définissant la clé $_SESSION[$key]["cancel_upload"] à la valeur
TRUE. Lors du téléchargement de plusieurs fichiers dans la même
requête, cette action n'annulera que le fichier actuellement en cours de téléchargement,
ainsi que ceux en attente de téléchargement mais n'annulera pas les téléchargements
terminés avec succès. Lorsqu'un téléchargement est annulé en utilisant cette méthode,
la clé error du tableau $_FILES sera définie à
UPLOAD_ERR_EXTENSION.
Les options de configuration INI session.upload_progress.freq et session.upload_progress.min_freq contrôlent la fréquence de mise à jour des informations de progression de téléchargement. Avec une configuration raisonnable de ces 2 options, la surcoût en terme de charge est quasi nul.
Exemple #1 Exemple
Exemple de structure du tableau contenant les informations de téléchargement.
<form action="upload.php" method="POST" enctype="multipart/form-data">
<input type="hidden" name="<?php echo ini_get("session.upload_progress.name"); ?>" value="123" />
<input type="file" name="file1" />
<input type="file" name="file2" />
<input type="submit" />
</form>
Les données stockées en session ressembleront à :
<?php
$_SESSION["upload_progress_123"] = array(
"start_time" => 1234567890, // L'heure de la requête
"content_length" => 57343257, // Longueur du contenu POST
"bytes_processed" => 453489, // Quantité d'octets reçus et traités
"done" => false, // true lorsque le gestionnaire POST a terminé, avec succès ou non
"files" => array(
0 => array(
"field_name" => "file1", // Nom du champ <input/>
// Les 3 éléments suivants sont équivalents à ceux dans $_FILES
"name" => "foo.avi",
"tmp_name" => "/tmp/phpxxxxxx",
"error" => 0,
"done" => true, // True lorsque le gestionnaire POST a terminé de gérer ce fichier
"start_time" => 1234567890, // L'heure de début de requête
"bytes_processed" => 57343250, // Quantité d'octets reçus et traités pour ce fichier
),
// Un autre fichier, en cours de téléchargement, dans la même requête
1 => array(
"field_name" => "file2",
"name" => "bar.avi",
"tmp_name" => NULL,
"error" => 0,
"done" => false,
"start_time" => 1234567899,
"bytes_processed" => 54554,
),
)
);
La mise en mémoire tampon de la requête du serveur web doit être désactivée pour la bonne marche de cette fonctionalité, sinon PHP ne verra le fichier qu'une fois qu'il sera totalement téléchargé. Les serveurs comme Nginx sont connus pour mettre en mémoire tampon de grosses requêtes.