File	Date	Author	Commit
CHANGES.txt	2016-04-22	Nutchanon Wetchasit	[6204f2] mentioning php_zip API change in CHANGELOG
COPYING.txt	2015-07-13	Nutchanon Wetchasit	[ff98f7] Initial commit
LICENSE.txt	2016-04-21	Nutchanon Wetchasit	[4d8582] changing version number to 1.0.0
README.txt	2016-04-23	Nutchanon Wetchasit	[54ee3f] adding ability to respond to HTTP If-Modified-S...
phunzip.php	2016-04-23	Nutchanon Wetchasit	[54ee3f] adding ability to respond to HTTP If-Modified-S...

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