# sfDoctrineCronManager plugin #
The `sfDoctrineCronManagerPlugin` provides backend administration capabilities for
cron jobs. This is useful if developers have limited access to the production server
but still need to schedule, modify, or run cron jobs without server access.
## Installation ##
* Install the plugin (via a package)
symfony plugin:install sfDoctrineCronManagerPlugin
* Install the plugin (via a Subversion checkout)
svn co http//svn.symfony-project.com/plugins/sfDoctrineCronManagerPlugin/trunk plugins/sfDoctrineCronManagerPlugin
* Activate the plugin in the `config/ProjectConfiguration.class.php`
[php]
class ProjectConfiguration extends sfProjectConfiguration
{
public function setup()
{
$this->enablePlugins(array(
'sfDoctrinePlugin',
'sfDoctrineCronManagerPlugin',
'...'
));
}
}
* Rebuild your model
symfony doctrine:build-model
symfony doctrine:build-sql
* Update you database tables by starting from scratch (it will delete all
the existing tables, then re-create them):
symfony doctrine:insert-sql
or do everything with one command
symfony doctrine-build-all-reload frontend
or you can just create the new tables by using the generated SQL
statements in `data/sql/schema.sql` for the sf_cron_manager_job table.
As another alternative, you can run
symfony doctrine:generate-migrations-diff
and use the resulting file to migrate an existing implementation.
* Enable the module in the `settings.yml` file for your backend application:
all:
.settings:
enabled_modules: [default, ..., sfCronManager]
* Clear your cache
symfony cc
* Finally, you must configure your server to call the new plugin each minute. This will run all other jobs in turn. To configure this, add the following to your crontab:
* * * * * php /path/to/symfony/project/symfony cron:go
## Features ##
* Configure cron jobs in a familiar manner, using standard cron syntax
* Take advantage of additional features not found in the cron package, described below
## Feature: Load Limits ##
Certain jobs are processor-intensive and can drag a server down. If cron blindly
continues to run these processes it has the potential to take the server down, or
make the user experience very poor. The ability to suppress a cron job based on the
current server load is an improvement beyond the capabilities of cron.
Set the limit as necessary within the job interface. This limit is numerical and
corresponds to a one-minute load given by the linux uptime command. If this limit is exceeded when
the job is due to run, it will be suppressed. Obviously, this could lead to the job
continually being suppressed and never running as a result. For this reason, we can set
a limit for how many times the job is suppressed.
## Feature: Maximum Suppressed Runs ##
This can be used to limit the number of consecutive times a job is suppressed. This is set,
by default, to a value of three. If the job is suppressed more than three times, the job will be run
regardless, and the current suppressed run counter will be reset to zero. This ensures that the job
cannot be permanently suppressed, but allows us to schedule non-critical jobs to off-peak periods.
## Feature: Run If Missed ##
If the server goes down for an extended period of time, certain jobs may not run. Rather
than look through the cron commands and calculate which jobs need to be run by hand, this
setting will ensure that any job that was missed will be run automatically when the server
is again running normally. This can be done because each time a job runs, the next run time
is calculated and stored. Checking the next run time of each job allows this feature to
run missed jobs.
## Schedule a cron job ##
* Open your project's backend and visit /sfCronManager, then click the `New` link.
* Provide the following information:
* Title: A descriptive title for the job
* Active: A flag that turns the job on or off
* Schedule: The standard, cron notation schedule for the job. For details on the cron format, [go here](http://en.wikipedia.org/wiki/Cron)
* Command: The command to be run when the conditions of the schedule are met. This can be a unix command, a call to a symfony task, etc.
* Load Limit: Allows the job to be suppressed if the one-minute load on the server exceeds this threshold.
* Max. Suppressed Runs: If the run has been suppressed based on server load, this limit can be set to ignore that and force the job to run.
* Run if missed: If the job is missed due to server downtime, this flag can be set so that the job will run if it was missed for any reason.
* If the job will run at a future date, you may click the Run Now option in the Actions column when looking at the jobs list. This will allow you to test.
## Tasks ##
This plugin provides a task to review all jobs and run those that are due based on the current time. The cron:go task, configured
during installation, will run all jobs. If you happen to know the ID of the job you wish to run, which is simply the database ID of the
job record, you may run it directly using the command:
symfony cron:go [task_id]
## To Do ##
* Add L, W, and # special characters in Day of Month and Day of Week fields
* Allow a year or year range to be explicitly defined