Bladerunner

WordPress plugin for Laravel Blade templating.

To install it to your Composer based WordPress installation:

composer require ekandreas/bladerunner

Activate the plugin inside WordPress and templates with *.blade.php are inspected and active. Your theme still needs an index.php due to WordPress basic functionality. When removed the theme is known as broken.

If you don't use a composer based WordPress development environment you can download the latest distributed plugin at Bladerunner site http://bladerunner.aekab.se and install it the common way with zip upload to WordPress via wp-admin.

Releases to this plugin is listed last in this readme.

Hello World

Install the library with composer
Make sure the cache-folder is writeable in uploads, eg ../wp-content/uploads/.cache
Activate the plugin

Create a view, eg:

<!-- view file: views/pages/index.blade.php -->
Hello World Page rendered at {{ date('Y-m-d H:i:s') }}

In your index.php, add a global call for the view created, eg:
```
<?php
bladerunner('views.pages.index')
```

https://laravel.com/docs/5.2/blade

Cache

If WP_DEBUG is set and true then templates always will be rendered and updated.
View files (cache) is invalidated at save_post
(It's a really good idea to empty the .cache folder inside uploads when develop templates. Eg, create a del command inside your gulp-file.)

Directories

Your cached views will always be stored in your wp upload folder, .cache
Your views must be placed within your theme folder.
Your views must have .blade.php extension.

Template helper

There is a template helper function named bladerunner, defined globally to use in standard WordPress templates.

Example: You want to create a 404-template and don't want to use the .blade.php extension to the template file.

Create a 404.php in the theme root.
Add the following code to the template:
```
<?php
bladerunner('views.pages.404');
```
In the folder views/pages, create a blade template 404.blade.php

You can pass any data with the global bladerunner function like so,

<?php
    bladerunner('views.pages.404', ['module'=>$module]);

or use compact, eg:

<?php
    bladerunner('views.pages.404', compact('module'));

Controllers

With version 1.7 controllers are added to Bladerunner. As default Bladerunner will look for extended classes in the theme folder + /controllers. If you would like to add or change the controller paths take a look below at filters!

The controller class has to extend \Bladerunner\Controller to work. It will guess the path to the view but you can override this with protected $view='your.custom.view.path''

The controller files follow the same hierarchy as WordPress. You can view the controller hierarchy by using the Blade directive @debug.

Extend the Controller Class, it is recommended that the class name matches the filename. Create methods within the Controller Class:

Use public function to expose the returned values to the Blade views/s.
Use public static function to use the function within your Blade view/s.
Use protected function for internal controller methods as only public methods are exposed to the view. You can run them within __construct

Controller example:

The following example will expose $images to views/single.blade.php

controllers/Single.php

<?php

namespace App;

use Bladerunner\Controller;

class Single extends Controller
{
    /**
     * Return images from Advanced Custom Fields
     *
     * @return array
     */
    public function images()
    {
        return get_field('images');
    }
}

views/single.blade.php

@if($images)
  <ul>
    @foreach($images as $image)
      <li><img src="https://github.com/ekandreas/bladerunner/raw/main/{{$image['sizes']['thumbnail']}}" alt="{{$image['alt']}}"></li>
    @endforeach
  </ul>
@endif

Hooks and Filters

Bladerunner continuously implements filters and hooks to modify values and processes.

Hooks

...

Filters

Modify Bladerunners cache folder path, default ../wp-content/uploads/.cache

add_filter('bladerunner/cache/path', function() {
    return '/my/path/to/cache';
});

If you don't want Bladerunner to create the cache folder:

add_filter('bladerunner/cache/make', function() {
    return false;
});

If you wan't to customize the base paths where you have your views stored, use:

add_filter('bladerunner/template/bladepath', function ($paths) {
    if (!is_array($paths)) {
        $paths = [$paths];
    }
    $paths[] = ABSPATH . '../../resources/views';
    return $paths;
});

If you wan't to customize the controller paths where you have your controllers stored, use:

add_filter('bladerunner/controller/paths', function ($paths) { 
    $paths[] = PLUGIN_DIR . '/my-fancy-plugin/controllers';
    return $path; 
});

We will soon add more WordPress extenstions to the Bladerunner engine. Please give us your great examples to implement!

Tests

Test requirements:

Latest Docker install (not the old school Boot2Docker)
PHP Composer Currently only tested on OSX.

Test step by step

Checkout the components for testing via Composer inside the repo:

composer update

Using Testrunner (required-dev package) and Docker the test should be exexuted with a single command:

vendor/bin/dep testrunner

ekandreas / bladerunner

readme