Tasks

Automating work in the background for you.

A task acts a bit like a hook, except that instead of a system event triggering your code to run, the code is run at a set interval. Tasks rely on a user having access to crontab on their server, which means that not everyone will be able to use tasks out of the box. We’ve tried to make the use of cron as small as possible, so even if you don’t have command-line access to it, there’s a chance that your server’s support team can set it up for you.

Using Tasks

To enable tasks, add the following line to your server’s crontab:

* * * * * curl --silent http://example.com/TRIGGER/tasks/tick > /dev/null 2>&1

You’ll want to replace example.com in the above code with your site’s URL. Once this line is in place, tasks should start running. Tasks will write a debug-level message to your log each time it fires if you have it enabled. It will also log messages about attempting to call tasks and whether or not it was capable.

Setting Up Tasks

To set up tasks for your add-on, first you’ll need to create the file that will hold your Tasks object. The file itself will be named after your add-on, for example, if your add-on is a folder called crank, your tasks file will be tasks.crank.php. This file goes into the root-level of your add-on’s folder.

Next, we need to create the object within the file. This object will extend Statamic’s Tasks object and must be named Tasks_ followed by the name of your add-on, like so:

class Tasks_crank extends Tasks
{

}

There is one required method to get tasks to work, although you’ll end up with two to create a task that does anything. Use the define method to define each of your add-on’s tasks as well as the interval (in minutes) that they should run at.

class Tasks_crank extends Tasks
{
   public function define()
   {
      // call the `kickIt` method every 5 minutes:
      $this->add(5, 'kickIt');
   }
}

As mentioned earlier, define is the only required method, but as you can see in the above example, without now defining the kickIt method, your Tasks file is a bit useless. So let’s create that method:

class Tasks_crank extends Tasks
{
   public function define()
   {
      // call the `kickIt` method every 5 minutes:
      $this->add(5, 'kickIt');
   }

   public function kickIt()
   {
      $this->cache->put('last_run', time());
      return true;
   }
}

Tasks are smart enough to only run the appropriate methods when its time to do so. Each task method is expected to return either true or false based upon whether whatever your tasks was supposed to do was successful. Returning true means that your task ran successfully. Returning false indicates that something went wrong. This will trigger a warning-message to be logged, and will cause Tasks to re-try running your task the next time tasks are run (about a minute later). So when you set a task to be every 5 minutes, it will try to run successfully every 5 minutes, running more frequently if needed.

The above example isn’t doing a whole lot of useful things, but remember that you can do virtually anything PHP can do in these methods. Also remember, your defined methods become available in $this->tasks within the other aspects of your add-on. So if you want to call kickIt within your crank add-on’s plugin file, you can do so like this:

$this->tasks->kickIt();