Event hooks

A file in the application's _events/ directory runs whenever the request reaches that moment - on every request, without touching the engine. The place to report an error to a tracker, log a slow query or an API that is down, or post-process the finished page.

file runs when its variables
_events/error.php an error is raised, whatever the error action does with it next $error, $file, $line
_events/sql.php db() ran a statement $sql as sent, $input, $vars, $result, $rows, $ms
_events/curl.php a remote fetch finished, well or not $url, $result (the HTTP code, 999 on a failure), $error, $ms
_events/output.php the page is about to be sent $output - change it to change the page

 

They are found the way callbacks are: the page's own directory first, then up to the application root, so a subdirectory can hear an event its own way. Here fragments/events/_events/sql.php keeps every statement in a list the page shows: 

<?php                                   // fragments/events/_events/sql.php

  $GLOBALS ['heard'] [] = $sql;

?>
PHP
fragments/events/events_1.php 		HTML
fragments/events/events_1.pad 		Result 
<?php

  $phone = db ( "field phone from staff where name = 'jim'" );
  $heard = $GLOBALS ['heard'] ?? [];

?>
 
<p>Jim's phone number is {$phone}</p>

<p>The sql hook heard:</p>
<ul>
  {heard}<li>{$heard}</li>{/heard}
</ul>

Jim's phone number is 555-4364

The sql hook heard:

  • select phone from staff where name = 'jim' limit 0,1

A hook runs in a scope of its own: the event's values are its variables, and the page's are reached through $GLOBALS. What it echoes is dropped. An error inside the error hook is logged and the original error goes its way; a query inside the sql hook does not call the hook again. 

<?php                                   // _events/output.php

  $output = str_replace ( '</body>', '<!-- served by PAD --></body>', $output );

?>

The output hook runs after tidying and before the page cache stores the page, so a cached page is served as the hook left it.