Filament Activitylog Laravel Package

Getting Started

• Install the package via Composer, publish its config and assets, and run any migrations it ships. The package centres on a log “entry page” with a context rail that reads properties.ip, properties.via and properties.agent.
• First place to look is the package config for logging.stamp_request. Set it to true to have those three context keys populated automatically for every entry, rather than stamping them by hand at each logging call.
• First use case: enable logging.stamp_request, emit a normal Laravel log entry from a web route, then open the entry page and confirm the context rail shows the client IP, request URI/via value and user agent. This is the fastest way to verify the new behaviour end to end.
• If the application sits behind a proxy or load balancer, configure trusted proxies before relying on the stamped IP. The package uses the client address to decide whether a request exists, so the address must be the real client address for the context to be useful.

Implementation Patterns

• Centralise request stamping. Turn on logging.stamp_request globally and remove manual properties.ip, properties.via and properties.agent assignments from individual log calls. This keeps every entry consistent, including entries written by third-party packages and framework internals.
• Override deliberately where needed. Caller-set keys are left alone, so you can still stamp a specific entry with a custom IP, via value or agent. Use this for impersonation flows, synthetic requests, or entries that need to describe a different context than the current HTTP request.
• Handle non-HTTP contexts explicitly. Queue workers, scheduled commands and other CLI processes have no client address, so the automatic stamping will not apply. In jobs and commands, set the relevant context keys yourself when the entry should carry request-like information, or accept that the entry describes a non-request context.
• Test with real request simulation. Because detection is based on the client address rather than runningInConsole(), tests can exercise the same path as production by making HTTP test requests with a known client IP. Assert that entries carry the expected ip, via and agent values. This avoids the SAPI-dependent behaviour that would otherwise make tests diverge from production.
• Integrate with existing logging discipline. Use the package as the single place where request context is attached. Keep application-level context—user ID, tenant, feature flag, correlation ID—as caller-set properties so it is preserved alongside the automatically stamped request keys.
• Use it for audit and support workflows. With request context stamped automatically, support and audit entries can be filtered by IP, route or user agent without relying on each developer remembering to add those fields. This is especially useful for entries emitted from middleware, exception handlers and package internals.

Gotchas and Tips

• Trusted proxies are critical. If the application is behind a load balancer, CDN or reverse proxy, the client address may be the proxy address unless TrustProxies is configured correctly. The stamped ip will then be misleading. Configure trusted proxies and verify the resolved client IP in the entry page.
• Caller-set keys win. The package leaves caller-provided properties.ip, properties.via and properties.agent untouched. That is useful for overrides, but it also means stale or copied context values can persist if you reuse a context array across entries. Be explicit when overriding.
• No request means no automatic stamping. CLI commands and queue workers do not have a client address, so logging.stamp_request will not fill the context rail. Do not expect queued entries to look like web entries unless you add the context manually.
• Tests can now exercise the production path. Since the decision is based on the client address, HTTP tests with a simulated request will trigger stamping. If a test asserts that context is absent, make sure the test request has no client address or disable the config for that test. Do not assume runningInConsole() will suppress stamping under the test runner.
• Clear config cache after changing the flag. If the application uses php artisan config:cache, run php artisan config:clear or rebuild the cache after changing logging.stamp_request. Otherwise the old value may remain active in production.
• Treat stamped data as potentially personal. IP addresses and user agents can be personal data. Review retention, access control and privacy obligations before enabling automatic stamping across all entries.
• Debugging missing context: check the config flag, confirm the request has a resolvable client address, confirm trusted proxies are correct, and check whether the caller is already setting one of the three keys. The entry page’s context rail is the quickest place to confirm what was actually stored.
• Extension points: the release adds a config-driven behaviour rather than a new public API. If custom context resolution is needed, prefer caller-set properties or application-level logging context rather than relying on undocumented internals.