michaels/mistletoe

Cron and Single Use Task Management for PHP.

v0.9.3 2017-05-18 13:58 UTC

This package is not auto-updated.

Last update: 2022-06-25 07:16:43 UTC


README

  • todo: Parse Annotated Classes
  • Separate processes (configurable)
  • Tests
  • documentation, repository

Mistletoe (PHP Cron Tasks)

Latest Version Software License Build Status Code Coverage Scrutinizer Code Quality Total Downloads

Because Task Management Should Feel Like Christmas...or at least not suck!

Mistletoe provides a super easy-to-use way to manage cron tasks for php. Simply use the human-readable, fluent builder to add tasks, point ONE cron task to the mt file, and watch the magic happen.

Basic Usage

In mistletoe.php

$planner = (new Mistletoe\TaskPlanner())
    ->add(\Some\Namespace\UpdateWhatever::class)->always()
    ->add('SomeOtherClass')->daily()->at('00:30')
    ->add(new Mistletoe\Command('gulp clean')->daily()->at('1:00')->onProductionOnly()
    ->add(function(){ echo "do something"; })->every5Minutes();

In your crontasks, simply add /path/to/bin/mt run:due to execute how ever often you want.

Includes Full Support For

  • Simplify ALL cronjobs into a single job
  • Environment detection and limiting (only run certain tasks in production)
  • Tasks may be console commands, classes, or callables
  • Fluent cron schedule builder
  • An included TaskRunner
  • Easy to create custom task runners
  • CLI application
  • Fully extensible
  • PSR and PHP The Right Way Compliant

Install

You can use mistletoe in one of three ways:

As a Phar (Best)

You may download a ready-to-use version of Box as a Phar:

As a Global Composer Install (Better)

This is probably the best way when you have other tools like phpunit and other tools installed in this way:

$ composer global require michaels/mistletoe --prefer-source

You may need to add composer's bin directory to your path.

As a Composer Dependency (Advanced)

You may also install Mistletoe as a dependency for your Composer managed project:

$ composer require chrismichaels84/mistletoe

(or)

{
    "require-dev": {
        "chrismichaels84/mistletoe": "~0.9"
    }
}

Be aware that using this approach requires additional configuration steps to prevent Mistletoe's own dependencies from colliding with your project's dependencies.

Usage

As a Command Line Tool

The easiest way to get setup is to create a mistletoe.php file to hold your cron tasks. This file simply returns an instance of Mistletoe\TaskPlanner all configured and ready to go.

$planner = (new Mistletoe\TaskPlanner())
    ->add(\Some\Namespace\UpdateWhatever::class)->always()
    ->add('SomeOtherClass')->daily()->at('00:30')
    ->add(new Mistletoe\Command('gulp clean')->daily()->at('1:00')->onProductionOnly()
    ->add(function(){ echo "do something"; })->every5Minutes();

From there, you just use the cli commands. Mistletoe assumes the default mistletoe.php is in the current working directory. You may specify a relative or absolute path to any file that returns a TaskPlanner instance.

For example:

  • mt list:all - assumes mistletoe.php is in this dir
  • mt list:all /full/path/to/file.php - will use the full path
  • mt list:all ../to/file.php - will use the relative path

Commands

  • list:all - Lists ALL the commands that are register with info about each
  • list:due - Lists only the command that are due at that moment with info about each
  • run:due - Runs whatever commands are due at that moment
  • run:all - Will force run EVERY command registered
  • run:task Full/Class/Path - Will run only that one task, due or not
  • help - Shows this guide

Options

If you set the verbosity level to "verbose" or higher, it will print extra information.

mt list:all -v

See http://symfony.com/doc/current/components/console/introduction.html#verbosity-levels for more information.

Setting up the TaskPlanner

The config file only need return an instance of TaskPlanner that has been configured. There are several methods that make setting it up easy. For more options, see Mistletoe\TaskPlanner.

Note: All that's required is at least on add() method

$planner = (new TaskPlanner())
    ->setTaskRunner(new CustomTaskRunner()) // Optional: Must implement Mistletoe\Contracts\TaskRunnerInterface
    ->setCurrentEnvironment('development') // Optional
    
    // Add a simple task to run every minute
    ->add('SomeClass')->always()

    // Add Tasks as Classes, Console Commands, or Callables
    ->add(SomeClass::class)->always()
    ->add(new Mistletoe\Command('curl http://google.com/')->always()
    ->add(function () { echo 'something' })->always()
    ->add(new CustomTask())->always() // implements RunnableInterface

    // Add Tasks in a Chain, also as class, command, or callable
    ->add(SomeClass::class)->always()->followedBy('SomeOtherClass')

    // Only run on certain environments
    ->add(SomeClass::class)->always()->onProductionOnly()
    ->add(SomeClass::class)->always()->onDevelopmentOnly()
    ->add(SomeClass::class)->always()->onEnvironment('SomethingCustom')

    // Give it a specific cron schedule
    ->add('SomeTask)->schedule('* 10 * 5 3')

    // Use the Fluent Builder to control scheduling
    ->add('SomeTask)->yearly()->onMonth(6)->onDay(16)
    ->add('SomeTask)->monthly()->onDay(21)
    ->add('SomeTask)->weekly()->onMonday()
    ->add('SomeTask')->daily()->at('1:00')
    ->add('SomeTask')->hourly()->atMinute(10)->andAtMinute(55)
    ->add('SomeTask)->every3Hours() // every{X}Hours()
    ->add('SomeTask)->every22Minutes()
    ->add('SomeTask)->daily()->atMidnight()j
    ->add('SomeTask)->daily()->atHour(7)->andAtHour(12)
    
    // And Mix and Match to your hearts content...
return $planner;

Change log

Please see CHANGELOG for more information what has changed recently.

Testing

$ composer test

Contributing

Please see CONTRIBUTING and CONDUCT for details.

Security

If you discover any security related issues, please email :author_email instead of using the issue tracker.

Credits

License

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