Microscope for Craft CMS
Microscope Documentation
Microscope audits your PHP runtime, database, server, Craft configuration, content schema and Twig templates for the things that make a site slow — and for each one, tells you what it costs and how to fix it.
It is not a profiler and it does not sit in the request path. It runs on demand or on a schedule, writes a report, and gets out of the way. Microscope is free, and needs Craft CMS 5.3+ and PHP 8.2+.
Getting started
Install the plugin, then run a scan — there is nothing to configure first. Everything after that is optional: narrowing the catalogue, putting scans on a schedule, or wiring --fail-on into a deploy pipeline.
Installation
Requirements, Composer, and the optional PDF dependency.
Running a scan
From the control panel, from the CLI, and which one to trust for what.
The check catalogue
All twenty-seven checks, what each one looks at, and how to switch one off.
Template analysis
The eight Twig rules, what each one catches and how to fix it.
Scores and findings
How the score is calculated, and what a skipped check means.
Reports and PDFs
The print view, the server-rendered PDF, and why dompdf is optional.
Scheduled scans
Cron or control panel triggers, and email notifications.
Configuration
Every setting, what it does and what it defaults to.
Console commands
Scanning, exporting, listing, pruning and CI gates.
Permissions
Who can view reports, run scans and change the schedule.
Twig API
Surfacing the score and findings in your own templates.
Extending
Registering your own checks and cancelling scans.
Troubleshooting
Skipped checks, disagreeing SAPIs, missing PDFs and scans that never start.
What a scan produces
A scan runs every enabled check, collects their findings, and stores the result as a scan record. Each finding carries:
- What was measured — the observed value, and the recommended one.
- Why it costs something, in plain language rather than benchmark jargon.
- How to fix it, with the actual config snippets.
- How to verify the fix worked.
That last pair is the point of the plugin. Detection is the easy half; a report is only worth handing to a client, a host, or the developer who inherits the site next year if it ends with instructions.
The six areas
Checks are grouped into PHP, Database, Server, Craft, Content schema and Templates. Each area is scored independently, so a report tells you where to look before you have read a single finding. See the catalogue for what is in each one.
One thing worth knowing early
A scan run from the command line reads the CLI PHP configuration, which routinely differs from the one serving your site — different memory_limit, different max_execution_time, and very often no OPcache. Microscope records which SAPI each scan came from and the PHP findings say so, but for the PHP area specifically a scan started from the control panel describes the site more accurately. See Running a scan.