Public Domain
-------------

This is free and unencumbered software released into the public domain.

Anyone is free to copy, modify, publish, use, compile, sell, or
distribute this software, either in source code form or as a compiled
binary, for any purpose, commercial or non-commercial, and by any
means.

In jurisdictions that recognize copyright laws, the author or authors
of this software dedicate any and all copyright interest in the
software to the public domain. We make this dedication for the benefit
of the public at large and to the detriment of our heirs and
successors. We intend this dedication to be an overt act of
relinquishment in perpetuity of all present and future rights to this
software under copyright law.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.

For more information, please refer to <http://unlicense.org/>

0.3.3 alpha (2014-09-03)
------------------------

+ Introduced regex surface scanner to extract class names, functions,
  constants from *.php source files.
- Disabled slower tokenizer method by default.
* Skippen hidden .dot directory (such as .git and .svn).
* Builtin auto_update flag set to false.

0.3.2 alpha (2014-02-14)
------------------------

* Using plain is_writable() check instead of Phar::canWrite().
- All constants (irrespective of define() case-variance) are
  lowercased for the time being (no rfc:autoload support anyway).
* Merged relative path building back into main handler.

0.3.1 alpha (2014-02-12)
------------------------

+ Honor AUTOLOADER_UPDATE environment variable.
* Fix relative_path() building and absolute_path() resolver.

0.3.0 initial (2014-02-11)
--------------------------

* Initial commit with tokenizer building, splittable phar structure,
  single classpath directory and fingeprinting.

0.2.0 (unreleased)
------------------

+ Introduced RecursivePharDirIterator support.

0.1.0 (unreleased)
------------------

+ Trivial tokenizer for scanning *.php scripts.

Canonic Autoloader
------------------

shared.phar is a PHP autoloader for classes and functions. It's map-based
and self-contained in a compressed phar.


 → It scans both .php scripts and .phar collections for class declarations.

 → Honors PHP semantics and avoids plattform ambiguity by interpreting all
   identifiers case-insensitively.

 → Can be updated manually or implicitly (AUTOLOADER_UPDATE env variable).


Usage
-----

Using it is as simple as:

    include("./vendor/shared.phar");

Updating the internal map can be done from the command line:

    php -dphar.readonly=0 ./shared.phar

It's currently best to do so in the main project directory. All scripts
are scanned for class/function/const declarations below its basedir.

There'll be warnings for duplicate declarations.  When using the internal
tokenizer method, there'll all also be warnings for syntax structure woes.
The default regex method will merely ignore invalid code for the generated
classmap.


Automatic scanning
------------------

For development setups the implicit update is advisable, which kicks in
whenever an unknown class name gets requested. Set it per virtual domain
with:

    SetEnv AUTOLOADER_UPDATE 1

On deployment `shared.phar` can just be copied along with the include
structure (AKA classpath).


Internal structure
------------------

`shared.phar` is a ZIP-based Phar. Its stub contains the autoloader logic,
while the classmap is located in `autoload.map.php` and the update code in
`autoload.update.php`.

Current versions (0.3.x) might be split up, while future versions will drop
that option.


Application advise
------------------

 → Preferrably encode class names *and* filenames in UTF-8.

   PHP 5.x isn't strict about this and literally accepts any character in
   the 0x7F-0xFF range as valid for identifiers. Thus `shared.phar` does not
   enforce anything either.

   It's common sense to use Unicode-valid filenames however WHEN there's a
   need for non-ASCII class names or file names.
   (Prefer plain English though generally for distributable code!)

 → Remove duplicate class declarations. Use a source code versioning system
   instead of leaving edited stubs or old backups in your classpath.

 → Optimize your class dependencies. When using a map-based autoloader,
   there's no need to scatter class declarations across hundreds of separate
   scripts.

.\"
.TH shared.phar "0.3.3 - September 2014" "BSD/Linux" "User Manuals"
.SH NAME
shared.phar \- Canonic PHP Autoloader
.SH SYNOPSIS
.I php
.B shared.phar
.RB [ path ,
.IR ... ]
.SH DESCRIPTION
shared.phar is a map-based autoloader for
.B *.php
scripts and
.B *.phar
collections. It self-contains the generated class map, and
also prepares for function autoloading support (far-fetched
future, when php-dev gets a grip).
.P
.VS
By default it scans the directories beneath its location.
The primary installation thus
.I /usr/share/php
and all its contained includes.
.P
.I Not impemented:
future versions will allow to specify a list of directories
as arguments to include in the scanning process. Hereby
.IR ./ relative
path names will be kept relative to 
.B shared.phar
itself. While absolute
.IR / paths
are never transformed.
.SH FEATURES
.IP \(bu 2
Traverses any directory structure, but skips .hidden dirs,
while scanning *.php scripts.
.IP \(bu 2
Stores identifiers (classes, functions) case-insensitively
for consistency with PHP.
.IP \(bu 2
Phar collections are traversed as well, and references
stored with relative paths.
.SH PHP USAGE
Activating the autoloader within PHP applications is as simple as calling
.IP 
.BR include_once (
.I """shared.phar""
.RB ) ;
.P
Which will implictly load the contained classmap.
.SH ENVIRONMENT
Recognized environment variables (as set via
.IB ".htaccess " SetEnv
for instance) in webserver or CLI context.
.TP
.BR AUTOLOADER_UPDATE " (boolean)"
Will enable implicit classmap updates on missed identifier (class)
lookups. Advisable for development setups only.
.SH FORMAT
The default
.B shared.phar
package is a PKZIP archive.
.SH "SEE ALSO"
.BR php (1)
.BR phar (5)