or: How to write a PHP autoloader.

This is a technical document, explaining implementation details for the X Autoload module on drupal.org.

Please apologize if the document may be incomplete. I simply do not have the time and energy to write this up all at once.

Goals

So, here is the wishlist for our specific autoloader:

• Support for PSR-0, PSR-0-NG (*), PEAR, PEAR-NG (*), and arbitrary custom logic registered for a specific namespace or prefix.
• Separation of concerns, composition over inheritance, slicing up our classes and objects into nice small components.
• Unit tests: Keeping most of our components agnostic about the environment, esp. the filesystem, and any platform-specific global state.
• Performance: Make direct lookups decently fast, and then put a cache layer on top of that.
• Support older PHP versions: Support autoloading with namespaces, but do not require them for the autoloader itself.
• A platform-agnostic library, that can be wired up with platform-specific logic.
• As a minimum, be technically competitive to symfony's autoload system.

Further reading:

• (*) X Autoload: "PSR-0-NG"
  Introducing PSR-0-NG as an interesting "home-made standard", with PSR-0 as a special case.
• X Autoload: Namespace registration interface
  Challenge: Support namespace and prefix registration for PSR-0, PEAR, PSR-0-NG, PEAR-NG and custom handlers.
• X Autoload: Slicing it up
  Splitting the logic into nice little, recombineable objects.
• X Autoload: Unit test abstractions, InjectedAPIs
  Factor out file_exists() for easier unit testing, and allow to record all filepath suggestions.
• X Autoload: Performance
  Be competitive with existing solutions, and try to be 90% competitive with the theoretical optimum.
  Optimize direct lookups, then add a cache layer on top of that.