Laravel Shortcodes

https://github.com/webwizo/laravel-shortcodes
Admin
Laravel Shortcodes provides WordPress-like shortcode functionality for Laravel 5.x, allowing...
Tokens:6,013
Snippets:39
Trust Score:8.4
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Installation

Source: https://context7.com/webwizo/laravel-shortcodes/llms.txt

Instructions for installing the Laravel-Shortcodes package using Composer.

```APIDOC
## Installation

Install the package via Composer. Laravel 11+ automatically discovers the service provider.

```bash
composer require webwizo/laravel-shortcodes
```

```php
// For older Laravel setups, manually register in config/app.php or bootstrap/providers.php
'providers' => [
    Webwizo\Shortcodes\ShortcodesServiceProvider::class,
],

'aliases' => [
    'Shortcode' => Webwizo\Shortcodes\Facades\Shortcode::class,
]
```
```

--------------------------------

### Example Shortcode Usage

Source: https://github.com/webwizo/laravel-shortcodes/blob/master/README.md

Demonstrates various shortcode syntaxes including bold text, tabs, and user display with attributes.

```php
[b class="bold"]Bold text[/b]

[tabs]
  [tab]Tab 1[/tab]
  [tab]Tab 2[/tab]
[/tabs]

[user id="1" display="name"]
```

--------------------------------

### Run Package Tests

Source: https://github.com/webwizo/laravel-shortcodes/blob/master/README.md

Execute the package's tests using Composer or the PHPUnit binary. Ensure you have run `composer install` first.

```bash
composer test
```

```bash
vendor/bin/phpunit
```

--------------------------------

### Install Laravel Shortcodes via Composer

Source: https://github.com/webwizo/laravel-shortcodes/blob/master/README.md

Use this command to add the package to your Laravel project.

```bash
composer require webwizo/laravel-shortcodes
```

--------------------------------

### Retrieve Attributes with get()

Source: https://context7.com/webwizo/laravel-shortcodes/llms.txt

Use the get method to retrieve attributes formatted as HTML strings with optional fallbacks.

```php
<?php

namespace App\Shortcodes;

class ImageShortcode
{
    public function register($shortcode, $content, $compiler, $name, $viewData)
    {
        // $shortcode->get() returns 'attribute="value"' format
        // If attribute is missing, uses fallback or returns null

        $classAttr = $shortcode->get('class', 'img-responsive');  // class="img-responsive" if not set
        $altAttr = $shortcode->get('alt');                         // null if not set
        $src = $shortcode->src ?? '';                              // Direct attribute access

        return sprintf(
            '<img src="%s" %s %s>',
            htmlspecialchars($src),
            $classAttr,
            $altAttr ?? ''
        );
    }
}

// Usage:
// [image src="/photo.jpg" class="thumbnail" alt="Photo"]
// Output: <img src="/photo.jpg" class="thumbnail" alt="Photo">

// Without optional attributes:
// [image src="/logo.png"]
// Output: <img src="/logo.png" class="img-responsive" >
```

--------------------------------

### BoldShortcode Class Implementation

Source: https://github.com/webwizo/laravel-shortcodes/blob/master/README.md

Example implementation of a shortcode handler class. The `register` method processes the shortcode, its content, and associated data to return the rendered HTML.

```php
namespace App\Shortcodes;

class BoldShortcode {

  public function register($shortcode, $content, $compiler, $name, $viewData)
  {
    return sprintf('<strong class="%s">%s</strong>', $shortcode->class, $content);
  }

}
```

--------------------------------

### Get Shortcode Instance from IoC

Source: https://github.com/webwizo/laravel-shortcodes/blob/master/README.md

Retrieve the shortcode instance bound to the IoC container using its key 'shortcode'.

```php
$shortcode = app('shortcode');
```

--------------------------------

### $shortcode->get()

Source: https://context7.com/webwizo/laravel-shortcodes/llms.txt

Retrieves an attribute value formatted as an HTML attribute string, with optional fallback.

```APIDOC
## $shortcode->get()

Retrieves an attribute value formatted as an HTML attribute string. Returns null if the attribute is not set and no fallback is provided. This is useful for conditionally outputting HTML attributes.

```php
<?php

namespace App\Shortcodes;

class ImageShortcode
{
    public function register($shortcode, $content, $compiler, $name, $viewData)
    {
        // $shortcode->get() returns 'attribute="value"' format
        // If attribute is missing, uses fallback or returns null

        $classAttr = $shortcode->get('class', 'img-responsive');  // class="img-responsive" if not set
        $altAttr = $shortcode->get('alt');                         // null if not set
        $src = $shortcode->src ?? '';                              // Direct attribute access

        return sprintf(
            '<img src="%s" %s %s>',
            htmlspecialchars($src),
            $classAttr,
            $altAttr ?? ''
        );
    }
}

