Revision as of 22:04, 2 April 2014

Introduction

X2Engine's source code is completely transparent and totally under your control. There's no need to compiled PHP, so altering your software is a simply a matter of hacking around in the files. Traditionally, this meant directly altering the source code within X2Engine's file structure. But this could be problematic to keep track of, given the vast number of files. On top of that, automatic updates to any of those files would wipe out all of your changes, so you would have to choose between customization and receiving updates.

X2Engine provides a means to alter classes and templates without modifying the original source files. You can create an alternate version of any PHP file, while preserving the original, which makes it much easier to keep track of your changes as well as preserving your alterations through updates. You may still need to rework your custom code when an update is incompatible, but it will be much easier.

Overriding Files

Practically any php file used in X2Engine can be overridden. X2Engine's customization framework resides in the /custom directory, which mirrors the structure of the source code. For example, /custom/protected/components corresponds to /protected/components. Any php file placed in /custom will be used instead of the original.

Extending Controllers

X2Engine is built on Yii, which uses MVC (model-view-controller) architecture. Overriding an entire file is practical when dealing with views or smaller classes (such as models), but controllers can present a greater challenge. It's only a matter of time before we update one of the 1500+ lines of code in a controller. This means you have to manually find and transfer your changes from the old version, which is time-consuming. To remedy this, we allow substitution of any controller in X2Engine with an extended class.

Whenever a controller is loaded, X2Engine checks for the same filename with "My" at the beginning. For example, if you want to override a single action to ContactsController, you can create a file called MyContactsController in /custom/protected/modules/contacts/controllers containing the following:

<?php
class MyContactsController extends ContactsController {
    function actionIndex() {
        echo 'Hello World!';
    }
}
?>

This file will automatically be used instead of ContactsController and should still work if ContactsController is changed in an update. You may still need to manually merge changes if an update alters the same part of the controller that you changed, but it will be much easier to find.

Custom App Configuration

The configuration for the Yii application can also be customized through the files "web.php", "console.php" and "test.php" in custom/protected/config. These files will be run in the default configuration files for X2Engine running as a web application, console application or unit testing environment (respectively).

An array which mirrors the modified parts of main.php (the default configuration file) should be returned within the custom config file. To customize the configuration of the application, i.e. to add parameters to Yii::app()->params, one only need add/remove/alter the values and keys within $config.

Automatically Updating Custom Code

For all non-controller components overriding core classes, a console command has been written to ease the process of merging upstream changes. This command, x2doc:MigrateCustomCommand, will perform this by automating the following procedural steps:

1. Copy all custom code into an up-to-date clone of the X2Engine Git repository.
2. Commit differences between the custom code and base code at the version where customization was performed into a temporary branch
3. Merge changes from the latter version into the temporary branch, leaving the user to sort out merge conflicts (if any)
4. Copy the updated custom files back into place

To run this command, you will need:

• A UNIX shell environment in which the rsync program is available
• An up-to-date clone of the X2Engine Git repository

Finally, the process to update is as follows:

1. In protected/, run:

   ./yiic migratecustom --origin=<version of X2Engine updating from> --target=<version of X2Engine updating to> --gitdir=<path to the Git repository>
   

2. If there were any merge conflicts, they should be displayed in the output. You should then resolve the conflicts, commit the changes, and follow the instructions printed by the command.

Note, the "migratecustom" command also accepts an optional --source argument pointing to the path of the custom source directory, if in a different directory than the installation of X2Engine in which the command is being run.

Known Issues

• Currently, only PHP files can be substituted. To change a CSS or Javascript file you would have to edit the original file.

• There is no guarantee a customized installation will still work after an update. You will still have to manually merge changes if you want (or need) to use an updated version of a customized file. Depending on the file, you may have to do this for most automatic updates (since some files are changed far more often than others). Luckilly, most of our changes are usually in controller files, which can be extended rather than just replaced, so the updates are less likely to be incompatible with your modifications.