Markdown Docs Bundle Laravel Package

Technical Evaluation

Release delta (v0.13.0). The first release since 2022-04-20. Contents are maintenance-grade, not feature-grade: PHP 8.1 added to the test matrix (#107), a test-app Kernel fix for Symfony 6 (#111), a "Print action" (#112), removal of package.json/yarn.lock (#113/#114), removed Travis badge (#110), commented-out testing contexts (#115). Every PR is from the same contributor. No breaking changes, no deprecations, no security fixes, no changelog entries affecting the public API. Two findings matter for us: Symfony 6 is now explicitly exercised, which materially softens the Composer-conflict risk for a Laravel 10 host; and the project is alive but not developed — a heartbeat, not a revival. The core recommendation does not change.

Architecture fit. Low as a drop-in dependency. Despite the "Laravel/PHP package" framing, mobizel/markdown-docs-bundle is a Symfony bundle — the name and the Mobizel stack both point there. That means it ships a Bundle subclass, a DI Extension + Configuration tree, Symfony routing (YAML or attributes), Twig templates, and symfony/finder-based discovery of a docs directory. None of those primitives exist in Laravel's service-provider/Blade/routing model. As architecture, the fit is poor; as a reference implementation of "scan a folder of markdown, build a nav tree, render to HTML," the fit is decent — the domain logic is thin and portable. v0.13.0 does not touch this verdict.

Integration feasibility. The valuable core is small: a doc-tree scanner, a slug/route resolver, a markdown→HTML step, and a view layer. That is a 1–2 week extraction for one engineer. The blocker was not code volume, it was Composer gravity — and v0.13.0 improves that picture at the margin:

• Improved: Symfony 6 compatibility is now tested, so a Laravel 10 app (Symfony 6.x components) is more likely to resolve than the prior assessment assumed. PHP 8.1 is validated; 8.2/8.3 remain unverified.
• Unchanged: Laravel 11/12 resolve Symfony 7.x components. Nothing in this release indicates a Symfony 7 constraint, so composer why-not friction is still the expected outcome there.
• Unchanged: Twig remains a hard blocker for a Blade shop, and the DI/config-tree layer remains dead weight we would never invoke.

The extraction effort estimate holds at 1–2 weeks.

Technical risk. Still high on sustainability, moderate on security. Revised on one axis:

• Abandonment — revised from "dead" to "dormant with a pulse." A multi-year gap followed by a maintenance-only release tells us the maintainer responds to low-effort hygiene work but is not investing in the package. Bus factor is still effectively one (single contributor across all of v0.13.0).
• No validation signal — unchanged. ~10 stars, 0 dependents. No production users means no inherited bug fixes or edge-case knowledge. The 0.73 score and 13.32 opportunity score still read as "novel but unproven."
• Rendering surface — unchanged and untouched by this release. Markdown viewers typically allow raw HTML → stored-XSS vector. Route parameters mapped to filenames → path traversal (../). Finder against symlinked trees can loop. v0.13.0 contains no security-related work, and there is still no advisory feed or disclosure policy.
• New, minor: asset distribution ambiguity. Removing package.json/yarn.lock means the frontend build path is gone from the repo. If a downstream fork needs to restyle or rebuild assets, it must determine whether pre-built files ship in the release artifact or whether assets were dropped entirely. Worth one ls in the tarball, not more.
• CI signal, minor positive. Travis badge removal plus an active Actions-style matrix implies CI is being maintained. Weak but non-zero evidence that PRs get merged.

Key questions to resolve before committing (Q4 now partly answered; Q7 new):

1. Which markdown parser does it wrap (league/commonmark, parsedown, michelf/php-markdown)? Determines whether we keep parsing semantics or re-implement them.
2. Does it support front-matter, ordered nav, and per-page metadata, or is the tree purely filesystem-derived?
3. Runtime rendering or build-time compile? Runtime means a request-time file scan and cache-invalidation problem.
4. What are the exact PHP and Symfony version constraints? Partly answered: PHP 8.1 and Symfony 6 are supported and CI-tested. Still open: the exact composer.json constraint string, and whether Symfony 7 / PHP 8.2+ are admissible.
5. Is the doc corpus internal-only or public-facing? Sets the security bar for raw HTML and traversal.
6. Do we get value from the bundle's conventions (nav semantics, URL scheme) that we can't cheaply reproduce?
7. New: What does the "Print action" (#112) actually do — a print-styled view, a ?print=1 variant, a PDF export? Cheap to port if it's a CSS/query-param variant; not worth it if it pulls a renderer dependency.

Integration Approach

Stack fit. Mismatched framework, matched language — unchanged by v0.13.0. A Laravel-native equivalent is roughly: league/commonmark (already present transitively in many Laravel apps), a Route::get('/docs/{page?}') controller, a Blade layout with a nav partial, a Finder/Storage scan, and a response cache. ~300–500 LOC on primitives the team already debugs daily.

Options, ranked:

Compatibility. PHP 8.1 is now CI-proven; PHP 8.2/8.3 presumed fine but unverified. The real question remains the Symfony constraint set versus the host app's resolved symfony/* versions. Update to the check: run composer why-not against both Laravel 10 (Symfony 6) and the actual target version — on Laravel 10 this is now plausible rather than near-certain to fail; on Laravel 11+ expect failure. Twig output is still a hard no; views get rewritten regardless.

Sequencing. Largely unchanged, with the spike cheaper:

1. Spike (2–3 days): clone, read the source, composer why-not against the target Laravel version, confirm parser and nav model, answer Q1–Q7. v0.13.0 does not shorten the reading — it answers one question for us.
2. Decision gate: if the parser is league/commonmark and nav is filesystem-derived, reimplement. If nav is config-driven and non-trivial, fork — accepting that the fork inherits a Symfony 6-era baseline.
3. Build (week 1–2): controller, tree builder, Blade views, route + slug validation, cache layer.
4. Harden (week 3): sanitize rendered HTML (allowlist), reject traversal, cap file size, tests for malformed markdown and missing directories. Do not assume upstream did this — v0.13.0 shows no security work.
5. Rollout (week 4): seed with a real doc set, collect author feedback on front-matter conventions.

Operational Impact

Maintenance. Revised framing: upstream is low-cadence and single-maintainer, not formally dead. The practical consequence is identical — treat any adoption as a fork, and the fork is yours — but the residual hope of upstream patches is now slightly higher for narrow issues (framework compatibility), and still near-zero for feature or security work. Inherited code surface stays tiny (single-digit classes), so carrying cost is low but non-zero. Budget a few hours per quarter for dependency bumps.

Support. No commercial support, no CVE feed, no maintainer SLA. v0.13.0 provides no evidence of a security-disclosure path being established. MIT still permits forking and internal relicensing, so legal risk is nil and continuity risk is entirely operational. Assign a named internal owner before starting — this is unchanged and remains the single most important operational control.

Scaling. Unchanged. Documentation traffic is near-static: rendered HTML cached per page keyed on file mtime, served from CDN, compute cost approaching zero. Two watch items: filesystem scans over hundreds of files at request time, and cold-cache rebuild storms after a deploy touching the docs folder. Compile-at-build remains the safer pattern for a large tree.

Failure modes to design against (none addressed by v0.13.0):

• Docs directory missing or renamed → 500s instead of a friendly 404.
• Path traversal via {page} → arbitrary file read; validate against the resolved tree, never raw input.
• Raw HTML in markdown → XSS; sanitize with an allowlist.
• Symlink loops / unreadable files in Finder → request hangs.
• Cache staleness after content edits → authors see old pages and lose trust.
• Non-UTF8 files → parse failures or mojibake.
• Broken relative links and images → silent 404s in the rendered page.
• New: missing/relocated frontend assets if the package.json removal means styling is now unbuilt or undocumented → unstyled print output.

Ramp-up. Unchanged. A Laravel developer rebuilds this in a day or two with league/commonmark; no Symfony fluency needed on that path. Forking does require Symfony fluency (DI, config tree, bundle bootstrapping), which is scarce in a Laravel shop and is itself a reason to prefer reimplementation. Doc authors need a short convention brief (front-matter keys, nav ordering, image paths) either way.

TPM recommendation. Unchanged: treat this package as a design reference, not a dependency. v0.13.0 is housekeeping — a maintained CI matrix and a Symfony 6 fix, plus a minor print feature. It reduces integration friction for a Laravel 10 host by a notch and does nothing to address abandonment, security posture, or Twig coupling. The opportunity score (13.32) still reflects a niche, unproven idea rather than a weak one: the idea is sound, the artifact is not a dependency. Rebuild natively.

What would flip this recommendation: a Symfony 7 / PHP 8.3 constraint bump with an active release cadence (2+ releases per year), a security advisory process, or evidence of third-party production use (dependents > 0). Any one of those would justify reopening the fork option; none is present in v0.13.0.