If you maintain a Grav plugin or theme, this post is your starting point for Grav 2.0. I know how a major version bump can look from the outside, especially when the headline features include a brand-new admin and a first-party API, so I wanted to get out in front of the obvious question: "what does this mean for my plugin?"

The short version is that most plugins will work on Grav 2.0 with little or no change at all. The plugin architecture, the event system, the configuration approach, the way blueprints are loaded and rendered, it's all the same. You're not staring down a rewrite. For a smaller group of plugins (the ones that go beyond standard configuration and ship their own admin UI), there's some real work to do, and we've put together a whole series of posts to walk you through it.

This post is the overview. It tells you what's stayed the same, what's changed, which bucket your plugin probably falls into, and where to go next.

What Hasn't Changed

The good news first, and there's a lot of it.

The plugin architecture is the same. Plugins still live in user/plugins/, still expose a PluginName.php class extending Grav's plugin base, still register against the same lifecycle events. If you can read your plugin's main class today, you can read it on 2.0.

The event system is unchanged. Same hooks, same signatures, same priorities. onPluginsInitialized, onPageInitialized, onTwigSiteVariables, the whole lineup, all wired up exactly as they were.

Blueprints work identically. The YAML schema you've been writing for a decade renders the same way. Standard form field types (text, textarea, select, toggle, array, list, file, the lot of them) all render correctly in Admin Next without you doing a thing. If your plugin's "admin presence" is just a configuration page driven by a blueprint, you don't even need to think about Admin Next. It just works.

Page processing hasn't changed. Pages are still resolved from the filesystem, Twig still renders them, modular pages still work the way they always have, and the page object's API surface is stable.

And of course, file-based everything is still the foundation. Plugins live in user/plugins/, their config in user/config/plugins/, no database, no build step, no surprises.

What Has Changed

There are real changes, and you should know what they are. None of them are particularly dramatic on their own, but together they're worth a careful read.

PHP 8.3+ as the Minimum

Grav 2.0 requires PHP 8.3 as a minimum and is tested through PHP 8.5+. If your plugin already runs cleanly on PHP 8.3, you're almost certainly fine.

The places I've seen plugins trip up are the usual suspects: deprecated PHP functions that were removed in the 8.x line, code that relied on lax type juggling that 8.x is stricter about, and built-in function signatures that changed (the str_* family, count() on non-countables, that kind of thing). If your plugin has been updated within the last year or two, the odds are very high you've already done most of this work.

Updated Core Libraries

We've moved Symfony, Twig, and the rest of the core library stack up to current versions. This is one of the things that pushed us toward calling this a 2.0 in the first place. Most plugins talk to these libraries through Grav's own API layer, and if that's you, you won't notice the upgrade at all.

If your plugin reaches into Symfony or Twig directly (custom Twig extensions doing exotic things, anything calling Symfony components without going through Grav), give those touchpoints a quick once-over against the new versions before you flag your plugin as 2.0 compatible.

Compatibility Flags (New)

Plugins and themes now declare which Grav major versions they've been tested against, via a new compatibility block in the blueprint. GPM reads these flags during install, and the migration tool uses them to decide whether to import a plugin into a 2.0 site automatically or hold it back for review.

Adding the flag is a one-line change to your blueprint, and for many plugins that's the entire 2.0 update. The full mechanics, including what GPM does when no flag is set and how the inference rules work, are covered in the next post in this series and in the Plugin Compatibility reference on the Learn site.

Admin Next Integration (If Applicable)

This one only matters if your plugin does something beyond standard blueprint configuration. Custom form field types, dedicated admin pages, panel widgets, menu bar items, that kind of thing.

If your plugin's admin contribution is a configuration page driven by a blueprint, you have nothing to do here. Admin Next renders standard blueprints natively. The work only kicks in for the plugins that go further, and the deep-dive posts later in this series cover each integration type with worked examples and reference plugins to copy from.

The Three Tiers of Plugin Compatibility

To make this easier to reason about, I've been thinking about plugins in three tiers depending on how much work the 2.0 transition involves. Most of you will land squarely in Tier 1.

Tier 1: Works Out of the Box

