AI blog · DotApp PHP Framework 2.0

Built-in events and database triggers in DotApp PHP Framework

The kernel already fires a small set of events on boot, routing, SQL, logging, and module lifecycle. You do not invent those names. You subscribe in module.listeners.php with Events::on and treat them as side effects — debug SQL, log a 404, notice that Shop finished initialize(). How the bus works (lowercase names, trigger() returns the first argument unchanged) is in Events and listeners. To watch every trigger in one place, subscribe to dotapp.catchall — that is the debug tap, not a business event. This article is the catalog: every PHP event the core actually triggers, plus ORM observe(), which is a different system.

Common mistakes

Rules that apply to every name

• Events::on and Events::trigger lowercase the name. DACore.login.before and dacore.login.before are the same bucket.
• Events::hasListener() does not lowercase. Kernel gates that call hasListener before trigger must see the exact stored key — always lowercase when you check.
• The listener signature is function ($result, ...$data). The first argument is whatever the kernel passed as $result. Returns are ignored.
• Exceptions abort later listeners. Wrap debug bodies in try/catch.
• dotapp.middleware is an alias of dotapp.router.resolve on register only.
• Every trigger() and triggerWithVeto() except dotapp.catchall itself first fires catchall. A throw there skips the named event.
• Listener returns on trigger() are ignored. The opt-in stop is triggerWithVeto() + Veto — How trigger with veto works.

Debug tap: dotapp.catchall

This is not a separate kernel site. DotApp::trigger() always runs it first (DotApp 2.0) so you can see every trigger in one listener. How the arguments are packed, the recursion guard, and a complete debug snippet: Events and listeners — catchall.

You will also see the rows below (router, SQL, dotapp.log, module lifecycle) plus every Shop name you fire. Do not persist or send email from this listener. If you use Logger::use(), skip dotapp.log or you recurse. A throw here skips the named event you were trying to debug.

Boot and modules

{name} is the module folder, then lowercased by trigger — Shop becomes dotapp.module.shop.init.end. dotapp.modules.loaded is the hook generated listeners already use: decide whether to claim GET / if nobody else did.

Do not subscribe to load_modules.override for tracing. The kernel skips modulesAutoLoader.php and the directory scan when that name has any listener. You would have to load every module yourself.

init.condition is a trap. The gate is hasListener('dotapp.module.' . $modulename . '.init.condition') with the folder spelling (Shop), while Events::on stores dotapp.module.shop.init.condition. Those strings do not match, so a normal subscription never runs. Override initializeCondition() on the module class instead. Details: module initialization.

Router

A 404 listener wins over Router::errorHandle(404, …). If you only want to log, do not send a body and exit — you would swallow the default 404 page. DACore registers a 404 listener only when hasListener('dotapp.router.resolve.404') is still false.

use Dotsystems\App\Parts\Events;
use Dotsystems\App\Parts\Logger;

Events::on('dotapp.router.resolve', function ($path, $method) {
    Logger::use()->warning('route', ['path' => $path, 'method' => $method]);
});
    

Database (the ones you were missing)

These are not MySQL CREATE TRIGGER objects. The PDO and mysqli drivers fire PHP events around every execute(). Same names on both drivers.

After a live execute, $execution_data also has affected_rows, insert_id, num_rows, and (mysqli) result. A cache hit still fires execute.success, but the success callback receives an empty execution bag — AIRULES already warns about that. If there is no error callback, a failed prepare throws instead of firing execute.error.

Events::on('dotapp.databaser.execute', function ($data) {
    Logger::use()->warning('sql', [
        'query' => $data['query'] ?? '',
        'bindings' => $data['bindings'] ?? [],
    ]);
});

Events::on('dotapp.databaser.execute.error', function ($error, $data) {
    Logger::use()->error('sql failed', [
        'error' => $error,
        'query' => $data['query'] ?? '',
    ]);
});
    

That is the debug hook. Keep it off in production or you will write one log line per query. CRUD itself still uses DB::module('RAW') callbacks — How to use the database.

ORM observe() — not Events

Optional DB::module('ORM') entities have observe($event, callable) on that instance. Names: creating, saving, updating, saved, created, updated, deleting, deleted. The callback receives the entity. Nothing is published on the Events bus. Another module cannot listen unless you also Events::trigger yourself.

Logger and CSRF

dotapp.log is useful to tee messages into another sink. Do not log from that listener with the same Logger::use() without a guard — you can recurse.

The CSRF name is a replacement hook, not a trace point. If any listener exists, crcCheck() skips the built-in token check and returns whatever trigger returns (the Request object, which is truthy). MUST NOT subscribe for debugging. You would disable CSRF.

Not PHP Events

• Browser boot: dotapp-register (early) and dotapp (DOM ready). That is dotapp.js, not this bus.
• Route ->before() / named Middleware — middleware.
• Your own shop.item.saved — you trigger those. The kernel does not.
• DACore names (dacore.login.before, page render, permissions refresh) — catalogued in the DACore article How DACore built-in events work when that section is on.