Realdom Laravel Package

Getting Started

hoa/realdom is a grammar-driven sampler: you hand it a grammar (the Hoa LL(k) dialect used by hoa/compiler) and it emits random-but-structurally-valid documents. It was the generation half of Hoa's testing toolchain. It is archived (last tag 1.17.01.13, 2017-01-13), has 7 stars, zero dependents — treat the decision to install it as "I am adopting this code," not "I am consuming a dependency."

1. Pin the runtime first. This is PHP 5.5–7.x-era code. Do not add it to an 8.x application. Run it in an isolated CLI container (php:7.1-cli) or a dev-only image, with its own composer.json.
2. Install and freeze.

   composer require hoa/realdom
   composer lock   # commit it; nothing upstream will ever fix a break
   

3. Verify autoloading. require 'vendor/autoload.php'; usually suffices, but older Hoa tags rely on hoa/consistency's own autoloader rather than a PSR-4 map. If Hoa\Realdom\* is not found, check that Hoa\Consistency\Autoloader is registered before blaming your app's autoload config.
4. Where to look, in this order: README.md (short, example-driven) → Hoa/Realdom/Realdom.php (the entire public surface) → the sampler/visitor classes (where the generation actually happens) → Test/Unit/ (the only guaranteed-working usage examples) → hoa/compiler's bundled grammar resources for a known-good grammar to feed it.
5. First use case: build a corpus of 100 sample documents that your parser, validator, or import pipeline must accept, then assert it never throws.

require 'vendor/autoload.php';

// Copy the constructor call verbatim from the README of the tag you installed —
// the signature drifted between releases and there is no API doc to fall back on.
$realdom = new Hoa\Realdom\Realdom(/* grammar, see Test/Unit for a working argument */);

for ($i = 0; $i < 100; ++$i) {
    file_put_contents(__DIR__ . "/fixtures/case-$i.xml", $realdom->generate());
}

If that snippet doesn't run in ten minutes, stop — the package has not earned more of your day than that.

Implementation Patterns

Data-provider generator. The highest-leverage integration is a thin factory that returns N samples into a PHPUnit data provider or an atoum dataset. Keep the factory in your own namespace so tests never import Hoa classes directly.

Single source of truth for the grammar. Feed Realdom the same grammar your parser is compiled from. Generated documents are then syntactically valid by construction, so any failure is a real bug in the consumer — this is the one thing Realdom does that Faker cannot.

Generate → validate loop. Realdom guarantees structure, not semantics. Pair it with a schema validator (libxml/XSD, respect/validation) to catch business-rule bugs, and let the sampler find the structural edges.

Snapshot mode for CI. A random generator in CI means flaky red builds on the day upstream disappears. Run generation once on a developer machine, commit the corpus, and point CI at the fixtures. Keep a --regenerate switch for deliberate churn.

Seed everything. The sampler draws from PHP's global RNG. Call mt_srand($seed) (and srand($seed)) before the first generate() and expose the seed in your test command so failures are reproducible.

Adapter behind an interface. Wrap it:

interface SampleGenerator { public function generate(int $n): iterable; }

You will want to swap it for Faker, eris/eris, or hand-written fixtures eventually — make that a one-file change.

Batch/console command. A small Artisan or Symfony command (xml:sample --count=500 --out=fuzz/) is the natural day-to-day entry point; nobody should be calling the library from controllers.

Gotchas and Tips

• PHP 8 is a hard stop. Hoa internals hit removed language features and the consistency layer breaks. Pin PHP ≤ 7.1 for the tool container; never let this land in the app's runtime requirements.
• Composer will fight you. Hoa packages pin each other tightly; dropping Realdom into a modern Laravel app triggers conflicts over hoa/compiler, hoa/stream, and hoa/consistency. Isolate it as a dev tool with its own lockfile rather than resolving it in the main graph.
• Abandoned means abandoned. No security patches, no PHP 8 support, no issue triage. If it becomes load-bearing, fork it into app/Support/ (or a private package), strip the hoa:// stream-wrapper dependency, and own it explicitly.
• Non-determinism is the default. Without seeding, every run differs — including on the machine of whoever debugs it tomorrow. Seed, log the seed, and print it in the test failure message.
• Unbounded grammars hang. Recursive productions can loop or explode memory. Cap sample size, set max_execution_time, and abort a batch after N seconds rather than debugging a stuck process.
• hoa:// URIs only resolve after bootstrap. hoa://Library/... paths fail if you require files manually or reorder the bootstrap. Let the consistency autoloader come up first.
• Errors are cryptic. A malformed grammar surfaces as an AST/visitor traceback, not a message. Dump the compiled AST from Hoa\Compiler before assuming Realdom is at fault — usually the grammar is.
• The extension seam is the sampler/visitor layer. When you need domain-realistic values (names, dates, currency strings) inside a valid skeleton, implement a custom sampler rather than post-processing the output with string surgery.
• Wrong tool for plain fixture data. If you don't need grammar-conformant structure, use fakerphp/faker; for property-based testing, use eris/eris; for schema checks, respect/validation. Realdom's only defensible niche is "many structurally valid documents from one grammar," and that niche is small enough that most teams should reach for it exactly once, evaluate for an hour, and move on.