Map-based autoloader across php and phar resources

⌈⌋ ⎇ branch:  Canonic Autoloader


Check-in [9a42dc06af]

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Update notes about pharmap.php and addPhar(). (Section about recommended alternative autoloaders finally committed.)
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 9a42dc06afd95cc72ea0c9f51d99435ebdac8ef9
User & Date: mario 2015-01-22 19:43:06
Context
2015-01-22
20:15
Transition to xpm package+phar building. Fix self::$instance[] appending. check-in: 806985bee2 user: mario tags: trunk
19:43
Update notes about pharmap.php and addPhar(). (Section about recommended alternative autoloaders finally committed.) check-in: 9a42dc06af user: mario tags: trunk
19:36
Tool to regenerate .phar-internal class/func `map`, which is compatible to the shared.phar/autoload.map.php array structure, but stored as Phar meta data array. (Compatibility to xpm-generated composer deb/rpm/phar bundles.) check-in: 369216d430 user: mario tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to README.

︙︙
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

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








|
|
>
|
|
>
>











|
|
>












>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>








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

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 invalidly structured code blocks.
 → The default regex method will merely ignore code nesting errors.

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


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

Then adapting phar.readonly=0 in the php.ini is necessary in any case.
(Which was intended as security feature obviously, to eschew manual file
permission management on a per-phar basis.)


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.


Composer .phars
---------------

You might use https://fossil.include-once.org/xpm/ to convert e.g. composer
bundles into system and .phar packages:

   xpm -s composer --phar -t deb,rpm,phar vnd/pkg

Which then contain a `map` array in the Phar containers meta data. It's
compatible to the shared.phar-internal identifier map, and can easily be
registered (at runtime) using:

   Canonic_Autoloader::addPhar("vnd-pkg.phar");

The same map[] can be crafted into any Phar using the `pharmap.php` tool.


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
︙︙
75
76
77
78
79
80
81
82
83
84

























   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.

 → It runs on PHP 5.3+, albeit PHP 5.2 (which even in 2014 is still used on
   around 20% of webservers) works too with present PECL Phar extension.


































|


>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>

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

   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.

 → It runs on PHP 5.3+, albeit PHP 5.2 (which even in 2014 is still used on
   over 20% of webservers) might work too with present PECL Phar extension.


Alternatives
------------

 → [Automap](https://github.com/flaupretre/automap) implements a similar
   map-based approach, also highly compliant to PHP semantics, including
   function and constant declaration lookups.
   The token traversor looks better designed than the one in Canonic_Automap;
   even takes meta definitions into account.
   Implements PHK format support (preceds PHAR packages), which already
   provide meta-bundling and some autoloading support by themselves.

 → [phpab](https://github.com/theseer/Autoload) is another well-designed
   autoload builder. It also doubles as Phar packaging tool for merging
   dependencies into distributable bundles. It's highly configurable (unlike
   shared.phar), therefore allows for more targetted results, and adds more
   robust PHP 5.2 compatibility.
   It's also PHP language compliant per default. (Doesn't yet scan within
   phar packages itself however.)

 → [OPL3/PHARLoader](https://github.com/OPL/opl3-autoloader) provides some
   Phar loading support, but being PSR-0 articled forgos proper identifier
   mapping.