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're using composer, please place the vendor directory into the sources directory!
If you want to use a third-party PHP library without using composer and it's autoloader, you 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\Application::getRootPath() . '/applications/app/sources/vendor/Library';
Otherwise, you will need to include the source files manually.
Report Document