[DannyvdSluijs]

Resolves the site-side items of #63.

Every claim in the issue was checked by executing the documented snippets against the real package
(JsonMapper/JsonMapper, develop, 4 commits past 2.25.1) rather than by reading. That changed
several of the issue's conclusions — see Findings below.

Findings that differ from the issue

mapToClass() is not unreleased. It has existed since 2.14.0. The defect is its signature:
mapToClass(\stdClass $json, string $class). The landing page passed a JSON string, so the first
snippet a new user sees died with a TypeError. The method that takes a string is
mapToClassFromString(). The site was never ahead of the release here.

The builder's constructor is new(), not create(). Item 1 resolves in favour of the landing
page. JsonMapperBuilder::new() was already used correctly on five other pages; only the Setup page
used ::create(), which exists on neither builder.

withProperyMapper is a docs-only typo — there is no API defect. git log -S finds no commit
ever introducing that spelling in src/. No alias and no deprecation are needed, so the follow-up
issue item 4 contemplated can be dropped. This also settles item 5: with the typo gone, the
"property mapper set twice" chain was one dead call plus one real one, so the dead call is removed
rather than corrected.

What was fixed

Code that could not run

Page	Was	Now
Landing page	mapToClass('{json}', …) → TypeError	mapToClassFromString()
Setup	JsonMapperBuilder::create(), PropertyMapperBuilder::create()	::new()
Setup	withJsonMapperClass()	withJsonMapperClassName()
Setup	withProperyMapper(…)	removed — dead call
Setup, Architecture	new DocBlockAnnotations() → ArgumentCountError	cache argument passed
Laravel Eloquent	create() → BuilderException (empty middleware chain)	bestFit()
Attributes	getId()/getName() on a class with public properties and no getters	->id / ->name
Laravel usage	$mapper declared as both a property and a promoted constructor argument → redeclaration fatal	promoted property only
Value transformation	callback 'srtolower'	'strtolower'
Abstracts	$object = AbstractShapeWrapper(); — no new	new AbstractShapeWrapper()
Interfaces	chain never called build(), so $mapper was a builder	->build() added

The last five were not in the issue.

Copy-pasteability (issue item 6)

The convention is settled as fully-qualified class names with no import block, applied site-wide.
That is what the site already did in most places, and it keeps a snippet short enough to read without
scrolling — an import block costs five or six lines before the reader reaches any working code.

Snippets that represent a real file in the reader's application — the ones declaring their own
namespace — keep their imports, since that is what a reader would actually write. The convention is
written down in CLAUDE.md so it stops drifting.

Four pages mapped onto \Tests\JsonMapper\Implementation\SimpleObject. The real fixture is
JsonMapper\Tests\Implementation\SimpleObject (the README's form), but as the issue notes, a class
from the package's test suite does not exist in a reader's application either way — so those examples
now define the small class they map onto (issue item 3).

The debugging page used Psr\Log\Test\TestLogger, which ships only with psr/log ^1.1 — one of the
three majors JsonMapper accepts — so it is written against a plain PSR-3 logger instead.

The creating-middleware page's prose was also wrong, which the issue did not catch: it described a
MiddlewareInterface::process() that takes and returns the object, and an addMiddleware() method on
JsonMapper/JsonMapperFactory. The interface method is handle(), it amends its arguments in place,
and middleware is added with the builder's withMiddleware().

Version annotations (issue item 8)

The docs index now names the release these pages describe, and an "Available since" line is added for
each API that landed during 2.x — taken from the tag that first shipped the class:

API	Since
Rename	2.2.0
ValueTransformation	2.9.0
StrictScalarCaster / PropertyMapperBuilder	2.10.0
Constructor	2.14.0

Middleware that predates 2.0 gets no line. The site documents v2, so a reader is assumed to be on it
and "available since 0.1.0" answers a question nobody has.

Verification

All 31 php fences were extracted and run against the real package, with canned HTTP responses and
stub files for reader-owned and framework classes:

• 31/31 pass php -l
• 18/18 executable pages run clean
• every documented output matches its inline comment exactly (42John Doe, john doe, A Meowtain., …)
• the site builds; no stale API reference survives in _site/
• composer validate --strict is clean

Not executed: the Laravel and Symfony guides and the Eloquent page, which need those frameworks
installed. The Symfony page was checked by hand against the bundle's services.xml — its
JsonMapper\JsonMapper type-hint matches the registered service id and is correct as written.

What is left

Item 7 — the stale README feature list. Out of scope here: the README lives in
JsonMapper/JsonMapper and needs its own PR. It lists 6 features against the site's 11+, omitting
constructor support, rename, value transformation, PHP attributes, Laravel Eloquent, enums and
readonly properties. Its own code example is correct as written, so only the list is stale. Packagist
renders that README, so the package's most-visited page understates the feature set by roughly half.

The preventative measures. Also JsonMapper/JsonMapper work:

• Executable examples in CI — the only measure that stops items 1, 2, 4 and 6 recurring. The harness
  built to verify this PR is a working starting point.
• Single source for the feature list — generate the README's list from the same data as the site's
  middleware index.

A convention to keep. New middleware and builder pages should carry the "Available since" line, and
the version named on the docs index needs bumping at each release.

Refs #63

🤖 Generated with Claude Code