Melody by SensioLabs

One-file composer scripts

One-file composer scripts

Melody is an open-source project, developed during a SensioLabs hackday.

Basically, it allows you to inline composer requirements and to execute a PHP script. It has never be easier to share a PHP code snippet with a gist.

<?php
<<<CONFIG
packages:
    - "twig/twig: ~1.0"
CONFIG;

$loader = new Twig_Loader_Array(array(
    'index' => "Hello {{ name }}!\n",
));

$twig = new Twig_Environment($loader);

echo $twig->render('index', array('name' => 'Melody'));

And simply run it:

$ melody run script.php

demo

Installation#

Locally#

Download the melody.phar file and store it somewhere on your computer.

Globally (manual)#

You can run these commands to easily access melody from anywhere on your system:

$ sudo sh -c "curl http://get.sensiolabs.org/melody.phar -o /usr/local/bin/melody && chmod a+x /usr/local/bin/melody"

Then, just run melody

Available features#

Run gists scripts#

You can easily create a gist to share a snippet and execute it using melody. Instead of downloading the file to your computer, simply pass the URL to melody:

$ melody run https://gist.github.com/lyrixx/565752f13499a3fa17d9

Supported formats:

Please note that melody can only handle gists which contain a single PHP file. It will report an error otherwise.

For those users behind a proxy server, melody now uses the HTTPS_PROXY environment variable.

Run streamed script#

You can run scripts from every supported streams (list streams with stream_get_wrappers):

Caching#

If you ran twice or more a script with the same dependencies, theses dependencies will be cached.

If you don't want this cache, you can disable the cache from the command line:

$ melody run --no-cache test.php

Debug scripts#

In case you want to have a look whats going on behind the scenes, use the verbose flag make melody print output produced by Composer:

$ melody run --vvv test.php

Download Mode#

There are two ways of downloading a package: source and dist. By default Melody will use the dist mode.

If --prefer-source is enabled, Melody will use the source mode and install from source if there is one. The --prefer-source can be used if you don't want Composer to download release archives but do git clone instead. It's very useful if you suffer from API throttling.

Only use this method if you know what you're doing, because --prefer-source is not efficient at all.

$ melody run --prefer-source test.php

Arguments#

Melody allows you to pass arguments to your script.

The simplest way, is to add your arguments after the name of the script.

$ melody run test.php arg1 arg2

But this method does not works with options starting by - or --, because melody will catch them. To use options, you must prepend your options by --.

$ melody run test.php -- -a --arg1 arg2

Trust#

By default, when you run an external resource (ie: a gist) Melody will display a warning message to let you choose if you want or not run the script. When you trust the resource, Melody will remember your answer and never again ask you for confirmation.

You are running an untrusted resource
  URL:             https://gist.github.com/565752f13499a3fa17d9
  Revision:        #1
  Owner:           lyrixx
  Created at:      Fri, 05 Dec 2014 22:22:28 +0000
  Last update:     Tue, 09 Dec 2014 13:45:02 +0000

What do you want to do (show-code, continue, abort)?

But if you trust the resource and don't want to interract with Melody, you can pass the parameter --trust to the command

$ melody run 565752f13499a3fa17d9 --trust

User Configuration#

Melody stores your configuration in a file located in ~/.sensiolabs/melody.yml. This file contains:

This file is stored with a YAML syntax. You can manually edit it to complete the list of trusted user for instance.

trust:
  signatures: []
  users:
    - jeremy-derusse
    - lyrixx

Front matter#

The script you want to run with melody must start with a YAML configuration embedded in a heredoc string named CONFIG. This config must contain at least one package to install.

Optionally you can provide a list of options to pass to php command. It could be useful to e.g. start a php web server or define php.ini settings.

<?php

<<<CONFIG
packages:
    - "silex/silex: *"
php-options:
    - "-S"
    - "localhost:8000"
CONFIG;

$app = new Silex\Application();
$app->get('/hello/{name}', function ($name) use ($app) {
    return 'Hello '.$app->escape($name);
});
$app->run();

Beware that CONFIG section contents must comply with YAML syntax restrictions:

Using fork and private repositories#

If you need to use packages not registred in Packagist repository, you can specify repositories in the YAML configuration. See composer documention.

<?php

<<<CONFIG
repositories:
    - type: vcs
      url: https://example.com/vendor/my-private-repo.git
packages:
    - "vendor/package-name: 1.0.2"
CONFIG;

Development#

Please read the Contributing guide.

Installation#

Clone repository and install dependencies:

$ git clone git@github.com:sensiolabs/melody.git
$ cd melody
$ composer install

Running tests#

A script is available to execute all projects tests. It should work after a fresh git clone:

$ phpunit

Generating the PHAR#

You need box to build the phar, then

$ box build

Contribution guide#

Melody is an open source project driven by SensioLabs.

Reporting a bug#

Whenever you find a bug in Melody, we kindly ask you to report it. Before reporting a bug, please verify that it has not already been reported by someone else in the existing bugs.

If you're the first person to hit this problem, create an issue and provide us maximum information about your system: OS, PHP version, composer version.

Release managers#

Release managers are allowed to manage the Github repository and do the following:

Github labels#

Labels on the repository are managed by release managers. Users can suggest tags by adding pseudo-labels in title:

[bug][new-feature] It's not a bug, it's a new feature!

Release managers are allowed to edit the user title to remove those labels and add them as labels.

Acceptance criteria#

References#