// Usage:
// [image src="/photo.jpg" class="thumbnail" alt="Photo"]
// Output: <img src="/photo.jpg" class="thumbnail" alt="Photo">

// Without optional attributes:
// [image src="/logo.png"]
// Output: <img src="/logo.png" class="img-responsive" >
```
```

--------------------------------

### Create Custom Shortcode Class

Source: https://github.com/webwizo/laravel-shortcodes/blob/master/README.md

Define a custom shortcode by creating a class with a method that handles the shortcode's logic. This example shows how to create an 'italic' shortcode.

```php
namespace App\Shortcodes;

class ItalicShortcode {

  public function custom($shortcode, $content, $compiler, $name, $viewData)
  {
    return sprintf('<i class="%s">%s</i>', $shortcode->class, $content);
  }

}
```

--------------------------------

### Register Shortcode with Conditional Attributes

Source: https://github.com/webwizo/laravel-shortcodes/blob/master/README.md

Register a shortcode that conditionally includes an HTML attribute based on its presence in the shortcode tag. Uses `$shortcode->get()` to provide a fallback value.

```php
class BoldShortcode {

  public function register($shortcode, $content, $compiler, $name, $viewData)
  {
    return '<strong '. $shortcode->get('class', 'default') .'>' . $content . '</strong>';
  }

}
```

--------------------------------

### Create a Shortcode Class

Source: https://context7.com/webwizo/laravel-shortcodes/llms.txt

Implement rendering logic within a dedicated class using the register method.

```php
<?php

namespace App\Shortcodes;

class AlertShortcode
{
    public function register($shortcode, $content, $compiler, $name, $viewData)
    {
        $type = $shortcode->type ?? 'info';
        $dismissible = $shortcode->dismissible ? 'alert-dismissible' : '';

        return sprintf(
            '<div class="alert alert-%s %s" role="alert">%s</div>',
            htmlspecialchars($type),
            $dismissible,
            $content
        );
    }
}

// Usage:
// [alert type="danger" dismissible="true"]Something went wrong![/alert]
// Output: <div class="alert alert-danger alert-dismissible" role="alert">Something went wrong!</div>

// Self-closing shortcode (no content):
// [alert type="success"/]
// Output: <div class="alert alert-success " role="alert"></div>
```

--------------------------------

### Generate Shortcode Classes via Artisan

Source: https://context7.com/webwizo/laravel-shortcodes/llms.txt

Use the make:shortcode command to scaffold new shortcode classes and publish stubs.

```bash
# Create a new shortcode class
php artisan make:shortcode Button
# Creates: app/Shortcodes/ButtonShortcode.php

# Overwrite existing class
php artisan make:shortcode Button --force

# Publish the stub for customization
php artisan vendor:publish --tag=shortcode-stubs
# Publishes to: resources/stubs/shortcode.stub
```

```php
<?php

// Generated file: app/Shortcodes/ButtonShortcode.php
namespace App\Shortcodes;

class ButtonShortcode
{
    public function register($shortcode, $content, $compiler, $name, $viewData)
    {
        // Implement shortcode logic here
        return $content;
    }
}

// Then register in your ShortcodesServiceProvider:
Shortcode::register('button', \App\Shortcodes\ButtonShortcode::class);
```

--------------------------------

### Create a New Service Provider

Source: https://github.com/webwizo/laravel-shortcodes/blob/master/README.md

Generate a new Service Provider using the Artisan command to manage shortcode registrations.

```bash
php artisan make:provider ShortcodesServiceProvider
```

--------------------------------

### Register Facade Alias

Source: https://github.com/webwizo/laravel-shortcodes/blob/master/README.md

Optionally, add this to your aliases array for convenient access to the Shortcode facade.

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

--------------------------------

### Run Project Tests

Source: https://github.com/webwizo/laravel-shortcodes/blob/master/CONTRIBUTING.md

Execute the project's test suite using Composer. Ensure all tests pass before submitting a pull request.

```bash
$ composer test
```

--------------------------------

### Enable Shortcode Compiling for a View

Source: https://github.com/webwizo/laravel-shortcodes/blob/master/README.md

Use the `withShortcodes()` method on the view factory to enable shortcode rendering for a specific view.

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

--------------------------------

### Generate Shortcode Class with Artisan

Source: https://github.com/webwizo/laravel-shortcodes/blob/master/README.md

Use the Artisan command to quickly generate a new shortcode class file. The command creates the file in the default `app/Shortcodes/` directory.

```bash
php artisan make:shortcode YourShortcodeName
```

--------------------------------

### Enable Shortcode Compiling Globally

Source: https://github.com/webwizo/laravel-shortcodes/blob/master/README.md

Call `Shortcode::enable()` to globally enable shortcode rendering for all views.

```php
Shortcode::enable();
```

--------------------------------

### Register Custom Service Provider

Source: https://github.com/webwizo/laravel-shortcodes/blob/master/README.md

Add your custom Service Provider to the `providers` array in `config/app.php` or `bootstrap/providers.php`.

```php
App\Providers\ShortcodesServiceProvider::class,
```

--------------------------------

### Creating Shortcode Classes

Source: https://context7.com/webwizo/laravel-shortcodes/llms.txt

Defines the rendering logic for a shortcode tag within a dedicated class.

```APIDOC
## Creating Shortcode Classes

Shortcode classes contain the rendering logic for a shortcode tag. The register method receives the shortcode instance for attribute access, the inner content, the compiler for nested processing, the tag name, and any view data passed to the view.

```php
<?php

namespace App\Shortcodes;

class AlertShortcode
{
    public function register($shortcode, $content, $compiler, $name, $viewData)
    {
        $type = $shortcode->type ?? 'info';
        $dismissible = $shortcode->dismissible ? 'alert-dismissible' : '';

        return sprintf(
            '<div class="alert alert-%s %s" role="alert">%s</div>',
            htmlspecialchars($type),
            $dismissible,
            $content
        );
    }
}

// Usage:
// [alert type="danger" dismissible="true"]Something went wrong![/alert]
// Output: <div class="alert alert-danger alert-dismissible" role="alert">Something went wrong!</div>

// Self-closing shortcode (no content):
// [alert type="success"/]
// Output: <div class="alert alert-success " role="alert"></div>
```
```

--------------------------------

### Publish Shortcode Stub for Customization

Source: https://github.com/webwizo/laravel-shortcodes/blob/master/README.md

Publish the stub file used for generating shortcode classes to customize the template. The stub is copied to `resources/stubs/shortcode.stub`.

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

--------------------------------

### Register Shortcode with Class Callback

Source: https://github.com/webwizo/laravel-shortcodes/blob/master/README.md

Register a shortcode named 'b' to be handled by the `BoldShortcode` class. This method is used within a Service Provider.

```php
Shortcode::register('b', BoldShortcode::class);
```

--------------------------------

### Compile Content with Default Shortcodes

Source: https://github.com/webwizo/laravel-shortcodes/blob/master/README.md

Use `Shortcode::compile()` to process a string containing shortcodes using the default registered shortcodes.

```php
Shortcode::compile($contents);
```

--------------------------------

### Manage Global Shortcode Compilation

Source: https://context7.com/webwizo/laravel-shortcodes/llms.txt

Toggle shortcode processing globally or conditionally within middleware.

```php
<?php

use Shortcode;

// Enable globally
Shortcode::enable();

// Disable globally (shortcodes won't be processed)
Shortcode::disable();

// Example: Toggle based on environment
if (config('app.env') === 'production') {
    Shortcode::enable();
}

// Example: Conditional in middleware
class EnableShortcodesMiddleware
{
    public function handle($request, Closure $next)
    {
        if ($request->user()?->canUseShortcodes()) {
            Shortcode::enable();
        }

        return $next($request);
    }
}
```

--------------------------------

### Shortcode::register()

Source: https://context7.com/webwizo/laravel-shortcodes/llms.txt

Registers a new shortcode tag with its rendering callback. Supports closures, class names, or class@method strings.

```APIDOC
## Shortcode::register()

Registers a new shortcode tag with its rendering callback. The callback receives the shortcode object (with attributes), content, compiler, name, and view data. You can pass a closure, class name, or class@method string.

```php
<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Shortcode;

class ShortcodesServiceProvider extends ServiceProvider
{
    public function register()
    {
        // Register with a closure callback
        Shortcode::register('b', function ($shortcode, $content, $compiler, $name, $viewData) {
            return sprintf('<strong class="%s">%s</strong>', $shortcode->class, $content);
        });

        // Register with a class (uses 'register' method by default)
        Shortcode::register('alert', \App\Shortcodes\AlertShortcode::class);

        // Register with a specific class method
        Shortcode::register('button', 'App\Shortcodes\ButtonShortcode@render');
    }
}

// Usage in Blade templates:
// [b class="highlight"]Bold text[/b]
// Output: <strong class="highlight">Bold text</strong>

// [alert type="warning"]Be careful![/alert]
// [button color="blue" size="lg"]Click Me[/button]
```
```

--------------------------------

### Force Overwrite Shortcode Class with Artisan

Source: https://github.com/webwizo/laravel-shortcodes/blob/master/README.md

When the shortcode class file already exists, use the `--force` option with the Artisan command to overwrite it.

```bash
php artisan make:shortcode YourShortcodeName --force
```

--------------------------------

### Register Shortcodes in ServiceProvider

Source: https://context7.com/webwizo/laravel-shortcodes/llms.txt

Define shortcode tags using closures, class names, or specific class methods within a ServiceProvider.

```php
<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Shortcode;

class ShortcodesServiceProvider extends ServiceProvider
{
    public function register()
    {
        // Register with a closure callback
        Shortcode::register('b', function ($shortcode, $content, $compiler, $name, $viewData) {
            return sprintf('<strong class="%s">%s</strong>', $shortcode->class, $content);
        });

        // Register with a class (uses 'register' method by default)
        Shortcode::register('alert', \App\Shortcodes\AlertShortcode::class);

        // Register with a specific class method
        Shortcode::register('button', 'App\Shortcodes\ButtonShortcode@render');
    }
}

// Usage in Blade templates:
// [b class="highlight"]Bold text[/b]
// Output: <strong class="highlight">Bold text</strong>

// [alert type="warning"]Be careful![/alert]
// [button color="blue" size="lg"]Click Me[/button]
```

--------------------------------

### Manually Compile Shortcodes in Strings

Source: https://context7.com/webwizo/laravel-shortcodes/llms.txt

Use Shortcode::compile to process shortcodes in raw strings or database content outside of standard view rendering.

```php
<?php

use Shortcode;

// Register shortcodes first
Shortcode::register('quote', function ($shortcode, $content) {
    $author = $shortcode->author ?? 'Unknown';
    return sprintf('<blockquote><p>%s</p><cite>— %s</cite></blockquote>', $content, $author);
});

Shortcode::register('code', function ($shortcode, $content) {
    $lang = $shortcode->lang ?? 'text';
    return sprintf('<pre><code class="language-%s">%s</code></pre>', $lang, htmlspecialchars($content));
});

// Compile content from database or any string
$rawContent = '[quote author="Einstein"]Imagination is more important than knowledge.[/quote]';
$compiled = Shortcode::compile($rawContent);
// Output: <blockquote><p>Imagination is more important than knowledge.</p><cite>— Einstein</cite></blockquote>

// Works with nested shortcodes
$nested = '[tabs][tab title="PHP"][code lang="php"]echo "Hello";[/code][/tab][/tabs]';
$result = Shortcode::compile($nested);
```

--------------------------------

### Registering Nested Shortcodes

Source: https://context7.com/webwizo/laravel-shortcodes/llms.txt

Defines container-style shortcodes that process inner content recursively. Supports balanced same-name nesting and escaping via double brackets.

```php
<?php

use Shortcode;

// Register container shortcodes
Shortcode::register('row', function ($shortcode, $content) {
    return '<div class="row">' . $content . '</div>';
});

Shortcode::register('col', function ($shortcode, $content) {
    $size = $shortcode->size ?? '6';
    return sprintf('<div class="col-md-%s">%s</div>', $size, $content);
});

Shortcode::register('div', function ($shortcode, $content) {
    $class = $shortcode->class ?? '';
    return sprintf('<div class="%s">%s</div>', $class, $content);
});

// Nested usage in Blade:
// [row]
//   [col size="4"]Left[/col]
//   [col size="8"]Right[/col]
// [/row]

// Same-name nesting (balanced matching):
// [div class="outer"]
//   [div class="inner"]Nested content[/div]
// [/div]

// Escaping shortcodes with double brackets:
// [[b]]This outputs literal [b] without processing[[/b]]
```

--------------------------------

### Register Service Provider and Aliases

Source: https://context7.com/webwizo/laravel-shortcodes/llms.txt

Manually register the service provider and facade for older Laravel versions.

```php
// For older Laravel setups, manually register in config/app.php or bootstrap/providers.php
'providers' => [
    Webwizo\Shortcodes\ShortcodesServiceProvider::class,
],

'aliases' => [
    'Shortcode' => Webwizo\Shortcodes\Facades\Shortcode::class,
],
```

