Skip to content

XELOS Coding Conventions

Abstract

XELOS strives to comply and follow the PHP Standards Recommendations (PSR) if coding style and decisions are to be made. For historical reasons not all code parts are following these recommendations yet, but the goal is to convert all active code parts step by step to follow the PSR.

Info

This document is to be followed for new developments. Pull Requests not meeting these standards are to be declined.

Common Code Conventions

Based on PSR-1 XELOS follows these conventions:

  • Files MUST use only <?php tags.
  • Files MUST use only UTF-8 without BOM for PHP code.
  • Files SHOULD either declare symbols (classes, functions, constants, etc.) or cause side-effects (e.g. generate output, change .ini settings, etc.) but SHOULD NOT do both.
  • Namespaces and classes MUST follow an “autoloading” PSR: [PSR-4].
  • Class names MUST be declared in StudlyCaps.
  • Class constants MUST be declared in all upper case with underscore separators.
  • Method names MUST be declared in camelCase.

File and Class Naming

Folder "class" in each module is the root folder of all PHP classes. All folders and class files are named in StudlyCaps. The class file name must match the class name.

Example:

Class: MyAwesomeClass
File:  MyAwesomeClass.php

Abstract classes

An abstract class does not have any prefix or suffix. The name of the class should be meaningful to show it's type / functionality.

Interfaces

Interfaces must be named with the suffix "Interface". They should be bundled into a separate "Interfaces" folder if there is more then one interface.

E.g.

Class: XELOS\Modules\MyModule\Hook\Interfaces\MyHookInterface
Location: <XELOSROOT>/modules/my_module/class/Hook/Interfaces/MyHookInterface

General Class Suffix

Some classes have to use a suffix to make their functionality obvious. The following classes should have a class name suffix:

Class / Type Suffix Example Class name
Controllers Controller AwesomeController
Pages Page AwesomePage
Actions Action AwesomeAction
Helpers Helper AwesomeHelper
Interfaces Interface AwesomeInterface
Traits Trait AwesomeTrait

Namespace

XELOS uses the PSR-4 autoloading standard for namespaces, which means that the namespace of each class must match the folder structure the class is located in. The class folder of each module is mapped as namespace root of the contained classes. Following namespace root mappings are used:

Namespace root Mapping path
XELOS\Framework <XELOSROOT>/class
XELOS\Modules <XELOSROOT>/modules
XELOS\Modules\Example <XELOSROOT>/modules/example/class
XELOS\Vendor\<vendor>\Modules <XELOSROOT>/vendor/<vendor>/modules
XELOS\Vendor\<vendor>\Modules\Example <XELOSROOT>/vendor/<vendor>/modules/example/class

Example for a module controller of the module "Awesome":

File: <XELOSROOT>/modules/awesome/class/AwesomeController.php
FQN of the class: XELOS\Modules\Awesome\AwesomeController

Hooks

Some modules offer one or more hook API-interfaces. Modules can use these to implement their own hook, which may be consumed by the compatible module if both modules are installed within XELOS. Hooks have a special location and naming convention which relate to the hook definition in the module configuration. The structure of a defined hook in the configuration is a combination of module name and hook type separated by a dot.

For example the module selector will consume hooks from type browser, so the name of this hook is:

Module: Selector
Hook:   selector.browser

The module, that wants to provide a "selector.browser" has to create a new hook class. The folder in which the hook class is placed must have the following convention:

<XELOSROOT>/modules/<my_module_name>/class/Hook/<hook_module_name>/

The hook class also has a naming convention which consists of the provided hook name and the hook type. In the case above the class should be specified as follows:

Location (Path):  <XELOSROOT>/modules/my_module/class/Hook/Selector/MyBrowser.php

Class (FQN):      XELOS\Modules\MyModule\Hook\Selector\MyBrowser

Module Controller

The module controller is located in the class folder of each module. The class name of the controller consists of the module name and the suffix "Controller".

E.g. the module controller of the module Forum

Path:   <XELOSROOT>/modules/forum/class/ForumController.php
Class:  XELOS\Modules\Forum\ForumController

Install Event

Since XELOS 8 the install event class is located in the class folder. The class name of each install event is the same.

E.g. the install event for module forum

Path:   <XELOSROOT>/modules/forum/class/InstallEvents.php
Class:  XELOS\Modules\Forum\InstallEvents

The InstallEvents class of a module should extends the XELOS\Framework\Module\InstallEvents class

Crons and Daemons

The cron and daemon classes always use the same name in each module.

E.g. forum cron:

Path:   <XELOSROOT>/modules/forum/class/SystemCron.php
Class:  XELOS\Modules\Forum\SystemCron

E.g. forum daemon

Path:   <XELOSROOT>/modules/forum/class/SystemDaemon.php
Class:  XELOS\Modules\Forum\SystemDaemon

Exceptions

Exceptions must be named with the suffix "Exception". They should be bundled into a separate "Exceptions" folder.

E.g.

Class: XELOS\Modules\MyModule\Exceptions\MyModuleException
Location: <XELOSROOT>/modules/my_module/class/Exceptions/MyModuleException

PHP Documentation

All classes, properties, methods, functions and constants should be have a PHPDoc comment, which should at least contains a short description and if exists, params, information, return and throw information. You should use only official PHPDoc tags .

Example class with PHPDoc:

<?php

namespace XELOS\Modules\MyModule;

/**
 * Summary description of this class
 *
 * Long Description of this class may contain markdown:
 *
 * **Example**
 * ```
 * $MyModuleController = Factory::get('MMC');
 * $MyModuleController->doSomeThing('example');
 * ```
 *
 * @method MagicReturn MagicMethodYouShouldKnow($param = 'example')
 * @see https://my.xelos.net/dev-doc/ for more documentation
 * @mixin MyModuleControllerMagicDocs
 */
class MyModuleController {

    /**
     * This is a short description of this property.
     * 
     * @var string
     * @see MyOtherModuleController::$property For possible values
     */
    protected $property;

    /**
     * This is a short description of the functionality.
     * 
     * @param int $number
     *
     * @return int
     *            
     * @throws \InvalidArgumentException
     * @example ../example.php 5 3 See Usage Example at line 5-8
     * @source 2 3 Exception includes your argument
     */
    public function doSomeThing($number){
        if( ! is_numeric($number) ){
            throw new \InvalidArgumentException($number);
        }
        return $number;
    }

}

This will result in something like:

PHP Doc