Laravel Soap Laravel Package

Getting Started

v4.0.0 is a major release that moves the package onto Laravel 12 and PHP 8.4. That single line is the most important detail in these notes — everything else is dependabot housekeeping (including several bumps confined to /docs/v3, which is the versioned documentation site, not shipped runtime code).

1. Check your runtime first: php -v and composer show laravel/framework. If you are still on PHP 8.2/8.3 or Laravel 10/11, do not upgrade yet — a major bump typically means the composer constraints have been tightened, and the upgrade will fail or silently lock you out of future patches. Plan the Laravel/PHP hop before the package hop.
2. composer require <vendor>/<package> --dry-run (or composer why-not <vendor>/<package> ^4.0) to see the real constraint clash before touching composer.json.
3. Review the published config: php artisan vendor:publish --provider="...ServiceProvider" --tag=config and diff it against your existing config/*.php. Major versions are exactly when new keys appear and old ones disappear.
4. First use case: take one real piece of content (a markdown-rendering endpoint, a doc page, a mail template) and run it through the package in a scratch route or php artisan tinker before migrating the rest.

If you are brand new to the package, read the versioned docs at /docs/v3 only for conceptual background — the API surface may have moved in v4, so treat v3 docs as a tutorial, not a reference.

Implementation Patterns

• Render in a service, not a controller. Wrap the package's rendering call in a small application-level service (e.g. MarkdownRenderer) and bind an interface in a service provider. When v5 lands you change one class, not forty controllers.
• Treat the CommonMark pipeline as a configuration surface. The league/commonmark dependency bump (2.5.3 → 2.6.0) plus the v4 major means extension registration, environment setup and extension priority ordering are the places most likely to shift. Register your custom extensions (ExternalLink, TableOfContents, custom inline parsers) in a dedicated provider so they are visible in one place.
• Cache rendered output. CommonMark is fast but not free; rendering the same docs on every request is wasted CPU. Cache keyed by content hash (not route) so edits invalidate correctly, and clear on deploy.
• Separate trusted from untrusted input. Any markdown authored by end users needs HTML stripping / a safe-mode configuration; anything authored by your team does not. Two renderer instances (or two named configs) is the cleanest expression of this.
• Queue heavyweight conversions. PDF/HTML export paths, full-document render + TOC + syntax highlighting, and bulk re-renders belong in jobs with a cache:clear-style reindex command you can run after an upgrade.
• Pin and test the upgrade in CI. Add a matrix job running PHP 8.4 + Laravel 12 alongside your current floor (if the package still supports it) so the next major doesn't surprise you. Snapshot-test rendered HTML for a handful of representative documents — that catches silent CommonMark output changes far better than unit tests.
• Use it in Mailables and notifications as well as views; that's usually where teams get the second-biggest payoff after documentation sites.

Gotchas and Tips

• Major version ≠ same API. The release notes list only the Laravel 12/PHP 8.4 upgrade, but a semver major almost certainly means dropped support for older Laravel/PHP and possibly renamed config keys, changed default options, or removed deprecated methods. Read the diff between the v3 and v4 branches (or the upgrade guide) before merging — do not infer backwards compatibility from the short changelog.
• Constraint hell is the real blocker. If any other package in your tree requires laravel/framework ^10.0|^11.0, upgrading this package will fail resolution. Use composer why-not and upgrade the blockers first.
• The /docs/v3 dependabot entries are noise. tar-fs, elliptic, pug, ws, prismjs, serve-static and @babel/runtime are all in the documentation site's toolchain. They do not affect your runtime and should not influence your upgrade decision — do not mistake CVE-looking bumps for security fixes in the package itself.
• symfony/validator 7.0 → 7.1 and the symfony/process / http-foundation 6.4 bumps are dev/CI-side in most Laravel apps; Laravel 12 will resolve its own Symfony versions. If you see a Symfony constraint conflict, it is coming from your app, not this package.
• Debugging rendering: dump the parsed AST ($environment->parse($markdown)) rather than the output HTML when markup looks wrong — that tells you instantly whether the problem is the parser extension or your CSS/template.
• Clear the compiled views and config cache after upgrading (php artisan optimize:clear). Stale cached config with removed keys is a classic post-major-version false alarm.
• Extension points to favour for customisation: a custom EnvironmentInterface factory (or a bound singleton), custom CommonMark extensions, and a config-driven allowlist. Avoid subclassing internals — those are precisely what a major version rewrites.
• Upgrade checklist: bump on a branch → run the full suite → visual diff of rendered output → smoke test mailables and exports → ship with the ability to roll back via composer.lock.