locomotivemtl/charcoal-contrib-command

Charcoal contrib to handle dynamic cron scripts as commands.

0.1.5.1 2021-07-05 15:59 UTC

Requires

• php: >7.1
• locomotivemtl/charcoal-core: ~0.4
• monolog/monolog: >=1.24.0

Requires (Dev)

• php-coveralls/php-coveralls: ^2.2
• phpunit/phpunit: ^7.1
• squizlabs/php_codesniffer: ^3.5

MIT

• Locomotive

• charcoal

README

A charcoal contrib used to provide dynamic cron scripts, easily schedulable.

Table of Contents

• Installation
  • Dependencies
• Service Provider
  • Services
• Configuration
  • Defaults
• Usage
  • Creating a command class
    • Interface
    • Example
  • Back-end form
  • Available services
    • Method
    • Parameters
• Development
  • API Documentation
  • Development Dependencies
  • Coding Style
• Credits
• License

Installation

The preferred (and only supported) method is with Composer:

$ composer require locomotivemtl/charcoal-contrib-command

Including the modules

Just add the following module in your json configuration file:

"charcoal/command/command": {},

Setting a cron

Script command/process-queue is added with the command's module.

* * * * * /path/to/bin/php /path/to/vendor/bin/charcoal command/process-queue > /dev/null 2>&1

Dependencies

Required

• PHP 7.1+: PHP 7.3+ is recommended.
• Monolog/monolog: Official project logger.

PSR

--TBD--

Service Provider

The following services are provided with the use of charcoal-contrib-command

Services

• command/queue-stack: instance of Command\Service\CommandQueuer

Configuration

Every bit of configuration for the command contrib should be under the namespace command. Configurations allows the possibility to define options for the logger, such as the handlers, processors or formatters. All default configurations are visible in the Charcoal\Command\Logger\Config\CommandLoggerConfig class.

Defaults

    "command": {
        "logger": {
            "level": "debug",
            "active": true,
            "handlers": {
                "charcoal/command/logger/handler/charcoal": {
                    "model": "charcoal/command/log",
                    "formatter": {
                        "charcoal/command/logger/formatter/command": {}
                    }
                }
            }
        }
    }

The handlers should be resolvable by the logger handler generic factory. In the given example, we see Charcoal\Command\Logger\Handler\CharcoalHandler class. The options defined with the handler will be passed in the handler's constructor method.

The formatters should be resolvable by the logger formatter generic factory. In the given example, we see Charcoal\Command\Logger\Formatter\Command. The options defined with the formatter will be passed in the formatter's constructor method.

The class should be resolvable by the model factory. In the given example, we see Charcoal\Command\Log.

Usage

Creating a command class

A command class should extend the AbstractCommand class. You can use the setDependencies public method to access any dependencies you might need. The public method execute is called when everything is ready.

Interface

• public AbstractCommand::__invoke ( array $arguments ): Sets arguments, execute command and log results
• public AbstractCommand::setDependencies ( Container $container ): Allows to set any required dependencies
• protected AbstractCommand::log (): Called upon execution. Logs according to the given options.
• protected AbstractCommand::setSuccess ( boolean $success ): Defines if the scripts was executed successfully or not.
• abstract protected AbstractCommand::execute (): The actual command goes in there.

Example

namespace Charcoal\Cache\Command;

[...]

/**
 * Cache clearer command
 */
class ClearCommand extends AbstractCommand
{
    use CachePoolAwareTrait;

    /**
     * @param array $arguments
     */
    public function setDependencies(Container $container)
    {
        parent::setDependencies($container);
        $this->setCachePool($container['cache']);
    }

    /**
     * @return mixed|void
     */
    public function execute()
    {
        $success = $this->cachePool()->clear();
        $this->setSuccess($success);
    }
}

Back-end form

Use the CommandQueue model to queue a new command.

Key	Type	Example	Description
command	string	charcoal/cache/command/clear	Should be resolvable by the command factory. Hits Charcoal\Cache\Command\ClearCommand
arguments	array	{ "someProperty": "someValue" }	Any arguments that could be necessary for the executed command. Passed as argument to the command's constructor method.
issuedDate	DateTime	now	When was the command issued. This is done on preSave and shouldn't be altered.
processingDate	DateTime	now	When should the script be run?
processedDate	DateTime	now	When has the script been ran? Could differ from the processingDate depending on the cron frenquency and the time of execution of the command.
processed	boolean	false	Flag as to whether or not the command has been processed.

Available Service

Method

public QueueStack::enqueue ( array $data ) : QueueStack

Parameters

Array data

• command: Required. Resolvable Command class string.
• processingDate: Optional. Date when the command should be run. Accept any valid DateTime format or a DateTime object. Defaults to now
• arguments: Options. Array of arguments to be passed to the command constructor method.

Example

    $stack = $container['command/queue-stack'];
    $stack->enqueue([
        'command' => 'charcoal/cache/command/clear',
        'processingDate' => 'NOW +1 day'
    ]);

The default processing date is "now".

Development

To install the development environment:

$ composer install

To run the scripts (phplint, phpcs, and phpunit):

$ composer test

API Documentation

• The auto-generated phpDocumentor API documentation is available at:
  https://locomotivemtl.github.io/charcoal-contrib-command/docs/master/
• The auto-generated apigen API documentation is available at:
  https://codedoc.pub/locomotivemtl/charcoal-contrib-command/master/

Development Dependencies

• [php-coveralls/php-coveralls][phpcov]
• [phpunit/phpunit][phpunit]
• [squizlabs/php_codesniffer][phpcs]

Coding Style

The charcoal-contrib-command module follows the Charcoal coding-style:

• PSR-1
• PSR-2
• PSR-4, autoloading is therefore provided by Composer.
• phpDocumentor comments.
• phpcs.xml.dist and .editorconfig for coding standards.

Coding style validation / enforcement can be performed with composer phpcs. An auto-fixer is also available with composer phpcbf.

Credits

• Locomotive

License

Charcoal is licensed under the MIT license. See LICENSE for details.