Streamline Developing Extras for Revo 2 & 3 with GPM

Learn how to configure Git Package Management (GPM V1) to make maintaining Extras easier for the two supported branches of MODX Revolution

By Thomas Jakobi
September 1, 2022
Streamline Developing Extras for Revo 2 & 3 with GPM

This is a post from long-time and prolific MODX Extras developer, Thomas Jakobi. Thomas recently updated and released most of his Extras for Revolution 3. In this post he shares how he created a streamlined environment so that he could develop for both MODX Revolution 2 and 3 more easily and effectively.


In January 2022, I tested most of my Extras (along with those I manage) in Revolution 3. To get things working, I partially modernized and adapted the code. To test the Extras in Revolution 2 and Revolution 3, I used two local MODX installations and a configuration with Git Package Management (GPM). With this configuration, an Extra can be tested simultaneously in Revolution 2 and Revolution 3 with a single code base.

Since this setup is surely also interesting for other developers, I decided to write it up to share.

Two Subfolder MODX Installs

Two different MODX subfolder installations are needed. I created two subfolders _modx2x and _modx3x in a parent folder Develop and set up the corresponding MODX version with their own database and subdomain (i.e. extras2x.localand extras3x.local) in both subfolders.

Setting Up Sessions

Both MODX installations need different sessions, otherwise you can't be logged into both versions at the same time. Therefore I filled the MODX system setting session_name with a version specific value: EXTRAS2x and EXTRAS3x. The MODX system setting session_cookie_path must be set to / in each case. After logging back into the respective MODX installation, everything is ready to proceed with the installation of GPM.

Set Up for Git Package Management

Since the installation package of an Extra should be installable in both MODX versions, I use GPM 1 in both installations. For this I use the directory structure Separate MODX, separate packages. My folder structure in this case is:

Develop 
  - _modx2x
  - _modx3x
  - Extras
    - gitpackagemanagement
    - package1
    - package2

GPM 1 can be installed from a cloned repository in the Extras directory in Revolution 2 via CLI quite easily. The paths queried during installation must be set according to the Separate MODX, separate packages configuration. In the Revolution 3 installation you have to transfer the GPM database table <prefix>_git_packages, the namespace entry, the system settings in the gitpackagemanagement namespace and the menu entry from the Revolution 2 installation.

Adjusting the Config File

The config.core.php file added by GPM in the root of a package folder includes the core of the MODX installation in which it was created. So there must be a switching config.core.php that recognizes the currently running MODX version based on the subdomain and includes the MODX core config file accordingly. I have added this file in the folder Develop with the following code:

<?php
$version = '_modx2x';
$ref = array_key_exists('HTTP_REFERER', $_SERVER) ? $_SERVER['HTTP_REFERER'] : '';
$ref = ($ref == '' && array_key_exists('HTTP_HOST', $_SERVER)) ? $_SERVER['HTTP_HOST'] : $ref;
if (!empty($ref)) {
    if (strpos($ref, 'extras2x.') !== false) {
        $version = '_modx2x';
    } elseif (strpos($ref, 'extras3x.') !== false) {
        $version = '_modx3x';
    }
}

require __DIR__ . '/' . $version . '/config.core.php';

Using this code, a package connector will include the MODX core configuration from which the connector is executed.

The config.core.php in the root of a package folder has to include this switching config.core.php and contains the following code:

<?php
require(dirname(__DIR__, 2) . '/config.core.php');

To automatically generate the contents of this file, you can modify the createConfigFiles method in the create.class.php, which has to write the code above during creating the GPM package.

With this configuration you can test your packages with Revolution 2 and Revolution 3 locally. You just have to add the package folder in GPM in both MODX installations and start your testing.


Thomas Jakobi is a German web-developer/designer. He is the developer of a number of open source Extras for MODX Revolution. Thomas the owner of Treehill Studio, a MODX agency developing premium Extras.