Contenido autoloader (since V. 4.8.17)

Introduction

Contenido provides autoloading for source files of classes/interfaces which are delivered by a Contenido package.
The main goal of autoloading is to reduce the list of needed includes which is usually at the beginning of scripts. By implementing a autoloader, the PHP engine has the possibility to load the file while trying to use a class/interface.

How it works?

The Contenido autoloader will be initialized during the application startup process. The autoloading solution in Contenido uses the class map strategy. It uses a generated class map configuration file, which is available inside contenido/includes/ folder.

contenido/includes/config.autoloader.php

Each class type name is pointed to a file which contains the implementation of the required class type. By trying to use a class type, the autoloader will load the needed file if not done before.

Example:
Usually you have to ensure that a class file is already loaded by using include/require statements or by using Contenido's cInclude function:

cInclude('classes', 'class.article.php');
$oArt = new Article();

With a autoloader the manually loading is not required anymore.

$oArt = new Article();

Classes/Interfaces available by the autoloader

At the moment all available classes/interfaces inside following directories of a Contenido installation:

contenido/classes/

NOTE:
The autoloader doesn't handle loading of files which don't belong to the Contenido package. This means, additional added files (e. g. user defined classes/libraries) aren't automatically available for the autoloader. Read the section below, if you want to provide autoloading of additional class type files.

Extending the class map configuration

Don't edit the class map configuration manually, the next update could overwrite your changes. The autoloading is extendable by adding a additional user defined class map file inside the "contenido/includes/" folder, which could contain further class map settings or could overwrite settings of main class map file.

contenido/includes/config.autoloader.local.php

This file will not be overwritten during a update.

The content of the user defined file should have the following structure:

<?php
return array(
    '{classname_1}' => '{path_to_classfile_1}',
    '{classname_2}' => '{path_to_classfile_2}',
    '{classname_3}' => '{path_to_classfile_3}',
);

Where {classname_X} is the name of the class/interface and {path_to_classfile_X} is the path (from Contenido installation folder) to the file which contains the implementation of the class/interface.

Example:
Let's assume that Contenido is installed in folder /var/www/ which contains a additional library "myLib" (full path: /var/www/myLib/) with a class "myFoobarClass" in file "class.myfoobarclass.php" (full path: /var/www/myLib/class.myfoobarclass.php). Then the user defined class map file should contain a entry for this like:

<?php
return array(
    ...
    'myFoobarClass' => 'myLib/class.myfoobarclass.php',
    ...
);

Auto generation of user defined class map configuration

If you don't want to maintain the user defined class map configuration manually, then you may let a copy of the command line script (which is adapted to your requirements) contenido/tools/create_autoloader_cfg.php to do the job.

Do following steps to achieve this:

• Create a copy of create_autoloader_cfg.php and name it e. g. create_localautoloader_cfg.php
• Open create_localautoloader_cfg.php and adapt it to your requirements (see Initialization/Settings)
  • Set setting $context->destinationFile to $context->destinationFile = $context->contenidoInstallPath . '/contenido/includes/config.autoloader.local.php'; NOTE: Don't use another file name, it's predefined and has to be "config.autoloader.local.php"
  • Define paths which should be parsed recursively, e. g.

    $context->pathsToParse = array(
        $context->contenidoInstallPath . '/my_path/',
        $context->contenidoInstallPath . '/my_other_path/',
    );
    

  • Change class type finder options (if required), e. g.

    // class type finder options
    $context->options = array(
        // list of directories which are to exclude from parsing (case insensitive)
        'excludeDirs'       => array('.svn'),
        // list of files which are to exclude from parsing (case insensitive), also possible regex patterns like /^~*.\.php$/
        'excludeFiles'      => array(),
        // list of file extensions to parse (case insensitive)
        'extensionsToParse' => '.php',
        'enableDebug'       => false,
    );
    

• Run the class map creator by typing following to the command line: $ php create_localautoloader_cfg.php NOTE: PHP needs write permissions for folder "contenido/includes/"
• Check the generated/upated file "config.autoloader.local.php" inside "contenido/includes/" folder

Adding class map configuration manually

As a addition to the user defined class map configuration, the Contenido autoloader provides the feature to add class map configurations manually by using following methods:

• cAutoload::addClassmapConfig(array $config)
  Adding additional autoloader classmap configuration.
  

  // Structure is: "Classname" => "Path to classfile from Contenido installation folder"
  $config = array(
      'myPluginsClass' => 'contenido/plugins/myplugin/classes/class.myPluginClass.php',
      'myPluginsOtherClass' => 'contenido/plugins/myplugin/classes/class.myPluginsOtherClass.php',
  );
  cAutoload::addClassmapConfig(array $config);
  

• cAutoload::addClassmapConfigFile($configFile)
  Adding additional autoloader class map configuration file.
  

  $configFile = '/path/to/additional/classmap/config.php';
  cAutoload::addClassmapConfigFile($configFile);
  

  The provided file must return a class map configuration array as follows:

  <?php
  // Structure is: "Classname" => "Path to classfile from Contenido installation folder"
  return array(
      'myPluginsClass' => 'contenido/plugins/myplugin/classes/class.myPluginClass.php',
      'myPluginsOtherClass' => 'contenido/plugins/myplugin/classes/class.myPluginsOtherClass.php',
      'myCmsClass' => 'cms/includes/class.myCmsClass.php',
  );
  

NOTE:
Since the autoloader is implemented for Contenido, it doesn't support to load classfiles being located outside of the Contenido installation folder.

Extending Contenido core with autoload mechanism

By using the Contenido autoloader it's possible to extend/overwrite Contenido core classes (except classes inside conlib directory) without changing the core files.

Let's assume, you want to use your own Template class in Modules, but everything should still be downwards compatible.

Do following steps to achieve this:

• Create a user defined folder (if required) which should contain your own Template class file
• Create a class file (e. g. class.mytemplate.php), which should contain the implementation of new class Template
• Implement your own Template class. Ensure that the interface of your Template class is identical to the Contenido Template class. This means, each public accessible property, method should have the same interface as in the original Contenido Template class (Same names, properties, parameters, etc.).
• Modify the functions to your requirements
• Add the class map configuration of your new Template class to the user defined file config.autoloader.local.php or regenerate the user defined class map file (see extending class map, auto generation of class map and adding manual class map configuration)

NOTE:
There is one main disadvantage by using this way of extending the Contenido core. Each time after an update of your Contenido installation it's strongly recommend to check your user defined implementations against changes in original Contenido core files and, if applicable, to adapt your files to those changes.