Last Modified: 31.10.2022
– process technique that permits you to launch arbitrary PHP functions (agents) with a preset frequency. Technically, agent - is an entry in a special table with the following data:
- which code is to be executed,
- when to execute,
- period of execution,
- how to set time for the next agent launch (strictly periodic or non-periodic agent).
The system automatically checks the agent's availability, requiring to be launched and executes it (if required) at the end of each page upload, after passing content to a browser.
How agent's availability was checked before the Main module version 20.5.0 release.
As each page starts loading (immediately before the event of OnPageStart), the system automatically checks if there is an agent that must be launched and, if necessary, executes it.
Note: Starting from the Main module version 20.5.0, agents and main events were moved to background jobs.
Time accuracy of the agent launching directly depends on the steadiness and density of the site traffic. Actual agent launch time is usually a little later than specified time of the agent. Moment of launch occurs when somebody has visited a site page.
If you need to arrange for launching of any PHP functions at a definitely preset time, you have to use the standard utility cron
available from most hosting providers.
In addition, resource intensive operations should not be assigned to agents, and there is a background launch option executed by cron.
In order for an agent to be executed at a set time, it must be registered in the system using the method of CAgent::AddAgent. An agent’s registration may be deleted using the function of CAgent::RemoveAgent.
If the agent function belongs to a module, this module will be automatically connected before the execution of such an agent function. Namely, the file /bitrix/modules/module ID/include.php will be connected. In this case, you have to make sure that the agent function will be available after the connection of this file.
If an agent function doesn't belong to any module, it must be located in the file /bitrix/php_interface/init.php. This file is automatically connected in the prologue.
The particularity of agent function creation is that the agent function must return a PHP code as function's return value that will be used during the next execution of this function.
List of agents, employed in the system is available at the Agents page (Settings > System Settings > Agents).
Historically, agents are called "periodic" and "non-periodic" which also can be named as "recurring" and "non-recurring".
The user interface within the admin panel for the agent settings likewise has remained the same:
Type of agent depends on the software developer who wrote the agent's code. This developer can create an agent that could repeat an infinite amount of times. Or only 2-3 times depending on set conditions. Example of agent function recurring infinitely:
Type of agent is defined by the method for calculating time of the next agent start: