/
upload-progress.xml
157 lines (153 loc) · 6 KB
/
upload-progress.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 184f3f7bd45643cb80f828d0bb001991ec3a5fad Maintainer: nobody Status: ready -->
<!-- Reviewed: yes Maintainer: samesch -->
<!-- Credits: tihox -->
<chapter xml:id="session.upload-progress" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Fortschritt eines Uploads in einer Session</title>
<para>
Wenn die Ini-Option
<link linkend="ini.session.upload-progress.enabled">session.upload_progress.enabled</link>
aktiviert ist, kann PHP den Upload-Fortschritt der einzelnen hochgeladenen
Dateien verfolgen. Die von PHP bereitgestellten Daten sind für den
eigentlichen Upload-Vorgang selbst nicht nutzbar, aber während des
Datei-Uploads kann eine Anwendung eine POST-Anfrage an einen separaten
Endpunkt senden (&zb; über <acronym>XHR</acronym>), um den
Status zu ermitteln.
</para>
<para>
Der Upload-Fortschritt steht während des Upload-Vorgangs in der
Superglobalen <varname>$_SESSION</varname> zur Verfügung und bei einer
POST-Anfrage nach der Variablen mit dem in der ini-Konfiguration
<link linkend="ini.session.upload-progress.name">session.upload_progress.name</link>
hinterlegten Namen. Wenn PHP eine solche POST-Anfrage erkennt, wird ein
Array mit Informationen in der <varname>$_SESSION</varname> hinterlegt. Die
Informationen werden mit dem aus den ini-Konfigurationen
<link linkend="ini.session.upload-progress.prefix">session.upload_progress.prefix</link>
und
<link linkend="ini.session.upload-progress.name">session.upload_progress.name</link>
zusammengesetzten Index gespeichert. Der Schlüssel wird dabei typischerweise
aus den ini-Konfigurationen zusammengesetzt, zum Beispiel:
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
$key = ini_get("session.upload_progress.prefix") . $_POST[ini_get("session.upload_progress.name")];
var_dump($_SESSION[$key]);
?>
]]>
</programlisting>
</informalexample>
</para>
<para>
Es ist auch möglich, den Upload-Vorgang <emphasis>abzubrechen</emphasis>,
indem der Session-Wert <literal>$_SESSION[$key]["cancel_upload"]</literal>
auf &true; gesetzt wird. Wenn mehrere Dateien in der gleichen Anfrage
übertragen werden, werden dabei nur der Upload der in der Verarbeitung
befindlichen Datei und alle ausstehenden Datei-Uploads abgebrochen. Bereits
erfolgreich übertragene Dateien werden nicht entfernt. Wenn ein Upload auf
diese Weise abgebrochen wird, enthält der <literal>error</literal>-Schlüssel
des <varname>$_FILES</varname>-Arrays den Wert
<constant>UPLOAD_ERR_EXTENSION</constant>.
</para>
<para>
Die Ini-Konfigurationen
<link linkend="ini.session.upload-progress.freq">session.upload_progress.freq</link>
und
<link linkend="ini.session.upload-progress.min-freq">session.upload_progress.min_freq</link>
steuern, wie häufig die Upload-Fortschrittsinformationen neu berechnet
werden sollen. Mit angemessenen Einstellungen bei diesen zwei Optionen ist
der Aufwand für diese Funktion sehr gering.
</para>
<para>
<example>
<title>Beispiel-Informationen</title>
<para>
Beispiel für den Formularaufbau des Upload-Fortschritts.
</para>
<programlisting role="html" xml:id="session.upload-progress.example-form">
<![CDATA[
<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>
]]>
</programlisting>
<para>
Die gespeicherten Daten in der Session sehen wie folgt aus:
</para>
<programlisting role="php" xml:id="session.upload-progress.example-array">
<![CDATA[
<?php
$_SESSION["upload_progress_123"] = array(
"start_time" => 1234567890, // Anfragezeitpunkt
"content_length" => 57343257, // POST-Gesamtdatenmenge (in Bytes)
"bytes_processed" => 453489, // Menge der empfangenen und verabreiteten Daten (in Bytes)
"done" => false, // true, wenn die POST-Datenverarbeitung beendet ist (erfolgreich oder nicht)
"files" => array(
0 => array(
"field_name" => "file1", // Name des <input/>-Feldes
// Die nächsten drei Elemente entsprechen den Angaben in $_FILES
"name" => "foo.avi",
"tmp_name" => "/tmp/phpxxxxxx",
"error" => 0,
"done" => true, // true, wenn die POST-Datenverarbeitung dieser Datei beendet ist
"start_time" => 1234567890, // Zeitpunkt, an dem die Verarbeitung der Datei begonnen hat
"bytes_processed" => 57343250, // Anzahl der empfangenen und verarbeiteten Daten dieser Datei (in Bytes)
),
// Eine weitere Datei, die noch nicht komplett hochgeladen ist, in derselben Anfrage
1 => array(
"field_name" => "file2",
"name" => "bar.avi",
"tmp_name" => NULL,
"error" => 0,
"done" => false,
"start_time" => 1234567899,
"bytes_processed" => 54554,
),
)
);
]]>
</programlisting>
</example>
</para>
<warning>
<para>
Damit dies richtig funktioniert, muss die Anfragepufferung des Webservers
deaktiviert sein, sonst sieht PHP den Datei-Upload möglicherweise erst,
wenn er abgeschlossen ist. Server wie Nginx sind bekannt dafür, große
Anfragen zu puffern.
</para>
</warning>
<caution>
<para>
Die Upload-Fortschrittsinformationen werden in die Session geschrieben,
bevor irgendein Skript ausgeführt wird. Daher führt die Änderung des
Session-Namens per <function>ini_set</function> oder
<function>session_name</function> zu einer Session ohne die
Upload-Fortschrittsinformationen.
</para>
</caution>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->