Defining Tasks

To define a new task you just need to define a function within the idxfile.php and it will be automatically mounted as an Idephix command.

1
2
3
4
5
6
<?php

function myNewTask()
{
    echo 'I am a brand new task' . PHP_EOL;
}

Now running idx you’ll get

$ bin/idx

$ Available commands:
$ help            Displays help for a command
$ initFile        Init idx configurations and tasks file
$ list            Lists commands
$ myNewTask

And you can execute it with:

$ bin/idx myNewTask
I am a brand new task

You can even execute a task within another task:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<?php

function anotherTask()
{
}

function myNewTask(\Idephix\Context $context)
{
    $context->anotherTask();
}

Hint

Every task can define a special arguments: $context. If you define an argument and type hint it as \Idephix\Context an instance of the context object will be injected at runtime. The context object allows you to execute tasks and access configuration parameters. For more info about Context check out Scripting with Idephix section

Adding task arguments

Function parameters will be used as the task arguments.

1
2
3
4
5
6
<?php

function yell($what)
{
    echo $what . PHP_EOL;
}

Mandatory Arguments

The parameter $name will be a mandatory option to be specified in the command execution.

$ bin/idx help yell
Usage:
    yell what

Arguments:
    what

You can add as many arguments as you need, just adding function parameters.

Optional Arguments

If you want to add optional arguments, just define a default value for the parameter, as:

1
2
3
4
5
6
<?php

function yell($what = 'foo')
{
    echo $what . PHP_EOL;
}

Optional arguments as task flags

A flag is a special parameter with default value false. Using flags should be useful to implement a dry-run approach in your script

1
2
3
4
5
6
7
8
   <?php

   function deploy($go = false){
        if ($go) {
            //bla bla bla
        return;
    }
}

Documenting tasks

Tasks and arguments can have a description. You can define descriptions using simple and well known phpdoc block.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
<?php

/**
 * This command will yell at you
 *
 *
 * @param string $what What you want to yell
 */
function yell($what = 'foo')
{
    echo $what . PHP_EOL;
}

Configure a task like

$ bin/idx help yell
Usage:
    yell [what]

Arguments:
    what    What you want to yell (default: "foo")

Scripting with Idephix

With Idephix you compose your script basically:

  • executing local commands
  • executing remote commands
  • executing other tasks you have already defined
  • sending some output to the console

In order to perform such operations you will need an instance of the Idephix\\Context object. Idephix will inject it at runtime in each tasks that defines an argument type hinted as Idephix\\Context. A Context implements \Idephix\TaskExecutor and \Idephix\DictionaryAccess allowing you to execute commands and to access the configuration data related to the choosen env.

Executing local commands

\Idephix\TaskExecutor::local allows you to execute local commands. A local command will be executing without any need for a SSH connection, on your local machine.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<?php

function buildDoc(\Idephix\Context $context, $open = false)
{
    $context->local('cp -r src/Idephix/Cookbook docs/');
    $context->local('make  -C ./docs html');

    if ($open) {
        $context->openDoc();
    }
}

If you need so you can execute the command in dry run mode

1
2
3
4
5
6
<?php

function buildDoc(\Idephix\Context $context, $open = false)
{
    $context->local('cp -r src/Idephix/Cookbook docs/', true);
}

In dry run mode the command will just be echoed to the console. This can be useful while debugging your idxfile to check the actual command that would be executed.

For local commands you can also specify a timeout:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
<?php

function buildTravis(\Idephix\Context $context)
{
    try {
        $context->local('composer install');
        $context->local('bin/phpunit -c tests --coverage-clover=clover.xml', false, 240);
        $context->runTask('createPhar');
    } catch (\Exception $e) {
        $context->output()->writeln(sprintf("<error>Exception: \n%s</error>", $e->getMessage()));
        exit(1);
    }
};

Executing remote commands

Running remote commands is almost the same as running local commands. You can do that using \Idephix\TaskExecutor::remote method. Dry run mode works quite the same as for local commands, but mind that at the moment is not possible to specify a timeout for remote commands.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<?php

function switchToNextRelease(Idephix\Context $context, $remoteBaseDir, $nextRelease, $go = false)
{
    $context->remote(
        "
        cd $remoteBaseDir && \\
        ln -nfs $nextRelease current",
        !$go
    );
}

In order to execute a remote command you must specify an environment using --env option. If you fail to specify a valid env name you will get an error and the command will not be executed.

Executing user defined tasks

Every task that you define will be accessible as a method of the Idephix\Context object. Mind that you don’t have to manually inject the Context object, Idephix will do that for you at runtime.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
<?php

function buildDoc(\Idephix\Context $context, $open = false)
{
    $context->local('cp -r src/Idephix/Cookbook docs/');
    $context->local('make  -C ./docs html');

    if ($open) {
        $context->openDoc();
    }
}

function openDoc(\Idephix\Context $context)
{
    $context->local('open docs/_build/html/index.html');
}

Accessing configuration from tasks

Idephix\Context object gives you also access to every configuration defined for the current environment. Imagine you have defined this configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
<?php

$environments = array(
    'prod' => array(
        'hosts' => array('127.0.0.1'),
        'ssh_params' => array(
            'user' => 'ideato'
        ),
        'deploy' => array(
            'repository' => './',
            'branch' => 'origin/master',
            'shared_files' => array('app/config/parameters.yml'),
            'shared_folders' => array('app/cache', 'app/logs'),
            'remote_base_dir' => '/var/www/testidx',
            'rsync_exclude' => './rsync_exclude.txt',
        )
    ),
    'test' => array(//blablabla),
);

While executing a command using --env=prod option your tasks will receive a Context filled up with prod data, so you can access to it. Context allows you to access configuration data implementing php \ArrayAccess interface or through get \Idephix\DictionaryAccess::get method.

1
2
3
4
5
6
7
<?php

function deploy(Idephix\Context $context, $go = false)
{
    $sharedFiles = $context->get('deploy.shared_files', array());
    $repository = $context['deploy.repository'];
    //cut

Writing output to the console

Idephix is based on Symfony console component so you can send output to the user using the \Symfony\Component\Console\Style\SymfonyStyle. You can get the full SymfonyStyle component through the \Idephix\TaskExecutor::output method or you can use the shortcut methods: \Idephix\TaskExecutor::write and \Idephix\TaskExecutor::writeln.

Here is an example of you you can send some output to the console.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
<?php

/**
 * This command will yell at you
 *
 * @param string $what What you want to yell
 */
function yell(\Idephix\Context $context, $what = 'foo')
{
    $context->writeln(strtoupper($what));
    $context->write(strtoupper($what) . PHP_EOL);

    $output = $idx->output();

    // common output elements
    $output->title($what);
    $output->section($what);
    $output->text($what);
    $output->comment($what);
    $output->note($what);
    $output->caution($what);
    $output->listing([$what, $what, $what]);
    $output->success($what);
    $output->error($what);
    $output->warning($what);

    //table
    $headers = ['Parameter', 'Value', 'Value 3'];
    $rows = [
      ['Param1', 'Value1', 'Value 3'],
      ['Param2', 'Value2', 'Value 3']
    ];
    $output->table($headers, $rows);
}

Hint

For more information about SymfonyStyle read the official component documentation