bangpound / edition-php-twig-development

Pattern Lab PHP bundled with Twig. For use in developing new features.

Pattern Lab Development Edition for Twig

The Development Edition for Twig allows the core team to work on and commit changes to the latest editions of select Twig-related components while running each one within the overall Pattern Lab environment. This edition is NOT stable.

Pattern Lab Standard Edition for Twig is the stable version. Please start there for all your Twig needs.

Packaged Components

The Development Edition for Twig installs the dev branch from each of the following components:

• pattern-lab/core: GitHub, Packagist
• pattern-lab/patternengine-twig: documentation, GitHub, Packagist
• pattern-lab/starterkit-twig-demo: GitHub, Packagist
• pattern-lab/styleguidekit-assets-default: GitHub, Packagist
• pattern-lab/styleguidekit-twig-default: GitHub, Packagist
• pattern-lab/unified-asset-installer: GitHub, Packagist

Installing the Development Edition for Twig

Pattern Lab uses Composer to manage project dependencies. If you are going to use the Development Edition you are required to have Composer installed.

1. Install Composer

Please follow the directions for installing Composer on the Composer website. We recommend you install it globally.

2. Install the Development Edition

Use Composer's create-project feature to install the Development Edition into a location of your choosing. Type:

cd install/location/
composer create-project pattern-lab/edition-development-twig your-project-name && cd $_

This will create a directory called your-project-name. It will also install Pattern Lab's default folder structure as well as core, its dependencies, and the select packages as separate Git clones.

Helpful Commands

These are some helpful commands you can use on the command line for working with Pattern Lab.

List all of the available commands

To list all available commands type:

php core/console --help

To list the options for a particular command type:

php core/console --help --[command]

Generate Pattern Lab

To generate the front-end for Pattern Lab type:

php core/console --generate

Watch for changes and re-generate Pattern Lab

To watch for changes and re-generate the front-end for Pattern Lab type:

php core/console --watch

Start a server to view Pattern Lab

You can use PHP's built-in web server to review your Pattern Lab project in a browser. In a seperate window type:

php core/console --server

Then open http://localhost:8080 in your browser.

Install a StarterKit

To install a near-empty StarterKit as a starting point for your project type:

php core/console --starterkit --init

To install a specific StarterKit from GitHub type:

php core/console --starterkit --install <starterkit-vendor/starterkit-name>

Update Git Remotes

Due to an issue with Composer the default remote values for the dev branches are set to the wrong locations. This will cause issues if/when you try to push your changes. To update them you must type:

git config branch.dev.remote origin

for each package. The list of packages included in the Development Edition and their locations are:

pattern-lab/core -> vendor/pattern-lab/core/
pattern-lab/unified-asset-installer -> vendor/pattern-lab/unified-asset-installer
pattern-lab/patternengine-twig -> packages/pattern-lab/patternengine-twig
pattern-lab/starterkit-twig-default -> packages/pattern-lab/starterkit-twig-default
pattern-lab/styleguidekit-assets-default -> packages/pattern-lab/styleguidekit-assets-default
pattern-lab/styleguidekit-twig-default -> packages/pattern-lab/styleguidekit-twig-default

Important: If you add another Pattern Lab package (e.g. plug-in, StarterKit, etc.) you must also make sure to update the origin for its dev branch.

Adding a New Package

To add a new package to your version of the Development Edition for Twig type:

composer require package-name/from-packagist

Composer uses Packagist as the repository of all Pattern Lab-related packages from the core Pattern Lab team.

Important: If you add another Pattern Lab package (e.g. plug-in, StarterKit, etc.) you must also make sure to update the origin for its dev branch. See instructions above.

Forking and Testing a Package

To use the Development Edition to test changes you may have made to a fork of a package do the following:

1. Fork a Package and Create a Feature Test Branch

On GitHub you can fork the package you want to modify. You must create a new branch in which you will create your new changes. In this example we will use pattern-lab/patternengine-mustache as the example of our forked project and bugfix as the name of our branch.

2. Update the Repositories Section of composer.json

In composer.json you need to add or update the repositories section to point at your forked repository for a package:

"repositories": [
    {
        "type": "vcs",
        "url": "https://github.com/your-name/patternengine-php-mustache"
    }
],

3. Update the Package Branch in Require Section of composer.json

In composer.json you need to update the require section to point at the new branch in your forked repository:

"require": {
    "pattern-lab/patternengine-twig": "dev-bugfix"
}

Reminder: dev- is used by Composer to know when it should clone a branch in a repo instead of downloading it. dev- should not he a part of the name of your branch.

4. Update the Development Edition's Dependencies

To update the Development Edition's dependencies to use your forked package type:

composer update pattern-lab/patternengine-twig

Testing Against "Releases"

Packages developed by the core Pattern Lab team use the gitflow model of Git repository management. Because the Development Edition clones the repos for each package you can technically switch each package to use the master branch to test against the last release of any particular package.