[RFC|Merged] Autoloading & Class Naming Convention

These requests for comments/change have lead to an implemented feature that has been successfully merged into the 3.1/Ascraeus branch. Everything listed in this forum will be available in phpBB 3.1.
User avatar
naderman
Product Manager
Product Manager
Posts: 1727
Joined: Sun Jan 11, 2004 2:11 am
Location: Karlsruhe, Germany
Contact:

[RFC|Merged] Autoloading & Class Naming Convention

Post by naderman » Fri Jun 25, 2010 6:37 pm

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.

User avatar
igorw
Registered User
Posts: 500
Joined: Thu Jan 04, 2007 11:47 pm

Re: [RFC] Autoloading & Class Naming Convention

Post by igorw » Fri Jun 25, 2010 11:39 pm

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.

User avatar
naderman
Product Manager
Product Manager
Posts: 1727
Joined: Sun Jan 11, 2004 2:11 am
Location: Karlsruhe, Germany
Contact:

Re: [RFC] Autoloading & Class Naming Convention

Post by naderman » Sat Jun 26, 2010 12:08 am

eviL3 wrote: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?
naderman wrote:
  • 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.
eviL3 wrote: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 ;-)

User avatar
igorw
Registered User
Posts: 500
Joined: Thu Jan 04, 2007 11:47 pm

Re: [RFC] Autoloading & Class Naming Convention

Post by igorw » Fri Jul 02, 2010 6:55 pm

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.

User avatar
naderman
Product Manager
Product Manager
Posts: 1727
Joined: Sun Jan 11, 2004 2:11 am
Location: Karlsruhe, Germany
Contact:

Re: [RFC] Autoloading & Class Naming Convention

Post by naderman » Sat Jul 03, 2010 12:01 pm

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

User avatar
naderman
Product Manager
Product Manager
Posts: 1727
Joined: Sun Jan 11, 2004 2:11 am
Location: Karlsruhe, Germany
Contact:

Re: [RFC] Autoloading & Class Naming Convention

Post by naderman » Sat Jul 03, 2010 1:44 pm

Added that to the coding guidelines myself.

User avatar
igorw
Registered User
Posts: 500
Joined: Thu Jan 04, 2007 11:47 pm

Re: [RFC] Autoloading & Class Naming Convention

Post by igorw » Sat Jul 03, 2010 1:58 pm

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.

User avatar
naderman
Product Manager
Product Manager
Posts: 1727
Joined: Sun Jan 11, 2004 2:11 am
Location: Karlsruhe, Germany
Contact:

Re: [RFC] Autoloading & Class Naming Convention

Post by naderman » Mon Jul 05, 2010 1:49 pm

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

User avatar
igorw
Registered User
Posts: 500
Joined: Thu Jan 04, 2007 11:47 pm

Re: [RFC] Autoloading & Class Naming Convention

Post by igorw » Mon Jul 05, 2010 3:49 pm

Awesome, thanks!

User avatar
igorw
Registered User
Posts: 500
Joined: Thu Jan 04, 2007 11:47 pm

Re: [RFC|Accepted] Autoloading & Class Naming Convention

Post by igorw » Sat Sep 04, 2010 8:43 am

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

Post Reply