Author: COil Date: 2010-09-01 18:15:28 +0200 (Wed, 01 Sep 2010) New Revision: 30806
Modified: plugins/sfTaskLoggerPlugin/branches/1.2/README plugins/sfTaskLoggerPlugin/branches/1.2/config/schema.yml plugins/sfTaskLoggerPlugin/branches/1.2/lib/task/sfBaseTaskLoggerTask.class.php plugins/sfTaskLoggerPlugin/branches/1.2/lib/task/sfTaskLoggerPurgeRunningTask.class.php plugins/sfTaskLoggerPlugin/branches/1.2/lib/task/sfTaskLoggerSampleTask.class.php plugins/sfTaskLoggerPlugin/branches/1.2/package.xml Log: [sfTaskLoggerPlugin] * Updated sample and purge tasks * Moved "env" and "application" options at the base task level * Prepared package and README for 1.0.2 version * Fixed typos Modified: plugins/sfTaskLoggerPlugin/branches/1.2/README =================================================================== --- plugins/sfTaskLoggerPlugin/branches/1.2/README 2010-09-01 16:00:07 UTC (rev 30805) +++ plugins/sfTaskLoggerPlugin/branches/1.2/README 2010-09-01 16:15:28 UTC (rev 30806) @@ -1,26 +1,43 @@ sfTaskLoggerPlugin ------------------ -The **sfTaskLoggerPlugin** allow you to run tasks and store the results. Results -are stored in the database in a specific table and also in a log file. Each task +The **sfTaskLoggerPlugin** allows you to run custom tasks and store the results. +Results are stored in the database in a specific table and/or in a log file. Each task has its own log file, witch is stored in a specific directory depending on its -namespace and name. (`/log/tasks/:TASK_NAMESPACE/:TASK_NAME`). +namespace and name. (`/log/tasks/:TASK_NAMESPACE/:TASK_NAME`). It allows you +to a clean log history of all the CRON executed by your symfony project. The database record stores the following informations: - * Options of the task - * Arguments of the task - * An error code - * Start and end time - * A success flag - * The log file path - * Extra comments (for admin) + * Name of the task + * List of arguments of the task + * List of options of the task + * Count of processed records + * Count of NOT processed records + * Flag that tells if task is actually running + * Last record Id fully processed without error + * Process start time + * Process end time + * Flag that tells if task finished without error + * An error code for success or failure of the task + * The full console output of the task (optional) + * The log file path associated to the task + * Additional admin comments about the task and its results (may be modified in an admin generator module) +The plugin base task has several useful options: + + * `config`: The YAML config used by the plugin (explained in the next section) + * `check-running`: Check that the task is not currently running + * `only-processed`: Record into log or database only if there were things processed by the task + * `once-by-day`: Check that the task was not already executed once today + >**Note** >The plugin is both [Doctrine](http://www.doctrine-project.org) and >[Propel](http://propel.phpdb.org) friendly, it you are using Doctrine, the > `/lib/config/doctrine/schema.yml` will be used whereas using Propel -> `the /lib/config/schema.yml` will be used. +> `the /lib/config/schema.yml` will be used. (BUT,I am sorry but I didn't test +>the Propel version with the last 1.4 package, so feel free to report me issues +>so I can fix them quickly) Installation ============ @@ -34,6 +51,7 @@ * Build the new plugin table and associated models: $ symfony doctrine:build-all-reload +(or launch each "build" task individually) Or for Propel: @@ -41,6 +59,7 @@ >**Note** >At this point you should have +> > * A new table called `tl_tasks` in your database > * A new set of model classes in `lib/model/sfTaskLoggerPlugin` or > `lib/model/sfTaskLoggerPlugin` @@ -52,46 +71,92 @@ ============= The plugin comes with a *base* task class witch is named `sfBaseTaskLoggerTask` -Therefore your tasks must extend this one. Because there is no autoloading at -the task level. Therefore, one must include the base class manually: +Therefore your tasks must extend this one. Because there is no auto-loading at +the task level, one must include it manually: [php] - require_once(dirname(__FILE__). '/sfBaseTaskLoggerTask.class.php'); - + require_once(dirname(__FILE__). '/sfBaseTaskLoggerTask.class.php'); + >**Note** >Of course you will have to change this path depending on where is located your ->task. For example if it is located in the `/lib/task` folder of your project, ->the include directive should look like this: +>task. For example if it is located in the `/lib/task` folder of your project, use +>the following code. +> +>Generally you will want to extend all your tasks with a custom project task +>so all of them will benefit from its generic methods, arguments or options +>(thus, it must stay abstract). It would looks like this: [php] + /** + * This the base task for all tasks of myProject. + * + * @author COil + * @since 01/09/2010 + */ + require_once(dirname(__FILE__). '/../../plugins/sfTaskLoggerPlugin/lib/task/sfBaseTaskLoggerTask.class.php'); + abstract class mySuperBaseTask extends sfBaseTaskLoggerTask + { + /** + * This function is callable by all the project tasks. + */ + public function superFunction() + { + } + } + +Your final task should extends this custom task and look like this: + + [php] + /** + * This a custom task + * + * @author Vernet Loïc aka COil <qrf_coil]at[yahoo[dot]fr> + * @since 1.0.0 - 7 aug 2009 + */ + class sfMyTask extends mySuperBaseTask + { + // check the following section for functions to implement + } + +---- + +Moreover the plugin comes with a *default* YAML configuration file, this file allows +you to tell if you want to log into the database, a file or both: + + * Copy the `/plugins/sfTaskLoggerPlugin/config/plugin_sftl.yml` into the `config` folder + of your application. Then this file will be used. + + * Now, you can add your own configurations. (copy paste the default one and rename the + key of the configuration) You should keep the `default` one witch is the basic + configuration provided by the plugin. + + * To use a specific config for a task, pass a `config` option to the task. (--config=myConfig) + where `myConfig` is the key of your configuration. If the config is invalid + an alert will be raised. + Usage ===== - * 1 - Create a new class that extends the plugin base class: +In your task (like `sfMyTask` above): - [php] - class sfTaskLoggerSampleTask extends sfBaseTaskLoggerTask + * 1 - Implement the `configure()` method as you would do with a standard task: +(don't forget to call the parent method to include generic parameters and options) - * 2 - Implement the `configure()` method as you would do with a standart task: - [php] /** * Main task configuration. */ protected function configure() { + parent::configure(); + $this->addArguments(array( new sfCommandArgument('arg_1', sfCommandArgument::OPTIONAL, 'Test argument 1', 'arg_1_value'), new sfCommandArgument('arg_2', sfCommandArgument::OPTIONAL, 'Test argument 2', 'arg_2_value'), )); - $this->addOptions(array( - new sfCommandOption('env', null, sfCommandOption::PARAMETER_REQUIRED, 'Environment used', 'prod'), - new sfCommandOption('application', null, sfCommandOption::PARAMETER_REQUIRED, 'Application used', 'frontend'), - )); - $this->namespace = 'sf_task_logger'; $this->name = 'sample'; @@ -107,7 +172,8 @@ Now there are 2 specific methods to implement: - * 3 - `checkParameters()` + * 2 - `checkParameters()` +(don't forget to call the parent method too) [php] /** @@ -115,19 +181,21 @@ */ protected function checkParameters($arguments = array(), $options = array()) { - /* // Stupid example test + parent::checkParameters($arguments, $options); + if ($this->args['arg_1'] != 'arg_1_value') { throw new InvalidArgumentException('The value for argument 1 is not valid ! Check the help of the task.'); } - */ return true; } >**Note** ->This method can be usefull if you have advanced controls to do on task parameters or ->arguments. Just return `true` if you don't have to use it. +>This method can be useful if you have advanced controls to do on task parameters or +>arguments. Raise an `InvalidArgumentException` if there is at least an invalid parameter. +>Don't forget to call at first the parent function so generic parameters can be +>checked at the base task level. (or at your project base task level) * 4 - `doProcess()` @@ -135,7 +203,7 @@ /** * Main task process. */ - protected function doProcess() + protected function doProcess($arguments = array(), $options = array()) { try { @@ -153,10 +221,14 @@ >**Note** >This is the main method of your task process. `$this->task` is the database >object that will be saved. As you can see the `setOk()` and `setNOk` methods ->allow to set the flag of the record automatically depending on the success or ->failure of the task. +>allow to set the status flag automatically depending on the success or +>failure of the task. We also set a status code that will give more details +>than success or not about how ended the process. +> +>If you want to resume a batch process from a given id, you can use the `last_id_processed` +>field for this purpose. -If you want more control on the task process you can also re-implement the `execute()` +Finally, if you want more control on the task process you can also re-implement the `execute()` method of the base class witch is responsible for calling all others sub functions: [php] @@ -167,12 +239,18 @@ */ protected function execute($arguments = array(), $options = array()) { + $this->createContext(); + + $this->config = $this->checkAndGetConfig($options['config']); + + $this->checkConfig(); + $this->setParameters($arguments, $options); + $this->initDatabaseManager(); + $this->checkParameters($arguments, $options); - $this->initDatabaseManager(); - $this->initLogger(); $this->logStart(); @@ -186,25 +264,30 @@ ===== >**Note** ->The plugin is bundled with a sample task: `/lib/task/sfTaskLoggerSampleTask.class` ->witch can be run with the following command: +>The plugin is bundled with a sample task: `/lib/task/sfTaskLoggerSampleTask.class.php` +>witch can be run with the following command (replace "frontend" with a valid application +>name of your project and "dev" with a valid environment): > -> > ./symfony sf_task_logger:sample - +> > ./symfony task-logger:sample --application="frontend" --env="dev" +> +>And also with a task: `/lib/task/sfTaskLoggerPurgeRunningTask.class.php` +>to purge tasks who ended with a fatal error and witch stayed +>with the running flag to "ON": +> +> > ./symfony task-logger:purge --task="myProject:myTask" --application=backend --env="dev" + TODO ==== - * Include model function to get the list of already executed task - * Comment last last_id_processed usages - * Include Doctrine admin generator module + * Add an admin comment when purging batchs + * Include model functions to get the list of already executed task + * Include a Doctrine admin generator module * Test Propel version - * Add an exception for fields - * Do 1.3 and 1.4 versions - + Support ======= -Please report bugs on the symfony TRAC, i could also answer if you ask on the +Please report bugs on the symfony TRAC, I could also answer if you ask on the symfony mailing list or IRC. Changelog Modified: plugins/sfTaskLoggerPlugin/branches/1.2/config/schema.yml =================================================================== --- plugins/sfTaskLoggerPlugin/branches/1.2/config/schema.yml 2010-09-01 16:00:07 UTC (rev 30805) +++ plugins/sfTaskLoggerPlugin/branches/1.2/config/schema.yml 2010-09-01 16:15:28 UTC (rev 30806) @@ -7,13 +7,13 @@ task: { type: VARCHAR, size: '255', required: true, description: 'Name of the task' } arguments: { type: VARCHAR, size: '255', description: 'List of arguments' } options: { type: VARCHAR, size: '255', description: 'List of options' } - count_processed: { type: INTEGER, required: true, description: 'Count or processed records', default: 0 } + count_processed: { type: INTEGER, required: true, description: 'Count of processed records', default: 0 } count_not_processed: { type: INTEGER, required: true, description: 'Count of NOT processed records', default: 0 } - is_running: { type: BOOLEAN, required: true, default: '0', description: 'Task is actually runing?' } - last_id_processed: { type: INTEGER, description: 'Last Id fully processed' } + is_running: { type: BOOLEAN, required: true, default: '0', description: 'Flat that tells if task is actually runing' } + last_id_processed: { type: INTEGER, description: 'Last record Id fully processed without error' } started_at: { type: TIMESTAMP, description: 'Process start time' } ended_at: { type: TIMESTAMP, description: 'Process end time' } - is_ok: { type: BOOLEAN, required: true, default: '0', description: 'Process finished without error?' } + is_ok: { type: BOOLEAN, required: true, default: '0', description: 'Flag that tells if task finished without error' } error_code: { type: INTEGER, description: 'Error code for success or failure' } log: { type: LONGVARCHAR, description: 'The full console output of the task' } log_file: { type: VARCHAR, size: '255', description: 'Log file associated to the task' } Modified: plugins/sfTaskLoggerPlugin/branches/1.2/lib/task/sfBaseTaskLoggerTask.class.php =================================================================== --- plugins/sfTaskLoggerPlugin/branches/1.2/lib/task/sfBaseTaskLoggerTask.class.php 2010-09-01 16:00:07 UTC (rev 30805) +++ plugins/sfTaskLoggerPlugin/branches/1.2/lib/task/sfBaseTaskLoggerTask.class.php 2010-09-01 16:15:28 UTC (rev 30806) @@ -244,6 +244,11 @@ parent::configure(); $this->addOptions(array( + new sfCommandOption('env', null, sfCommandOption::PARAMETER_REQUIRED, 'The environment', 'dev'), + new sfCommandOption('application', null, sfCommandOption::PARAMETER_REQUIRED, 'Application used', 'frontend'), + )); + + $this->addOptions(array( new sfCommandOption('config', false, sfCommandOption::PARAMETER_REQUIRED, 'The yaml config used by the plugin', 'default'), new sfCommandOption('check-running', false, sfCommandOption::PARAMETER_OPTIONAL, 'Check that the same task is not currently running'), new sfCommandOption('only-processed', false, sfCommandOption::PARAMETER_OPTIONAL, 'Record into database only if there were things processed by the task.'), Modified: plugins/sfTaskLoggerPlugin/branches/1.2/lib/task/sfTaskLoggerPurgeRunningTask.class.php =================================================================== --- plugins/sfTaskLoggerPlugin/branches/1.2/lib/task/sfTaskLoggerPurgeRunningTask.class.php 2010-09-01 16:00:07 UTC (rev 30805) +++ plugins/sfTaskLoggerPlugin/branches/1.2/lib/task/sfTaskLoggerPurgeRunningTask.class.php 2010-09-01 16:15:28 UTC (rev 30806) @@ -16,11 +16,12 @@ protected function configure() { + parent::configure(); + $this->addOptions(array( - new sfCommandOption('env', null, sfCommandOption::PARAMETER_REQUIRED, 'The environment', 'dev'), new sfCommandOption('task', null, sfCommandOption::PARAMETER_REQUIRED, 'The task to purge'), )); - + $this->namespace = 'task-logger'; $this->name = 'purge'; $this->briefDescription = 'Purge running (or failed) tasks '; @@ -41,6 +42,9 @@ */ protected function checkParameters($arguments = array(), $options = array()) { + // check parent parameters + parent::checkParameters($arguments, $options); + return true; } @@ -53,7 +57,7 @@ { $purge_count = $this->purge($this->opts['task']); $this->task->setCountProcessed($purge_count); - $this->printAndLog('> '. $purge_count. ' task(s) updated.'); + $this->printAndLog('> '. $purge_count. ' record(s) updated.'); $this->task->setErrorCode(self::ERROR_CODE_SUCCESS); $this->setOk(); } Modified: plugins/sfTaskLoggerPlugin/branches/1.2/lib/task/sfTaskLoggerSampleTask.class.php =================================================================== --- plugins/sfTaskLoggerPlugin/branches/1.2/lib/task/sfTaskLoggerSampleTask.class.php 2010-09-01 16:00:07 UTC (rev 30805) +++ plugins/sfTaskLoggerPlugin/branches/1.2/lib/task/sfTaskLoggerSampleTask.class.php 2010-09-01 16:15:28 UTC (rev 30806) @@ -26,11 +26,6 @@ new sfCommandArgument('arg_2', sfCommandArgument::OPTIONAL, 'Test argument 2', 'arg_2_value'), )); - $this->addOptions(array( - new sfCommandOption('env', null, sfCommandOption::PARAMETER_REQUIRED, 'Environment used', 'prod'), - new sfCommandOption('application', null, sfCommandOption::PARAMETER_REQUIRED, 'Application used', 'frontend'), - )); - $this->namespace = 'task-logger'; $this->name = 'sample'; @@ -40,7 +35,7 @@ The task [task-logger:sample|INFO] doesn't do that much. It logs itself in the database and in the file system: - [./symfony task-logger:sample --env=prod|INFO] + [./symfony task-logger:sample --application=backend --env=prod|INFO] EOF; } @@ -49,14 +44,9 @@ */ protected function checkParameters($arguments = array(), $options = array()) { - // check-runing parameter - $parent = parent::checkParameters($arguments, $options); + // check parent parameters + parent::checkParameters($arguments, $options); - if ($parent === false) - { - return false; - } - // Stupid test if ($this->args['arg_1'] != 'arg_1_value') { Modified: plugins/sfTaskLoggerPlugin/branches/1.2/package.xml =================================================================== --- plugins/sfTaskLoggerPlugin/branches/1.2/package.xml 2010-09-01 16:00:07 UTC (rev 30805) +++ plugins/sfTaskLoggerPlugin/branches/1.2/package.xml 2010-09-01 16:15:28 UTC (rev 30806) @@ -3,13 +3,14 @@ <name>sfTaskLoggerPlugin</name> <channel>pear.symfony-project.com</channel> <summary> -The sfTaskLoggerPlugin allow you to run tasks and store the results in both database and log file. +The sfTaskLoggerPlugin allow you to run tasks and store the results in both database and/or a log file. </summary> <description> -The **sfTaskLoggerPlugin** allow you to run tasks and store the results. Results -are stored in the database in a specific table and also in a log file. Each task +The **sfTaskLoggerPlugin** allows you to run custom tasks and store the results. +Results are stored in the database in a specific table and/or in a log file. Each task has its own log file, witch is stored in a specific directory depending on its -namespace and name. (`/log/tasks/:TASK_NAMESPACE/:TASK_NAME`). +namespace and name. (`/log/tasks/:TASK_NAMESPACE/:TASK_NAME`). It allows you +to a clean log history of all the CRON executed by your symfony project. </description> <lead> <name>Vernet Loic</name> @@ -17,7 +18,7 @@ <email>[email protected]</email> <active>yes</active> </lead> - <date>2010-08-13</date> + <date>2010-09-01</date> <version> <release>1.0.2</release> <api>1.0.2</api> @@ -33,6 +34,8 @@ <dir name="config"> <file name="schema.yml" role="data" /> <dir name="doctrine"> + <file name="config_handlers.yml" role="data" /> + <file name="plugin_sftl.yml" role="data" /> <file name="schema.yml" role="data" /> </dir> </dir> @@ -76,13 +79,16 @@ <api>stable</api> </stability> <license uri="http://www.symfony-project.com/license";>MIT license</license> - <date>2010-08-10</date> + <date>2010-09-01</date> <license>MIT</license> <notes> + * Updated sample and purge tasks + * Moved "env" and "application" options at the base task level + * Updated package and README * Tempory logs stored into the log application of the project * Packages for symfony 1.1, 1.3 and 1.4 * Plugin has now a yaml config to configure if one must save the main output in a file, the database or both - * Add new field to store the id of the last fully processed record + * Added new field to store the id of the last fully processed record * New option that allows to log only if there were thing processed by the task * New option to check if the task was already run once in a day * New option to check if the task is already running -- You received this message because you are subscribed to the Google Groups "symfony SVN" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/symfony-svn?hl=en.
