Skip to main content

Usage

The System Events package automatically logs all DomainFlow events to a file using a customizable format. Once the service provider is registered, no additional configuration is required for basic functionality.

Default Behavior in DomainFlow​

If you're using the DomainFlow Application class (core package) and have registered the SystemEventsServiceProvider, the system will:

  • Log all fired events automatically
  • Replay in-memory events captured before the service provider was registered
  • Use FileSystemEventProcessor with default settings
  • Output logs to a daily log file under a logs/ folder

Default Log Format​

The file writer uses a default template to format each log entry:

[{{timestamp}}] Event: {{eventName}}; Args: {{args}}

Available Placeholders​

Here’s a list of built-in placeholders you can use in your log templates:

PlaceholderDescription
{{timestamp}}Current datetime in Y-m-d H:i:s format
{{eventName}}Name of the dispatched event
{{args}}JSON-encoded arguments passed with the event

📝 You can inject your own placeholders via environment variables. Learn more in the Template Customization section.

Changing Log File Location​

By default, logs are written to a file like:

/your-project-root/logs/YYYY-MM-DD-system-events.log

To change the location, set the LOG_FILE_PATH environment variable:

LOG_FILE_PATH=/var/logs/domainflow/system-events.log

You can also configure it at runtime:

putenv('LOG_FILE_PATH=/tmp/my-events.log');
$processor = new FileSystemEventProcessor();

Customizing the Log Format​

To change the log format template at runtime, call:

$processor = new FileSystemEventProcessor();
$processor->setTemplate("[{{timestamp}}] {{eventName}} => {{args}}\n");

Or set it using an environment variable:

CUSTOM_LOG_TEMPLATE=[{{timestamp}}] {{eventName}} => {{args}}

🔧 The template is applied once during instantiation, so set the environment variable early (e.g., in your bootstrap file or .env file).

Manually Processing Events​

You can also use the processor manually, outside of the automatic DomainFlow event system:

use DomainFlow\SystemEvents\Processor\FileSystemEventProcessor;

$processor = new FileSystemEventProcessor();
$processor->processEvent('my.custom.event', ['foo' => 'bar']);

This is especially useful in CLI scripts or test utilities.