https://github.com/travelopia/wordpress-blade
Use Laravel Blade components in WordPress
https://github.com/travelopia/wordpress-blade
laravel-blade wordpress wordpress-plugin
Last synced: about 1 month ago
JSON representation
Use Laravel Blade components in WordPress
- Host: GitHub
- URL: https://github.com/travelopia/wordpress-blade
- Owner: Travelopia
- License: mit
- Created: 2024-08-06T04:18:54.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-11-13T14:35:33.000Z (over 1 year ago)
- Last Synced: 2025-01-29T08:11:28.866Z (over 1 year ago)
- Topics: laravel-blade, wordpress, wordpress-plugin
- Language: PHP
- Homepage: https://packagist.org/packages/travelopia/wordpress-blade
- Size: 60.5 KB
- Stars: 4
- Watchers: 10
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: license
Awesome Lists containing this project
README
# WordPress Blade Plugin
Use Laravel Blade components in WordPress.
🚨 Note: Only Anonymous Components are currently supported: https://laravel.com/docs/10.x/blade#anonymous-components
Built by the super talented team at Travelopia.
## Video Tutorial
▶ ️[tutorial](https://www.youtube.com/watch?v=M7aCzMkL7Lo)
## Installation
### Install via Composer (recommended):
```
$ composer require travelopia/wordpress-blade
```
* Your composer file should include this
```json
{
"name": "your/packagename",
"description": "Description",
"extra": {
"installer-paths": {
"wp-content/mu-plugins/{$name}/": ["type:wordpress-muplugin"]
}
},
"require": {
"travelopia/wordpress-blade": "^1.0.0",
"composer/installers": "^2.3"
},
"config": {
"allow-plugins": {
"composer/installers": true
}
},
"scripts": {
"wordpress-blade": "wordpress-blade"
}
}
```
* This installs it as an MU Plugin.
* Then load this plugin in your mu plugins loader file e.g. mu-plugins/loader.php
```php
require_once WPMU_PLUGIN_DIR . '/wordpress-blade/plugin.php';
```
* Then require the autoload file from vendor directory by adding the following code in your wp-config.php file.
```php
require_once 'vendor/autoload.php';
```
### Manual Installation (if you know what you are doing):
1. Download this repository as a ZIP file.
2. Run `composer install --no-dev --optimize-autoloader`
3. Use it either as an MU plugin or a normal plugin!
## Building for Production
Compile your Blade components for production as a best practice. Some production environments are read-only, in which case this step is necessary.
Run the following command:
`composer exec wordpress-blade -- --config-file=blade.config.php` - Ensure the path to the Blade config is correct.
## Usage
First, create a `blade.config.php` file at the root of your project, and add the following code in there:
```php
[
__DIR__ . '/wp-content/themes//',
'parts' => __DIR__ . '/wp-content/themes//', // With namespace.
// Any other paths where Blade needs to look for components.
],
'path_to_compiled_views' => __DIR__ . '/wp-content/themes//dist/blade', // Where you want Blade to save compiled files.
'never_expire_cache' => false, // Use `true` on production environments.
'base_path' => __DIR__, // The base path that is common to the front-end and admin.
'encode_echo' => true, // Double-encode entities in `{{ }}` output. See "Echo encoding" below.
'register_wp_directives' => true, // Register `@escHtml`, `@escUrl`, `@escAttr`, `@wpKsesPost`, `@stripTags`, `@safeEscape` directives. See "WordPress-aware escape directives" below.
]
);
```
#### Echo encoding
By default Blade's `{{ $value }}` calls `e( $value, true )`, which **double-encodes** HTML entities. This is the Laravel default and is preserved by setting `encode_echo => true`.
If your templates receive values that have already been escaped upstream (for example, the output of WordPress's `esc_html()`, `esc_attr()`, or `wptexturize()`), double-encoding turns `&` into the literal text `&`. Set `encode_echo => false` to switch to single-encoding (`e( $value, false )`) so upstream encoding is preserved.
#### WordPress-aware escape directives
The package registers six Blade directives that wrap WordPress's escape helpers, letting templates express intent rather than the function call:
| Directive | Compiles to | Use for |
|---|---|---|
| `@escHtml( $v )` | `echo esc_html( $v );` | Plain text in HTML bodies |
| `@escUrl( $v )` | `echo esc_url( $v );` | `href` / `src` attribute values |
| `@escAttr( $v )` | `echo esc_attr( $v );` | Other HTML attribute values |
| `@wpKsesPost( $v )` | `echo wp_kses_post( $v );` | Rich text from editors (block content, ACF WYSIWYG, etc.) |
| `@stripTags( $v )` | `echo wp_strip_all_tags( $v );` | Atomic strip-only — for values that need tag removal but will be escaped or used somewhere else (JSON, plain text response, an upstream-escaped pipeline). |
| `@safeEscape( $v )` | `echo esc_html( wp_strip_all_tags( $v ) );` | The combined "strip then escape" path — the safe default for plain-text fields that may receive `wpautop`-wrapped or otherwise tag-laden content (post titles via filters, ACF text fields rendered alongside WYSIWYG siblings). |
Directive names are prefixed / cased to correlate with the underlying WordPress helper (`@esc*` → `esc_*()`, `@wp*` → `wp_*()`, `@stripTags` → `wp_strip_all_tags()`, `@safeEscape` → the combined safe-default) and stay out of Laravel's reserved-directive namespace.
The expression — including its surrounding parentheses — is forwarded verbatim to the underlying WordPress helper. To skip registration (for example, if your project registers its own escape directives), set `'register_wp_directives' => false` in the bootstrap config or filter `wordpress_blade_register_wp_directives`.
### Bootstrap a layout.
As a best practice, and if applicable, bootstrap an entire layout like so:
```bladehtml
# bootstrap.blade.php
Hi there!
```
```bladehtml
# layout.blade.php
@php
get_header();
@endphp
{{ $slot }}
@php
get_footer();
@endphp
```
```bladehtml
# hello.blade.php
@props( [
'name' => '',
] )
{{ $slot }}
Hello, {{ $name }}
```
And then load the view in your template:
```php
Travelopia\Blade\load_view( 'bootstrap' );
```
You can also load an individual component like so:
```php
$name = 'hello'; // The name of the component.
$attributes = [ 'name' => 'Jane' ]; // Properties / attributes to pass into the component.
$echo = true; // Whether to echo the component. `false` returns the component as a string.
Travelopia\Blade\load_view( $name, $attributes, $echo );
```
This is especially useful when you want to load components from Blocks and Full Site Editing.
If you've used namespaces, you can use them like so:
```bladehtml
```