- How do I install webwizo/laravel-shortcodes?
- Install it with Composer using composer require webwizo/laravel-shortcodes. On Laravel 5.5 and later the service provider is registered automatically through package discovery, so no manual provider entry is needed. Older Laravel versions require adding the provider to your config/app.php providers array. After that you can register shortcode classes and start parsing content.
- Which Laravel versions does this shortcode package support?
- The package targets a very wide range of Laravel releases: 4.2, the 5.x line, and 6.x through 13.x. That breadth makes it a reasonable choice for multi-project shops maintaining applications on mixed framework versions. Check your Composer constraint against the package version you install, since the latest 1.0.x line is what receives the current fixes.
- How do I register a custom shortcode class?
- You create a shortcode class that defines its tag name and a compile method, then register that class with the package so the parser knows about it. Once registered, any occurrence of the tag in a string is resolved to the output your class produces. The registration API is the same one used for the package's built-in rendering path, so no special bootstrap code is required beyond your service provider.
- Can I use shortcodes in Blade views, emails, and stored content?
- Yes. The package parses a string and returns rendered output, so it works anywhere you have text: a Blade view variable, a rendered email body, a CMS field, or a database column. You pass the content through the parser at render time rather than trying to embed shortcode logic in the template itself. This keeps the same shortcode syntax consistent across web pages, notifications, and mailables.
- Do shortcodes support attributes and enclosing (paired) tags?
- Yes, both forms are supported. Self-closing tags accept quoted attributes such as [widget id="5" mode="x"], which arrive at your shortcode class as named key/value pairs. Enclosing tags let you wrap inner content between an opening and closing shortcode and process that content inside your compile method. This mirrors the WordPress shortcode conventions most developers already know.
- Does the parser work with content that passes through an HTML sanitizer first?
- It does, but the ordering matters: sanitize first, then compile shortcodes. Sanitizers such as HTMLPurifier commonly rewrite quotes and equals signs into numeric HTML entities, which previously caused attribute parsing to break. A patch in the 1.0.x line decodes those entities before parsing attributes, so sanitized content now resolves to proper named attributes. Verify the specific entity forms your sanitizer emits, since decimal entities are the documented case.
- Why do my shortcode attributes come back as numeric keys like 0, 1, 2?
- That is the symptom of the entity-encoding bug fixed in the 1.0.x patch line. When a sanitizer converts quotes to entities, the attribute parser fails to match key/value pairs and falls back to indexed fragments. Upgrading to the patched release restores named attributes, but only for content parsed after the upgrade. Clear any cached or pre-rendered output that was produced by the broken parser.
- Will upgrading within 1.0.x change the rendered output of my content?
- For content that never touches a sanitizer, output is unchanged. For content where a sanitizer rewrote attribute characters, the rendered output will change from garbled indexed fragments to correctly parsed named attributes, which is the intended fix. That is a behavioral change rather than an API change, so no code edits are required. Inventory the content types that pass through a sanitizer and diff their output before and after the upgrade.
- How should I test shortcode rendering before deploying an upgrade?
- Build a fixture set covering three cases: shortcodes with quoted attributes and no sanitizer, shortcodes passed through your sanitizer, and plain content with no shortcodes at all. Assert that attributes resolve to named key/value pairs rather than numeric indices. The package ships a regression test for entity-encoded attribute parsing, which is worth keeping in view as the guardrail for this behavior. Clear compiled and rendered caches in staging so you are not comparing against stale output.
- What are the alternatives to using this shortcode package?
- You can hand-roll Blade directives or write custom regex parsing, but you end up reimplementing attribute tokenization, self-closing versus enclosing tag handling, and entity decoding. That is exactly the surface area where subtle bugs like the numeric-entity parsing issue appear. Using a maintained package keeps that logic centralized and tested. It is also worth confirming the ordering contract between your sanitizer and the parser regardless of which approach you choose.