Include a PHP file passing it all API variables and optionally your own specified variables
This is the same as PHP’s include()
function except for the following:
- It receives all API variables and optionally your custom variables
- If your filename is not absolute, it doesn’t look in PHP’s include path, only in the current dir.
- It only allows including files that are part of the PW installation: templates, core modules or site modules
- It will assume a “.php” extension if filename has no extension.
Note this function produces direct output. To retrieve output as a return value, use the
$files->render()
function instead.
Usage
// basic usage
$bool = $files->include(string $filename);
// usage with all arguments
$bool = $files->include(string $filename, array $vars = [], array $options = []);
Arguments
Name | Type(s) | Description |
---|---|---|
filename | string | Filename to include |
vars (optional) | array | Optional variables you want to hand to the include (associative array) |
options (optional) | array | Array of options to modify behavior:
|
Return value
bool
Always returns true
Exceptions
Method can throw exceptions on error:
WireException
- if file doesn’t exist or is not allowed
Hooking $files->include(…)
You can add your own hook events that are executed either before or after the $files
method is executed. Examples of both are included below. A good place for hook code such as this is in your /site/ready.php file.
Hooking before
The 'before' hooks are called immediately before each $files
method call is executed. This type of hook is especially useful for modifying arguments before they are sent to the method.
$this->addHookBefore('WireFileTools::include', function(HookEvent $event) {
// Get the object the event occurred on, if needed
$files = $event->object;
// Get values of arguments sent to hook (and optionally modify them)
$filename = $event->arguments(0);
$vars = $event->arguments(1);
$options = $event->arguments(2);
/* Your code here, perhaps modifying arguments */
// Populate back arguments (if you have modified them)
$event->arguments(0, $filename);
$event->arguments(1, $vars);
$event->arguments(2, $options);
});
Hooking after
The 'after' hooks are called immediately after each $files
method call is executed. This type of hook is especially useful for modifying the value that was returned by the method call.
$this->addHookAfter('WireFileTools::include', function(HookEvent $event) {
// Get the object the event occurred on, if needed
$files = $event->object;
// An 'after' hook can retrieve and/or modify the return value
$return = $event->return;
// Get values of arguments sent to hook (if needed)
$filename = $event->arguments(0);
$vars = $event->arguments(1);
$options = $event->arguments(2);
/* Your code here, perhaps modifying the return value */
// Populate back return value, if you have modified it
$event->return = $return;
});
API reference based on ProcessWire core version 3.0.236