Findable Laravel Package

Getting Started

elaniin/findable is a Statamic SEO add-on — it gives you a reusable SEO fieldset you attach to blueprints and an Antlers/Blade-facing way to render the resulting meta tags in your <head>. Treat it as a thin glue layer over per-entry SEO fields plus defaults, not a full technical-SEO suite.

Minimal path:

1. Install: composer require elaniin/findable (pin the version — see Gotchas).
2. Read the README top-to-bottom before running anything else. At 13 stars and a 2022 last release, docs are the primary source of truth; don't assume Statamic 3 conventions still apply if you're on Statamic 4/5.
3. Publish what the README tells you to publish — typically a fieldset (and possibly a config file). Check resources/fieldsets/ in the package to see what actually shipped.
4. Attach the published SEO fieldset to the blueprint(s) that represent indexable content (pages, posts, products). Do this in the Statamic CP under Blueprints, not by hand-editing YAML.
5. Add the SEO render tag/partial into your layout's <head>.

First use case: open a single Entry in the CP, fill in meta title/description/OG image, then view source on the front end and confirm tags render. That's your smoke test — if that loop doesn't close, stop and debug before wiring up more collections.

Where to look first when something's off:

• resources/ (fieldsets, views/partials) — what actually gets published.
• src/ — look for the Antlers tag class or view composer that assembles the head output; that's where fallback logic lives.
• config/ — defaults for title suffixes, social handles, image fields.
• Your own blueprint YAML — 90% of "it's not working" turns out to be the fieldset not attached or fields renamed.

Implementation Patterns

Fieldset-on-blueprint, not global fields. Attach the SEO fieldset per blueprint so each content type can have different defaults (e.g. blog posts fall back to the entry title, products fall back to a short description field). Resist the urge to make one giant global SEO tab.

Central <head> partial. Wrap the render call in a single partial (resources/views/partials/seo.antlers.html or similar) and include it once in your layout. This gives you one place to layer package output with your own fallbacks, canonical URLs, and JSON-LD. Don't scatter SEO tags through individual templates.

Fallback chain, defined in one place. The package will handle seo_title ?: title, but you'll want more: seo_description ?: excerpt ?: summary field ?: site-wide default. Implement that chain in the partial or in a small view-model/controller helper so it's testable, rather than relying entirely on package defaults.

Defaults via config or a Globals set. Site-wide defaults (site name suffix, default OG image, Twitter handle) belong in either the package config or a Statamic Globals set that the partial reads. Globals wins if editors need to edit them without a deploy.

Per-collection OG strategy. For pages use the hero image; for products use the primary product image; for posts use the featured image. Wire each blueprint's OG image field to the right asset field so editors don't hand-pick per entry.

Multi-site. If you're running Statamic multi-site, verify the package resolves the correct site's defaults per locale. Test by switching sites on one entry and viewing both front ends — if the SEO title from site A leaks into site B, you'll need to override the fallback logic in your partial.

Caching. If you cache rendered pages (static caching, response cache), SEO output is baked in — clear cache on entry save. Wire an event listener on Entry::saved (or use Statamic's static caching warmer) so editors don't wonder why their meta description didn't update.

Sitemap pairing. This package doesn't replace a sitemap. Pair it with Statamic's sitemap or a custom one, and make sure your "noindex" field (if the package provides one) is respected there too.

Gotchas and Tips

Maintenance risk is the headline gotcha. Last release was January 2022 and it has 13 stars. Before adopting:

• Pin to an exact version in composer.json.
• Check the composer.json constraints for statamic/cms — if it caps below your Statamic major, don't install; you'll fight it.
• Skim open issues and the last few commits. If it's abandoned, plan to fork or vendor the fieldset definitions into your own project (fieldsets are just YAML — you can copy them and drop the dependency).
• Budget for a fork. The valuable part is the fieldset schema and the head-rendering partial; both are small enough to own.

Fieldset attach ≠ fields appear. After publishing the fieldset, you still must attach it to a blueprint and save the blueprint. Statamic won't show fields on existing entries until the blueprint is saved. Also, existing entries get the fields but empty — your fallback chain matters from day one.

Renaming SEO fields breaks the package. The render tag/partial expects specific field handles. If you rename seo_title to meta_title for editor clarity, you must update the render partial too. Do the rename in one commit and grep for the old handle.

Antlers vs Blade. Statamic projects vary. If the package ships an Antlers tag, it won't work in Blade without the Statamic Blade directives. If it ships a partial, you may be able to @include it. Confirm which mode the package is in before building your layout around it.

Debugging the head output. When tags are missing, work the chain backwards: (1) {{ dump }} the entry's SEO fields in a scratch template — are values populated? (2) Is the partial included in this layout? (3) Is there a site-level override suppressing output? (4) Is static cache serving stale HTML? This sequence resolves nearly every report.

Config cache. If you add a config file, remember php artisan config:clear in dev. Statamic's own caching won't help you here, and a stale config is a silent failure.

Escape output. Meta descriptions and OG titles are editor-supplied. Confirm the package escapes them; if not, wrap with {{ ... | sanitize }} or equivalent. Don't trust a 2022 package to have this right by default — verify.

Extension points to lean on. The likely safe extension points are: the published fieldset (edit YAML freely), the published config (defaults and suffixes), and your own head partial (override logic there rather than forking PHP). Avoid subclassing package classes; with an unmaintained package, class-level coupling is what turns a minor upgrade into a rewrite.

Don't rely on it for technical SEO. Structured data, canonical strategy, redirects, hreflang, and sitemap generation are outside scope. Use dedicated tools (or hand-written JSON-LD in your partial) and keep this package responsible only for meta/social tags. That boundary keeps the eventual replacement cheap.