Terms Module Chromium Bundle Laravel Package

Getting Started

The package now identifies itself as a Chromium Generator (v1.0.0, "Initial version"). That reframes what the bundle is for: it is more likely a generator module in the rich-id ecosystem (code/scaffold generator, or a headless-Chromium-backed generator) than a runtime "render the terms page" helper. Read the source before assuming either way — the terms-module prefix in the package name is now much weaker evidence of the package's actual job than the v1.0.0 release note.

1. Install and pin the exact tag first:

   composer require rich-id/terms-module-chromium-bundle:1.0.0
   

   There is still only this one release and no downstream users to copy fixes from. Pin now; don't let Composer float you onto a hypothetical 1.1.0.

2. Read composer.json for two things, not one. First, Laravel/PHP constraints (as before — do not assume Laravel 11/12 works). Second, what the generator actually depends on: symfony/panther, spatie/browsershot, chrome-php/*, a Twig/Blade stub directory, or nothing at all. That require block is the fastest answer to "is this a headless-browser wrapper or a code scaffolder?"

3. Locate the generator entry point. Grep the source for Generator, generate(, class Chromium, and any Contract/Interface. In v1.0.0 there is likely a single ChromiumGenerator class with one or two public methods. That method signature is the entire API surface.

4. Smoke test with the smallest possible input — a single string or array in, an artifact out (generated file, HTML string, PDF, or class file). Do this on a known-good input before wiring it into a controller. You are not debugging your app yet; you are debugging whether Chromium launches, templates resolve, and output lands somewhere.

5. Confirm where output goes. If it writes to disk, verify the path is not inside vendor/. If it returns a string, verify the string actually contains what you expect. This is your integration contract for everything downstream.

Implementation Patterns

The v1.0.0 note confirms this is a generator, so the working pattern is: call it from a service you own, treat the output as an artifact, and never call it inline on a request that needs to respond quickly.

• Wrap behind your own interface. App\Contracts\TermsGenerator with a Chromium implementation that delegates to the package. When the package is abandoned (single release, zero stars — assume it will be) you swap one binding, not every call site.
• Queue it. If it launches a browser or renders PDFs, a request-scoped call will blow your PHP execution time on any non-trivial input. Dispatch a GenerateTermsJob, return a job ID to the caller, and expose a status endpoint. This is the single biggest architectural decision — make it before the first real invocation, not after.
• Cache keyed by input hash. Generator output is deterministic for a given input + version. cache()->remember('terms-gen:' . sha1($input) . ':v1.0.0', $ttl, fn () => $generator->generate($input)). Include the package version in the key so a future upgrade doesn't serve stale artifacts.
• Store artifacts on a named disk. Storage::disk('terms')->put($path, $result). Keeps the package's output path out of your public tree unless you deliberately expose it, and makes cleanup / re-generation straightforward.
• Config over code. Publish the config, commit it, and drive paths, binaries, timeouts, and template locations from config/terms-chromium.php (adjust name to what publishes). Any hardcoded binary path you find in the source is a bug waiting to happen in Docker.
• Feature-flag the integration. Given the package's immaturity, gate callers behind config('features.chromium_generator') so you can turn it off without a deploy if it starts failing in production.
• Escape hatch still stands. If the generator turns out to be 40 lines around a browser you already run elsewhere, or it depends on unpublished rich-id internals (check require and any repositories entry), reimplement it. A v1.0.0 with no users is cheap to fork and cheap to replace.

Gotchas and Tips

• "Chromium" almost certainly means a browser now. v1.0.0's "Chromium Generator" naming is direct. That means the deployment surface just got bigger: your PHP container needs a Chromium/Chrome binary on PATH, --no-sandbox if it runs as root in Docker, and enough shared memory (--shm-size=1g or --disable-dev-shm-usage). Budget that into infra work, not application work.
• Fonts in containers. If the generator renders HTML → PDF/image, missing fonts produce silent layout failures that will not appear on your Mac. Install fonts-liberation (or equivalent) in the image and verify output inside the container.
• Timeouts and memory. Chromium is a memory hog. Set a generation timeout in config, set memory_limit high enough for the worker, and put a retryUntil / maxExceptions on the queued job. A hung Chromium process is a hung queue worker.
• Config caching. php artisan config:cache silently drops config values the generator reads lazily from boot(). First debugging step for "it worked yesterday" is still php artisan config:clear.
• Route name collisions. If v1.0.0 registers any routes (generator dashboards / preview endpoints are common), check with php artisan route:list | grep -i terms before assuming the namespace is yours.
• PHP 8.2+ deprecations. Written in 2023 likely means 8.0/8.1 targets. Run with error_reporting(E_ALL) and watch the log — dynamic properties and Serializable are the usual suspects.
• The terms-module prefix may now be misleading. The v1.0.0 note describes a generator, not a terms renderer. Do not wire it in assuming it renders a terms page. Confirm by reading the main class before writing any Blade view against it.
• No upstream support path. Zero stars, zero dependents, single-release history still describes the support situation accurately. Fork to your org (repositories.vcs in composer.json) the first time you need a patch, and pin the fork by commit SHA in composer.lock.
• Read first, commit second — still true, and now more literal. v1.0.0 could mean "the package is brand new and undocumented," or "the Oct 2023 release was a 0.x precursor and this is the real initial release." Either way, the source is still the spec.