Download the PHP package rondodevs/craft-toolkit without Composer

Craft Toolkit

Internal Craft CMS plugin bundling a set of control panel utilities:

• Site Config — CP-editable overrides for site name/URL on top of env defaults, exposed via GraphQL.
• KV Cache — settings and controls to purge an external edge/KV cache (tags or full flush) when entries/assets change.
• Static Labels — CP-editable label overrides per site, exposed via GraphQL.
• Average Color — enable/disable and per-volume control for automatic average-color calculation on image assets, with a check of which volumes already have an averageColor field in their field layout. The media volume is selected by default when present.
• Org Schema — CP panel with per-site defaults for the schema.org identity (Organization, LocalBusiness, MedicalClinic/MedicalBusiness, Person, ...: name, logo, one or more addresses, sameAs social profiles, contact info), exposed via GraphQL for Nuxt SEO's default schema.org identity. Plus an Org Schema field type to attach one or more arbitrary schema.org pieces (Article, Product, Event, MedicalClinic, FAQPage, ...) to individual entries, each with type-specific basic fields (e.g. NAP + geo-coordinates + opening hours for locations) and a JSON escape hatch for anything else.
• Misc handlers: a CP alert when the default GraphQL route is missing, and a site-request redirect controller.

Requirements

• Craft CMS 5.0.0 or later
• PHP 8.2 or later

Getting started (development)

Requires DDEV and Docker/OrbStack running locally.

1. Clone the repo and start DDEV (spins up web/db containers, no host PHP needed):

2. Install the plugin's own dependencies, so your IDE resolves craft\... classes:

3. Install the playground's dependencies (symlinks this plugin in via the path repository already committed in playground/composer.json):

4. Create the playground's local env file (DB credentials are injected automatically by DDEV; leave CRAFT_APP_ID/CRAFT_SECURITY_KEY blank, craft install fills them in):

5. Install Craft — since playground/config/project/project.yaml is already committed, this provisions the DB schema and applies that project config automatically:

6. Open https://craft-toolkit-playground.ddev.site/admin/login and log in.

From here, edit anything under src/ and reload the CP — changes are live via the symlinked plugin, no reinstall step. See DDEV playground below for how the playground itself was scaffolded and how to regenerate it from scratch if it ever needs a reset.

Installation

From Packagist (once published)

Then install the plugin in the Craft control panel, or via:

Local development (path repository)

While developing this plugin alongside a Craft project, add a path repository to the consuming project's composer.json so Composer symlinks it instead of downloading a tagged release:

Adjust the url to the relative (or absolute) path to this directory, then run composer update rondodevs/craft-toolkit. Changes made here are picked up immediately in the consuming project without republishing.

DDEV playground

For interactive testing (CP, GraphQL, utilities) this repo ships a DDEV project rooted at the repo root with its docroot at playground/web. The playground/ directory holds a full Craft install that requires this plugin via a local path repository (symlinked), so edits under src/ are picked up immediately — no reinstall needed. It's gitignored; regenerate it anytime with:

Then edit playground/composer.json:

Then visit https://craft-toolkit-playground.ddev.site/admin/login.

KV Cache: Cloudflare purge

After every Nuxt cache purge (on entry/asset save or delete, manual tag purge, full flush) the plugin can also purge the Cloudflare edge cache. It is switched on and off from its own Toolkit → Cloudflare screen, with:

• Zone ID and API token: both accept $ENV_VAR and default to these env vars. The token needs the "Zone → Cache Purge" permission on that zone to purge, plus "Zone → Cache Rules → Edit" for the edge cache check to read, create and fix the Cache Rule; no Cloudflare login or OAuth is involved.

• Create token on Cloudflare: opens the Cloudflare token form with the "Cache Purge" and "Cache Rules → Edit" permissions and a name already filled in; narrow Zone Resources to the site's zone there, then paste the token.
• Verify saved Cloudflare settings: purges one URL that is never cached, to check the zone ID and the token's permission without touching any cached page.

Until the switch is saved once, it is on when both env vars are set and Craft is not in dev mode, so a local install never purges the production zone.

Edge cache check requests the Frontend URL like a visitor (following redirects, so apex → www ends on the host that serves the pages) and reports:

• Frontend CDN cache: the home page sends CDN-Cache-Control, i.e. NUXT_CDN_CACHE_ENABLED=true with the data cache on. Cloudflare passes this header on to visitors, so it is seen from outside.
• Cloudflare proxy: the response has a cf-ray header (the DNS record is proxied, and the Frontend URL is the public one, not the origin).
• Edge cache of HTML: a second request comes back HIT (or STALE, UPDATING, REVALIDATED); DYNAMIC means no Cache Rule makes the HTML cacheable.
• Craft previews: a URL with x-craft-preview asked twice is never served from the cache.
• Cache Rule: read through the API, the rule for the host is enabled, Eligible for cache, Edge TTL bypass_by_default ("Use cache-control header if present, bypass cache if not"), Browser TTL Respect origin, keeps the query string in the cache key (_payload.json?_b=<build id>) and leaves out /__nuxt_multi_cache/, /api/, x-craft-preview, x-craft-live-preview and token=. This needs the token to also have the "Zone → Cache Rules → Edit" permission; without it the row is skipped.

