Extending Primer’s CLI Tool

Primer is a tool to aid with the design & development of a web site or app. It helps focus the design process into a series of reusable components and patterns instead of thinking just about templates. Make Primer more powerful by building your own CLI toolkit. Save time by automating your workflow.

Primer has a handy CLI tool baked in, which provides a convenient way to add a new pattern. Under the hood it uses Symfony’s Console package. This makes it really easy to build up your own command line tools to make your development workflow easier.

The following command creates a new pattern within Primer, when run from the root directory:

php primer pattern:make components/cards/news-card

This is great; it lets you add components effortlessly and saves you time painstakingly creating folders and files. However, you may be thinking “This is great, but why doesn’t it do X or Y?”.

Luckily, we can create our own! This post will run through how to create your own custom command. For this example we will simply write Hello World back to the command line. First, let’s create a new class for our command. Where this lives is totally up to you, but for the sake of this example we’ll add an app/Commands directory and pop our file in there:

[project root]
    - app/
        - Commands/
            - HelloWorld.php
    - bootstrap
    - patterns
    ...

And here’s what the HelloWorld.php looks like. Note how we’ve:

  • Set a namepsace of AppCommands, so we can auto-load this bad-boy
  • Extended Symfony’s Command class, so we can use all of their goodies
namespace AppCommands;

use SymfonyComponentConsoleCommandCommand;
use SymfonyComponentConsoleInputInputInterface;
use SymfonyComponentConsoleInputInputOption;
use SymfonyComponentConsoleOutputOutputInterface;

class HelloWorld extends Command {

    protected function configure()
    {
        $this->setName('helloworld')
            ->setDescription('Prints Hello World');
    }

    protected function execute(InputInterface $input, OutputInterface $output)
    {
        $output->writeln('Hello World');
    }
}

Open up bootstrap/start.php, and inside the cli.init event closure we can inject our new command.

Event::listen('cli.init', function ($cli) {
    $cli->add(new AppCommandsHelloWorld);

    // ... Other custom commands
});

Next, we need to tell composer to autoload it. Add the following autoload mapping to the composer.json file.

"require": {
    ...
},

"autoload": {
    "psr-4": {
        "App\": "app/"
    }
}

Lastly, regenerate the autoload class maps. The -o is optional and also optimises it.

composer dump-autoload -o

Now we are ready to test our command out. Head to the command line and put in:

php primer helloworld

And you’re done! This example is trivial, but allows you to write any CLI tool you need. For example, you could extend the pattern:make command to allow --js --sass options, which automatically js / sass files for you. Or you could create an exporter which converts Primer templates to a static site. You could even write a command which creates a new command (like Laravel’s make:console <name>)