Agents

Agents is the technology which allows running PHP functions (agents) at the specified time interval.

When a page starts execution (before the OnPageStart event) the system automatically checks for pending agents and executes them if required.

Note
The agent run time precision depends on the site traffic density and uniformity. If you need to precisely run any PHP function at the time specified, you should use the system cron utility, which is supplied by most of hosting providers.

To run the agent at the specified time, the calling code should register it in the system using the method CAgent::AddAgent. You can unregister the agent function by calling CAgent::RemoveAgent.

If the agent function is a member of a module, that module will be automatically included which involves including the file /bitrix/modules/module ID/include.php. If this is the case, you have to ensure that the agent function is available after the above mentioned file is included.

If the agent function is not a member of a module, it should be placed in the file /bitrix/php_interface/init.php. This file is automatically included in the prologue.

The following should be considered when creating agent functions.

A global object $USER of the CUser class is not available in the agent function. If you intend to use this object, place the following code prior to calling any of the CUser class methods:
```
global $USER;
if (!is_object($USER))
    $USER = new CUser;
```
As a return value, the agent function should return a PHP code that will be used at the next call to this function.

Example

<?
// add agent of the Statistics module
CAgent::AddAgent(
    "CStatistic::CleanUpStatistics_2();", // function name
    "statistic",                          // module ID
    "N",                                  // number of executions is not critical
    86400,                                // time out is 24 hours
    "07.04.2005 20:03:26",                // time of the first check
    "Y",                                  // agent is active
    "07.04.2005 20:03:26",                // time of the first execution
    30);
?>

<?
// add agent of the Techsupport module
CAgent::AddAgent(
    "CTicket::AutoClose();",  // function name
    "support",                // module ID
    "N",                      // number of executions is not critical
    86400,                    // time out is 24 hours
    "",                       // time of the first check; use current time
    "Y",                      // agent is active
    "",                       // time of the first execution; use current time
    30);
?>

<?
// add an agent which is not a member of any module
CAgent::AddAgent("My_Agent_Function();");
?>

<?
// file /bitrix/php_interface/init.php

function My_Agent_Function()
{
   // perform any action
   return "My_Agent_Function();";
}
?>

<?
// add an agent of my_module

CAgent::AddAgent(
   "CMyModule::Agent007(1)", 
   "my_module", 
   "Y", 
    86400);
?>

<?
// execute this agent 7 times, once per 24 hours, 
// and unregister it afterwards.

Class CMyModule
{
   function Agent007($cnt=1)
   {
      echo "Hello!";
      if($cnt>=7)
         return "";
      return "CMyModule::Agent007(".($cnt+1).")";
   }
}
?>

Agents

Example

See Also