Download the PHP package zergius-eggstream/amp-converter without Composer

php-amp-converter

Convert rendered HTML pages into AMP-valid HTML — pure PHP, no Node runtime.

PHP port of the Node-based convert-rendered-to-amp.js shipped with the amp-seo-sites toolset. Designed for build-time conversion of pre-rendered HTML into AMP HTML that passes the official amphtml-validator, with no Node runtime in the conversion path.

Status

Port complete, ready for review. All 13 algorithm stages implemented and exercised end-to-end on a real-world ~119 KB rendered page (covering amp-img, amp-youtube, amp-iframe, amp-bind burger, amp-accordion FAQ, inlined external CSS, JSON-LD); PHP output sits within 0.1 % of the Node reference (113.6 KB vs 113.7 KB, structurally identical AMP). 258 phpunit tests / 513 assertions; PHPStan level 8 clean. CI runs on PHP 8.4. Stage map: doc/port-status.md.

Requirements

• PHP >=8.4 (will be lowered if no 8.x features end up being required)
• ext-libxml, ext-mbstring, ext-simplexml
• ext-gd is NOT required at runtime. Raster image dimensions come from getimagesize(), which is part of PHP core; SVG parsing uses ext-simplexml. GD is only used by the unit tests to generate PNG fixtures, and the affected tests auto-skip when GD is absent. The package works fine on slim production servers that don't have GD loaded — that path is exercised in CI under the no-gd matrix entry.
• No Node.js — pure PHP

Installation

Once the maintainer of the consuming projects forks/republishes the package under their preferred vendor, that require line points at the new name (the namespace stays AmpConverter\ so call sites don't change).

Usage

Arguments:

The package is intentionally agnostic about where the host gets canonicalUrl from (TSV, per-site config, request data, hard-coded mapping, …) — that's a host concern. The package just emits what it was given.

ConversionResult exposes:

• html: string — the converted AMP HTML.
• usedComponents: list<string> — AMP custom components actually emitted (amp-img, amp-youtube, amp-iframe, amp-bind, amp-accordion, …). The pipeline emits a <script async custom-element="…"> for each one (except amp-img, which ships with v0.js).
• warnings: list<string> — non-fatal issues encountered (unresolvable image, dropped CSS block, malformed tag, …). The host project decides whether to log, surface or ignore them.

Symfony integration

The package is framework-agnostic. A typical Symfony host wires it through a thin one-line autowired service:

If a future iteration ships a Symfony Bundle for zero-config auto-wiring (Bridge/Symfony/AmpConverterBundle), it will be additive — the framework-agnostic core won't change.

Architecture

The converter is an ordered pipeline of transformers. Each transformer implements Transformer::apply(string $html, Context $ctx): string and owns one feature area; Context carries cross-transformer state (siteRoot, used components, warnings, detected FAQ classes, font @imports collected from CSS, …).

Replace the default pipeline by constructing AmpConverter directly:

Error handling

Strict but graceful: when the converter cannot transform a fragment (unparseable <img> tag, malformed CSS block, missing image dimensions), it removes the fragment and records a warning rather than throwing. The whole page still converts. Build pipelines decide what to do with warnings (log / fail / ignore). Exceptions are reserved for unrecoverable programmer errors (e.g. invalid pipeline configuration).

Testing

Layout:

• tests/Unit/<Area>/<Class>Test.php — per-rule unit tests for every transformer; each spec rule has its own positive + negative test.
• tests/Regression/EndToEndSmokeTest.php — end-to-end smoke test on a real rendered page. Reads the fixture directory from the AMP_CONVERTER_SMOKE_FIXTURE_DIR environment variable; auto-skips when the variable is unset or the path is missing, so CI just runs the unit tests.

CI is GitHub Actions over PHP 8.4 with the libxml, mbstring, simplexml, gd extensions; no Node required.

License

MIT.