Spec

Spec 1.0

Creating packages MODX Revolution using Composer for type: modx-package. 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. Its goal is to define a specification for what a modx-package is and how it is structured.

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 within the repository. The default location should suffice for most use cases, but customizations are possible via the options in the "extra" node.

Assets (assets_path)

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 (core_path)

Files intended to be installed to the core/{$packagename}/ folder shall comprise the bulk of the package -- unless otherwise indicated, any file or folder in the repository root will be installed to core/{$packagename}/. This folder shall be defined by "extra":{"core_path":""}, and the default is be the repository root. The assets/ directory is omitted from this by default because it gets installed into assets/components/{$packagename}/

Elements (elements_path)

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 consists 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. elements/templates/, elements/chunks/, elements/snippets/, elements/plugins/, and elements/tvs/.

Controllers (controllers_path)

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

Model (orm_path)

The model/ directory holds sub-directories for xPDO's Object-Relational-Mappings (ORMs) and one for "schema/" (containing xPDO XML schemas which describe the model classes and relations). This directory 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". When Repoman is installed as a composer plugin, it will handle installation of the files into MODX during composer operations.

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/"