https://github.com/tehwave/laravel-shortcodes
Simple, elegant WordPress-like Shortcodes the Laravel way
https://github.com/tehwave/laravel-shortcodes
laravel package php shortcodes wordpress
Last synced: about 2 months ago
JSON representation
Simple, elegant WordPress-like Shortcodes the Laravel way
- Host: GitHub
- URL: https://github.com/tehwave/laravel-shortcodes
- Owner: tehwave
- License: mit
- Created: 2019-12-19T23:36:41.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2025-10-13T18:01:18.000Z (4 months ago)
- Last Synced: 2025-10-21T23:02:00.215Z (3 months ago)
- Topics: laravel, package, php, shortcodes, wordpress
- Language: PHP
- Homepage:
- Size: 113 KB
- Stars: 12
- Watchers: 4
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# Laravel Shortcodes
Simple, elegant WordPress-like Shortcodes the Laravel way.
[](LICENSE)
## Requirements
The package has been developed and tested to work with the latest supported versions of PHP and Laravel as well as the following minimum requirements:
- Laravel 11
- PHP 8.2
### Version Compatibility
| Laravel | PHP | Branch |
|---|---|---|
| 11+ | 8.2+ | [master](https://github.com/tehwave/laravel-shortcodes/tree/master) |
| 10 and below | 8.1 and below | [1.x](https://github.com/tehwave/laravel-shortcodes/tree/1.x) |
## Installation
Install the package via Composer.
```bash
composer require tehwave/laravel-shortcodes
```
## Usage
`Laravel Shortcodes` work much like WordPress' [Shortcode API](https://codex.wordpress.org/Shortcode_API).
```php
[!NOTE]
> All values in the `attributes` array are cast to `string` type when parsed unless specifically cast to a type via the `$casts` property.
```php
attributes['escape_html']) && $this->attributes['escape_html'] === 'true')) {
return sprintf('%s', htmlspecialchars($this->body));
}
return sprintf('%s', $this->body);
}
}
```
#### Naming
The shortcode's tag is derived from the class name to snake_case.
You may specify a custom tag using the `tag` property or by overwriting the `getTag` method.
Shortcode tags must be alpha-numeric characters and may include underscores.
```php
Hello World[/italics]');
// <b>Hello World</b>
```
You may specify a list of instantiated `Shortcode` classes to limit what shortcodes are parsed.
```php
'boolean',
'count' => 'integer',
'price' => 'float',
'name' => 'string',
'tags' => 'array',
'options' => 'collection',
'metadata' => 'object',
'config' => 'json',
'published_at' => 'date',
];
/**
* The code to run when the Shortcode is being compiled.
*
* @return string|null
*/
public function handle(): ?string
{
$publishedAt = $this->attributes['published_at'] instanceof Carbon
? $this->attributes['published_at']->toFormattedDateString()
: 'N/A';
$tags = implode(', ', $this->attributes['tags']);
$options = $this->attributes['options']->implode(', ');
return sprintf(
'Active: %s, Count: %d, Price: %.2f, Name: %s, Published At: %s, Tags: %s, Options: %s',
$this->attributes['is_active'] === true ? 'Yes' : 'No',
$this->attributes['count'],
$this->attributes['price'],
$this->attributes['name'],
$publishedAt,
$tags,
$options
);
}
}
```
When you compile content with this shortcode, the attributes will be automatically cast to the specified types.
```php
'boolean',
'count' => 'integer',
];
public function handle(): ?string
{
// Access attributes as properties
$isActive = $this->is_active;
$count = $this->count;
return sprintf('Active: %s, Count: %d', $isActive === true ? 'Yes' : 'No', $count);
}
}
```
### Example
I developed `Laravel Shortcodes` for use with user provided content on [gm48.net](https://gm48.net).
The content is parsed using a Markdown converter called Parsedown, and because users can't be trusted, the content has to be escaped.
Unfortunately, this escapes the attribute syntax with double quotes, but singular quotes can still be used as well as just omitting any quotes.
> [!NOTE]
> Quotes are required for any attribute values that contain whitespace.
Let's take a look at the following content with some basic `Row`, `Column`and `Image` shortcodes.
```
# Controls:
[row]
[column]
[image align=left src=http://i.imgur.com/6CNoFYx.png alt='Move player character']
[/column]
[column]
[image align=center src=http://i.imgur.com/8nwaVo0.png alt=Jump]
[/column]
[column]
[image align=right src=http://i.imgur.com/QsbkkuZ.png alt='Go down through platforms']
[/column]
[/row]
```
When running the content through the following code:
```php
$parsedDescription = (new Parsedown())
->setSafeMode(true)
->setUrlsLinked(false)
->text($this->description);
$compiledDescription = Shortcode::compile($parsedDescription);
```
We can expect to see the following output:
```html
Controls:
```
You should still escape any user input within your shortcodes' `handle`.
## Tests
Run the following command to test the package.
```bash
composer test
```
## Security
For any security related issues, send a mail to [peterchrjoergensen+shortcodes@gmail.com](mailto:peterchrjoergensen+shortcodes@gmail.com) instead of using the issue tracker.
## Changelog
See [CHANGELOG](CHANGELOG.md) for details on what has changed.
## Upgrade Guide
See [UPGRADING.md](UPGRADING.md) for details on how to upgrade.
## Contributions
See [CONTRIBUTING](CONTRIBUTING.md) for details on how to contribute.
## Credits
- [Peter Jørgensen](https://github.com/tehwave)
- [All Contributors](../../contributors)
Inspired by https://github.com/webwizo/laravel-shortcodes and https://github.com/spatie/laravel-blade-x
## About
I work as a Web Developer in Denmark on Laravel and WordPress websites.
Follow me [@tehwave](https://twitter.com/tehwave) on Twitter!
## License
[MIT License](LICENSE)