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 }}!

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

And simply run it:

$ melody run script.php

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

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:

Gist Id: 565752f13499a3fa17d9

Username/Id: lyrixx/565752f13499a3fa17d9

Gist URI: https://gist.github.com/lyrixx/565752f13499a3fa17d9

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 ):

http : http://my.private/snippets/test.php

: ftp : ftp://user:password@server/public/test.php

: php : php://stdin

: data : data://text/plain;base64,SSBsb3ZlIFBIUAo[...]==

: phar : phar:///opt/resource.phar/test.php

: zlib : compress.zlib:///opt/resource.gz

: bzip2 : compress.bzip2:///opt/resource.bz2

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

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

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:

a list of trusted resources signatures (see section Trust).

a list of trusted users.

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:

- "silex/silex: *" without quotes is an invalid YAML.

without quotes is an invalid YAML. - "silex/silex: ~1.2" without quotes is a YAML object and refused by melody.

without quotes is a YAML object and refused by melody. - "-S" without quotes is an array of arrays.

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;

Please read the Contributing guide.

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:

They close or re-open issues;

They merge pull-requests into master;

They manage labels and milestones on issues;

Github labels#

bug (see all): an issue or a PR for a feature that doesn't work If the issue about a usage problem, it will probably be flagged as bug .

wip (see all): long-running PR This label allows other people to review the code before merging the code. It's very useful for long-running PR, and to avoid merging an unfinished feature. If you make a pull-request and plan to make it long-running, please add [WIP] also in the title, so a release manager can flag it as wip and remove it from your title.

discuss (see all): an issue about a feature suggestion or changing an existing feature An issue suggesting a new feature will be flagged as discuss .

refactor (see all): an issue or a PR that is about changing the implementation of an existing feature; A refactor usually have no functional benefit, but can be required by a new feature , or any other issue;

new feature (see all): a feature that is decided to be done If there is no milestone attached, it's an unplanned new feature.

duplicate (see all): an issue or PR that is a duplicate of another. The original issue should be referenced inside duplicated issue with a comment or in the description: Duplicate of #32

wontfix (see all): an issue that cannot be fixed because of a limitation or a decision; The limitation or reasons of the decision should be exposed in the issue.

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#