Jump to content

Community

Developer Documentation

Autoloading classes

Classes in IPS Community Suite 4 are "autoloaded". This means you never have to include or require an IPS4 source file.

For reference, the autoload method is \IPS\IPS::autoloader() which is located in the init.php file of the root directory.

 

Locating Classes

Classes must be located in the correct location and be named properly so the autoloader can find them. There are generally three locations:

  • Framework classes
    Classname structure: \IPS\Namespace\Class
    Location on disk: system/Namespace/Class.php
     
  • Application classes
    Classname structure: \IPS\app\Namespace\Class (note that the application key is lowercase, but the parts after are PascalCase)
    Location on disk: applications/app/sources/Namespace/Class.php
     
  • Application extensions and modules
    Classname structure: \IPS\app\modules\front\module\controller (note all the parts are lowercase)
    Location on disk: applications/app/modules/front/module/controller.php

For Framework classes and Application classes, the final file must always be in within a folder (not loose in the system directory). If only one-level deep, the system will look for a file in a directory of the same name. For example \IPS\Member is located in system/Member/Member.php while \IPS\Member\Group is located in system/Member/Group.php

 

Monkey Patching

When declared, classes always start with an underscore. For example, throughout the IPS Community Suite, you call \IPS\Member, however, if you look in the source file you will see it declared like this:

namespace IPS;
class _Member { ...

This is a technicality of a feature called monkey patching which allows third party developers to overload any class without any consideration throughout the code and in a way where hooks do not conflict with one another.

In this example, the system will execute, right after autoloading the Member.php file, code like this:

namespace IPS;
class Member extends \IPS\_Member { }

If a third party developer wants to overload \IPS\Member, the system will inject this in between, so you end up with a structure like so:

  • \IPS\Member extends hook1
  • hook1 extends \IPS\_Member 

Or if two hooks wanted to overload \IPS\Member:

  • \IPS\Member extends hook1
  • hook1 extends hook2
  • hook2 extends \IPS\_Member

This means that the framework, and any third party code only ever has to call \IPS\Member, and the system will not only automatically autoload the source, but create a chain of any hooks wanting to overload the class.

If the mechanics of this are confusing (it is an unusual practice) - it is not essential to thoroughly understand. You only need to know that classes must be prefixed with an underscore when declared, but that underscore is never used when actually calling the class.

It also means that rather than calling "self::" within the class, you should call "static::" so you are calling the overloaded class, not the original.

 

Third Party Libraries

If you want to use a third-party PHP library they will of course need to be included manually and cannot be monkey patched.

If the library follows the PSR-0 standard for naming, you can add it to \IPS\IPS::$PSR0Namespaces like so, and the autoloader will then autoload it:

\IPS\IPS::$PSR0Namespaces['Libary'] = \IPS\ROOT_PATH . '/applications/app/system/3rd_party/Library';

Otherwise, you will need to include the source files manually.


  Report Document


×