Phpake: A Tool like Make/Rake Built for PHP

Phpake is a make-like utility built for PHP. It is pronounced fake because the second p is silent just like the second p in the word elephpant.

I've always found writing a Makefile quite challenging because the syntax is similar to the shell, but quite different at the same time. When I’m working with Ruby, I use rake and it’s awesome because it uses Ruby syntax. When I work with PHP, I miss having a similar tool that is easy to install, easy to use, and allows full-fledged PHP syntax. Thus, Phpake was born.

2 minute version

• Phpake (pronounced fake) is a tool like make and rake.
  • It is built with Symfony Console.
  • It lets you define tasks in PHP syntax, which can then be run from the command-line interface.
• Install Phpake with composer require jigarius/phpake.
• Create a Phpakefile in your project to define tasks.
  • This is just a PHP file containing functions.
  • Each function is a Phpake task and can be run with phpake.
  • Function doc blocks are used as metadata for the phpake sub-commands.
• For example, a function hello_human($fname, $lname = NULL).
  • This can be executed as phpake hello-human Joey B.
  • It takes parameters fname (required) and lname (optional).
• Tasks can be organized with PHP namespaces.
• Run the command phpake to see a list of available commands.
• For more documentation,
  • Visit the Phpake repository on GitHub.
  • See the sample Phpakefile.

Why Phpake?

There are other PHP tools that do a similar job, i.e. define tasks and then run them. Phpake differs from these tools by keeping this as simple as possible to reduce the learning curve. In general, all you do is:

• Create a PHP file named Phpakefile.
• Write some PHP functions in it and you’re set!
• Use doc blocks to document the tasks.
• Use PHP namespaces to organize the tasks.

Of course, there are a few special things here and there, but they’re purely optional.

Installation

Phpake can be installed with composer, either globally or in a specific project.

# System-wide (global) installation.
composer global require jigarius/phpake
# Project-specific installation.
composer require jigarius/phpake

Use the --dev flag to install as a dev dependency.

Note: To run phpake from anywhere in the terminal, you need to add composer’s vendor/bin directory to your system’s PATH variable.

Usage

Out of the box, Phpake comes with 2 commands which are introduced by Symfony Console.

• phpake list: Shows a list of all sub-commands.
• phpake help: Shows help.

The rest of the commands are to be defined by you using a Phpakefile as discussed in the next section.

Phpakefile

A Phpakefile is similar to a Makefile or a Rakefile. It is a PHP file which defines one or more functions (tasks). Tasks can be organized into separate files and included from the main Phpakefile or they can be organized into PHP namespaces.

Example 1: Simple task

Say, you create a Phpakefile with a basic command.

<?php

/**
 * Say hello world.
 */
function hello_world() {
  echo 'Hello world' . PHP_EOL;
}

This task can be run as phpake hello-world.

Example 2: Input/Output

If your tasks expect arguments, all you have to do is define them as arguments to your task callback, i.e. function in your Phpakefile. Doc blocks are used to document these commands and are visible as help text in the command-line interface.

<?php

/**
 * Say hello to a human.
 *
 * This paragraph is displayed on the command-specific help page.
 * Notice how the built-in parameter $output was kept towards the end.
 *
 * @usage Jigarius
 * @usage Jigarius Caesar
 *
 * @param string $fname First name.
 * @param string|null $lname Last name.
 * @param object $output
 */
function hello_human(string $fname, string $lname = NULL, $output = NULL) {
  $name = $lname ? "$fname $lname" : "$fname";
  $output->writeln("Hello <info>$name</info>!");
}

Here’s a breakdown of what’s going on.

• The first line of the doc block will be used as the command’s summary.
• The other lines will be used as additional help text.
• The @param tags will be used as argument descriptions.
• The @usage tags provide usage examples.
  • Notice how only the arguments are written.
• $output is a special, built-in argument.
  • Read more about it on the project’s readme.

This task can then be executed as phpake hello-human Bunny Wabbit. Here, Bunny becomes $fname, and Wabbit becomes $lname.

Example 3: Shell commands

I often use Makefile or Rakefile to create shortcuts to frequently used project-specific commands. Say, I often run the following command:

docker compose exec main sh

I can define this shell command as a Phpake task as follows:

namespace Docker;

function ssh() {
  $process = proc_open(
    'docker compose exec main sh',
    [STDIN, STDOUT, STDERR],
    $pipes
  );
  proc_close($process);
}

Now we can run this command easily with phpake docker:ssh. Notice how namespace docker affects the command name.

Conclusion

When working on a PHP project, Phpake can be used instead of make. It is easier to use and maintain because it is built on and for PHP. Just install Phpake with composer and define your tasks in a Phpakefile and you’re all set!

Next steps

• See the Phpake repo on GitHub.
• Read about Make and Rake.
• Use Phpake in a projects.