Generate PHP API documentation automatically

[erseco]

Summary

• generate a complete PHP API reference from source PHPDoc with phpDocumentor
• publish generated API HTML under site/api-docs/ alongside the existing MkDocs site
• pin phpDocumentor to v3.10.0
• verify the downloaded PHAR with its release SHA-256 digest before execution
• run documentation builds on pull requests that touch source or docs
• deploy GitHub Pages only from pushes to main
• verify both the MkDocs entry point and generated API entry point before deployment
• add a documentation page linking the curated API guide and generated PHP reference
• link generated API docs from the README

Stack

This is the first PR in the new quality/supply-chain stack and targets main.

Validation

The regular PHP 8.0–8.5, coverage, Composer, PHPCS and PHPStan checks are green. Opening this PR also exercises the documentation build without deploying it.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.4%. Comparing base (2ad7287) to head (4245383).

Additional details and impacted files

@@           Coverage Diff           @@
##              main     #34   +/-   ##
=======================================
  Coverage     92.4%   92.4%           
  Complexity     801     801           
=======================================
  Files           30      30           
  Lines         2639    2639           
=======================================
  Hits          2441    2441           
  Misses         198     198           

Flag	Coverage Δ
unit	92.4% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.