Conventions

Repoman makes MODX Revo development easier because it introduces some simple conventions. These conventions were inspired by existing development practices already used by the MODX community. Many of them are configurable (see composer.json).

Constants: core_path, assets_url, and assets_path

Throughout your code, you should never hard-code the MODX_CORE_PATH or the MODX_ASSETS_URL. Instead, your code should first look for a local development version of your package, and if that’s not available, then fall back to the standard location used by installed packages. This allows your code to be flexible and run both in dev environments and in production environments.

core_path

While developing, your core path represents a specific directory in your repository, usually the repository root. You can configure the "core_path" attribute in your composer.json to point to a sub-directory if you desire but this is not recommended. When installed via package, the core_path should represent your package’s directory inside of "core/components/your-package/".

Use the following pattern in your code:

$core_path = $modx->getOption('mypkg.core_path','',MODX_CORE_PATH.'components/mypkg/');
require_once $core_path.'some/file.php';

Warning

Here you have to hard-code your package’s namespace because it will get installed intoa sub-directory inside of the "core/components/" directory.

assets_path

The assets_path is not frequently used since most PHP files live in the core_path, but it is a setting that is controlled by Repoman.

While developing, your assets path represents a specific directory in your repository, usually "assets/". You can configure the "assets_path" attribute in your composer.json to point to a sub-directory. When installed via package, the assets_path will represent your package’s directory inside of "assets/components/your-package/".

Use the following pattern in your code:

$assets_path = $modx->getOption('mypkg.assets_path','',MODX_ASSETS_PATH.'components/mypkg/');
require_once $core_path.'some/file.php';

Warning

Here you have to hard-code your package’s namespace because it is used as a sub-directory inside of the "assets/components/" directory.

Although the "assets/" directory is inside your core_path while developing, the build process moves it to its own separate directory, so do not rely on relative paths when making references to files from or to the assets directory.

assets_url

$assets_url = $modx->getOption('mypkg.assets_url','',MODX_ASSETS_URL.'components/mypkg/');
print '<link rel="stylesheet" href="'.$assets_url.'stylesheet.css">';
// or in a Chunk:
<link rel="stylesheet" href="[[++mypkg.assets_url]]stylesheet.css">

The placeholders will be stripped and replaced with [[++assets_url]] when the package is built to ensure proper functionality when the package is deployed.

Be especially vigilant about this if you are using a lot of HTML templates and chunks that reference asset URLs. You may need to pass this value as a placeholder via getChunk() or parseChunk()

See composer.json for more information.