Janitor guide
The Janitor module allows an app to program tasks to be executed periodically.
Last updated
Was this helpful?
version 1.x beta
The Janitor module allows an app to program tasks to be executed periodically.
Last updated
Was this helpful?
In many cases you'll need some sort of mechanism to automatically execute tasks with certain periodicity, at certain times of the day, every few days or every few minutes. The module is designed to do exactly that.
Some examples of the kind of tasks you might want to automate with are:
Maintenance tasks, like optimizing a database periodically.
Batch processes, like gathering all the invoices at the end of the day to generate daily reports.
Database purges, like removing old data from a database to avoid cluttering it.
Cache flushes, like periodically clearing certain cached data.
Buffer commits, like committing data stored in a shared memory buffer to a database for persistence.
Janitor uses the cherrycake_janitor_log database table to store information about the executed tasks.
You can create the Janitor table in your database by importing the
janitor.sqlfile you'll find in the , under theinstall/databasedirectory.
To set up a task to be executed by the module, you first create a new class that extends the core class.
Imagine we wanted to create a task to update the IMDB rating of the movies in the database every day. To do so, we would create the file src/JanitorTaskMoviesUpdateImdbRating.class.php like this:
There are also other execution periodicities you can use:
JANITORTASK_EXECUTION_PERIODICITY_EACH_SECONDS The task will be executed every specified seconds. Seconds are specified in periodicityEachSeconds config key.
JANITORTASK_EXECUTION_PERIODICITY_MINUTES The task will be executed on the given minutes of each hour. Desired minutes are specified as an array in the periodicityMinutes config key. For example: [0, 15, 30, 45]
JANITORTASK_EXECUTION_PERIODICITY_HOURS The task will be executed on the given hours of each day. Desired hours/minute are specified as an array in the periodicityHours config key in the syntax ["hour:minute", ...] For example: ["00:00", "10:45", "20:15"]
JANITORTASK_EXECUTION_PERIODICITY_DAYSOFMONTH The task will be executed on the given days of each month. Desired days/hour/minute are specified as an array in the periodicityDaysOfMonth config key in the syntax ["day@hour:minute", ...] For example: ["1@12:00", "15@18:30", "20@00:00"]
JANITORTASK_EXECUTION_PERIODICITY_ALWAYS The task will be executed every time Janitor run is called.
JANITORTASK_EXECUTION_PERIODICITY_ONLY_MANUAL The task can only be executed when calling the Janitor run process with an specific task parameter.
In our example, the config/Janitor.config.php would look like this:
Cherrycake itself sets up by default the following core Janitor tasks:
In Linux, you would set up the Janitor cron job by editing your crontab with the command:
And adding a line like this:
The Janitor logs all its activity on the cherrycake_janitor_log, so you can check there to see what's happening in real time.
In the config property, we set the executionPeriodicity key to , and the periodicityHours to ["00:00"]. This will cause this task to run once at each one of the times specified in the periodicityHours array. In this case, at midnight precisely.
With , you can specify more times for tasks to be executed more than once a day. For example, if you set periodicityHours to ["00:00", "12:00"], the task will be executed every day at midnight and at noon.
In our task class, the run method is the one that will be executed when the task is due, so it's where you should put your task code. Like in our example, if you need to work with core or app modules there, use or .
Just like you see on the example above, the run method must return an array containing at least one element, being one of the available constants. You can add a second element containing a description of the task execution result.
The last step to having your Janitor tasks automatically executed, is creating the config/Janitor.config.php file and adding them to the configuration key.
JanitorTaskJanitorPurge Performs maintenance tasks related to the module itself, like purging old log items from the database.
JanitorTaskSystemLogPurge Performs maintenance tasks related to the module, like purging old log items from the database.
JanitorTaskSystemLogCommit Commits the events stored in the cache shared memory to the database for persistence and for optimal performance.
JanitorTaskSessionPurge Performs maintenance tasks related to the module, like purging old sessions.
JanitorTaskStatsCommit Commits the events stored in the cache shared memory to the database for persistence and for optimal performance.
JanitorTaskLogCommit Commits the events stored in the cache shared memory to the database for persistence and for optimal performance.
To let do its job, the named janitorRun must be executed every minute automatically by the operating system in the server. This is usually done by setting up a cron job in Linux that does it by using the Cherrycake .
If you've not used the to build your project, take a look at the section to learn how to call CLI actions from the Linux command line.
When using the to run your Cherrycake app, this cron job is already set up and running.
You can also execute the janitorStatus , which will show you the current status of all the tasks in your app, plus information about the last time they were executed. It looks like this: