Setting Up Time Based Scripts to Run using Crontab
MODX Cloud supports cron functionality on a per-cloud basis. Cron is managed from the command line, not from the dashboard, and therefore requires a little bit of knowledge about how to log in, and run basic commands.
Here's a primer on what cron is and how to use it.
Cron is managed with the crontab command. After logging into a cloud via SSH, typing crontab -e loads up the vi editor to allow you to edit the contents of your crontab. There are lots of resources to help you get up to speed with using vi, if you're not already familiar with it. The ultra-short version: hit the i key to get into "insert mode" where you can edit text; hit the Esc key to get out of insert mode; type :wq (colon, w, q) to save and quit. On saving, your crontab will be updated and changes will take effect within one to five minutes.
Any command that you can run from the command line can be placed into your crontab. This includes calling shell scripts, mysql, PHP scripts and so on. Paths in your crontab are relative to your home directory. If you're not sure if cron is running your command, make sure it runs from the command line first.
Using Crontab with MODX
If you wish to run MODX or a PHP script that includes MODX from cron, it's easy! Let's take a look at a simple example. Every minute of every day, I want MODX to log something. This is what I put into my crontab:
* * * * * php /www/mycron.php
Each line has five time-and-date fields, followed by a command, followed by a newline character ('\n'). The fields are separated by spaces. The five time-and-date fields cannot contain spaces. The five time-and-date fields are as follows: minute (0-59), hour (0-23, 0 = midnight), day (1-31), month (1-12), weekday (0-6, 0 = Sunday). Asterisks mean every increment of every option.
Crontab in MODX Cloud currently only works with a single space between each crontab time entry value. Remove any extra spaces or tabs you may copied from other servers.
The PHP script that cron is going to run (mycron.php in your www directory) looks like this:
<?php require_once dirname(__FILE__) . '/config.core.php'; require_once MODX_CORE_PATH.'model/modx/modx.class.php'; $modx = new modX(); $modx->initialize('web'); $modx->log(modX::LOG_LEVEL_ERROR, 'cron time! ' . time());
If you look at MODX's log file (located in
www/core/cache/logs/error.log) in a text editor, you'll note there is an entry logged each minute by this cron.
Please note that after you save your crontab, changes will only be executed after 5 minutes when an update script is ran. Please wait 5 minutes after updating your crontab before reporting an issue.
Don't hesitate to contact us should you have any further questions about cron.
Example: Use a Shell Script to Retrieve a CSV File Twice Daily
Assume you need to retrieve a CSV file at 5AM (before business opens) and 8PM (after all orders are shipped) every day to update inventory on a site. In your web root—so it will be backed up with your MODX site—create the following script, called
cron.sh. Change the URL to your source location of course:
#!/bin/ash wget -O /www/file.tmp https://www.example.com/obscure/path/source.csv if [[ $? -ne 0 ]]; then echo "wget failed" exit 1; fi mv /www/file.tmp /www/import.csv
Now, update your crontab to the following entry, per the instructions above:
* 5,20 * * * www/cron.sh
Assuming the source server is reachable and functioning, every day at 5AM AND 8PM, you should see a new
import.csv file created in your webroot. Use whatever logic or functions to process then remove this file in your application as needed.
It’s probaby a good idea to move this to a more secure non-web-accessible location, requiring changes to the the paths in the shell script, crontab and NGINX web rules to lock this down further, but this gives you the basics to remotely retrieve your data file from a public web location.