BUGFIX Calling init() on CliController subclasses before triggering process(), to give the controller a chance to perform permission control etc.

MINOR Documentation for Task* classes

git-svn-id: svn://svn.silverstripe.com/silverstripe/open/modules/sapphire/trunk@67018 467b73ca-7a2a-4603-9d3b-597d59a354a9

cli/CliController.php

@@ -1,6 +1,11 @@
 <?php
 /**
- * Base class invoked from CLI rather than the webserver (Cron jobs, handling email bounces)
+ * Base class invoked from CLI rather than the webserver (Cron jobs, handling email bounces).
+ * You can call subclasses of CliController directly, which will trigger a
+ * call to {@link process()} on every sub-subclass. For instance, calling
+ * "sake DailyTask" from the commandline will call {@link process()} on every subclass
+ * of DailyTask.
+ * 
  * @package sapphire
  * @subpackage cron
  */
@@ -12,13 +17,17 @@ abstract class CliController extends Controller {
   
     function index() {
         foreach( ClassInfo::subclassesFor( $this->class ) as $subclass ) {
-        	echo $subclass;
+        	echo $subclass . "\n";
         
             $task = new $subclass();
+			$task->init();
             $task->process();
         }
     }
     
+	/**
+	 * Overload this method to contain the task logic.
+	 */
     function process() {}
 }  
 ?>

tasks/DailyTask.php

@@ -1,6 +1,11 @@
 <?php
 /**
- * Classes that must be run daily extend this class
+ * Classes that must be run daily extend this class.
+ * 
+ * Please note: Subclasses of this task aren't extecuted automatically,
+ * they need to be triggered by an external automation tool like unix cron.
+ * See {@link ScheduledTask} for details.
+ * 
  * @todo Improve documentation
  * @package sapphire
  * @subpackage cron

tasks/HourlyTask.php

@@ -1,12 +1,11 @@
 <?php
-
-/**
- * @package sapphire
- * @subpackage cron
- */
-
 /**
  * Classes that must be run hourly extend this class
+ * 
+ * Please note: Subclasses of this task aren't extecuted automatically,
+ * they need to be triggered by an external automation tool like unix cron.
+ * See {@link ScheduledTask} for details.
+ * 
  * @package sapphire
  * @subpackage cron
  */

tasks/MonthlyTask.php

@@ -1,6 +1,11 @@
 <?php
 /**
  * Classes that must be run monthly extend this class
+ * 
+ * Please note: Subclasses of this task aren't extecuted automatically,
+ * they need to be triggered by an external automation tool like unix cron.
+ * See {@link ScheduledTask} for details.
+ * 
  * @package sapphire
  * @subpackage cron
  */

tasks/ScheduledTask.php

@@ -1,6 +1,22 @@
 <?php
 /**
- * Abstract task representing scheudled tasks
+ * Abstract task representing scheudled tasks.
+ * You can use the different subclasses {@link HourlyTask}, {@link DailyTask},
+ * {@link WeeklyTask} to determine when a task should be run,
+ * and use automation tools such as unix cron to trigger them.
+ * 
+ * Example Cron:
+ * <code>
+ * # HourlyTask (every hour at 25 minutes past)
+ * 25 * * * *  www-data /my/webroot/sapphire/cli-script.php /DailyTask > /var/log/silverstripe_dailytask.log
+ * 
+ * # DailyTask (every day at 6:25am)
+ * 25 6 * * *  www-data /my/webroot/sapphire/cli-script.php /DailyTask > /var/log/silverstripe_dailytask.log
+ * 
+ * # WeelkyTask (every Monday at 6:25am)
+ * 25 6 1 * *  www-data /my/webroot/sapphire/cli-script.php /WeeklyTask > /var/log/silverstripe_weeklytask.log
+ * </code>
+ * 
  * @todo Improve documentation
  * @package sapphire
  * @subpackage cron

tasks/WeeklyTask.php

@@ -1,6 +1,11 @@
 <?php
 /**
  * Classes that must be run weekly extend this class
+ * 
+ * Please note: Subclasses of this task aren't extecuted automatically,
+ * they need to be triggered by an external automation tool like unix cron.
+ * See {@link ScheduledTask} for details.
+ * 
  * @package sapphire
  * @subpackage cron
  */

tasks/YearlyTask.php

@@ -1,6 +1,11 @@
 <?php
 /**
  * Classes that must be run yearly extend this class
+ * 
+ * Please note: Subclasses of this task aren't extecuted automatically,
+ * they need to be triggered by an external automation tool like unix cron.
+ * See {@link ScheduledTask} for details.
+ * 
  * @package sapphire
  * @subpackage cron
  */