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éversement (upload). Cette information n'est pas particulièrement utile pour la requête de téléversement en tant que tel, mais pendant le téléversement, une application peut envoyer une requête POST séparée (via XHR par exemple) pour vérifier le statut de ce téléversement.
La progression du téléversement sera disponible dans la variable super-globale $_SESSION lorsque le téléversement est en cours, et lors d'un envoi en méthode POST d'une variable du même nom que celui défini 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éversement courant
en définissant la clé $_SESSION[$key]["cancel_upload"] à la valeur
true. Lors du téléversement 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éversement mais n'annulera pas les téléversement
terminés avec succès. Lorsqu'un téléversement 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éversement. 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éversement.
<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éversement, 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 fonctionnalité, sinon PHP ne verra le fichier qu'une fois qu'il sera totalement téléversé. Les serveurs tel que Nginx sont connus pour mettre en mémoire tampon des grosses requêtes.
Les informations de la progression du téléversement sont écrite en session avant qu'un script soit éxécuté. Par conséquence changer le nom de session grâce à ini_set() ou session_name() donnera une session sans les informations de progression du téléversement.