Using Composer Dist Installer

Composer Dist Installer is a small tool I developed for Cube to help developers setup Composer-managed projects easily. Its purpose is to take developers through a quick console-based wizard in order to gather basic configuration options for your project and install the corresponding configuration files.

Its primary goal is to make the process easier for first-time installations. But it can also be used to help automate the configuration of the project during deployment by providing default values for fields, for example.

The purpose of this tutorial is to take you through a step-by-step guide on how to integrate this tool with an existing project. We’ll use the Doctrine2 ORM Tutorial as an example, only that instead of connecting to a SQLite database (which requires little configuration) we’ll connect to a MySQL database.

Prerequisites

This guide assumes you have the following prerequisites installed and properly configured:

• PHP 5.4 or above
• A doctrine-compatible database server (e.g. MySQL).
• Composer Package Manager (Install Composer)

Step 1: Setup Project

First you’ll have to fork and clone (or manually download) the Doctrine2 ORM Tutorial source code.

Now let’s tell Composer about our tool’s and hook it to the “install” command by editing composer.json as follows (make sure you remove the comments!):

{
    "require": {
        "doctrine/orm": "2.*",
        "symfony/yaml": "2.*",
        // add this line (and don't forget the comma at the end of the previous line)
        "cube/composer-dist-installer": "~1.0@beta"
    },
    // .. other composer settings
    "scripts": {
        "post-install-cmd": [
            "Cube\\ComposerDistInstaller\\Bootstrap::install"
        ]
    }
}

Then open the boostrap.php file and change the $conn variable assignment (currently around line 14) to:

$conn = include __DIR__ . '/config/database.config.php';

Step 2: Create the Distribution File

We’re not going to create the config/database.config.php file yet. That’s a file that will hold the database connection information, and will therefore probably have different data for you than it will for another developer.

Here’s where Composer Dist Installer comes in. Create a file at config/database.config.php.dist and save it with this data:

<?php
return [
    'dbname' => '{{DB Name?|mydb}}',
    'user' => '{{DB User []?|testuser}}',
    'password' => '{{DB Password?}}',
    'host' => '{{DB Host []?|localhost}}',
    'driver' => 'pdo_mysql',
];

Now that the file is created let’s tell Composer where it is. Add the following to composer.json right below your previous changes:

{
    "scripts": {
        "post-install-cmd": [
            "Cube\\ComposerDistInstaller\\Bootstrap::install"
        ]
    }, 
    // new stuff below (again, don't actually copy this comment please!)
    "extra": {
        "dist-installer-params": {
            "file": "config/database.config.php" 
            // will automatically detect the corresponding .dist file
        }
    }
}

Step 3: Test It

Testing is simple, just run composer install and at the end of the process Composer will start asking you questions. Answer them and when you’re done you’ll see a new file at config/database.config.php ready for use by boostrap.php.

TIP: If something goes wrong, you should be able to run composer install as many times as you need

What’s more, next time someone checks out your project and runs composer install to download and install dependencies, our tool will be there to install the distribution files automatically!

Final Words

If you used or plan to use this tool I’d love to hear from you! Any feedback is appreciated.

You can also help by sharing this page (or the repository), personally telling your colleagues / friends about it, and of course by contributing new features or bug-fixes.

The post Using Composer Dist Installer appeared first on Gabriel Somoza.