Melody is a really handy open-source tool to create one-file PHP scripts with Composer dependencies.

Melody is a tool to execute one-line PHP scripts with dependencies

Melody is a tool to execute one-line PHP scripts with dependencies


As Melody is just a PHAR file, we only need to download it and include it in one of the directories included in our PATH environment variable, for example at /usr/local/bin/:

$ sudo sh -c "curl -o /usr/local/bin/melody && chmod a+x /usr/local/bin/melody"

Then, if we execute “melody”, we should see something like this:

$ melody
Melody version 1.0 by SensioLabs

 [options] command [arguments]
 --help (-h)           Display this help message.
 --quiet (-q)          Do not output any message.
 --verbose (-v|vv|vvv) Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug.
 --version (-V)        Display this application version.
 --ansi                Force ANSI output.
 --no-ansi             Disable ANSI output.
 --no-interaction (-n) Do not ask any interactive question.

Available commands:
 help          Displays help for a command
 list          Lists commands
 run           execute a script
 self-update   Update melody.phar to the latest version.

Simple example

Let’s create a simple example to understand how Melody works. The following script makes use of the symfony/finder component to look for PNG files in the current directory (and subdirectories):

    - "symfony/finder: ~2.6"

$finder = Symfony\Component\Finder\Finder::create()

foreach ($finder as $file) {
    echo $file, "\n";

As you can see, it’s a regular PHP script with a heredoc string at the beginning, which defines the packages the script depends on, using the YAML format in a similar way as we do it in composer.json files.

Melody reads the heredoc string called CONFIG and downloads the packages behind the scenes using Composer. To run the script:

$ melody run example.php

Extra arguments

It is possible to send additional parameters to the PHP script appending them after the name of the script so they can be read using the $argc and $argv variables. For example, to configure the directory to look for PNG images:

$finder = Symfony\Component\Finder\Finder::create()

And then:

$ melody run example.php /tmp

PHP options

What if you need to pass additional options to the PHP binary? For example, you may want to start the built-in server or change some settings. This can be done using the “php-options” setting.

In the following example, the memory_limit setting has been set to 256M and the built-in server will be launched:

    - ...
    - "-d"
    - "memory_limit=256M"
    - "-S"
    - "localhost:8000"

Running gists

Melody has another nice feature, it can run GitHub gists directly! This can be useful for scripts that we want to execute in different computers. For example, I created a simple script to check your ServerGrove’s mail settings sending a test email based on servergrove/email-test. To execute it, you need to include 3 parameters: $from, $to and $password:

$ melody run 123456

This script sends a test email from to using the ServerGrove’s mail server. Obviously, it will only work if you are using our mail server, but setting up a different one is trivial.


Melody can be really handy. At ServerGrove, we are thinking about creating a repository of small tools to help our clients to check and manage their servers. What do you think?

Photo: “Music box 2”, by grfx_guru.