If you’ve found an error, spotted something missing, or feel a section could be clearer or better explained, we’d love to hear from you. Your feedback helps keep the documentation accurate and useful for everyone.
Please report issues or suggest improvements on GitHub. Community input is invaluable in making the docs stronger.
Not comfortable with GitHub? No problem — you can also get in touch with us directly via our contact form. We welcome all feedback.
Interceptors
Interceptors are a powerful new feature in Trongate v2 that allow you to execute code early in the request lifecycle, before the main controller processing begins. Think of interceptors as application-wide middleware that runs on every request, providing a clean way to implement cross-cutting concerns without modifying the core framework files.
Benefits of Using Interceptors
Request Monitoring and Logging
Interceptors are perfect for logging every request that comes into your application. You can track API usage, monitor performance, or create comprehensive audit trails without adding logging code to every controller method.
Authentication and Security Checks
Implement global authentication checks, API rate limiting, or security validations that need to run before any controller logic executes. This ensures consistent security across your entire application.
System Health and Maintenance
Use interceptors to check if your application is in maintenance mode, verify database connectivity, or perform other system health checks before processing user requests.
Configuring Interceptors
Interceptors are configured in your main configuration file (config/config.php). You define them as an associative array where the key is the module name and the value is the method to call:
Creating a Request Logging Interceptor
One of the most practical uses for interceptors is comprehensive request logging. This example shows how to create an endpoint listener that captures detailed information about every request to your application.
endpoint_listener table in your database. You can find the complete SQL schema at the end of this documentation page.
The Interceptor Controller
Create a new module called endpoint_listener with the following controller:
For the purposes of brevity, we haven't added any security to the code above. If you're planning on using a feature like the one described above on a live web application, you should add your own security protocols. This could include:
- Restricting access so that only users from your IP address can view and delete records
- Implementing authentication and authorization checks before displaying sensitive request data
- Adding rate limiting to prevent abuse of the logging system
- Sanitizing or filtering sensitive data (passwords, API keys, etc.) before storage
- Setting up regular log rotation or cleanup to manage database size and retention policies
Viewing the Logged Requests
The interceptor example includes a web interface for viewing captured requests. Create a view file called display_records.php in your endpoint_listener/views directory to display the logged data in a user-friendly format.
your-site.com/endpoint_listener in your browser. The interface includes features like expandable headers and payload data, plus a convenient "Clear Records" button for maintenance.
How the Interceptor Works
When configured in your config.php file, the record method runs automatically on every request. Here's what happens:
- Request Capture: The interceptor captures the full URL, HTTP method, IP address, and other request details
- Header Collection: All HTTP headers are collected and stored as JSON
- Payload Extraction: POST data, JSON payloads, and raw request bodies are captured
- Database Storage: All information is stored in the database with a timestamp
- Recursion Prevention: The interceptor skips logging its own requests to prevent infinite loops
Database Schema
To use this interceptor example, create the following table in your database:
Best Practices
Performance Considerations
Since interceptors run on every request, keep the code efficient. The example above is optimized for performance, but consider implementing cleanup routines to prevent the log table from growing too large.
Avoid Recursion
Always include logic to prevent your interceptor from logging requests to itself. The example shows how to skip logging when the URL contains the interceptor module name.
Data Privacy
Be mindful of what data you're logging. Consider filtering out sensitive information like passwords or API keys from headers and payloads before storing them.
Conclusion
Interceptors provide a clean and powerful way to implement application-wide functionality in Trongate v2. The request logging example demonstrates how you can capture comprehensive request data with minimal code, giving you valuable insights into your application's usage patterns and helping with debugging and monitoring.