Macdom Laravel Package

Technical Evaluation

Architecture fit: Macdom is a standalone PHP HTML preprocessor, not a Laravel package. It does not naturally fit Laravel’s request lifecycle, Blade rendering, view composers, middleware, or caching abstractions. It is only a reasonable architectural fit if the need is build-time or offline HTML transformation for static/marketing/email-like assets, not runtime application templating. Using it alongside Blade would create a dual-templating model with separate escaping, testing, caching, and ownership concerns.

Integration feasibility: Likely installable through Composer, but there is no evidence of Laravel service providers, facades, configuration publishing, or framework integration. Integration would require a thin internal adapter and probably an Artisan command or build script. The package’s last release was 2017-10-08, so PHP 8.x compatibility, dependency freshness, PSR-4 autoloading, and parser behavior must be proven before adoption. BSD-3-Clause is permissive and permits a fork, which is the main mitigation if the capability is valuable.

Technical risk: High. Signals include 11 stars, a low health score of 0.145, no release since 2017, and an unknown repository in the supplied metadata. This implies weak maintenance, unclear provenance, limited community support, and likely compatibility drift with modern PHP/Laravel. Other risks include HTML parsing edge cases, unsafe escaping if user content is processed, silent output changes, abandoned-package security scanner flags, and no upstream security response process. The package should not become a strategic runtime dependency without a fork-and-own plan.

Key questions: What exact preprocessing feature is required, and can Blade components, Twig, Latte, or a simple internal preprocessor replace it? Must Macdom run per request, or can it run only at build time? Which PHP versions and dependency versions does it actually support? How does it handle escaping and untrusted HTML? Can outputs be cached and invalidated deterministically? Who will own a fork if PHP 8/9 compatibility breaks? Is the repository provenance verifiable? What is the rollback and exit plan?

TPM recommendation: Reject for Laravel runtime templating. Conditionally accept only for an isolated, non-critical, build-time use case with a pinned version, golden-file tests, security review, and a funded fork/exit plan.

Integration Approach

Stack fit: Poor for runtime Laravel integration; acceptable for an isolated CLI/build step. If used, invoke Macdom from an Artisan command or CI job that writes compiled HTML to public/build or storage, then serve static output through Laravel/CDN. Keep Blade as the application view engine. Do not introduce Macdom as a parallel runtime template engine for normal application pages.

Migration path: Do not migrate existing Blade views wholesale. Run a bounded proof of concept against one non-critical template set. Wrap Macdom behind an internal interface such as HtmlPreprocessor so the implementation can be replaced. Compare rendered output against current templates with golden files. If the POC does not show a clear capability or cost benefit, retire it and use Blade components or an actively maintained template engine.

Compatibility: Verify Composer platform requirements against the target Laravel/PHP matrix. Pin the exact package version and, if possible, a commit hash. Add static analysis, unit tests, and golden-output tests in CI. Check transitive dependencies for conflicts and security advisories. If PHP 8 compatibility fails, either fork and patch or stop.

Sequencing: 1) Confirm the business need and alternatives. 2) Review source, license, repository provenance, and dependencies. 3) Run a PHP/Laravel compatibility spike. 4) Test escaping, malformed HTML, and output determinism. 5) Build an internal adapter and Artisan command. 6) Add CI golden tests and cache invalidation. 7) Canary one static page or asset set. 8) Document rollback. 9) Decide whether to fork, contain, or retire.

Operational Impact

Maintenance: High. There is no active upstream release history after 2017, so the team must own PHP compatibility, parser bugs, security review, and dependency updates. Prefer a require-dev or build-only dependency if possible. If the capability is retained, assign an internal owner and budget for fork maintenance.

Support: Weak. With 11 stars and no recent releases, community support is minimal. There is no vendor SLA. BSD-3-Clause allows a fork, but forking transfers all support burden internally. Create a runbook covering build invocation, cache behavior, escaping rules, rollback, and known parser limitations.

Scaling: Acceptable only as a compile-time preprocessor with cached outputs. Runtime preprocessing would add CPU cost, latency variance, and cache complexity to request handling. Precompile assets, use content-hash cache keys, and serve through Laravel/CDN. Avoid preprocessing unbounded or user-generated HTML.

Failure modes: PHP fatal errors after PHP upgrades; Composer dependency conflicts; parser failures on malformed HTML; escaping mismatches leading to XSS; silent output drift after template changes; stale build cache; abandoned-package security flags; and loss of upstream patches. Mitigate with exact version pinning, golden tests, input sanitization, fail-closed build behavior, and a documented rollback to Blade/static output.

Ramp-up: The API surface is likely small, so initial ramp-up is low: roughly 1–2 days for a proof of concept. Hardening for production use is higher: roughly 1–2 weeks for compatibility, escaping, CI, caching, and rollback work. If the team must fork and maintain the package, plan for ongoing engineering ownership rather than a one-time integration.