Using Pestle

Want to help? Great! Here's an escalating list of things you can do to be involved.

Using Pestle

The easiest way to contribute? Use pestle while working on your Magento 2 projects, and report any bugs or behavior tweaks you'd like. You can download a copy of pestle using curl

curl -LO http://pestle.pulsestorm.net/pestle.phar

and get a list of commands by running

pestle.phar list

and get help for any specific command by running

$ pestle.phar help generate_module        
Name
    generate_module

Description
    Generates new module XML, adds to file system
    This command generates the necessary files and configuration
    to add a new module to a Magento 2 system.

    pestle.phar Pulsestorm TestingCreator 0.0.1

    @argument namespace Vendor Namespace? [Pulsestorm]
    @argument name Module Name? [Testbed]
    @argument version Version? [0.0.1]
    @command generate_module

It's pretty straight forward from there. Although we're reasonable confident in pestle's stability, this is early days beta software, so be sure you've got a backup of your system.

Creating New Commands

Want to contribute a command? Great! You can get the boiler plate for a new command using pestle itself by running the create_pestle_command command

$ pestle.phar generate_pestle_command
New Command Name? (foo_bar)] my_command
Creating the following class
<?php
namespace Pulsestorm\Magento2\Cli\My_Command;
//...
vi modules/pulsestorm/magento2/cli/my_command/module.php

After running the above command, you'll have a boilerplate command created in

#File: modules/pulsestorm/magento2/cli/my_command/module.php
<?php
namespace Pulsestorm\Magento2\Cli\My_Command;
use function Pulsestorm\Pestle\Importer\pestle_import;
pestle_import('Pulsestorm\Pestle\Library\output');

/**
* One Line Description
*
* @command my_command
*/
function pestle_cli($argv)
{
    output("Hello Sailor");
}

Put the code for your command in the pestle_cli function, and run it with

$ php runner.php my_command
Hello Sailor

Anything that goes in a normal PHP file can go in a pestle module. You can happily write plain old PHP code in this file without understanding the inner workings of pestle.

Understanding a Pestle Module

Pestle is an experiment. We're taking a step back from writing code in a Java/C# style, and trying out patterns that are more common in languages like python and ruby. A preference for simple functions that operate and scaler and array data, but nothing blocking users who want to create a class hierarchy in their own modules.

When we started, we wanted to leverage native PHP features as much as possible, and test the robustness of PHP's namespaces. Every pestle module is a namespaced PHP file

namespace Pulsestorm\Magento2\Cli\My_Command;

Unfortunately, we quickly hit tow major road blocks.

1. PHP has no way to import all the functions from a module/namespace (without listing them all out)
2. PHP has no system for automatically loading namespaces files in place, and the spl_autoloader only works with classes.

That's where the pestle_import function comes in.

use function Pulsestorm\Pestle\Importer\pestle_import;
pestle_import('Pulsestorm\Pestle\Library\output');

The function can be used to import specific functions from another namespace into your pestle module. It will handle autoloading the correct module file (pulsestorm/pestle/library/module.php), and ensur you have a function output available to you in your file to call later, (output in the example above)

/**
* One Line Description
*
* @command my_command
*/
function pestle_cli($argv, $options)
{
    output("Hello Sailor");
}

At this time, the pestle_cli function is required in all modules, and it the main entry point for a command. The @command attribute is what gives a command its name. If you're writing a function library, just mark @command with the special library keyword and leave the function empty.

/**
* One Line Description
*
* @command library
*/
function pestle_cli($argv, $options)
{
    
}

We're going to be fast and loose with the implementation details of pestle's module format in the early days of the framework. Part of the idea here is to experiment and noodle on code to see what does and doesn't work.