[RFC|Merged] Autoloading & Class Naming Convention

[naderman]

Based on some initial discussion (viewtopic.php?p=208560#p208560) I would like to propose a convention for naming classes and discuss the patch I created for autoloading these classes.

The ticket is located at http://tracker.phpbb.com/browse/PHPBB3-9682
The proposed patch can be found at http://github.com/naderman/phpbb3/compa ... to-loading

Since we are going to use object orientation a lot more, we naturally have more class definitions, which will not always need to be loaded. Autoloading provides a simple yet sufficiently efficient mechanism to avoid many conditional file inclusions. They also avoid the (unecessary) call to a class loading function. To use autoloading a convention for naming class needs to be established.

I propose that phpBB class name lookups follow these rules:

• All classes are prefixed with phpbb_
• All classes reside in includes/ or a subdirectory thereof
• Directories must not contain underscores
• The class name is separated into parts by underscores, the parts are checked from first to last, until one is found which is not a directory, all remaining parts make up the file name. If no parts are left, the last directory name is used.

Examples:

Code: Select all

  directory structure:
    includes/
      class_name.php
      dir/
        class_name.php
        dir.php
        subdir/
          class_name.php

lookups:

Code: Select all

    phpbb_class_name            -> includes/class_name.php
    phpbb_dir_class_name        -> includes/dir/class_name.php
    phpbb_dir                   -> includes/dir/dir.php
    phpbb_dir_subdir_class_name -> includes/dir/subdir/class_name.php

Optionally the class loader can be supplied with a cache instance, either in the constructor or via set_cache() at a later time. This allows for the lookups to be cached, so the directories do not have to be traveresed on every request. This makes it necessary for the cache and its dependency to continue to be loaded the old way - without autoloading.

Code will not be changed to use autoloading, but it will rather only be used for new classes where applicable.

[igorw]

More aggressive than what I had in mind, but I guess more convenient. Works for me, I'd be glad to have real autoloading. For conflicts, what is favored? dir/class_name or dir_class_name?

Also, are nested subdirs of includes/ supported? Such as includes/tasks/core/some_thing.php.

[naderman]

More aggressive than what I had in mind, but I guess more convenient. Works for me, I'd be glad to have real autoloading. For conflicts, what is favored? dir/class_name or dir_class_name?

• The class name is separated into parts by underscores, the parts are checked from first to last, until one is found which is not a directory, all remaining parts make up the file name. If no parts are left, the last directory name is used.

So dir/class_name.php will be the result if dir/ exists, dir_class_name.php is not even checked. In my eyes this would complicate matters more than it would help.

Also, are nested subdirs of includes/ supported? Such as includes/tasks/core/some_thing.php.

Yes arbitrary depth nesting is supported. As you can see from my includes/dir/subdir/class_name.php example

[igorw]

One of the things that is not mentioned in your post is whether singulars or plurals should be used. I proposed using singular, eg. includes/cron/task/something.php. Otherwise you get awkward names like phpbb_cron_tasks_something, which does not make sense.

[naderman]

The class naming convention doesn't really say anything about what the names should be other than what their formatting has to be, so I don't think that really fits in there. Or if you really want that in there (I would think it's common sense) can you phrase it in a way I could include? Thanks

[naderman]

Added that to the coding guidelines myself.

[igorw]

True, the whole singular/plural thing is a more general issue and a great inconsistency in phpBB already (files/images/includes/styles vs. language). So it might be a good idea to have a clear general convention for anything new at some point.

But for now it won't hurt to have it in the guidelines.

[naderman]

Alright, this implementation has now been merged into develop and can be used for all new code.

[igorw]

Awesome, thanks!

[igorw]

We still need some documentation for this. Either in coding-guidelines, a new document and/or the wiki.