Laravel Shortcodes Laravel Package

Getting Started

• Install/upgrade with the patch containing the numeric-entity fix: require ^1.0.34 (or the package’s equivalent constraint), then run composer update.
• First look at:
  • The package README for the compile() entry point and shortcode registration API.
  • The service provider / config where shortcodes are registered or auto-loaded.
  • parseAttributes() if you need direct attribute-parsing behavior.
  • The new HtmlEntityAttributeParsingTest for the expected numeric-entity behavior.
• Minimal first use case: register a shortcode such as [button url="..." label="..."], then compile stored content before rendering:

Shortcode::register('button', function (array $attrs, ?string $content = null) {
    $url = $attrs['url'] ?? '#';
    $label = $attrs['label'] ?? 'Button';

    return sprintf(
        '<a class="btn" href="%s">%s</a>',
        e($url),
        e($label)
    );
});

{!! Shortcode::compile($post->body) !!}

• Start with a simple named-attribute shortcode. Avoid positional/numeric-index assumptions in handlers; v1.0.34 specifically corrects cases where encoded attributes were previously parsed as numeric-indexed fragments.

Implementation Patterns

• Centralize shortcode registration in a service provider or dedicated registry class. Keep handlers small and return escaped HTML.
• Treat compile() as the rendering boundary. Store shortcode markup in the database, compile at render time, and cache the rendered result only when the shortcode registry and content are stable.
• Validate and normalize attributes inside handlers:

$url = filter_var($attrs['url'] ?? '', FILTER_VALIDATE_URL) ?: '#';
$target = in_array($attrs['target'] ?? '', ['_blank', '_self'], true)
    ? $attrs['target']
    : '_self';

• Prefer compiling shortcodes before the final HTML sanitization step when your pipeline allows it. If your sanitizer must run first, v1.0.34 makes numeric-entity-encoded attributes such as = and " parse correctly.
• For user-authored content passing through HTML sanitizers, add an integration test that mirrors production:

$input = '[button url="https://example.com?a=1&b=2" label="Go"]';
$html = Shortcode::compile($input);

$this->assertStringContainsString('href="https://example.com?a=1&b=2"', $html);

• Use named attributes in all documentation and tests. Assert on named keys from parseAttributes() rather than relying on 0, 1, etc.
• Cache compiled content by a key that includes the raw content hash and a shortcode-registry version. Invalidate when handlers, attribute rules, or package versions change.
• In Blade, render compiled output with {!! !!} only after ensuring handlers escape user-controlled attribute values. Prefer a dedicated helper or Blade directive so views do not call the compiler inconsistently.
• For APIs or JSON responses, compile before serialization and store both raw content and rendered HTML if clients need stable output.

Gotchas and Tips

• Upgrade specifically for numeric entities. htmlspecialchars_decode() alone does not decode numeric entities like = and ". v1.0.34 fixes this inside the package’s attribute parser, so pin ^1.0.34 if your content passes through sanitizers.
• Do not “fix” this by running htmlspecialchars_decode() over the whole content. That can reintroduce encoded HTML and create XSS risks. Let the package parse shortcode attributes, or decode only targeted attribute values before escaping on output.
• Sanitizer order matters. Compiling after sanitization now handles encoded attributes, but shortcode output generated afterward may bypass that sanitizer. Sanitize the final rendered HTML when handlers can emit user-influenced markup.
• Check custom code that expected numeric-indexed fragments. The fix changes mis-parsed attributes into named key/value pairs. If any handler or test depended on the old broken shape, update it.
• Escape at output, not at parse time. Pass decoded attribute values to handlers, then escape with e() or your templating engine when building HTML.
• Test with the actual sanitizer in your stack. Different sanitizers encode =, ", and & differently. Cover =, ", and entity-encoded ampersands in URLs.
• Watch malformed attributes. The regression test covers valid numeric-entity decoding; still validate required attributes and provide safe defaults for missing values.
• Clear caches after registration changes. If you cache compiled output, config, or rendered blocks, invalidate those caches when shortcode handlers or package versions change.
• Use the regression test as a template. HtmlEntityAttributeParsingTest exercises both parseAttributes() and the full compile() flow; mirror that in your application’s integration tests.