Spec

Spec 1.0

Creating packages MODX Revolution using Composer. Specification version 1.0

Although this specification was written to codify the directory structures used by packages using Repoman, the specification guidelines here are intended to be agnostic of any particular installation utility.

Goals

This spec should define how PHP developers can author packages for the MODX Revolution CMS using Composer for installation and dependency management. The goals of the workflow are:

• The development and installation of MODX packages is the same as creating "normal" composer/packagist packages.
• MODX packages can be made available via Packagist or any similar public PHP package repository.
• Dependencies should be referenced and resolved in the standard composer way: by referencing them by name in the composer.json "require" node.
• The workflow should be compatible with the envisioned future versions of MODX when MODX itself is a composer-driven application.

---

File Locations

The purpose of a file is inferred in part from the location of the file. The

Assets

All files that must be web-accessible are referred to as "assets" and they must be stored in a dedicated folder. This folder shall be defined by "extra":{"assets_path":"assets/"}, default: assets/

Core Path

Files intended to be installed to the core/{$packagename}/ folder shall comprise the bulk of the package. This folder shall be defined by "extra":{"core_path":""}, and the default shall be the repository root.

Elements

Elements are defined as any chunk of PHP code or HTML that must be registered within the MODX CMS to provide formatting or functionality. Although an element may reference additional files (e.g. a CSS style sheet or a PHP class), the element itself must consist of a single file. Elements currently consist of Templates, Chunks, Snippets, Plugins, and Template Variables (i.e. custom fields). These should be contained in their own directory defined by "extra":{"elements_path":""}, and the default shall be elements/. The type of element shall be determined by the sub-directories inside of the elements/ directory, e.g. templates/, chunks/, snippets/, plugins/, and tvs/.

Controllers

Controllers are classes used for handling requests inside the MODX manager. Default: "extra":{"controllers_path":"controllers/"}

Model

The model directory holds sub-directories for Object-Relational-Mappings (ORMs) and one for "schema/" (containing xPDO XML schemas which describe the model classes and relations). A given ORM contains PHP class files used and/or generated by xPDO to describe the underlying database tables. Default: "extra": {"orm_path":"model/"}

---

composer.json

When developing a MODX package, the package's composer.json needs to identify the type: "type": "modx-package".

Extra

As referenced, the following parameters can be set in the "extra" node:

• assets_path : defines the folder containing assets, default "assets/"
• core_path : defines the folder containing main package files (installed to core/{$packagename}/). Default is empty (i.e. the repository root).
• controllers_path : defines the folder containing controller classes. Default "controllers/"
• orm_path : defines the folder containing ORM model sub-directories, default "model/"