New extension guidelines

Those are the new guidelines to make an extension, it is absolutely not mandatory for it to work, but is highly recommended as it will help other people to understand how the extension works.

Code

The code of a module should never be prefixed by combodo- or itop-, which are Combodo reserved prefix

Folders

This structure has been designed collectively by the Combodo R&D team on may 2019.

Files structure

<extension-root>
   asset
      js
      css
      img
      lib
   bin
   dictionaries // iTop 3.0+
   doc
   [legacy]
   src
      Controller
      Helper
      Service
      <SomeService>
      Hook
      Model
   tests
      php-unit-tests
         integration-tests
         unitary-tests
         phpunit.xml
      ci_description.ini
   templates
   vendor
   [compatibilitybridge.php]
   composer.json
   index.php
   Jenkinsfile
   module.<module>.php
   datamodel.<extension>.xml
   [extension.xml]
   [license.<module>.xml]

Folder/File	Mandatory	Description
asset	No	Public resources of the extension (images, stylesheets, JS scripts, libraries, …).
bin	No	Scripts / executables to be run in CLI.
dictionaries	No	Dictionary files (eg. en.dict.<extension>.php) for the module. Can be used only since iTop 3.0.0, before this version files must be in the root folder.
doc	No	Files for the documentations. Can be either images for the README.md, markdowns files, …
legacy	No	Only when the extension should be compatible with a version of iTop introducing a breaking change.
src	No	The PHP files. The sub-folders should be camel-cased and following the namespace of the files so the autoloader can work. The structure of those sub-folders is not fixed and be changed if it makes more sense for the extension.
src/Controller	No	Controllers classes when using MVC pattern.
src/Hook	No	PHP classes implementing/extenting iTop APIs.
src/Model	No	PHP classes of entities (Either from the DataModel or not).
tests	No	Structural folder for all kind of tests
tests/php-unit-tests	No	Structural folder for all PHPUnit tests
tests/php-unit-tests/integration-tests	No	Integration test files
tests/php-unit-tests/unitary-tests	No	Unitary test files, should match the structure of your /src folder
tests/php-unit-tests/phpunit.xml	No	Tests suites to run
tests/ci_description.ini	No	File describing the parameters to use (overloads of the default ones) when run by the CI
templates	No	Templates used by the extension (HTML, JS, …).
vendor	No	Do not put anything in this, it will be automatically built by composer (Third-party libs and autolaoders).
compatibilitybridge.php	No	Only when the extension should be compatible with a version of iTop introducing a breaking change. Will be loaded in the `module.<extension>.php` and will take care of loading the correct files regarding the iTop version.
composer.json	No	- Put extension classes namespaces and/or classmaps - Put third-party libs to be included
index.php	No	The endpoint used by the MVC.
Jenkinsfile	No	File to enable the extension in the CI
module.<extension>.php	Yes	Extension definition file, contains its code, version, dependencies, installer, …
datamodel.<extension>.xml	No	DataModel XML alteration of the extension (see note below about corresponding model.php file).
extension.xml	No	Meta data about the extension (Author, compatiblity, description, URL, … Used by the Designer, the Hub and the Setup. Will be generated during the build by the Factory.
exclude.txt	No	Contains a list of files/folders to exclude from the extension build. Typically the `doc/` folder and “README.md” file.
README.md	No	For non official extensions, a description of what it does, how to use it and it compatibility with iTop. Will be removed when extension becomes an official one and its documentation goes to the wiki.
license.<module>.xml	No

What about the famous main.<extension>.php file and its many classes? 😬

You should not have this file anymore, all classes it contains should now be in separated/dedicated PHP class file under the src/ folder

If your module contains a datamodel.<module>.xml, then you must :

add an empty model.<module>.php !
reference this file in your module.<module>.php 'datamodel' key

Files

PHP

A PHP file should contain only ONE class.
A PHP file should be name using PSR-4 convention, meaning that for a “MyCMDBObject” class, the file should be “MyCMDBObject.php” instead of “mycmdbobject.class.inc.php”.

Autoloader

Instead of loading PHP files in every iTop pages by including them in the 'datamodels' section of the module.<extension>.php file, we can use an autoloader to load them only when necessary. 🤩

This autoloader will come in addition of iTop base autoloader.

Limitations: PHP classes using the iTop APIs must be explicitly loaded in the 'datamodels' section otherwise iTop won't be able to find them.

Once you edited the composer.json file to put the namespaces (and/or classmaps), generate the autoloader and add it in the 'datamodels' section.

Commands to dump the autoloader

cd <PATH_OF_THE_EXTENSION>
composer.phar dump-autoload -a

Include autoloader in module.extension.php

...
    'datamodels' => array(
        // Module's autoloader
        'vendor/autoload.php',
        // Explicitly load APIs classes if any
        'src/Hook/MyConsoleUIExtension.php',
    ),
...

Sidebar

New extension guidelines

Code

Folders

Files

PHP

Autoloader

Table of Contents