ci: parse and analyse the documentation's PHP examples

[DannyvdSluijs]

Follow-up to #63 / #68 — the preventative half of that issue, for this repo.

Why

The package these pages document lives in
JsonMapper/JsonMapper, so nothing in the build compiles the
examples. A snippet that is not valid PHP renders perfectly and ships broken. That is how the drift in
#63 survived: the Setup page called JsonMapperBuilder::create(), a method that does not exist, and the
landing page passed a JSON string to mapToClass(), whose first parameter is a \stdClass. Both looked
fine on the page.

What this adds

.github/scripts/lint-code-examples.php pulls every ```php fence out of _docs/ and
resources/includes/ and runs php -l over each one, then
.github/workflows/lint-examples.yml runs it on pull requests and pushes to main.

Failures are reported against the markdown file and the line the fence starts on, not the temporary
file the linter actually saw:

::error file=_docs/middleware/rename.md,line=22::syntax error, unexpected token ";"

1 of 31 code blocks in 24 files failed to parse.

Blocks are linted individually, because that is how a reader meets them. A fence may or may not open
with its own <?php; the script normalises to exactly one and tracks whether that shifted the code, so
the reported line stays correct either way. Both shapes were tested by deliberately breaking a fence of
each kind and confirming the reported line matched the break.

Scope

It is a parse check and nothing more — it will not tell you an example is wrong, only that it is not
valid PHP. Actually running the examples means installing json-mapper/json-mapper here and pinning a
version, which is the coupling this repo has so far avoided. The linter needs only a PHP binary and no
Composer install, so the job takes seconds.

That leaves the stronger check — executing the examples against a real package — as a candidate for the
package's own repository, where the dependency already exists.

Also

The README gains a Code examples section, since the conventions are now partly enforced: full class
names with no import block (and the namespace-declaring exception), examples defining the classes they
map onto rather than pointing at the package's test fixtures, and "Available since" only for APIs added
during 2.x.

Run it locally with:

$PHP .github/scripts/lint-code-examples.php

Currently: All 31 PHP code blocks in 24 files parse cleanly.

🤖 Generated with Claude Code

---

Update: a second pass that catches more than parse errors

A parse check alone is too weak, and #63 proves it — every defect in that issue was valid PHP.
JsonMapperBuilder::create() parses perfectly and does not exist.

So this PR now runs two passes. The second installs json-mapper/json-mapper as a dev dependency and
runs PHPStan against it, checking the examples against the API they actually document.

I verified it by re-introducing five of the original defects. The parse pass stayed green; the analysis
pass caught all five, on the right page and the exact line:

All 31 PHP code blocks in 24 files parse cleanly.          <- pass 1, still green

::error file=_docs/middleware/attributes.md,line=29::Call to an undefined method …User::getId().
::error file=_docs/usage/setup.md,line=35::DocBlockAnnotations constructor invoked with 0 parameters, 1 required.
::error file=_docs/usage/setup.md,line=48::Call to an undefined static method PropertyMapperBuilder::create().
::error file=_docs/usage/setup.md,line=53::Call to an undefined method JsonMapperBuilder::withJsonMapperClass().
::error file=resources/includes/home-example.md,line=12::Parameter #1 $json of mapToClass() expects stdClass, string given.

Six of the seven defect shapes from #63 are now caught. The seventh —
(new JsonMapperFactory())->create() with no middleware — is valid, well-typed, and throws only at run
time, so no static analyser can see it. That would need the examples executed, which is better placed
in the package's own repository where the dependency already exists.

How the line numbers work

The extractor keeps every line at its markdown line number, blanking out whatever is not code, so
PHPStan's "line 48" is line 48 of the page. No line map, no translation.

Examples are extracted per page, because pages routinely define a class in one fence and map onto it in
the next, and each page gets its own namespace so the User that several pages define does not
collide. A fence declaring its own namespace becomes its own analysed file.

Placeholders

Classes the examples borrow from the reader's application, or from companion packages that conflict
with Hyde's dependencies, are declared in .github/stubs/placeholders.php. Where a real package does
coexist it is required instead of stubbed — json-mapper/laravel-package and monolog/monolog are
installed, so the Laravel and debugging pages are checked against genuine classes.

Four examples now name their placeholders in full (\App\Models\License,
\JsonMapper\SymfonyBundle\JsonMapperBundle, and so on), which matches the site's fully-qualified
convention. The final-callback example dropped a Cache::put() line that referenced an undefined
$seconds and stood for nothing in particular.

Job runs in 23s.

---

Update: the documented version is now read, not written

_docs/index.md used to claim "These pages describe JsonMapper 2.25.1" in prose — a number
nobody would remember to change. Now that the examples are analysed against an installed
json-mapper/json-mapper, the version the site documents and the version its examples are checked
against are the same fact, so it is read from Composer instead.

App\Support\DocumentedVersion resolves it, and config/docs.php renders it once, at the foot of
the documentation sidebar next to the existing links:

GitHub · Twitter · Documenting JsonMapper 2.25.1

Bumping the dependency now updates the site. No version number is hardcoded in any page.

The --no-dev catch. Composer\InstalledVersions only knows about installed packages, and the
deploy workflow runs composer install --no-dev while JsonMapper is a dev dependency — so at build
time it is absent and getPrettyVersion() throws OutOfBoundsException. The resolver falls back to
composer.lock, which ships either way and pins the same version.

Verified rather than assumed: both branches were exercised directly, and a full --no-dev build was
run end to end, which still rendered Documenting JsonMapper 2.25.1 in the sidebar.

A dev- branch alias resolves to no version at all rather than printing something meaningless, in
which case the sidebar simply omits the line.