Docxmustache Laravel Package

Getting Started

• Install with composer require <vendor>/<package> and note the version constraint — 0.0.44 is pre-1.0, so pin exactly ("0.0.44") or use ~0.0.44 rather than ^0.0 if you value stability.
• Publish the config first (php artisan vendor:publish --tag=...) and read it end-to-end before writing any cleaning logic; the allowed-tag list, attribute whitelist, and encoding options are almost always the source of "the cleaner ate my markup" bug reports.
• Locate the cleaner implementation and its test suite. As of v0.0.44 the tag cleaning path is no longer regex-based, so the authoritative behaviour is whatever the tokenizer/parser tests assert — read those tests as the spec, not the README.
• First use case: sanitise a single untrusted rich-text field (e.g. posts.body from a WYSIWYG) on the way into the database. Start with one field, one entry point, and a fixture set of "dirty" HTML before wiring it into middleware or a global pipeline.
• Verify the happy path with a quick tinker session: clean a string containing a script tag, an onclick attribute, and an unclosed <b> — confirm both the output and that no exception is thrown on malformed input.

Implementation Patterns

• FormRequest prepareForValidation() — the cleanest default for user input. Clean the specific fields there, so controllers and models stay unaware of sanitisation and the rule set is testable in isolation.
• Middleware for bulk/prose endpoints — apply cleaning to a configured list of request keys (not the whole payload) when many routes accept HTML. Keep it opt-in per route group; blanket middleware on api/* tends to mangle JSON that legitimately contains angle brackets.
• Model mutator / custom cast — good for "this column is always HTML". Centralises the policy, but be deliberate: mutators fire on every assignment, including seeded and imported data, which can silently rewrite content you trusted.
• Clean on input, escape on output — the safe pairing. Store the cleaned-but-not-escaped string, and still use {{ }} in Blade. Treat the cleaner as defence-in-depth, not a replacement for output escaping.
• Bulk/backfill work in a queued job — when retrofitting an existing app, run historical rows through the cleaner in chunks, logging before/after samples. Do this after the input path is already clean so you never re-clean new data inconsistently.
• Custom rules as extension points — if the package exposes per-tag handling, register project-specific allowances (e.g. <iframe> for a trusted embed host) as configuration or a small subclass rather than post-processing the cleaned string with str_replace.
• Test with fixtures, not inline strings — keep a tests/fixtures/html/ directory of real-world dirty input. This is what makes the v0.0.44-style internal rewrite a five-minute verification instead of a regression hunt.

Gotchas and Tips

• v0.0.44 changed the internals, not (necessarily) the contract. The regex→non-regex rewrite for tag cleaning is a behavioural risk on edge cases regexes happened to get "wrong but predictably": unclosed tags, nested/mismatched brackets, comments, CDATA, attribute values containing > or quotes, and self-closing XHTML syntax. Re-run your fixture corpus against 0.0.43 and 0.0.44 and diff the output before bumping.
• Pin the version and read the diff. At 0.0.x, patch-level bumps can change output. composer update on a Friday afternoon is how sanitisation regressions ship.
• Expect output to be normalised, not merely filtered. Parser-based cleaners typically re-serialise markup — attribute quoting, tag case, entity encoding, and void-element syntax may all shift. If you diff stored HTML, snapshots, or email templates, budget for churn.
• Don't double-escape. Cleaning then calling e()/htmlspecialchars() then rendering with {!! !!} produces visible entities. Pick one layer to own escaping.
• Watch for silent truncation. A tokenizer that hits malformed input may stop rather than throw — content after the breakpoint disappears. Assert on total output length in tests, not just "no script tag present".
• Config caching bites. php artisan config:cache means edits to the published config are invisible until re-cached; in local dev, check bootstrap/cache/config.php when changes "don't apply".
• Memory on large payloads. Non-regex cleaners usually stream or tokenize, which is faster but can hold more state; test with your largest realistic document (10k+ words of pasted Word HTML) rather than a 200-character sample.
• Debugging technique: bisect on the input, not the config. Feed progressively smaller fragments of a failing string in artisan tinker until the output changes — the boundary is almost always an unclosed tag or an attribute with an unusual quote style.
• Report upstream. If you find an input where 0.0.44 output differs from 0.0.43 in a way you consider a regression, that's a high-value bug report; the rewrite is exactly the moment maintainers want those fixtures.