Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Automatic Class Loading Proposal

From MoodleDocs

Note: This page is a work-in-progress. Feedback and suggested improvements are welcome. Please join the discussion on moodle.org or use the page comments.

Moodle 2.6

Automatic Class Loading
Project state Proposal
Tracker issue n/a
Discussion n/a
Assignee Petr Škoda (škoďák)


Automatic class loading is a feature that eliminates manual including of PHP files. It can be implemented only if you can derive the location of class from its name. Usually one class needs to be stored in one file.

This is a proposal for standardisation of class naming and class file storage in Moodle using existing Frankenstyle rules.

Pros

  • improved coding style
  • lower memory footprint
  • enforcing of standardised class names and location of source files
  • possibility to replace standard classes in local customisations via custom classloader without core modification

Cons

  • potentially lower performance because Moodle class names are ambiguous and plugin locations are dynamic, hopefully we could optimise that

Plugin class naming

The general plugin class name should be: plugintype_pluginname_typeofclass_someclass

Unfortunately the pluginname part might contain multiple underscores which may lead to various problems.

The algorithm for finding of the class file location from given class name is:

  1. we have a class aaa_bbb_ccc_ddd_eee_fff
  2. aaa is always the plugin type, it can not be word core or moodle, ex.: mod, tool, block
  3. bbb is a candidate for plugin name, if this plugin exists look for file bbbdir/classes/ccc/ddd/eee/fff.php
  4. if plugin or class does not exist bbb_ccc is another candidate for plugin name, look for bbb_cccdir/classes/ddd/eee/fff.php
  5. repeat until reaching the limit of underscores in plugin name (5?)

Core class naming

The general core class name should be: core_optionalsubsystem_typeofclass_someclass

The algorithm for finding of the class file location from given class name is:

  1. we have a class core_aaa_bbb_ccc
  2. look for file /lib/classes/aaa/bbb/ccc.php
  3. if aaa is a subsystem look for aaasubsystemdir/classes/bbb/ccc.php

We would have to decide what to do with current subsystem classes without the core_ prefix, the options are:

  • require "core_" prefix, ignore the rest
  • hardcode some core classes in loader
  • look for known core sybsystem names and search in lib/classes/ or susbsystemdir/classes/

Potential candidates

  • new events classes
  • admin settings in plugins
  • any new core feature implemented using OOP
  • internat implementation of add-ons
  • some existing core subsytems
  • some existing plugins that already use these rules (ex.: tinymce plugins)

Backwards compatibility

There should not be any significant problems because the classes subdirectory is searched only if class not already included - classloader is used only for missing classes. Please note this proposal does not change Frankenstyle class naming rules for plugins in any way.

We should probably require the use of automatic class loading only in new APIs and let add-on developers decide for themselves. It is also technically possible to migrate some existing classes from lib.php files to /classes/ while keeping 100% backwards compatibility.

Implementation steps

  1. Finalise rules for class names, class file names and locations.
  2. Implement basic loader using current (slow) plugin API - such as https://github.com/skodak/moodle/compare/master...classloader.
  3. Improve performance and stability by rewriting get_plugin_types(), get_plugin_list() and friends.
  4. Ideally this plugin info API should be self contained without any dependencies.

Frequently asked questions

Why not use existing class loading standard?
The proposal builds on top of PSR-0, but it must take into account our ambiguous plugin naming rules and dynamic plugin locations.
Is it compatible with 3rd party libraries?
Most probably yes, Frankenstyle was supposed to resolve this. This biggest current problem are short names without the "core_" prefix, this proposal would finally require all core things to start with "core_".
Is this compatible with other classloaders?
Yes. spl_autoload_register() allows multiple class loaders, Frankenstyle loader one should be the last one because it will be most expensive.
Is this compatible with code obfuscators?
No, but Moodle already breaks with them and we will never support it.
Why only one class per file?
Because it makes things easier for everybody.

See also