rougin/blueprint

A bootstrap for PHP console projects.

v0.7.0 2024-10-20 16:32 UTC

Requires

• php: >=5.3.0
• rougin/slytherin: ~0.9
• symfony/console: ~2.8|~3.0|~4.0|~5.0|~6.0
• symfony/yaml: ~2.8|~3.0|~4.0|~5.0|~6.0

Requires (Dev)

• phpunit/phpunit: ~4.2|~5.7|~6.0|~7.0|~8.0|~9.0
• sanmai/phpunit-legacy-adapter: ~6.1|~8.0

MIT

• Rougin Gutib

• generator
• blueprint
• php-console

README

Blueprint is a PHP package for bootstrapping console applications.

Installation

Install Blueprint via Composer:

$ composer require rougin/blueprint

Basic usage

Create a blueprint.yml file using the initialize command:

$ vendor/bin/blueprint initialize

# blueprint.yml

name: Blueprint
version: 0.7.0

paths:
  templates: %%CURRENT_DIRECTORY%%/src/Templates
  commands: %%CURRENT_DIRECTORY%%/src/Commands

namespaces:
  commands: Rougin\Blueprint\Commands

Note

• Replace the values specified in the blueprint.yml file.
• Add commands and templates (if applicable) to their respective directories.

To write a command, the commands property in blueprint.yml must be updated first:

# blueprint.yml

# ...

namespaces:
  commands: Acme\Commands

Then create the command (e.g., TestCommand) to its assigned directory (e.g., src/Commands):

// src/Commands/TestCommand.php

namespace Acme\Commands;

use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;

class TestCommand extends Command
{
    protected function configure()
    {
        $this->setName('test');

        $this->setDescription('Returns a "Test" string');
    }

    protected function execute(InputInterface $input, OutputInterface $output)
    {
        $output->writeln('<info>Test</info>');
    }
}

Before running the command, kindly check if its namespace is defined in Composer:

// composer.json

// ...

"autoload":
{
  "psr-4":
  {
    "Acme\\": "src"
  }
}

// ...

$ composer dump-autoload

$ vendor/bin/blueprint test

Test

Extending Blueprint

To use Blueprint as a console application, the Blueprint class must be created first:

// bin/app.php

use Rougin\Blueprint\Blueprint;

// Return the root from "vendor" --------
$vendor = __DIR__ . '/../../../../';

$default = __DIR__ . '/../';

$loader = '/vendor/autoload.php';

$exists = file_exists($vendor . $loader);

$root = $exists ? $vendor : $default;
// --------------------------------------

// Load the Composer autoloader -------
require $root . '/vendor/autoload.php';
// ------------------------------------

$app = new Blueprint;

The following details can now be updated after creating the class:

// bin/app.php

// ...

// Sets the directory for the defined commands ----
$app->setCommandPath(__DIR__ . '/../src/Commands');
// ------------------------------------------------

// Sets the directory for the templates. Useful -----
// for creating commands with template engines ------
$app->setTemplatePath(__DIR__ . '/../src/Templates');
// --------------------------------------------------

// Sets the name of the console application ----
$app->setName('Acme');
// ---------------------------------------------

// Sets the version of the console application ---
$app->setVersion('0.1.0');
// -----------------------------------------------

// Sets the namespace for the "commands" path ---
$namespace = 'Acme\Simplest\Commands';

$app->setCommandNamespace($namespace);
// ----------------------------------------------

// Runs the console application ---
$app->run();
// --------------------------------

Note

Using this approach means the blueprint.yml can now be omitted. This approach is also applicable to create customized console applications without the Blueprint branding.

Once configured, the console application can now be run in the terminal:

$ php bin\app.php

Acme 0.1.0

Usage:
  command [options] [arguments]

Options:
  -h, --help            Display help for the given command. When no command is given display help for the list command
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi|--no-ansi  Force (or disable --no-ansi) ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Available commands:
  completion  Dump the shell completion script
  help        Display help for a command
  list        List commands

Customized Command

Blueprint also provides an alternative Command class for creating commands with descriptive methods and less code:

// src/Commands/TestCommand.php

namespace Acme\Commands;

use Rougin\Blueprint\Command;

class TestCommand extends Command
{
    protected $name = 'test';

    protected $description = 'Returns a "Test" string';

    public function execute()
    {
        $this->showPass('Test');
    }
}

Kindly see COMMAND for its available properties and methods.

Note

All of the functionalities for the Command class is derived from the Symfony's Console component.

Injecting dependencies

To perform automagic resolutions in each defined commands, the addPackage can be used with the additional functionality from the Container class from Slytherin:

// src/Sample.php

namespace Acme;

class Sample
{
    protected $name;

    public function __construct($name)
    {
        $this->name = $name;
    }

    public function getName()
    {
        return $this->name;
    }
}

// src/Packages/SamplePackage.php

namespace Acme\Packages;

use Acme\Sample;
use Rougin\Slytherin\Container\ContainerInterface;
use Rougin\Slytherin\Integration\Configuration;
use Rougin\Slytherin\Integration\IntegrationInterface;

class SamplePackage implements IntegrationInterface
{
    public function define(ContainerInterface $container, Configuration $config)
    {
        return $container->set(Sample::class, new Sample('Blueprint'));
    }
}

// bin/app.php

use Acme\Packages\SamplePackage;
use Rougin\Slytherin\Container\Container;

// ...

// Add the specified integration (or package) to the container ---
$container = new Container;

$container->addPackage(new SamplePackage);
// ---------------------------------------------------------------

// Set the container to the console application ---
$app->setContainer($container);
// ------------------------------------------------

With the above-mentioned integration, for any command that uses the Sample class will get the text value as the $name property:

namespace Acme\Commands;

use Acme\Sample;
use Rougin\Blueprint\Command;

class TextCommand extends Command
{
    protected $name = 'text';

    protected $description = 'Shows a sample text';

    protected $sample;

    public function __construct(Sample $sample)
    {
        $this->sample = $sample;
    }

    public function run()
    {
        $this->showText('Hello, ' . $this->sample->getName() . '!');

        return self::RETURN_SUCCESS;
    }
}

$ php bin/app.php text

Hello, Blueprint!

Changelog

Please see CHANGELOG for more recent changes.

Contributing

See CONTRIBUTING on how to contribute.

License

The MIT License (MIT). Please see LICENSE for more information.