Map-based autoloader across php and phar resources

⌈⌋ branch:  Canonic Autoloader


Artifact [3a5a1a9784]

Artifact 3a5a1a97841061913a30b39acef632af39367ce0:

  • File README — part of check-in [0f47a9ce94] at 2014-09-08 13:44:19 on branch trunk — Add minimum documentation. (user: mario size: 2400)


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.