Create Plugin

Create a Marko Plugin

This skill is the canonical specification for a Marko plugin. Do not inspect existing plugins in this project to infer structure — siblings may have drifted from spec. Copy the templates from assets/ verbatim, substitute placeholders, and stop.

A plugin is a class that intercepts the input or output of a public method on any other class — without replacing that class. Plugins are Marko's fine-grained extensibility primitive. They are auto-discovered from any module's src/ directory; no manual registration is needed.

When to use

Use a plugin when the user wants to modify arguments to, or the result from, a public method on a class without rewriting or subclassing it. Common cases:

• Enrich a return value
• Validate or transform inputs before the method runs
• Short-circuit (cache hit, guard, redirect)
• Log or observe calls
• Chain transformations across modules

For total replacement of a class, use a Preference instead — that is a separate skill (marko-create-preference). Plugins and Preferences are complementary; only Preferences swap entire implementations.

Plugin model — two timings only

Marko supports exactly two plugin types. A third type that wraps the call is intentionally absent — anything it could do is expressed as a Before (short-circuit) or After (result transformation), keeping the call stack debuggable.

Before return semantics

After return semantics

After plugins receive $result (the return value of the original method or a prior After plugin) as their first parameter, followed by the (possibly modified) original arguments. Each After plugin's return value feeds the next After plugin in sort order — always return the (possibly modified) result.

sortOrder

sortOrder is defined on the method-level attribute, not the class. Lower numbers run first; negatives are valid; default is 0.

#[Before(sortOrder: -10)]   // runs before plugins at default 0
#[After(sortOrder: 100)]    // runs after lower-priority Afters

Runbook

Step 1 — Identify the target

Determine which class and public method to intercept. Plugins cannot intercept protected or private methods, and the target class must not be final.

Step 2 — Copy the plugin class template

Copy assets/PluginClass.php.tmpl verbatim. Substitute:

{{Vendor}}\{{Name}} is inherited from the module that hosts the plugin — read it, do not re-derive it. A plugin lives inside an existing module, so its namespace must match that module exactly. Read the host module's composer.json autoload.psr-4 key and use its prefix verbatim:

• App-local module (app/{name}/) → namespace App\{Name} (the vendor segment is always the literal App, never the project directory name).
• Distributable module (modules/{vendor}/{name}/) → namespace {Vendor}\{Name} from that module's psr-4.
• Framework monorepo package (packages/{name}/, root contains packages/core/) → namespace Marko\{Name}.

Never use Marko as the vendor outside the framework monorepo. Do not infer the vendor from the project's root composer.json name: a skeleton-derived project still carries marko/skeleton there. The host module's own psr-4 mapping is the source of truth.

Place the file at src/Plugins/{{TargetClass}}Plugin.php inside the module.

Add the correct use statement for the fully-qualified target class.

Remove any #[Before] or #[After] methods that are not needed for this plugin — the template shows both for illustration.