Logger for Statamic

Logger for Statamic is a new addon on the Statamic Marketplace that writes and allows you to view human-friendly audit logs. Humans, like your site’s users. You know, the non-techy ones who don’t want to read a raw log file.

This isn’t an addon to replace Laravel’s logging (that logs all of your site’s errors and exceptions, if/when they occur), but one that is designed to report on user actions. Not in a creepy “we’re watching you” kinda way, but more like an audit trail of who did what and when.

Logger for Statamic:

• writes to its own logs, with a daily rotation and customisable retention period

• can track authenticated actions (where a user is logged in) and anonymous actions (such as a non-logged-in public visitor)

• renders log messages using Blade templates to make them super human-friendly

• can view logs within the Statamic Control Panel, with daily access, pagination, full raw message support and download capability

• has thorough and detailed documentation

• has a test suite

At Mity Digital, we had a client who wanted to be able see what their Control Panel-logged-in users were changing. So when an Entry was changed, or a new Asset was uploaded.

And this could be accomplished using two existing addons - however, the client also wanted to be able to do more advanced things such as logging Laravel events (around authentication), and even showing before and after details when a user’s role was changed.

Enter Logger for Statamic. And initially it was going to be basic and do just that.

But why write something so closed and rigid, especially given the scale of possible events within both the Statamic and Laravel ecosystem? This got me thinking about:

• excluding events

• how to best encapsulate logging behaviour for both reading and writing for easy re-usability

• how to add supplementary data to a log without re-writing the whole listener

• subscribing to app-specific events

So Logger for Statamic started to grow… and the build took a few days longer than initially planned, but has resulted in a far more flexible addon - one that I’m so proud and excited about. And yes, I know it’s about logging, but still I think it really is so very very cool.

Configurable and flexible, with Logger for Statamic:

• Logs can be retained for a given number of days using an .env variable.

• Excluding events can be defined in the configuration file

• Subscribing to events can extend a base Event Listener definition that helps handle the core inner workings

• Existing events can have a listener re-defined (if you want to keep it, but make a minor tweak, such as changing a layout or even adding supplementary data)

So yes, it is just logging… but it is logging with its foot flat to the floor.

OK, so this is neat, and I love the way this works. Out-of-the-box, Logger for Statamic subscribes to a stack of Statamic and Laravel events. But your app may have its own app-specific events - and this really showcases Logger for Statamic’s easy extensibility.

So what’s the process:

• create a new listener that extends Logger for Statamic’s base “EventListener” class

• subscribe to a specific event to be handled by your new listener

Yes, really it is that simple.

Logger for Statamic’s base class, \MityDigital\StatamicLogger\Abstracts\EventListener, is an abstract class that can prepare the event’s data, write to the log, and provide support for rendering the message in the Control Panel.

By extending this class, your listener only needs a few abstract functions be implemented - the absolute bare minimum.

1. one gets the data that should be logged,

2. one defines what view (Blade template) to use, and

3. one that provides a language-based verb based on the action of the event (such as “Created” for an EntryCreated event)

Within a Service Provider, you can then call Logger for Statamic’s subscribe method to define the event to listen for, and your listener to handle it.

That’s really it. Logger for Statamic will take care of the rest for you.

There’s a whole section about the base Event Listener and subscribing to your own events. Give these a read for full implementation details and code samples.

If you want to add more data to an existing listener, you can extend that listener and use the supplement method to define additional data to be added to the log. This keeps all of the existing behaviour intact, but just adds more data to the log output.

If you want to change the layout of an existing listener, extend it and use the view method to change the Blade template that will be loaded.

And of course, there’s documentation for extending existing events, supplementary data and customising views.

Subscribing and extending is basic… you can also do cool things like store temporary data for the life of the request to allow you to track changes of the before and after state - such as what a User’s role was before saving and after saving, allowing your log message to show this level of detail.

You guessed it… there is documentation for this specific advanced use case to help you see the entire process, including details on how Logger for Statamic can help you store data for the life of the request.

Within the Statamic Control Panel you can view daily log files, and each event will have its message rendered using its Blade template.

And the cracker feature here is that they’re paginated too!

If you have multiple authors, and lots of daily updates, these logs could get rather large. Pagination is a must.

The challenge here is that logs are written to sequentially, with the most recent log at the end of the file. So in reading back logs, pagination is working in reverse, with the most recent entry appearing first.

And if needed, the raw logs can be downloaded too.

Head over to the documentation and give it a good read. It covers configuration, excluding events, and full details on how to subscribe to your own events, and prepare your own listeners and Blade templates.

When you’re ready to go live, you’ll need a license from the Statamic Marketplace. You’re free to use Logger for Statamic without a license during your site’s build, but on production, will require a license.