Basics

To get started using Repoman, it's helpful to have some overview on what it does and how it works. Here's a run through of what you need to know to understand how Repoman works -- click any heading for more information about a topic, and remember, the Tutorials are meant to introduce these core concepts to you, so learn by doing once you're ready.

Installation

Get started so you can get started: read the Installation instructions to get things going.

Folder-Structure

The first thing to be aware of in a Repoman project is that it expects your project's files and folders to be organized in a certain way. Customizations can be made in the composer.json, but the default folder structure represents the simplest arrangement.

The goal of the folder structure is to keep all of a project's assets together for easy version control and to avoid redundant folder names (the "Department of Redundancy Department" was a problem in old-school MODX development). The project root contains your composer.json, optionally an "assets/" folder where any CSS, Javascript, or images would be stored, an "elements/" folder for your MODX Snippets, Chunks, Templates, and Plugins.

Coding Conventions

A Repoman project must follow a few coding conventions so that your code will work both in production and development environments where the paths and URLs will differ. This all boils down to deferring to MODX System Settings that exist in a development environment and then fall back to a production value. The most important of these is the core path:

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

Be sure your Repoman projects use this core path when including or requiring files.

DocBlocks

The meat-and-potatoes of MODX packages are elements: Snippets, Plugins, Chunks, and Templates. Repoman streamlines the usage of these via "DocBlocks". These are inspired by the JavaDoc spec, and it lets you set an object's attributes in-line in your static file. This makes it easier to manage your elements and it provides an incentive for better documentation. Win-win!

Here's an example of a MODX snippet using a Repoman DocBlock:

<?php
/**
 * @name DemoPage
 * @description This generates a demo page for the Repoman docs
 */
return 'Demo page here...';

Make sure you save this in the correct location according to the folder structure: elements/snippets/DemoPage.php

Composer

Repoman was written to be 100% compatible with Composer: all of Repoman's custom configurations are defined within a project's composer.json file. Composer lets you easily include third-party packages and it generates autoload files so you can easily include your PHP class files. All of Repoman's configuration details are set within the composer.json's "extra" node.

A sample composer.json with Repoman attributes is shown below:

{
    "name": "craftsmancoding/repoman",
    "description": "Repoman makes your live as a MODX developer easier.",
    "type": "library",
    "keywords": ["modx","composer","repository","manager","autoload","git"],
    "homepage": "https://github.com/craftsmancoding/repoman",
    "extra": {
        "package_name": "Repoman",
        "namespace": "repoman",
        "version": "1.0.2",
        "release": "pl",
        "category":"Repoman",
        "core_path": "",
        "assets_path" : "assets/",
        "docs_path" : "docs/"
    }
}