Skip to content
Wordpress based Shortcodes for Laravel
Branch: master
Clone or download
Latest commit 6924477 May 5, 2019

readme.md

Laravel Shortcodes

Latest Version on Packagist Software License Total Downloads Build Status StyleCI

Wordpress based Shortcodes for Laravel Framework 5.x with shared variables, debugbar integration, flexible configurations and other useful features.

Build powerful and simple layouts using shortcodes in the content or views like this:

[b]Bold text[/b]

[row]
  [col md=8]
    [posts_list types="post,gallery" show_tags="yes"]
  [/col]
  [col md=4]
    [poll id="1"]
    [user_info username="test_user" website="mywebsite.com" active="yes"]
    [last_free_post title="Free Posts"]
  [/col]
[/row]

Installation

Via Composer

$ composer require vedmant/laravel-shortcodes

This package supports Laravel Auto-Discovery and will be discovered automatically.

For Laravel versions prior to 5.5 please add Vedmant\LaravelShortcodes\LaravelShortcodesServiceProvider::class to the providers array in config/app.php and 'Shortcodes' => Vedmant\LaravelShortcodes\Facades\Shortcodes::class to the aliases array.

Configuraton

Publish configuration.

php artisan vendor:publish --tag=shortcodes

It will publish configuration file shortcodes.php, edit it as needed.

Usage

Shortcode class

Shortcode class should extend abstract \Vedmant\LaravelShortcodes\Shortcode class.

This packages adds the make:shortcode artisan command:

php artisan make:shortcode PostsListShortcode

Which generates a shortcode class in the app/Shortcodes folder by default.

Register shortcodes

You can use AppServiceProvider::boot method to register all needed shortcodes.

Using shortcode class:

Shortcodes::add('b', BShortcode::class);

Using shortcode classes in array, preferable for lots of shortcodes:

Shortcodes::add([
   'a' => AShortcode::class,
   'b' => BShortcode::class,
]);

Using closure:

Shortcodes::add('test', function ($atts, $content, $tag, $manager) {
   return new HtmlString('<strong>some test shortcode</strong>');
});

Render shortcodes

Views auto-render

By default this package extends the View class to parse all shortcodes during views rendering. This feature can be disabled in the config file: 'render_views' => false. For better performance with lots of views it's advised to disable views auto-render.

Enable / disable rendering per view

Also to enable / disable rendering shortcodes for a specific view you can use:

view('some-view')->withShortcodes();
// Or
view('some-view')->withoutShortcodes();

Render shortcodes with the facade

{{ Shortcodes::render('[b]bold[/b]') }}

Render shortcodes with blade directive

@shortcodes
   [b class="block"]Content[/b]
@endshortcodes

Or

@shortcodes('[b]bold[/b]')

Render shortcodes with shortcodes() helper

<div class="some-block">
   {{ shortcodes('[b]bold[/b]') }}
</div>

Shared attributes

Occasionally, you may need to share a piece of data with all shortcodes that are rendered by your application. You may do so using the shortode facade's share method. Typically, you should place calls to share in the controller, or within a service provider's boot method.

Shortcodes::share('post', $post);

Then you can get shared attributes in the shortcode class:

$post = $this->shared('post');
$allShared = $this->shared();

Option to not throw exceptions from views

There is a useful option to aviod server (500) error for whole page when one of shortocode views has thrown an exception.

To enable it set 'throw_exceptions' => false, in the shortcodes.php config file. It works only when $this->view('some-view'); method is used in the shortcode class.

This will render exception details in the place of a shortcode and will not crash whole page request with 500 error. It will still log exception to a log file and report to Sentry if it's integrated.

Comma separated values (array attributes)

If you need to pass an array to a shortcode, you can pass values separated by comma:

[posts_list ids="1,2,3"]

Then in the render function you can parse this attribute using built-in method:

$ids = $this->parseCommaSeparated($atts['ids']);

Integration with Laravel Debugbar

This packages supports Laravel Debugbar and adds a tab with detailed info about rendered shortcodes. Integration can be disabled in the config file with option: 'debugbar' => false,.

Testing

$ vendor/bin/phpunit

TODO

  1. Shortcodes help data generator
  2. Add Debugbar integration tests
  3. Casting attributes (int, bool, array (comma separated))
  4. Add basic bootstrap shortcodes set
  5. Add commands to generate a shortcode view, generate view by default with make:shortcode
  6. Optional attributes validation
  7. Add custom widget for debugbar integration
  8. Create performance profile tests, optimize performance

Contributing

Please see contributing.md for details and a todolist.

Security

If you discover any security related issues, please email vedmant@gmail.com instead of using the issue tracker.

Credits

License

MIT. Please see the license file for more information.

You can’t perform that action at this time.