Laravel Shortcodes Laravel Package

Getting Started

• v3.0.0 is primarily a compatibility release: it supports Laravel 12 and 13, and drops Laravel 11. New Laravel 12/13 projects should use tehwave/laravel-shortcodes:^3; Laravel 11 projects should stay on the 2.x branch.
• Confirm the PHP constraint before installing: Laravel 12 uses PHP 8.2–8.5; Laravel 13 uses PHP 8.3–8.5.
• Install with composer require tehwave/laravel-shortcodes:^3. If the package exposes config or views, publish them only when you need to customize output.
• Look first at the package README, service provider, facade/helper entry point, and any Blade integration. Identify the exact API for registering a shortcode handler and compiling content.
• First use case: register one small shortcode, such as a button or callout, in a dedicated service provider. Render it through the package’s compile/render path in a controller or Blade view, then cover it with a feature test before using it in CMS pages, emails, or documentation.

Implementation Patterns

• Centralize shortcode registration in AppServiceProvider or a dedicated ShortcodeServiceProvider. Keep each handler small, deterministic, and free of request/session side effects.
• Prefer returning a Blade partial from each handler, for example a shortcodes.button view, rather than building HTML strings inline. Validate required attributes, apply defaults, and cast booleans/numbers in the handler.
• Create a single application-level rendering helper or service that wraps the package compiler. Use it consistently in controllers, Blade templates, mailables, API transforms, and admin previews so output cannot drift.
• Compile content at the correct boundary: compile-on-save for static CMS pages, and compile-on-render for dynamic or per-user content. Cache compiled HTML for expensive or frequently rendered content.
• Include a cache key version based on the content hash, shortcode handler version, and relevant view/app version. Invalidate compiled caches when shortcode views or handler behavior changes.
• Be explicit about escaping. Let Blade escape normal values inside partials, and centralize raw HTML output at one boundary, such as an HtmlString or a single unescaped Blade expression.
• Decide and test the order of shortcode compilation versus Markdown rendering. Use the same pipeline in preview and production, otherwise editors will see different results from published content.
• For multi-tenant or plugin-style content, allowlist which shortcodes are available per context and keep custom handlers in application code rather than editing vendor files.

Gotchas and Tips

• The main v3 breaking change is platform compatibility, not a new feature set. Do not upgrade to v3 while still on Laravel 11; either stay on ^2 or upgrade Laravel first. On Laravel 13, update CI and local environments to PHP 8.3+.
• If Composer reports conflicts after upgrading, check composer why-not tehwave/laravel-shortcodes ^3 and verify the Laravel/PHP platform constraints in composer.json and CI.
• Treat shortcode content as untrusted when it comes from editors or users. Escape attributes, sanitize allowed HTML, and never let untrusted users register arbitrary shortcode handlers.
• Test parser edge cases: quoted attributes, brackets inside attributes, empty content, self-closing shortcodes, and nested or enclosed shortcodes if supported. If nesting is not supported, document that limitation and avoid relying on it.
• Common symptoms have predictable causes: literal shortcode text usually means compile was not called or output was escaped; double-escaped HTML usually means the handler escaped values and Blade escaped the result again; missing handlers usually mean registration happened too late or the shortcode name/case does not match.
• When debugging, call the compiler directly with a small fixture, log the normalized attributes passed to the handler, and verify the rendered partial independently before testing the full content pipeline.
• Cache invalidation is a frequent source of stale output. Clear compiled-content caches when changing shortcode views, handler logic, or allowed attributes.
• Prefer package extension points such as custom handlers, config, and published views over patching vendor code. Keep the major version constraint explicit so future compatibility changes are deliberate.