- Does this package work with Laravel 8/9/10, or is it limited to Laravel 5.x?
- The package is designed for Laravel 5.x and may not work out-of-the-box with newer versions due to deprecated facades and Blade syntax changes. You’d need to fork the repo, update dependencies (like `illuminate/support`), or use a compatibility layer like `laravel-shift/blade-one` for Laravel 8+. Always test thoroughly in a staging environment.
- How do I register a custom shortcode like `[user-avatar]` with parameters?
- Use the `ShortCode::addShortcode()` method to register a handler. For example: `ShortCode::addShortcode('user-avatar', function($params) { return view('avatar', ['user' => $params['id']]); });`. Parameters are passed as an associative array (e.g., `[user-avatar id=123]`). The handler should return HTML or a string for rendering.
- Can I use this for parsing shortcodes in email templates (e.g., Mailgun, Postmark)?
- Yes, the package is ideal for email templates. Parse the shortcodes before sending via `ShortCode::parse($emailBody)`. For dynamic emails, combine it with Laravel’s `Mailable` classes or queue delayed jobs. Sanitize output with `spatie/laravel-html` if embedding user-generated content to prevent XSS.
- What happens if a shortcode isn’t registered or fails to parse? Does it break the entire string?
- By default, unregistered shortcodes are rendered as raw text (e.g., `[unknown]`). To customize error handling, override the `ShortCode::onUnknownShortcode()` method. For example, you could log errors or replace them with a fallback like `[?]`. This prevents parsing failures from breaking the entire string.
- Is there built-in caching for parsed shortcodes to improve performance?
- No, the package doesn’t include caching out of the box. For high-traffic sites, wrap `ShortCode::parse()` in Laravel’s cache (e.g., `Cache::remember('parsed_content', now()->addHours(1), fn() => ShortCode::parse($text))`). This is especially useful for static or rarely changing content like documentation or marketing pages.
- How do I handle nested shortcodes (e.g., `[parent [child]]`)?
- The package supports nested shortcodes by default, parsing them recursively. However, ensure your handlers are idempotent (e.g., don’t modify the input string during parsing). For complex nesting, test edge cases like `[a [b [c]]]` to verify the expected output. If issues arise, debug with `ShortCode::parse($text, true)` to see the intermediate steps.
- Are there security risks with user-generated shortcodes (e.g., XSS attacks)?
- Yes, user-generated shortcodes can expose your app to XSS if handlers render unsanitized HTML. Always sanitize output using `spatie/laravel-html` or `htmlspecialchars()`. Avoid dynamic `eval()` or `include` in shortcode handlers. For untrusted content, restrict shortcodes to a whitelist or use a sandboxed environment.
- What alternatives exist for shortcode parsing in Laravel?
- Alternatives include custom Blade directives (for Laravel 8+), `spatie/laravel-html` (for safer HTML parsing), or rolling your own regex-based parser. For CMS integrations, consider headless solutions like Strapi or Contentful with frontend frameworks (React/Vue). If you need a more modern approach, evaluate Laravel’s native Blade components or Alpine.js for client-side rendering.
- How do I test shortcode parsing in PHPUnit? Since there are no built-in tests, what’s a good approach?
- Write unit tests by mocking the `ShortCode` facade and verifying parsed output. For example: `$parsed = ShortCode::parse('[test]'); $this->assertEquals('expected', $parsed);`. Test edge cases like empty strings, malformed shortcodes, and nested structures. Use Laravel’s `RefreshDatabase` trait if shortcodes interact with your database. Document test cases for future maintenance.
- Can I use this package in a serverless environment (e.g., AWS Lambda, Bref)?
- The package may work in serverless environments, but you’ll need to handle Laravel’s service container initialization manually (e.g., via `bootstrap/app.php`). Avoid global state or facades that rely on Laravel’s bootstrapping. For performance, cache parsed shortcodes aggressively. Test with a minimal Laravel setup (e.g., `laravel-zero` or `spatie/laravel-serverless`) to identify compatibility issues.