Skip to main content

Log Template Customization

The System Events package uses a flexible template system to control the appearance of each log entry. You can define a custom template using environment variables or programmatically via code.

Default Log Template​

If no custom template is set, the following format is used by default:

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

This template outputs the timestamp, event name, and any arguments in JSON format.

Setting a Log Custom Template​

There are two ways to customize the template used by the FileSystemEventProcessor.

1. Via Environment Variable​

Set the CUSTOM_LOG_TEMPLATE environment variable in your .env file or bootstrap logic:

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

This template will automatically be applied the next time the processor is instantiated.

⚠️ This must be set before the FileSystemEventProcessor is created (e.g., at app bootstrap time).

2. Via Code​

You can set or override the template programmatically at runtime:

use DomainFlow\SystemEvents\Processor\FileSystemEventProcessor;

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

Adding Custom Placeholders​

You can inject custom placeholder values using the CUSTOM_LOG_PLACEHOLDERS environment variable.

Example​

CUSTOM_LOG_PLACEHOLDERS={"{{appVersion}}": "1.0.3", "{{env}}": "production"}

Then use them in your template:

CUSTOM_LOG_TEMPLATE=[{{timestamp}}] {{eventName}} [env={{env}}] v{{appVersion}} - {{args}}

These values will be merged into the template rendering logic along with the built-in ones.

📌 Custom placeholders must be provided as a valid JSON object where keys are placeholder strings (including the {{ }} braces).

Tips​

  • \n in environment values will automatically be converted to actual newlines by setTemplate().
  • Placeholders that are not defined will be left as-is in the log output.
  • Avoid using complex logic in templates—keep them simple and readable.

That’s it! You can now fully control the formatting of your event logs using either environment-based or programmatic templates.