Bbcodeparser Laravel Package

Technical Evaluation

Architecture fit. golonka/bbcodeparser is a standalone, framework-agnostic PHP text transformer: raw BBCode in, HTML string out. It is not a Laravel package — no service provider, no facade, no publishable config, no Blade directive. In a Laravel codebase it occupies the same architectural slot as a Markdown renderer (e.g. league/commonmark): a pure, stateless presentation-layer concern invoked at render time or during write-time normalization. If the product has no legacy BBCode content and no user base fluent in BBCode, this dependency adds surface area without solving a live problem. Its real value is narrow and specific: preserving rendering fidelity for legacy forum/comment bodies already stored as BBCode.

Integration feasibility. High effort-to-value ratio is favorable in the narrow case. The library is small, MIT-licensed, and has a simple imperative API (instantiate parser, register filters/rules, call parse()), so wrapping it in a Laravel service is a ~50-line adapter. There is no auto-discovery, so wiring is entirely on us: a singleton binding behind an interface, a BBCode::parse() facade if desired, and a Blade directive only if templates need it. Because it has zero dependents and one star on this fork, we are effectively adopting an unmaintained library and must own the integration glue ourselves.

Technical risk. The dominant risk is staleness, not complexity. Last release 2019-07-30 places it in the PHP 7.x era; Laravel 10/11 require PHP 8.1/8.2, and nothing in the repo's history confirms 8.x CI coverage. Deprecations (dynamic properties, implicit nullable params, each()-style constructs) are plausible and would surface only on the affected code paths. Second risk is output safety: BBCode parsers are XSS-adjacent by design — [url], [img], and any raw-HTML pass-through option must be verified against javascript: schemes, data: URIs, and attribute-breaking quotes. Third is fork provenance: this is a derivative of juiceland/BBCodeParser, so CVE response, if any, lands on us.

Key questions. Which PHP versions are actually exercised in CI (or must we add it)? Does the parser emit escaped attributes for [img src=...] and [url href=...], and can raw HTML be disabled entirely? Which tags/filters ship enabled by default versus requiring registration? Is the parser fully stateless and safe as a container singleton under Octane? What is the fork's relationship to upstream, and are we willing to vendor and patch it?

Integration Approach

Stack fit. Fits cleanly as an infrastructure adapter in the domain/presentation boundary. Define an internal BbcodeRenderer interface with render(string $bbcode): string, implement it with a thin GolonkaBbcodeRenderer that owns parser construction and filter registration. Bind it as a singleton in a dedicated service provider. This keeps the third-party namespace out of controllers, models, and Blade templates, so the dependency is replaceable in one file.

Migration path. Treat stored BBCode as immutable source data. Do not attempt a bulk BBCode→HTML rewrite as step one; render on read and cache the output (keyed by content hash + parser version). This gives a rollback-safe path: if the renderer is swapped or patched, cache keys invalidate and content re-renders correctly. If the strategic direction is Markdown/CommonMark, run both renderers in shadow mode on a sample of real content, diff the outputs, and only then decide between (a) dual-render with a per-record format flag or (b) a one-time conversion job that rewrites the source column.

Compatibility. Pin the exact version in composer.json (no caret range) and commit the lockfile. Before adoption, build a smoke-test corpus of 30–50 representative real posts — nested quotes, lists inside lists, unclosed tags, URLs with query strings, code blocks containing angle brackets, emoji/multibyte text — and run it under the target PHP version. If PHP 8 incompatibilities appear, fork to app/Support/BbcodeParser under MIT attribution with phpunit coverage around the corpus; the fork cost is low because the codebase is small.

Sequencing. (1) Corpus + compatibility spike on target PHP. (2) Adapter, interface, and provider behind a feature flag. (3) Shadow-render comparison against current production output. (4) Enable for read paths with cache and length caps. (5) Only then consider write-time normalization or format migration. Do not sequence migration before the adapter is stable — the adapter is the rollback lever.

Operational Impact

Maintenance. Effectively zero upstream maintenance; plan for us to be the maintainer. Budget a recurring (quarterly) review: PHP/Laravel upgrade compatibility, dependency audit, and re-running the golden corpus. Keep the fork or pinned version documented in an ADR so future maintainers understand why a 2019 library is in the tree.

Support. No vendor, no SLA, no security contact. Support burden is internal and modest given the small code surface, but it lands on whoever owns the rendering layer. Ensure the ADR names an owning team and a deprecation trigger (e.g. "retire when <5% of content is BBCode").

Scaling. Parsing is CPU-bound regex/string work, linear in input size, and stateless — it scales horizontally with the app tier. The practical concerns are unbounded input and nesting: cap BBCode body length and tag nesting depth before parsing, and cache rendered HTML (Redis/file) so hot pages never re-parse. Rendering at read time without a cache is the only realistic throughput problem.

Failure modes. Malformed or unclosed tags producing truncated output; deeply nested [quote]/[list] causing pathological regex backtracking; XSS via unvalidated URL/image attributes; silent data loss if a filter throws and the exception is swallowed; cache staleness after a parser patch (mitigate by including parser version in cache keys). Instrument render failures with the offending record ID and fall back to escaped plaintext rather than raw or empty output.

Ramp-up. Low for any PHP developer — the API is a handful of methods and the domain concept (BBCode) is well understood. The real ramp-up cost is tribal knowledge of which tags the community actually uses and how tolerant the parser is of their malformed variants; capture that in the golden corpus rather than in prose. Estimate half a day for the adapter, one to two days for the corpus and compatibility verification, and one day for caching and observability wiring.