1. Features
2. Requirements
3. Usage

This extension is a helper class for running actions. It makes controller actions reusable within different contexts.

Features ¶

• Run controller actions as background tasks
• Configure cron jobs
• 'Touch' urls at remote/local servers.
• Run preconfigured batchjobs or php scripts
• Use builtin Http client for simple GET and POST requests (since v1.1)
• Interval filter for controller actions (since v1.1)

Requirements ¶

• Developed with Yii 1.1.7

• When using 'touchUrlExt' (see below) you have to install the extension ehttpclient

Usage ¶

1. Extract the files under .../protected/extensions.
2. Import the component in the top of controller file, where you are using ERunActions:

Yii::import('ext.runactions.components.ERunActions');

class MyController extends CController {
...

This is only a quick overview of the usage. I don't list all configurable properties or methods here. Please take a look at the comments in the code of ERunActions.php

1. 'Touch' a url

Use this static methods to start processes at a remote or the own webserver. A request to the url will be sent, but not waiting for a response.

ERunActions::touchUrl($url,$postData=null,$contentType=null);

uses a simple built in httpclient (fsockopen).

ERunActions::touchUrlExt($url,$postData=null,$contentType=null,$httpClientConfig=array());

uses the extension EHttpClient, if you need support for redirect, proxies, certificates ...

NOTE:

• touchUrl only works with absolute urls
• Since v1.1 touchUrl works with https too

2. Run a controller action

Similar to CController.forward but with the possibility to suppress output with logging output, skip filters and/or before-afterAction.

ERunActions::runAction($route,$params=array(),$ignoreFilters=true,$ignoreBeforeAfterAction=true,$logOutput=false,$silent=false);

The 'route' is the route to the controller including the action. $params will be added as query params.

You can configure to ignore filters, before and afterAction of the controller, only log the output of the controller if $silent and $logOutput is set to true.

If both $ignoreFilters and $ignoreBeforeAfterAction are set to false, this will be the same as when using the method CController.forward.

3. Run a php script

This is a simple method that includes a script and extract the params as variable. The include file has to be located in runaction/config by default.

ERunActions::runScript($scriptName,$params=array(),$scriptPath=null)

4. Run a controller action as a background task

Use this if you have implemented time-consuming controller actions and the user has not to wait until finished. For example:

• importing data
• sending newsletter mails or mails with large attachments
• cleanup (db-) processes like flush ...

public function actionTimeConsumingProcess()
	{
		if (ERunActions::runBackground())
		{
		   //do all the stuff that should work in background
		   //mail->send() ....
		}
		else
		{
			//this code will be executed immediately
			//echo 'Time-consuming process has been started'
			//user->setFlash ...render ... redirect,
		}
	}

5. Run preconfigured actions as batchjob

Run the config script 'cron.php' from runactions/config

$this->widget('ext.runactions.ERunActions');

The cron.php should return a batch config array(actiontype => configarray). There are 4 actiontypes (see methods from above) available

• ERunActions::TYPE_ACTION
• ERunActions::TYPE_SCRIPT
• ERunActions::TYPE_TOUCH, ERunActions::TYPE_TOUCHEXT

For example:

return array(
   //execute ImportController actionRun ignoring filters and before- afterAction of the controller
    ERunActions::TYPE_ACTION  => array('route' => '/import/run'),
    ...
    
   //run the php file runaction/config/afterimport.php to do something with the imported data
    ERunActions::TYPE_SCRIPT  => array('script' => 'afterimport'),
    ...
    
   //inform another server that the process is finished
   ERunActions::TYPE_TOUCH => array('url'=>'http://example.com/processfinished');
);

You can override the configure the properties of the widget in the config of the action.

Run the config script 'runactions/config/myscript.php'

$this->widget('ext.runactions.ERunActions',
              'config'=>'myscript',
              'ignoreBeforeAfterAction' => true,
              'interval' => 3600,
              'allowedIps' => array('127.0.0.1'),
);

Content of 'myscript.php'

return array(
    ...
    
    ERunActions::TYPE_ACTION  => array('route' => '/cache/flush'
                                       'ignoreBeforeAfterAction' => false,
									   ),
    ...
);

6. Use the widget to expose a 'cron' controller action

Add the RunActionsController as 'cron' to the controllerMap in applications config/main.php

'controllerMap' => array(
   'cron' => 'ext.runactions.controllers.RunActionsController',
   ...
 ),

Now you can run the config script runactions/config/cron.php by calling

http://localhost/index.php/cron

or another script by

http://localhost/index.php/cron/run/config/myscript

or running in background so that a HTTP 200 OK will immediatly be returned

http://localhost/index.php/cron/touch/config/myscript

Configure the urls in your crontab by using 'wget'.

7. GET / POST requests

You can use the builtin Http client for simple requests:

echo ERunActions::httpGET('https://example.com',array('type'=>1,'key'=>123));

Will get the content from the url 'https://example.com/?type=1&key=123'

echo ERunActions::httpPOST('https://example.com',array('name'=>'unknown'),null,array('type'=>1,'key'=>123));

Will POST the form variable name='unknown' to the url 'https://example.com/?type=1&key=123

8. Interval filter

You can install the component 'ERunActionsIntervalFilter' (since v1.1) as a filter in a controller. See CController::filters()

public function filters()
 {
   return array(
		  ... 
                   array(
		        'ext.runactions.components.ERunActionsIntervalFilter + export, import',
		        'interval'=>15,  //seconds
                        'perClient'=>true, //default = false
                        //'httpErrorNo' => 403, (=default)
                        //'httpErrorMessage' => 'Forbidden',  (=default) 
		    ),
                   ....
	);

This will ensure, that the controller actions 'export' and 'import' can only be executed once withing the time interval of 15 seconds per client (= IP-Address) If the action is called more than once, a CHttpException will be thrown.

Note: There maybe has to be stored a lot of data in the global storage if you set 'perClient' to true.

9. Notes

a) In a controller action executed by 'runAction', 'touchUrl' or a batch script you can use the static methods

• ERunActions::isRunActionRequest()
• ERunActions::isBatchMode()
• ERunActions::isTouchActionRequest()

to switch behavior if the action is called in contexts above.

b) The widget catches all errors (even php errors) and uses Yii::log if an error occurs. So running cron jobs will not display internal errors.

Changelog

• v.1.1:
  • Modified and fixed bugs in ERunActionsHttpClient
  • Added support for https in ERunActionsHttpClient
  • New static methods httpGET,httpPOST
  • New interval filter ERunActionsIntervalFilter