PHUnzip Code
Allow web server to serve files inside ZIP archive
Status: Alpha
Brought to you by:
xwindows
Menu
▾
▴
Tree [54ee3f] master / History
Read Me
PHUnzip (PHp Unzip)
Allow web server to serve files inside ZIP archive
PHUnzip serves as an easy (maybe too easy) way for client to access files
inside ZIP archive on the web server in a transparent manner. It acts
as an ZIP extractor which reads ZIP file, extract the content and pass it along
directly to the client.
You can use it to serve entire folder from a compressed ZIP archive;
exellent when you have a space-constrained web hosting.
Or use it as a way to see/download individual file inside a ZIP archive
as well as allowing user to download the archive itself without actually
hosting *two copies* of your file.
Tradeoff is more processing power and memory was required to serve
files inside ZIP, compared to regular file.
Project website: http://phunzip.sourceforge.net/
Contents
--------
1. How to Use
2. System Requirements
3. Limitations
4. Advanced Usage
4.1 General
4.2 Security Considerations
4.3 Directory Listing
4.4 Welcome File
4.5 Custom MIME Types
4.6 URL Rewriting
5. Troubleshooting
6. Author
1. HOW TO USE
=============
1. Unpack 'phunzip.php' to your web space, in the same folder as your ZIP file.
2. Now you can access contents inside your ZIP file by adding 'phunzip.php/'
in front of your ZIP file name in the URL, and add '/path/to/file/inside'
at the end of your ZIP file name.
Example:
ZIP file URL: http://phunzip.sourceforge.net/0.2.0/example.zip
When you want to access 'triangle.bmp', within folder 'test2' inside
the ZIP file, the URL is:
http://phunzip.sourceforge.net/0.2.0/phunzip.php/example.zip/test2/triangle.bmp
Simple, right?
3. If your zip file have the same structure as a web folder (with 'index.html'
and all), you can specify just a path to folder in ZIP file.
Example:
ZIP file URL: http://phunzip.sourceforge.net/0.2.0/example.zip
When you want to access main folder inside the ZIP file, which have
web content and index page, the URL is:
http://phunzip.sourceforge.net/0.2.0/phunzip.php/example.zip/
4. If you just want to let your user browse for files in the folder, there is
also a directory listing available. This is not enabled by default,
see 'Advanced Usage' section on how to enable it first.
Example:
ZIP file URL: http://phunzip.sourceforge.net/0.2.0/example.zip
When you want to browse for files in folder 'test1' inside the ZIP file
(the folder must not have an 'index.html' file), URL is:
http://phunzip.sourceforge.net/0.2.0/phunzip.php/example.zip/test1/
2. SYSTEM REQUIREMENTS
======================
To use PHUnzip, your web server must...
- Support PHP (obviously), using version 5.2.0+.
- Have ZIP support ('php_zip' extension with ZipArchive API) enabled in PHP
runtime. (It was enabled by default since PHP 5.3) You'll know immediately
if your PHP installation doesn't; see 'Troubleshooting' section about
403 Forbidden error.
3. LIMITATIONS
==============
- It does not support viewing inside ZIP file that is contained in another
ZIP file.
- Web applications and '.htaccess' file won't work from inside the ZIP file,
for an obvious reason.
- 'phunzip.php' must be placed in the same real folder tree as the ZIP file.
Don't worry about this if you didn't use Apache's <Alias> directive.
- Advanced features like download continuation, and HTTP OPTIONS method are
not supported. HTTP HEAD method support is provided by web server.
- Classic ZIP format only, maximum 65535 files+folders inside. Single
uncompressed file must not be bigger than 2GiB-1 bytes. Encryption and ZIP64
format are not supported.
4. ADVANCED USAGE
=================
4.1 General
-----------
You don't have to put your ZIP file into the same folder as 'phunzip.php',
subfolders works too. For example:
You ZIP file: /some/folder/zipfile.zip
Your phunzip.php: /phunzip.php
File inside zip: file/inside.txt
Access URI: /phunzip.php/some/folder/zipfile.zip/file/inside.txt
4.2 Security Considerations
---------------------------
It is recommended that you put some access control mechanism in place to limit
which ZIP file is viewable via PHUnzip to prevent security issue,
for example:
- When you have several non-ZIP file in the same folder/subfolder as
'phunzip.php', some file may not be well-liked by PHP's ZIP API; trying to
access them via PHUnzip may cause PHP to crash and/or allow attacker to
take control of your server.
Common access control mechanism, for example: Allow/Deny directive in
'.htaccess', or Apache's mod_rewrite. Or you may want to use URL rewriting
facility (like Apache's mod_rewrite) to hide the fact that you're using
PHUnzip altogether.
Another workaround is just separating 'phunzip.php' along with ZIP files that
are intended to be viewed via PHUnzip into a dedicated folder.
4.3 Directory Listing
---------------------
Directory listing inside ZIP file is supported but not enabled by default.
You can enable it by looking for a line like this in 'phunzip.php':
$allow_listing=FALSE;
Change 'FALSE' to 'TRUE' then save, and directory listing will be enabled.
4.4 Welcome File
----------------
If you want to change welcome file name (file in a directory that will be shown
by default if user requested to view a directory in ZIP file) which is
'index.html' by default, look for a line like this in 'phunzip.php':
$welcomefile="index.html";
You could change 'index.html' to any file name you want, e.g. 'README.txt'.
(File name is case sensitive)
If you want to turn off welcome file support (for whatever reason),
either remove 'index.html' part (keep the double quotes) or comment out
the entire line by putting '#' in front of the line.
4.5 Custom MIME Types
---------------------
If you got a file with weird extension and found that PHUnzip served it up
using a generic 'application/octet-stream' MIME type, you can fix it by
adding your custom MIME type mapping. Look for a line like this in
'phunzip.php':
$mimemap=array(
Lines followed them define file extension to MIME type mapping in this
format:
"filextension" => "mimetype",
'fileextension' must be lowercase and exclude dot ('.'). Also, if you add
your custom extension as the last entry, the trailing comma (',') must be
omitted. For example, adding AutoCAD file of '.dwg' extension:
"dwg" => "application/acad",
Extra note: PHUnzip cannot use server's configured MIME type mapping,
this was due to PHP's limitation.
4.6 URL Rewriting
-----------------
Special consideration when URL rewriting mechanism is used:
If welcome file found (and enabled) and/or directory listing is enabled,
when user tries to access a directory without using a trailing slash,
PHUnzip redirects to the slash-added *user URL* rather than the slash-added
internal URI, for example:
User URI: /somefile.zip/path/to/folder
Internal URI: /private/phunzip.php/otherfile.zip/path/to/folder
Redirect URI: /somefile.zip/path/to/folder/
This means a rewrite rule like this won't work properly if user-requested
folder path is not ended with slash:
User URI: /zipfile?file=path/to/folder
Internal URI: /private/phunzip.php/otherfile.zip/path/to/folder
Redirect URI: /zipfile/?file=path/to/folder
You'd see that redirection doesn't go as expected, as slash is not added
in the right place (and results in HTTP 404 Not Found error).
So, as a rule of thumb, URL rewriting rules which works with PHUnzip
in most configuration would look like this:
User URI: /public/prefix/(FILEPATH)
Internal URI: /internal/path/phunzip.php/path/to/zipfile.zip/(FILEPATH)
And, optionally, use HTTP 302 to redirect the `/public/prefix` (without
trailing slash) to the one with trailing slash, just in case user tries to
access ZIP's root directory without slash.
An alternative way to use unconventional user-side URL is to specify
rewrite rule for every individual file you'd like to make available.
Also, this redirection problem won't affect you if you didn't use both
welcome file and directory listing support.
5. TROUBLESHOOTING
==================
PHUnzip does not use any kind of error reporting or logging, other than the
error pages that are displayed to user. Error page are designed to mimic
Apache's default error pages to make the access transparent as much as possible
(at some expense of troubleshooting).
PHUnzip produces four kinds of error page, which each one corresponds to a HTTP
response code:
- 403 Forbidden:
"Forbidden
You don't have permission to access /x/y/z on this server."
If you encountered this error when using PHUnzip (provided that no other
access control mechanism triggered the error), it means that your PHP
runtime has no ZIP support.
If your server is running on GNU/Linux, you should be able to just install
a package named "php-zip" and gain ZIP support. For other ways to add
ZIP support to your PHP installation without upgrading whole PHP runtime,
see <http://php.net/manual/en/zip.installation.php>.
- 404 Not Found:
"Not Found
The requested URL /x/y/z was not found on this server."
This one is the least obvious error, if you specified path to phunzip.php
correctly, it can mean either that no ZIP file was specified in the URL,
ZIP file specified in the URL was not found, file path specified within
the ZIP was not found, or path within the ZIP you specified was a folder
rather than file (when directory listing was not enabled and no welcome file
was found in that folder).
- 500 Internal Server Error:
"Internal Server Error
The server encountered an internal error or misconfiguration and was
unable to complete your request.
Please contact the server administrator, and inform them of the time the
error occurred, and anything you might have done that may have caused the
error.
More information about this error may be available in the server error
log."
If you encountered this error when using PHUnzip (provided that no other
problem with server or PHP runtime triggered it), it means that PHUnzip
encountered problem on opening/reading the ZIP file. Usually happen when you
tried to access a corrupted ZIP file or non-ZIP file via PHUnzip.
Extra note: PHUnzip cannot use server's default error pages directly, due to
limitation of PHP and CGI in general.
6. AUTHOR
=========
PHUnzip is written by Nutchanon Wetchasit,
released as Free Software under GNU GPL.
For legal information, see LICENSE.txt
