README

composer-hydration

Introduction

composer-hydration is a simple package that provides a Composer Script to be used as placeholder replacement, mostly used by 'skeletons' projects.

Example:

composer run-script hydrate -- --replace={FRUIT}:"apple",{INGREDIENT}:"cinnamon" 

The script will search for the placeholders in file content, file names and folders.

Before:

$ /path/composer/project/{FRUIT}.txt "I love {FRUIT} with {INGREDIENT}, is a good combination!" 

After:

$ /path/composer/project/apple.txt "I love apple with cinnamon, is a good combination!" 

Installation

Install Composer

Since composer-hydration is a Composer script, you need to install composer first.

Note: The instructions below refer to the global composer installation. You might need to replace composer with php composer.phar (or similar) for your setup.

Add package dependency

Add composer-hydration as package dependency of your project, updating your composer.json:

 "require": { ... "jkribeiro/composer-hydration": "~1" } 

Define the Composer Script

Define the Composer script, adding this entry to your composer.json:

 "scripts": { "hydrate": "Jkribeiro\\Composer\\ComposerHydration::meatOnBones" } 

Install Project

composer install 

Usage

There are some ways that you can execute this script:

Execute the command manually

After have the package installed, you can run the command manually to have your values placed.

composer run-script hydrate -- --replace={SEARCH}:{REPLACE},..." 

Hydrate during the Composer Events

Composer fires some events during its execution process, useful to define on which step/event it will perform the hydration process.

In the example below, the hydration process will occur after the project installation:

 "scripts": { "hydrate": "Jkribeiro\\Composer\\ComposerHydration::meatOnBones", "post-install-cmd": "@composer run-script hydrate -- --replace={{PROJECT_NAMESPACE}}:{%BASENAME%}" } 

Variables as Replacement values

Sometimes we need to use dynamic replacement values on composer.json, not only hardcoded values like {FRUIT}:banana, for these cases, there are two possibilities:

Environment Variables

composer.json allows environment variables as replacement placeholder value, like {{PROJECT_NAMESPACE}}:$PROJECT_NAME", $PROJECT_NAME is the variable name. You must define the variables before execute the Composer commands.

Example:
composer.json

 ... "scripts": { "hydrate": "Jkribeiro\\Composer\\ComposerHydration::meatOnBones", "post-install-cmd": "@composer run-script hydrate -- --replace={{PROJECT_NAMESPACE}}:$PROJECT_NAME" } 

Execution

$ export PROJECT_NAME="My Project" $ composer install 

"Magic Constants"

Using the same idea of PHP Magic constants, composer-hydration provides some Magic constants too.

• {%BASENAME%}: Returns the base folder name where the script is being executed, normally is the name of the project.

• {%UCFIRST_BASENAME%}: Returns the base folder name with the first character capitalized.

• {%UPPER_CAMEL_CASE_BASENAME%}, {%LOWER_CAMEL_CASE_BASENAME%}: Returns the base folder name using the upper/lower camel case format. Only the folder name separators '-', '_' are allowed.

  Example:

  $ ~/Projects/myproject: composer run-script hydrate -- --replace={{PROJECT_NAMESPACE}}:{%BASENAME%}" 

  Placeholders with {{PROJECT_NAMESPACE}} will be replaced by myproject.