Skip to content

docs(installation): rewrite Composer install guide#397

Open
enricobattocchi wants to merge 2 commits intomainfrom
22545-improve-composer-install-docs
Open

docs(installation): rewrite Composer install guide#397
enricobattocchi wants to merge 2 commits intomainfrom
22545-improve-composer-install-docs

Conversation

@enricobattocchi
Copy link
Copy Markdown
Member

Refs Yoast/wordpress-seo#22545

Summary

The current Composer install page tells integrators to run composer require from inside the plugins/ directory (which produces an incorrect install path through composer/installers) and claims the published package "installs all necessary dependencies". In practice the Composer-distributed artifact is source-style: it does not include vendor/autoload.php, and Yoast SEO's classes are reached through the consumer project's root autoloader. Composer-managed WP setups that don't register an autoloader before plugins load (a common case on stacks where wp-config.php is platform-supplied) end up with a broken install — see Yoast/wordpress-seo#22545.

This rewrite restructures the page around that requirement, separates the free and Premium flows, documents the MyYoast token + repository setup for Premium, and folds the contributor-only yarn / grunt build steps out of the install guide into a single link to the contributor setup.

Relevant technical choices

  • The opening section makes the autoloader requirement explicit and gives the canonical require_once __DIR__ . '/vendor/autoload.php'; line, without prescribing where to put it (intentionally stack-agnostic).
  • The Premium section uses the three-line token + repository + require flow that mirrors the Composer install instructions surfaced in MyYoast.
  • The page still references the same id: using-composer, sidebar label, and headings file slug, so deep links and the sidebar entry remain unchanged.
  • The "self-deactivate with a notice" sentence currently describes the free plugin's behaviour. It will also apply to Premium once the Premium-side bootstrap fix lands (companion change in Yoast/wordpress-seo-premium); if this PR ships first, the sentence may need to be softened to acknowledge that Premium currently fatals rather than deactivates.

Test instructions

This PR can be acceptance tested by following these steps:

  1. Run yarn build locally (or wait for CI's preview deploy) and open docs/development/installation/using-composer.md in the rendered Docusaurus site.
  2. Confirm the page renders with the four sections (requirement, free, Premium, updating) and that the in-page anchor link from the Premium section back to "requirement" works.
  3. Confirm the contributor-setup link at the top of the page still resolves to /development/environment/setup.

Quality assurance

  • Security - I have thought about any security implications this code might add.
  • Performance - I have checked that this code doesn't impact performance (greatly).
  • Caching - I have analyzed the caching methods that this code touches and have added instructions to deal with those.
  • Tested - I have tested this code to the best of my abilities.
  • Automated tests - I have added unit tests to verify the code works as intended.
  • Testability - I have added unique ids to elements, so they can be located in automated testing.
  • I have altered a filename.
    • I have adjusted the ID property accordingly and updated all internal links.
    • I have added the redirect to the _redirects file in the root of the project.

The previous page told integrators to run `composer require` from
inside the `plugins/` directory (which produces an incorrect install
path) and claimed the package "installs all necessary dependencies".
In practice the published artifact is source-style and relies on the
consumer registering a project-level Composer autoloader.

Restructure the page around that requirement, separate the free and
Premium flows, document the MyYoast token + repository setup for
Premium, and move the contributor-only `yarn` / `grunt build` steps
out of the install guide into a single link to the contributor setup.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@cloudflare-workers-and-pages
Copy link
Copy Markdown

cloudflare-workers-and-pages Bot commented Apr 29, 2026

Deploying yoast-developer with  Cloudflare Pages  Cloudflare Pages

Latest commit: 857284b
Status: ✅  Deploy successful!
Preview URL: https://58e4750f.yoast-developer.pages.dev
Branch Preview URL: https://22545-improve-composer-insta.yoast-developer.pages.dev

View logs

Refer to Yoast SEO by name throughout, distinguishing it from Yoast SEO
Premium where context requires.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant