Laravel Shortcodes

The compiler scans templates from left to right. Key behaviors include:

• Attributes: Supports quoted values with spaces and hyphenated keys (e.g., data-size="large").
• Void / self-closing: Tags without a matching closing tag (e.g., [alert type="info"]) are treated as self-closing.
• Nested same-name tags: Uses balanced opening/closing pairs to preserve innermost structures.
• Unknown [ text: Text in square brackets that doesn't match a registered shortcode is left untouched.
• Escaping: Use double brackets [[b]] to output a literal [b].

To register shortcodes, create a ServiceProvider and use the Shortcode::register() method in the register() or boot() method. You can register a class that implements a default register method, or a class with a specific custom method.

// In a ServiceProvider
public function register()
{
    // Registering a class with a default 'register' method
    Shortcode::register('b', BoldShortcode::class);

    // Registering a class with a specific custom method name
    Shortcode::register('i', 'App\Shortcodes\ItalicShortcode@custom');
}

By default, shortcodes are not compiled in views. To enable shortcode rendering for a specific view, chain the withShortcodes() method onto the view return.

return view('view')->withShortcodes();

Install the package using Composer. Laravel 11+ will automatically discover the service provider. For older versions, you must manually register the provider.

composer require webwizo/laravel-shortcodes

To use the Shortcode facade for cleaner syntax, add the following alias to your configuration (e.g., in config/app.php):

'Shortcode' => Webwizo\Shortcodes\Facades\Shortcode::class,

You can enable shortcode compilation for mailable views by calling withShortcodes() within the build() method of your Mailable class.

use Illuminate\Mail\Mailable;

class NewsletterMail extends Mailable
{
    public function build()
    {
        return $this
            ->subject('Weekly newsletter')
            ->view('emails.newsletter', [
                'content' => 'Mail content',
            ])
            ->withShortcodes();
    }
}

To change the template used when generating new shortcode classes, publish the stub file to your resources directory.

```bash
php artisan vendor:publish --tag=shortcode-stubs

After publishing, edit resources/stubs/shortcode.stub.

If your Laravel setup does not support automatic package discovery, add the Webwizo\Shortcodes\ShortcodesServiceProvider to your config/app.php or bootstrap/providers.php file.

Webwizo\Shortcodes\ShortcodesServiceProvider::class,

You can publish the default shortcode stub file to your application's resources/stubs directory. This allows you to customize the boilerplate code generated when using the MakeShortcodeCommand.

php artisan vendor:publish --tag=shortcode-stubs

Shortcode classes receive several arguments in their callback method: $shortcode (the attribute object), $content (inner content), $compiler, $name, and $viewData. Use $shortcode->get($key, $default) to safely retrieve attributes.

namespace App\Shortcodes;

class BoldShortcode {
  public function register($shortcode, $content, $compiler, $name, $viewData)
  {
    // Using get() to handle attributes with a fallback
    $class = $shortcode->get('class', 'default');
    return sprintf('<strong class="%s">%s</strong>', $class, $content);
  }
}

You can manually compile or strip shortcodes from a string using the Shortcode facade.

// Compile shortcodes in a string
Shortcode::compile($contents);

// Strip shortcodes from a string
Shortcode::strip($contents);

Use the Shortcode facade to globally enable or disable shortcode processing.

Shortcode::enable();

Shortcode::disable();