Download the PHP package rasuvaeff/yii3-seo without Composer

rasuvaeff/yii3-seo

Русская версия

Next.js-inspired, Yii3-native typed SEO metadata. Describe a page with one declarative Metadata object — title templates, OpenGraph, Twitter cards, hreflang, canonical URL, robots directives, icons, verification and JSON-LD — and a single MetadataDefaults instance supplies site-wide values. Tags land in <head> automatically via WebViewRenderer. XML sitemaps are generated from the same configured origin.

Using an AI coding assistant? llms.txt has a compact API reference ready to paste into context. Projects using the llm/skills Composer plugin also get this package's agent skill synced into .agents/skills/ automatically on install.

Requirements

• PHP 8.3+, ext-filter, ext-mbstring, ext-xmlwriter
• yiisoft/html ^3.13 || ^4.0
• yiisoft/view ^12.0
• yiisoft/yii-view-renderer ^7.4
• psr/http-message, psr/http-server-handler, psr/http-server-middleware (self-canonical middleware)
• psr/http-factory (sitemap responses)

Installation

Concept

The API brings the declarative style of the Next.js Metadata API to Yii3:

Defaults are merged with the page metadata: the title template wraps the page title, OpenGraph/Twitter inherit unset fields, and relative URLs are resolved against metadataBase.

Unlike Next.js, nested OpenGraph/Twitter values are merged field by field and social title, description and image fallbacks are enabled by default. These Yii3-native rules reduce repetition while explicit page values always win.

Quickstart

Two configuration edits, one dispatch and two lines in the layout.

1. Site-wide defaults — config/common/params.php

2. Add the injection to the view renderer — config/common/di.php

3. Describe the page — in an action

That is the whole integration. A request for https://example.com/products/awesome?utm_source=mail renders:

og:title/og:description fell back to the page title and description, twitter:* fell back to OpenGraph, the canonical URL came from the request path with the tracking parameter stripped, and the layout only had to print <title> and the JSON-LD block (step 4).

What the package wires for you

HttpApplicationRunner reads the events-web group with RecursiveMerge, so these listeners merge with the application's own and with other packages' listeners for the same event instead of colliding.

Upgrading from 1.0.x: remove the SeoMetadataEvent entry from the application's own config/common/events-web.php. Merged listeners stack rather than deduplicate, so keeping it invokes the handler twice per dispatch. That is harmless today — setMetadata() re-resolves the same input — but it is dead configuration.

4. Print title and JSON-LD — in the layout

WebViewRenderer has injection interfaces for meta and link tags only, so these two elements are rendered from the automatically injected $seo parameter:

Public API

Metadata

Immutable declarative object (all fields optional). A string title is normalized to Title::of().

MetadataDefaults

Site-wide defaults: metadataBase, title (template/default), applicationName, generator, themeColor, colorScheme, robots, openGraph, twitter, icons, verification, jsonLd, other. Provide via the rasuvaeff/yii3-seo → defaults parameter.

MetadataResolver + ResolvedMetadata

MetadataResolver is the single source of truth for defaults, title templates and social fallback rules. It returns an immutable ResolvedMetadata that can be inspected independently of Yii rendering:

Configured relative crawler-facing URLs remain relative in ResolvedMetadata; rendering resolves them against metadataBase. Normally applications obtain the current result through SeoInjection::getResolvedMetadata().

ResolvedMetadata::toArray() exports the same result as a normalized array for JSON APIs, SPA payloads, preview tooling and debugging:

MetadataValidator

MetadataValidator inspects a ResolvedMetadata and reports typed issues. It never throws and never modifies metadata, so it is safe to run in a development toolbar, a preview page or a CI check:

Each MetadataIssue carries a MetadataIssueSeverity (Error or Warning), a stable machine-readable code for filtering, and a human-readable message.

Lengths are advisory: they never make the result invalid.

Title

Alternates

Locales match /^(?:[a-z]{2}(?:-[A-Z]{2})?|x-default)$/.

SelfCanonical + SelfCanonicalMiddleware

Opt-in: derive the canonical URL of pages that do not declare one from metadataBase plus the current request path.

A request for https://example.com/products/1?page=2&utm_source=mail then renders <link rel="canonical" href="https://example.com/products/1?page=2">.

SelfCanonicalMiddleware calls SeoInjection::setRequestPath(); it works regardless of whether the action sets page metadata before or after it.

