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 : attributes

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

package_name : (string) Human readable name of the package.

namespace : (string, required) the MODx namespace for the package. Traditional MODx code will use a single lowercase word without slashes for the MODX Namespace. If omitted, Repoman will take the package name from Composer's package name, e.g. Repoman would use packagename if your Composer package was defined as vendorname/packagename.

version: (string) MODx packages require a version number to help identify when upgrades are required. The MODx version should be 3 digits, e.g. "1.0.2l". This is important so MODx when update scripts should be run. This is not the same as the version attribute in the main JSON block, and it is not required to be pegged to a Git tag. (Recommended changes in v2: defer to Git tag)

release: (string) indicates the type of version, e.g. "pl", "rc", "dev", or "beta". (Recommended changes in v2: defer to Git tag)

docs_path: (string) This directory contains your package documentation, e.g. your license.txt, changelog.txt, and readme.txt. Default: "docs/". (Recommended changes in v2: defer README and LICENSE files in repository root)

chunks_path: (string) directory relative to core_path containing Chunks. Default "elements/chunks/".

plugins_path: (string) directory relative to core_path containing Plugins. Default "elements/plugins/".

snippets_path: (string) directory relative to core_path containing Snippets. Default "elements/snippets/".

templates_path: (string) directory relative to core_path containing Templates. Default "elements/templates/".

tvs_path: (string) directory relative to core_path containing Template Variables (TVs). Default "elements/tvs/".

orm_path: (string) directory base for where xPDO stores its ORM classes, relevant for use with the addPackage() and addExtensionPackage() methods. Default "model/".

omit: (array) list files or directories relative to package root that should be ignored/omitted from packaging into core/components/{$packagename}, e.g. ["assets/","builds/"]. This is how you can ignore paths and prevent them from cluttering your transport package, e.g. to avoid distributing seed data or screenshots with your package. Default: ["assets/","screenshots/","tests/","composer.json","composer.lock"]. If a value is specified, it will override and replace the default, so if you want to add a file or directory to the default values, you must manually state the default values before appending a value to it.

require_docblocks: (boolean) if true, elements must define docblocks in order to be imported.

seeds_path: (array) sub-dir(s) relative to core_path containing seed data to be imported during build or install operations. Default: "model/seeds/"

target: (string) specific path directory where export operations should save data. This attribute is most often passed as a command-line argument. Default "model/seeds/"

build_attributes: (hash) a data structure defining how the various custom objects are to be installed.

"build_attributes":{
    "Currency": {
        "preserve_keys":true,
        "update_object":true,
        "unique_key":true
    }
}

Each node inside of "build_attributes" defines a key for the classname and a value which is a hash with the following values:

• preserve_keys : boolean
• update_object : boolean
• unique_key : mixed - string for single column, array for compound keys
• related_object : boolean
• related_object_attributes : array

abort_install_on_fail: (boolean) should package installation halt if vehicles fail? Default: true.