--------------------------------

### Register Shortcode with Custom Method Callback

Source: https://github.com/webwizo/laravel-shortcodes/blob/master/README.md

Register a shortcode named 'i' to be handled by the `custom` method of the `App\Shortcodes\ItalicShortcode` class. This is useful for custom logic.

```php
Shortcode::register('i', 'App\Shortcodes\ItalicShortcode@custom');
```

--------------------------------

### Strip Shortcodes from Content via Class

Source: https://github.com/webwizo/laravel-shortcodes/blob/master/README.md

Use `Shortcode::strip()` to remove all shortcodes from a given string of content.

```php
Shortcode::strip($contents);
```

--------------------------------

### Strip Shortcodes from Content

Source: https://context7.com/webwizo/laravel-shortcodes/llms.txt

Remove shortcode tags while preserving inner text, useful for generating plain text excerpts.

```php
<?php

use Shortcode;

// Register shortcodes (required for strip to recognize them)
Shortcode::register('highlight', fn($s, $c) => "<mark>$c</mark>");
Shortcode::register('link', fn($s, $c) => "<a href='{$s->url}'>$c</a>");

$content = 'Check out [highlight]this important[/highlight] text with [link url="/page"]a link[/link].';

// Strip shortcodes, keeping inner content
$plain = Shortcode::strip($content);
// Output: 'Check out this important text with a link.'

// Useful for generating excerpts
$excerpt = Str::limit(Shortcode::strip($post->body), 150);
```

--------------------------------

### Accessing View Data in Shortcodes

Source: https://context7.com/webwizo/laravel-shortcodes/llms.txt

Utilizes the fifth parameter in the callback to access variables passed from the controller to the view.

```php
<?php

use Shortcode;

Shortcode::register('user-greeting', function ($shortcode, $content, $compiler, $name, $viewData) {
    $user = $viewData['user'] ?? null;

    if (!$user) {
        return '<p>Welcome, Guest!</p>';
    }

    return sprintf('<p>Hello, %s! %s</p>',
        htmlspecialchars($user->name),
        $content
    );
});

// In controller:
return view('dashboard', ['user' => Auth::user()])->withShortcodes();

// In Blade template:
// [user-greeting]Welcome back to your dashboard.[/user-greeting]
// Output: <p>Hello, John! Welcome back to your dashboard.</p>
```

--------------------------------

### Control Shortcode Processing in Views

Source: https://context7.com/webwizo/laravel-shortcodes/llms.txt

Use these methods on view responses to enable, disable, or strip shortcodes for specific templates.

```php
<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;

class PageController extends Controller
{
    public function show($slug)
    {
        $page = Page::where('slug', $slug)->firstOrFail();

        // Enable shortcode processing for this view
        return view('pages.show', [
            'page' => $page,
            'title' => $page->title,
        ])->withShortcodes();
    }

    public function preview($id)
    {
        $draft = Page::findOrFail($id);

        // Disable shortcodes for preview (even if globally enabled)
        return view('pages.preview', ['draft' => $draft])->withoutShortcodes();
    }

    public function plain($slug)
    {
        $page = Page::where('slug', $slug)->firstOrFail();

        // Strip all shortcode tags, keeping only inner content
        return view('pages.plain', ['page' => $page])->withStripShortcodes();
    }
}
```

--------------------------------

### Strip Shortcodes from a Rendered View

Source: https://github.com/webwizo/laravel-shortcodes/blob/master/README.md

Use the `withStripShortcodes()` method on the view factory to remove all shortcodes from a specific view's output.

```php
return view('view')->withStripShortcodes();
```

--------------------------------

### Register Service Provider Manually

Source: https://github.com/webwizo/laravel-shortcodes/blob/master/README.md

For older Laravel versions or specific configurations, manually register the service provider in your app configuration.

```php
Webwizo\Shortcodes\ShortcodesServiceProvider::class,
```

--------------------------------

### Disable Shortcode Compiling Globally

Source: https://github.com/webwizo/laravel-shortcodes/blob/master/README.md

Call `Shortcode::disable()` to globally disable shortcode rendering.

```php
Shortcode::disable();
```

--------------------------------

### Disable Shortcode Compiling for Specific Views

Source: https://github.com/webwizo/laravel-shortcodes/blob/master/README.md

Use the `withoutShortcodes()` method on the view factory to disable shortcode rendering for a specific view, overriding the global config.

```php
return view('view')->withoutShortcodes();
```
Tokens:
Raw