These are the plugins with standard blueprint-driven configuration, which use Grav's public API the way it's documented, and which don't ship any custom admin UI. The vast majority of plugins fall here.

What you need to do: test on PHP 8.3+, add the compatibility flag to your blueprint, and fix any deprecation notices that come up. That's it. For a lot of plugins this is a five-minute job.

Tier 2: Minor Updates Needed

These are the plugins that touch Symfony or Twig APIs directly, or that have lingering PHP 8.3+ compatibility issues. Still no Admin Next work, just a little bit of code maintenance.

What you need to do: update deprecated calls, test against the new library versions, and add the compatibility flag once you're confident it works.

Tier 3: Admin Next Integration Needed

These are the plugins with custom form field types, dedicated admin sections, panel widgets, or menu bar items. The best public reference implementations here are the free, openly available git-sync and license-manager plugins, which anyone can clone from GitHub and read end-to-end. They're real shipping plugins, not toy demos, and they cover the most common integration patterns. If you happen to be a Grav Premium customer with access to AI Pro, AI Translate, Yeti Search Pro, or SEO Magic, those add a second layer of reference for more advanced patterns like AI-driven panels and full sidebar-driven admin sections.

What you need to do: rebuild your custom UI as Admin Next components. The good news is that the patterns are well documented, free reference implementations are a git clone away, and the grav-api-admin-next-integration Claude skill (more on that below) will walk Claude Code through the integration patterns alongside you.

The Developer Series Roadmap

This overview is the first post in a six-part developer series. Here's the full lineup:

1. This post: the overview, what's changed, and which tier your plugin falls into.
2. Compatibility Flags: the new blueprint system for declaring Grav version support, how GPM uses it, the inference rules when no flag is set, and exactly what you need to do.
3. API Integration for Plugins: how plugins extend and interact with the Grav API directly, including adding custom endpoints and consuming the API from inside a plugin. The companion reference on the Learn site is Plugin API Integration.
4. Admin Next: Custom Form Fields: building custom form field types as web components, with worked examples from license-manager (free) and the premium plugins.
5. Admin Next: Custom Pages: full admin sections with sidebar navigation, tabbed interfaces, and mixed blueprint/custom field layouts. git-sync is the open-source reference here, with Yeti Search Pro and SEO Magic as additional premium examples.
6. Admin Next: Panels & Menu Bar: the bottom-right pop-up panels and quick-link menu bar items, demonstrated by the premium AI Pro and AI Translate plugins.

Resources

A handful of places to point you at:

• The Grav API: Getting Started guide on the Learn site, which is the canonical reference for the API itself (endpoints, authentication, the request/response shape).
• The Plugin API Integration docs, covering how plugins extend the API with their own routes and how to call into it from plugin code.
• The Plugin Compatibility docs, which spell out the compatibility block, the GPM enforcement behavior, and the inference rules in full.
• The Admin Next Developer Documentation on the Learn site, which is the canonical reference for the Admin Next integration APIs.
• The free, openly available git-sync and license-manager plugins as the headline reference implementations: both are real, shipping plugins with non-trivial Admin Next integrations, and the source is a git clone away on GitHub.
• The Grav Premium plugins (AI Pro, AI Translate, Yeti Search Pro, SEO Magic) as additional reference implementations covering the more advanced integration patterns, available to anyone with a Premium license.
• The Grav Skills for Claude Code repository: a marketplace of Grav-specific Claude skills, including grav-api-integration and grav-api-admin-next-integration, which walk Claude Code (and other Claude-aware editors) through the integration patterns covered in this series. Useful both for upgrading existing plugins to 2.0 and for scaffolding new ones from scratch. Install with /plugin marketplace add getgrav/grav-skills.
• And as always, the Discord is the fastest place to get a hand from the development team and the wider community.

If you only do one thing after reading this, it's this: spin up a 2.0 test environment, install your plugin, click through the basics, and see what shakes out. For most plugins, that's the entire transition. Add the compatibility flag, ship an update, and you're done.

Thanks for everything you build on top of Grav. The plugin ecosystem is the single biggest reason Grav has stayed alive and useful for a decade, and your work continuing into 2.0 is what makes the whole release matter.

Andy

---