OpenGraph + OgImage

TwitterCard

Robots

Icons / Icon, Verification, Author

MetaTag

JsonLd

Renders as <script type="application/ld+json"> with JSON_HEX_TAG to prevent </script> injection.

SeoInjection

Singleton registered in DI. Implements LayoutParametersInjectionInterface, MetaTagsInjectionInterface and LinkTagsInjectionInterface. The package DI config also registers a service reset hook, so stale per-request metadata is cleared between requests in reusable runtimes.

Sitemaps

The sitemap side of the package is independent of the head metadata: it needs nothing but a source of URLs and the same metadataBase. The package never crawls the site — the application always says what belongs in the sitemap.

SitemapUrl

Locales use the same rules as Alternates: de, de-DE or x-default.

SitemapProviderInterface

Yield instead of returning an array: every consumer below pulls one URL at a time, so a provider backed by a database cursor never materialises its result set.

Sitemap and SitemapIndex

Both implement SitemapDocumentInterface and emit the document as chunks:

A document built from a Generator can be emitted once; pass an array to make it re-renderable. SitemapIndex takes SitemapIndexEntry objects (loc plus an optional lastModified) and produces a <sitemapindex>.

SitemapFileExporter

Writes a URL stream to disk, enforcing both protocol limits — 50 000 URLs and 50 MiB uncompressed — by measuring each rendered entry before appending it:

The layout depends only on the URL stream:

export() returns the written file paths in write order. Nothing is deleted: chunk files left by an earlier, larger export stay on disk and the fresh index never references them. A single URL that cannot fit into the byte limit throws InvalidArgumentException rather than producing an over-limit file — the chunk opened at that moment is left on disk without its closing tag, so treat a failed export as one to re-run, not as a partial result to publish.

publicPath must match where the written files are actually served from: exporting into /var/www/public/sitemaps while leaving publicPath at / produces an index pointing at https://example.com/sitemap-1.xml, which 404s. Nothing can check this for you — the exporter never sees the URL the directory is published under.

SitemapFileExporter is wired in DI and inherits metadataBase from the configured MetadataDefaults; publicPath comes from the rasuvaeff/yii3-seo → sitemap → publicPath parameter.

SitemapResponseFactory

Serves a document from a route. The body is a php://temp stream, so a 50 MiB sitemap does not cost 50 MiB of PHP memory:

It needs a PSR-17 ResponseFactoryInterface and StreamFactoryInterface, both of which a Yii3 application already has in its container.

robots.txt

RobotsTxt is a typed document, not a template: every user agent and path is validated, and a value carrying a control character is rejected rather than written, so configuration can never forge an extra Disallow: / line.

Serving it

RobotsTxtAction is a PSR-15 handler; both dependencies come from the container, so the route is the whole integration:

The document it serves is bound in DI from parameters:

The package never inspects the environment. When indexable is false the bound document is RobotsTxt::disallowAll() — every crawler blocked, no sitemap advertised — regardless of what robots contains. A wrong guess here would either de-index production or expose staging, so the decision is always the application's, stated explicitly. RobotsTxtResponseFactory is available directly if a route needs to build the document per request.

X-Robots-Tag

Responses without a <head> — generated PDFs, images, exports — carry the same policy as a header. Robots::toHeaderValues() returns one value per header line:

Security

• Crawler-facing URLs (canonical, hreflang, og:image, og:url, twitter:image, and every sitemap URL) are resolved against metadataBase; absolute URLs are validated with FILTER_VALIDATE_URL. A relative URL with no base throws InvalidArgumentException.
• HTML escaping is handled by Yiisoft\Html — no raw string concatenation.
• Sitemap XML escaping is handled by XMLWriter; only the fixed document header and footer are literals, and they carry no input.
• robots.txt values are rejected when they contain a control character, so configuration cannot forge an extra directive line. Whether a site may be indexed is never guessed from the environment — the application passes it in.
• JSON-LD uses JSON_HEX_TAG to prevent </script> injection.

Examples

See examples/ for runnable scripts and a Yii3 integration sketch: examples/yii3-app.php. Sitemap generation and file export: examples/sitemap.php; crawl policy: examples/robots-txt.php.

See ROADMAP.md for planned curated structured-data builders.

Development

License

BSD-3-Clause. See LICENSE.md.