Binaries

Introduction

Rocketeer uses a variety of commands to execute your commands, most are low-level (change directory, symlink, etc) but it also needs to exploit the various tools your application uses to live, test, etc. For this it uses wrapper classes called Binaries.

Using binaries

A binary class is any class extending Rocketeer\Abstracts\AbstractBinary. The core of said class is the getCommand method which allows you to build commands fluently, it takes three arguments: the command to call, its arguments, and its options.

By default binary classes are only preoccupied with returning commands that are meant to be executed by a third party. They don't run anything anywhere, they just build what is meant to be executed and return it to you. Per example in the context of a class, this is how you'd create a git command and execute it:

$this->run(array($git->clone(['from','to'],['--branch'=>'master'])));

However binary classes also come with magic methods that allow you to directly execute the built command. For this, simply call any of the run* methods usually found on tasks, directly on the binary instance. This means these two examples do the same thing:

Getting a binary instance

To get an instance of a binary in a task, or a strategy, simply use the binary method. It will return either an instance of AnonymousBinary if no built-in class for that binary exists, or if there already exists a class extending AbstractBinary in Rocketeer, it will return that:

The difference is built-in binaries come with extra helper methods that are most of the time aliases to longer commands. Per example let's take a look at the PHP::extensions binary method which returns all available extensions of a PHP instance:

Parent callers

Sometimes binaries have to be run by other binaries, per example the Artisan CLI tool needs to be run by PHP. For this you'll use the setParent method on the binary class. It accepts both instances of AbstractBinary or simple strings:

The advantage of using binary classes instead of running raw commands is that they have already built-in pathfinders. Meaning if you call $this->artisan()->run('migrate') instead of simply $this->run('php artisan migrate'), Rocketeer knows what those binaries are and where they are. You'll automatically get the correct path to PHP set as parent, the correct path to Artisan, etc.

Creating your own binaries

Creating your own binaries is fairly straight-forward. At their core they're simply classes extending Rocketeer\Abstracts\AbstractBinary. There is no required method at all, they're just canvas to add your own aliases and/or known paths.

To set the predefined known paths of a binary, simply override the getKnownPaths method. It returns an array with two entries: first entry is what to call which on, and if that doesn't work, it'll use the second path. In other words, the second entry of the array is a fallback path.

<?phpnamespaceAcme;useRocketeer\Abstracts\AbstractBinary;classGruntextendsAbstractBinary{/**
* Get an array of default paths to look for
*
* @return string[]
*/protectedfunctiongetKnownPaths(){returnarray('grunt',$this->releasesManager->getCurrentReleasePath('node_modules/.bin/grunt'),);}}

From there you're free to add whatever methods you feel are good to have around, and call them as any other commands:

<?phpnamespaceAcme;useRocketeer\Abstracts\AbstractBinary;classGruntextendsAbstractBinary{/**
* Get an array of default paths to look for
*
* @return string[]
*/protectedfunctiongetKnownPaths(){returnarray('grunt',$this->releasesManager->getCurrentReleasePath('node_modules/.bin/grunt'),);}publicfunctionforceAssets(){return$this->assets(null,'--force');}}