You are here

Home » API reference » Autoload 6.2

README.txt in Autoload 6.2

Same filename and directory in other branches
  1. 6 README.txt
ABOUT

The autoload module is a utility module.  It allows other modules to leverage
PHP 5's class autoloading capabilities in a unified fashion.  It does, naturally,
require PHP 5.1.2 or later.

You do not need this module unless you are developing a module that makes use of
classes or you are installing a module that depends on this one.


API

PHP 5 supports automatic class lazy-loading in user-defined ways.  A developer
can register one or more autoload functions.  When PHP encounters a request for
a class that is not yet loaded, it will then call all registered autoload
functions to allow them to try and load the library in which that class is
defined.  It then tries to load the class again.  If the class is now available,
it loads normally.  If not, it generates a fatal error just as it would have
if there had been no autoload functions.  The catch, of course, is making sure
the autoload functions know how to find the requested class.

This module provides one one hook, but it's an alter. To declare files that
contain classes or interfaces, it's very easy. You add them to your module's
.info file as file directives. Example:

files[] = mymodule.inc
files[] = includes/mymodule.randomfile.inc

hook_autoload_registry_files_alter() is a typical alter hook, and is provided
primarily because having alter hooks is the Drupal Way (tm).

That's it!  Once you declare a class and its location (and clear the cache!),
the autoload module knows about it and will lazy-load the class for you as
needed.  You do not need to make any other changes to your object-using code.
Simply call:

$example = new ExampleClass();

as you normally would anyway and the rest happens automatically.

The included "autoloadtest" module provides a trivial but working example.  It
does not include an info file in order to keep it from showing up in the modules
list.


OPTIMIZATION

Do not fall into the easy trap of having one class per file!  Lazy-loading classes
is intended to reduce the amount of code that needs to be parsed on every page,
thus improving performance.  However, loading multiple files into memory is slower
than loading a single file into memory.  There is a trade-off that you will need
to optimize for your specific use case.

In general, classes that will be needed very frequently should remain in the
.module file.  Other classes should be logically grouped into separate include
files so that classes and interfaces that are used together are loaded
together as well.  That skips the autoloading process as well as the extra disk
hit.

When in doubt, benchmarks are your friend.


CREDITS

This module was developed by Larry "Crell" Garfield and
backported from Drupal 7 (aka improved) by Dave "The Doctor" Reid.

File

README.txt
View source 
  1. ABOUT

  2. 

  3. The autoload module is a utility module.  It allows other modules to leverage

  4. PHP 5's class autoloading capabilities in a unified fashion.  It does, naturally,

  5. require PHP 5.1.2 or later.

  6. 

  7. You do not need this module unless you are developing a module that makes use of

  8. classes or you are installing a module that depends on this one.

  9. 

  10. 

  11. API

  12. 

  13. PHP 5 supports automatic class lazy-loading in user-defined ways.  A developer

  14. can register one or more autoload functions.  When PHP encounters a request for

  15. a class that is not yet loaded, it will then call all registered autoload

  16. functions to allow them to try and load the library in which that class is

  17. defined.  It then tries to load the class again.  If the class is now available,

  18. it loads normally.  If not, it generates a fatal error just as it would have

  19. if there had been no autoload functions.  The catch, of course, is making sure

  20. the autoload functions know how to find the requested class.

  21. 

  22. This module provides one one hook, but it's an alter. To declare files that

  23. contain classes or interfaces, it's very easy. You add them to your module's

  24. .info file as file directives. Example:

  25. 

  26. files[] = mymodule.inc

  27. files[] = includes/mymodule.randomfile.inc

  28. 

  29. hook_autoload_registry_files_alter() is a typical alter hook, and is provided

  30. primarily because having alter hooks is the Drupal Way (tm).

  31. 

  32. That's it!  Once you declare a class and its location (and clear the cache!),

  33. the autoload module knows about it and will lazy-load the class for you as

  34. needed.  You do not need to make any other changes to your object-using code.

  35. Simply call:

  36. 

  37. $example = new ExampleClass();

  38. 

  39. as you normally would anyway and the rest happens automatically.

  40. 

  41. The included "autoloadtest" module provides a trivial but working example.  It

  42. does not include an info file in order to keep it from showing up in the modules

  43. list.

  44. 

  45. 

  46. OPTIMIZATION

  47. 

  48. Do not fall into the easy trap of having one class per file!  Lazy-loading classes

  49. is intended to reduce the amount of code that needs to be parsed on every page,

  50. thus improving performance.  However, loading multiple files into memory is slower

  51. than loading a single file into memory.  There is a trade-off that you will need

  52. to optimize for your specific use case.

  53. 

  54. In general, classes that will be needed very frequently should remain in the

  55. .module file.  Other classes should be logically grouped into separate include

  56. files so that classes and interfaces that are used together are loaded

  57. together as well.  That skips the autoloading process as well as the extra disk

  58. hit.

  59. 

  60. When in doubt, benchmarks are your friend.

  61. 

  62. 

  63. CREDITS

  64. 

  65. This module was developed by Larry "Crell" Garfield and

  66. backported from Drupal 7 (aka improved) by Dave "The Doctor" Reid.