A rule for the host is never duplicated. When the zone has none, Create Cache Rule adds the HTML e payload rule last, so it wins over the rules before it. When the rule is there but wrong (the one with that name, or else the first cache rule naming the host), the button becomes Fix Cache Rule and rewrites that rule in place. When it is right, the button does not show, and the action changes nothing. It only runs when the host is proxied, since a host outside the proxy most likely belongs to another zone. The screen also shows the expression, to create the rule by hand.

View Cache Rules opens a modal with the zone's Cache Rules in the order Cloudflare applies them: name, enabled or not, settings in the dashboard's words and expression. The rule the check uses for the frontend's host is highlighted with what is wrong in it, and the enabled rules after it are marked, since for the same setting the last matching rule wins. It needs the same "Zone → Cache Rules → Edit" permission (read is enough).

• Tag purges send the same tags to POST /zones/:zone_id/purge_cache ({"tags": [...]}, in chunks of 100); a full flush sends {"purge_everything": true}.
• The purge runs as a queue job 10 seconds after the Nuxt one, because nuxt-multi-cache applies tag purges after its cacheTagInvalidationDelay (3s): purging Cloudflare first would let it refetch a still-stale page.
• The frontend must send Cache-Tag comma-separated (Cloudflare does not allow spaces in tags), as @studio-fes/layer-craft does.
• A failing Cloudflare purge never fails the Nuxt purge; the job is retried by the queue and the edge cache still expires on its own max-age.
• Emergency purges run right away, even with automatic invalidation or Cloudflare purging switched off. The Advanced screen has Purge all caches (Craft's caches, then KV, then the whole zone: purged first, Cloudflare would refetch pages built from stale data) and one button per layer; the Cloudflare screen also has Purge Cloudflare cache for the zone alone.

Org Schema (schema.org / Nuxt SEO)

Two pieces work together to feed Nuxt SEO's schema-org module:

• Toolkit → Org Schema (CP panel): per-site defaults for the site's schema.org identity — Organization, Corporation, NGO, LocalBusiness, ProfessionalService, MedicalBusiness, MedicalClinic, EducationalOrganization or Person — following the shape expected by Nuxt SEO's default schema.org identity (name, legalName, url, logoUrl, description, email, telephone, sameAs, addresses). logoUrl is picked via a native Craft asset selector (upload or choose an existing image) rather than typed as a raw URL, and resolved to its URL for output. Fields shown in the CP adjust to what each type actually defines per schema.org (verified against schema.org directly):

  Field	Shown for
  legalName, logoUrl	Organization, Corporation, NGO, LocalBusiness, ProfessionalService, MedicalBusiness, MedicalClinic, EducationalOrganization — not Person (schema.org's Person has neither property)
  priceRange	LocalBusiness, ProfessionalService, MedicalBusiness, MedicalClinic — defined directly on LocalBusiness
  openingHours	the same LocalBusiness types, plus EducationalOrganization — EducationalOrganization inherits openingHours from CivicStructure (Thing > Place > CivicStructure > EducationalOrganization), but does not inherit priceRange from anywhere in its hierarchy

  addresses supports multiple locations — for a multi-clinic/multi-branch business, add one per physical location. Since priceRange and openingHours are properties of a physical place in schema.org (not of the identity as a whole), they live on each address rather than on the identity, and each location can have its own value — so two locations of the same MedicalClinic can have different hours. openingHours is entered via a day-picker + open/close time per schedule and compiled into an array of schema.org strings, e.g. ["Mo-Fr 09:00-18:00", "Sa 10:00-14:00"]. Exposed via GraphQL:

  For a multi-location business (e.g. a medical group with several clinics), use MedicalBusiness here for the sitewide identity with one address (and its own price range/hours) per clinic. If a location also needs its own dedicated page, model it as its own entry instead and put its NAP/geo/hours on that entry via the Org Schema field below with @type set to MedicalClinic (or Dentist/Physician/Hospital/Pharmacy) — its basic fields cover name, telephone, street address/locality/region/postal code/country (merged into a nested address), latitude/longitude (merged into a nested geo), openingHours and priceRange.

• Org Schema field: a field type you can add to any field layout to attach one or more arbitrary schema.org pieces (Article, Product, Event, FAQPage, HowTo, ...) to a specific entry/element. Each row is a @type plus a JSON object of additional properties; GraphQL exposes each piece pre-merged and ready to parse:

In Nuxt, combine both with useSchemaOrg() — the site-wide identity via defineOrganization()/definePerson(), and the entry-level pieces passed through as raw schema.org objects:

Publishing to Packagist

1. Push this repository to GitHub (e.g. github.com/rondodevs/craft-toolkit).
2. Tag a release, e.g. git tag v1.0.0 && git push --tags.
3. On packagist.org, submit the GitHub repository URL.
4. Enable the GitHub Packagist webhook (Packagist "Settings" tab -> instructions, or add it manually under the GitHub repo's Settings -> Webhooks) so new tags are picked up automatically.
5. From then on, composer require rondodevs/craft-toolkit resolves the package for anyone with access to the repository.

License

MIT