Download the PHP package indexnowkit/yii2 without Composer

Yii2 IndexNow extension — indexnowkit/yii2

Tell search engines about new, changed and deleted pages the moment an ActiveRecord row is committed. One attribute on the model, one component, done.

github.com/indexnowkit/php (the php-* repositories are read-only splits)

Who gets notified

Yandex, Bing (and DuckDuckGo via Bing), Naver, Seznam, Yep, Internet Archive, Amazon — every engine in the IndexNow registry. One request to the shared endpoint reaches all of them; name engines explicitly only to reach a single one.

Google: no. Google does not support IndexNow; this package will not pretend otherwise.

Notification, not indexing. IndexNow tells an engine that a URL changed; whether and when the page is crawled and indexed is the engine's decision. See the result in Bing Webmaster Tools (IndexNow Insights) and Yandex.Webmaster (Indexing → Reindex pages); a useful metric is the share of submitted URLs in the index after a few days. Deleted pages: answer 410 (gone for good) or 404 (temporarily); for a move answer 301 and submit both URLs; a soft-404 or a redirect to the home page does harm. Bing's URL Submission API and Google's Indexing API are different protocols and not covered here.

Why this over X

Most IndexNow packages are a thin HTTP client: you collect the URLs, you call it, you read the answer. This family does the part that goes wrong in practice:

• Declared on the model (#[IndexNow]) and submitted from the ORM hooks — no controller code to forget.
• After the commit, not on flush: a rolled-back transaction announces nothing.
• Debounce (10 minutes per URL, shared through your cache), batches of up to 10 000 URLs, one key per host from env.
• Answers handled: 202 (key pending), 422, 429 with Retry-After back-off and a retry through your queue, 403 escalation.
• check before the first submission says what is wrong (key file, engines, queue, cache, environment); explain says why a URL was or was not sent.
• One core under the Symfony, Laravel, Yii2 and Doctrine adapters with a shared conformance suite: the same behaviour everywhere, documented once.

Install

Yii2 does not read .env by itself: export the variable (export INDEXNOW_KEY=…), put it in the web server or container environment, or load the file with vlucas/phpdotenv before config/*.php runs — getenv('INDEXNOW_KEY') returns false until one of these is done, and check says no key configured. In yii2-app-basic, config/web.php and config/console.php are independent: configure the indexnow component and urlManager (pretty URLs, rules) in both, or check, explain and submit-record see a different setup than the web application. Pretty URLs (urlManager.enablePrettyUrl) are required for the key file route /<key>.txt. The package needs a PSR-18 client (symfony/http-client + nyholm/psr7 as above, or Guzzle); it discovers one, or takes the component/class named in http.client.

Declare what has a public page

#[IndexNow] is repeatable: one attribute per family of public URLs. IndexNowBehavior registers the hooks. Save the example as models/Post.php under namespace app\models; — it reads the columns slug, title, body, published, amp (the AMP page exists while it is true) and category_id; Category is a record of your own with its own #[IndexNow] rule (drop the via: 'category' line if you have none).

Accessors read ActiveRecord attributes and relations (category.slug) and fall back to methods. A when column that only has a database default is null on a fresh record: call $this->loadDefaultValues() in init() or set the attribute before save().

Classes you cannot annotate: 'active_record' => ['models' => [Product::class]] in the options, or Yii::$app->indexnow->observe(Product::class, [new IndexNow(...)]) at runtime.

Full model, typed parameters, inheritance and the semantics table: core attribute reference.

Verify

Run it after every key rotation and after every deployment that touches the configuration.

How it works

• URLs are resolved in the ActiveRecord event, while the old state is live (changedAttributes on afterUpdate, the row and its relations in beforeDelete). A renamed page announces its old URL as deleted.
• Outside a transaction they go to the request collector right away. Inside one, Yii2 gives no savepoint events, so they are held with a verifier and re-read by primary key when the transaction commits: a change the row does not show (an inner beginTransaction() that rolled back) is dropped with every URL it produced. A rollback drops everything. One SELECT per changed record, only inside explicit transactions. Details: docs/commit-safety.md.
• Everything collected during one request is sent after the response (Response::EVENT_AFTER_SEND), in one batch; console commands flush when they end, queue workers after every job.
• dispatch: auto (default) pushes a SubmitUrlsJob to the queue component when yiisoft/yii2-queue is configured (429/5xx re-pushed with the delay of retry.*, Retry-After honoured), else sends synchronously. Details: docs/queue.md.
• Nothing thrown from a rule, a resolver or the HTTP layer reaches your application: it is logged under the indexnow category, the save succeeds. An invalid configuration disables IndexNow with one critical line; php yii indexnow/check prints the exact error.

Commands

<class> is an FQCN or a short name under app\models. Ids are space- or comma-separated.

Sitemaps

composer require indexnowkit/sitemap # optional: the indexnow/sitemap command

indexnow/sitemap with no argument reads sitemap.url, else <base_url>/sitemap.xml; a local path works too. Without the package everything else works unchanged: indexnow/sitemap says indexnowkit/sitemap is not installed: composer require indexnowkit/sitemap and exits 1, indexnow/check prints sitemap: not installed (…), a sitemap block in the options is ignored, sitemapConfig() / sitemapSource() throw a LogicException with the same sentence. Nothing is logged about it.

History

composer require indexnowkit/history # optional: what was submitted, when, with what answer

Every Result the submitter produces — the flush after the response, the yii2-queue job, the commands, a URL skipped by indexnowkit/verify — is recorded: normalized URLs, host, engine, status, reason, HTTP code, the error message (never the response body or the key). php yii indexnow/history lists them newest first (--host, --status, --url, --since, --json); indexnow/history --purge removes what is older than history.retention_days (a cron line); php yii indexnow/status prints the switches, the dispatch mode with the queue component, the debounce store, the 403 counter of every host, the last successful submission and the history size (--json for machines). pdo needs the table: the migration is in the package's docs/migrations.md (Schema::sql()); until it exists indexnow/check prints a history.store error and the submitter logs the failure without breaking the flush. psr16 is a ring buffer of history.limit records for one process and small sites. The submissionStore property of the component takes precedence over either. Without the package indexnow/history and indexnow/status say indexnowkit/history is not installed: composer require indexnowkit/history and exit 1, indexnow/check prints history: not installed (…), historyConfig() throws a LogicException with the same sentence.

Configuration and docs

Every option, its default and what it does: docs/configuration.md. Commit safety: docs/commit-safety.md. Replacing pieces, custom resolvers, checks: docs/queue.md. Several hosts, www and apex, languages: docs/testing.md.

Operations

• Production checklist — key and base URL, check in the deploy pipeline, strict_hosts, a shared debounce store, a monitored queue, staging that cannot submit, the three lines to alert on.
• Monitoring rules and the Sentry filter, deleted pages, what not to submit.
• troubleshooting.

Debugging

php yii indexnow/check validates the options, fetches the key file and reports how submissions are wired (queue, cache, pretty URLs, ActiveRecord hooks, sitemap spool); php yii indexnow/explain 'app\models\Post' 1 shows the rules, guards and URLs of one record without sending anything; the indexnow log category at debug tells why a URL was or was not submitted. Symptoms and fixes: docs/troubleshooting.md.

Limitations

• updateAll(), deleteAll(), updateAttributes(), updateCounters() fire no events (conformance A13): call Yii::$app->indexnow->submitRecords(Post::find()->where(...)->all()) or php yii indexnow/submit-record afterwards.
• link() / unlink() write the junction row with a plain command, no event on the owner: save the owner with a bumped timestamp afterwards ($post->updated_at = time(); $post->save(false)), or call submitRecord($post).
• The sync driver of yii2-queue ignores the delay between attempts: 429/5xx attempts run back-to-back (development only, check warns).
• Without pretty URLs the key file cannot be routed: enable them, or serve /<key>.txt as a static file and set key_file.enabled: false.

Compatibility

Public API: the options tree, command names and options, IndexNowComponent methods and properties, ActiveRecord\IndexNowBehavior, Queue\SubmitUrlsJob. The core's rules apply: bc.md; what this package itself keeps stable: docs/bc.md. Before 1.0 a minor version may break; every break is listed under "Changed" in CHANGELOG.md. Yii 2.0.45+, PHP 8.2–8.5.

Notes for AI assistants

• Composer package indexnowkit/yii2 (Yii 2.0.45+, on indexnowkit/core); the indexnow/sitemap command needs indexnowkit/sitemap; pre-flight checks need indexnowkit/verify; indexnow/history / indexnow/status need indexnowkit/history (history.store: psr16|pdo). Configuration: the indexnow application component (options array), 'bootstrap' => ['indexnow']. php yii indexnow/key-generate --write-env writes a fresh INDEXNOW_KEY; php yii indexnow/submit <url>… submits URLs by hand, php yii indexnow/explain <Record> <id> shows why a URL is or is not produced.

• Minimal complete snippet (every use included):

• Verify: php yii indexnow/check (exit 1 on any error; --strict fails on warnings too, --json for machines), php yii indexnow/config --json (the effective configuration, keys masked: paste it into a bug report), php yii indexnow/explain 'app\\models\\Post' 1 (why a URL was or was not produced), php yii indexnow/submit-record 'app\\models\\Post' 1 --dry-run.
• Pitfalls:
  • dispatch: auto exists in Symfony (auto | messenger | sync | none) and Yii2 (auto | queue | sync | none), not in Laravel (queue | sync | none).
  • Locales: router.locales in Laravel and Yii2, framework.enabled_locales in Symfony; locales: 'all' on a rule uses that list.
  • url: names an accessor (method or property) that returns the URL; urls: is a list of literal URLs. Never put a literal in url:.
  • A string in when: is an accessor read as truthy (published, isPublished). A status string needs Equals: when: new Equals('status', 'published') (IndexNowKit\Attribute\Param\Equals).
  • Manual submission is submitEntity() in Symfony, submitModel() in Laravel, submitRecord() in Yii2; the commands are indexnow:submit-entity, indexnow:submit-model, indexnow/submit-record. Bulk queries (update(), DB::table(), updateAll()) fire no hooks: submit afterwards with those.
  • Laravel has two classes called IndexNowKit: the facade IndexNowKit\Laravel\Facades\IndexNowKit and the core service IndexNowKit\IndexNowKit (inject by type). Yii2 exposes the core through Yii::$app->indexnow->kit().
  • Outside production a configured key with dry_run unset makes check fail (a staging copy would submit real URLs): set dry_run: true there, or dry_run: false explicitly when it submits on purpose.
  • Unknown configuration keys are warned about at boot (typos such as debounce.per_urls); the key list is Config::OPTIONS plus the adapter's own keys.

Other frameworks

MIT. IndexNow is a trademark of its owner; this project is independent and not affiliated with Microsoft, Yandex or indexnow.org.