Namespaces and Autoloader

[Aaron Wells]

Discussed at the 52nd developer meeting: https://wiki.mahara.org/wiki/Developer_Area/Developer_Meetings/52

[Aaron Wells (u-aaronw)]

The general plan is this:

1. Put a namespace onto every library file. As per PSR-2 (and the way we already code Mahara), a library file is one that contains only class and function declarations, and is not meant to be directly accessed by URL. In Mahara, these are the ones that don't start with "define('INTERNAL', 1);" (and that *should* start with "if (!defined('INTERNAL')) die();")

2. Put all these namespaces under a root "\Mahara" namespace.

3. Use hierarchical namespaces for plugintypes, i.e. \Mahara\Artefact\File

4. Employ an autoloader that can read these namespaces and understand where the corresponding physical file is located. Then remove all require's and include's.

5. Because only classes with work with an autoloader, and not standalone functions, move all standalone functions into static methods of utility classes. i.e. smarty() in htdocs/lib/web.php becomes \Mahara\Web::smarty()

6. Once all that is set up, a simple find/replace should fix all occurrences in the core code.

7. For backwards compatibility with 3rd-party code, provide a "deprecated.php" file that maps the old standalone function names to the new static methods, i.e. "function smarty($arg1, $arg2) { return \Mahara\Web::smarty($arg1, $arg2); }".

8. Likewise, the deprecated.php can provide "wrapper classes" that provide a non-namespaced classes & interfaces that are children of the new namespaced classes, so that 3rd-party plugins' object declarations will still work. i.e. "class PluginArtefact extends \Mahara\Plugin\Artefact {};"

Possible trouble spots:

1. Dwoo templates. In a Dwoo tag you can access any standalone function that is in scope, by its name, e.g. "{$printthis|hsc}" is equivalent to "echo hsc($printthis)". But does it work with static function methods?

2. Pieforms. It uses franken-named functions instead of classes. We'd need to refactor it into the modern era in order to use it with namespaces, probably.

3. Code that calls functions indirectly with strings and call_user_func(). The find/replace probably won't work with these, so we may need to take extra care with them.

4. Backporting. If the names of *every* function everywhere have been changed, then it'll make backporting code a pain. Perhaps we could mitigate this with an automatic translation script based on deprecated.php

Additional notes:

At the developer meeting it was mentioned that Moodle went through a similar transition a few releases back, so we may want to take a look at what they've done to draw inspiration.

[Aaron Wells (u-aaronw)]

Another big area where we call code directly from strings, is the cron system. It uses a "callfunction" string stored in the database, to call a function with that name.

[Aaron Wells (u-aaronw)]

Oh, also Pieform callback functions, are currently required to be standalone functions in the global namespace. That is, if you name a Pieform "newcomment", then Pieform will look for and call a validation function named newcomment_validate() and another called newcomment_submit(). (These names can also be manually over-ridden with config values in the form's definition.)

[Kristina Hoeppner (kris-hoeppner)]

SimpleSAML and Dwoo are now namespaced