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
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
# uploadprogress
A PHP extension to track progress of a file upload, including details on the
speed of the upload, estimated time remaining, and access to the contents of the
file as it is being uploaded.
## Requirements
The uploadprogress extension works on PHP 7.2+ and PHP 8. It works with
[Apache HTTP Server][] using [mod_php][], as well as [Apache HTTP Server][],
[nginx][], and [Caddy][] through [PHP-FPM][]. It might work on other web
servers; let us know where you're using it.
## Example
Check out the [examples][] directory for a working example that you can run on
your local machine.
## Installation
Install uploadprogress with `pecl`:
```
pecl install uploadprogress
```
If it is not automatically added to your `php.ini` file by the `pecl` command,
you will need to update `php.ini` by adding the following line:
``` ini
extension=uploadprogress
```
## Documentation
In forms for which you wish to track a file upload using uploadprogress, you
must include a field named `UPLOAD_IDENTIFIER`.
The value of the `UPLOAD_IDENTIFIER` field may be any string. We recommend a
random, unique string per upload. This extension will use this value to keep
track of the upload, and you may query the extension using this identifier to
check the progress of the upload.
For example, you might choose to define the `UPLOAD_IDENTIFIER` field as such:
``` html
<input type="hidden" name="UPLOAD_IDENTIFIER" value="<?php echo bin2hex(random_bytes(16)); ?>">
```
The uploadprogress extension provides two functions: `uploadprogress_get_info()`
and `uploadprogress_get_contents()`.
While a file is uploading, you may call these functions from a different script
to check on the progress of the uploading file, providing the same identifier
used as the `UPLOAD_IDENTIFIER`.
For example, you might make an HTTP `GET` request to
`/check-progress.php?identifier=some_identifier&fieldName=the_file_upload_form_field_name`.
The contents of `check-progress.php` might contain code like this:
``` php
$identifier = filter_input(INPUT_GET, 'identifier', FILTER_SANITIZE_STRING);
$fieldName = filter_input(INPUT_GET, 'fieldName', FILTER_SANITIZE_STRING);
$info = uploadprogress_get_info($identifier);
$contents = uploadprogress_get_contents($identifier, $fieldName);
```
### php.ini Settings
* `uploadprogress.file.filename_template`:
Set the path and pattern to which the *info* file should be written. This is
where we will store the data about the uploaded file, while it is being
uploaded. You may set it to a directory, or you may optionally use a filename
pattern. It defaults to `sys_get_temp_dir() . '/upt_%s.txt'`. The `%s` is
replaced with the value of `UPLOAD_IDENTIFIER`.
* `uploadprogress.file.contents_template`:
Set the path and pattern to which the *contents* of the uploaded file should
be written. This allows us to read the contents of the file, while it is still
being uploaded. You may set it to a directory, or you may optionally use a
filename pattern. It defaults to `sys_get_temp_dir() . '/upload_contents_%s'`.
The `%s` is replaced with the value of `UPLOAD_IDENTIFIER` combined with the
name of the file upload form field.
* `uploadprogress.get_contents`:
Set to "On" to enable the ability to read a file's contents while it is still
uploading. Defaults to "Off."
**NOTE:** The paths for these INI settings must be *absolute* paths. Relative
paths will not work.
#### Example php.ini
``` ini
extension=uploadprogress
uploadprogress.get_contents=On
uploadprogress.file.filename_template=/tmp/upt_%s.txt
uploadprogress.file.contents_template=/tmp/upload_contents_%s
```
### uploadprogress_get_info
``` php
uploadprogress_get_info ( string $identifier ) : array
```
The `$identifier` is the value of the form field named `UPLOAD_IDENTIFIER`.
This returns an associative array with the following keys:
* `upload_id` - The value of `UPLOAD_IDENTIFIER`.
* `fieldname` - The name of the file upload form field for this file upload.
* `filename` - The original name of the file being uploaded.
* `time_start` - The Unix timestamp at which the upload began.
* `time_last` - The Unix timestamp at which this information was last updated.
* `speed_average` - The average upload speed, in bytes.
* `speed_last` - The last speed calculation, in bytes.
* `bytes_uploaded` - The number of bytes uploaded so far.
* `bytes_total` - The total number of bytes to be upload.
* `files_uploaded` - The total number of files uploaded so far.
* `est_sec` - The estimated number of seconds remaining until the upload is
complete.
### uploadprogress_get_contents
``` php
uploadprogress_get_contents ( string $identifier , string $fieldName [, int $maxLength ] ) : string
```
The `$identifier` is the value of the form field named `UPLOAD_IDENTIFIER`.
The `$fieldName` is the value of the file upload form field name.
The `$maxLength` is an optional number of bytes to read, if you wish to read
only the first `$maxLength` bytes of the uploading file. Otherwise, all bytes
currently uploaded will be read.
This returns a string of all the bytes currently uploaded for the uploading file.
## Contributing
Your contributions and bug reports are highly appreciated. To contribute, fork
and create a pull request. To report a bug use the [PHP Bug Tracking
System](https://bugs.php.net/report.php?package=uploadprogress).
### Building on *nix systems
To compile this extension, execute the following steps:
```shell
phpize
./configure --enable-uploadprogress
make
```
### Building on Windows
The extension provides the VisualStudio V6 project file:
uploadprogress.dsp
To compile the extension you open this file using VisualStudio, select the
apropriate configuration for your installation (either "Release_TS" or
"Debug_TS") and create `php_uploadprogress.dll`.
After successfull compilation you have to copy the newly created
`php_uploadprogress.dll` to the PHP extension directory (default:
`C:\PHP\extensions`).
### Testing
You may now run the tests with the following (on Windows, use `nmake`):
```shell
make test TESTS="-n --show-diff tests"
```
For application testing, you can now load the extension using a php.ini directive
``` ini
extension=uploadprogress
```
The extension should now be available, which you can test using the
`extension_loaded()` function:
``` php
if (extension_loaded('uploadprogress')) {
echo "uploadprogress loaded :)";
} else {
echo "something is wrong :(";
}
```
The extension will also add its own block to the output of `phpinfo();`.
[Apache HTTP Server]: https://httpd.apache.org
[mod_php]: https://www.php.net/manual/en/install.unix.apache2.php
[php-fpm]: https://www.php.net/fpm
[examples]: ./examples
[nginx]: https://nginx.org
[caddy]: https://caddyserver.com
|
