README

BladeOne_Engine

A BladeOne Engine for the PinkCrab Renderable Interface.

Supports and tested with the PinkCrab Perique Framework versions 2.0.*

Why?

The BladeOne implementation of the Renderable interface, allows the use of Blade within the PinkCrab Framework.

Setup

$ composer require pinkcrab/bladeone-engine

Out of the box, you can just include the BladeOne module when you are booting Perique and you will have full access to the BladeOne engine.

// Bootstrap for Perique follows as normal.. 
$app = ( new App_Factory('path/to/project/root') )
   ->default_config()
   ->module(BladeOne::class)
   // Rest of setup
   ->boot();

By default the following are assumed

path/to/project/root/views as the view path
path/wp-content/uploads/blade-cache as the cache path
MODE_AUTO

Usage

Just like the native PHP_Engine found with Perique, you can inject the View service into any class and use it to render a view.

class Some_Class {
   
      public function __construct( View $view ) {
         $this->view = $view;
      }
   
      public function render_view() {
         return $this->view->render('some.path.view_name', ['data' => 'to pass']);
      }
}

The above would render the template path/to/project/root/views/some/path/view_name.blade.php with access to $data in the view which would be to pass.

<p>{{ $data }}</p>

Would render as

<p>to pass</p>

It is fully possible to make use of the template inheritance and other blade features.

<div class="wrap">
   @include('partials.header')
   @yield('content')
   @include('partials.footer')
</div>

@extends('layouts.default')
@section('content')
   Some content
@stop

Configuring BladeOne

As with all other modules, BladeOne can be configured by passing a \Closure as the 2nd argument to the module() method.

// Bootstrap for Perique follows as normal..
$app = ( new App_Factory('path/to/project/root') )
   ->default_config()
   ->module(BladeOne::class, function( BladeOne $blade ) {
      // Module config.
      $blade
         ->template_path('path/to/custom/views')
         ->compiled_path('path/to/custom/cache'); // Fluent API for chaining.
      
      $blade->mode( BladeOne::MODE_DEBUG );

      // BladeOne_Engine config.
      $blade->config( function( BladeOne_Engine $engine  {
         // See all methods below.
         $engine
            ->set_compiled_extension('.php')
            ->directive('test', fn($e) =>'test'); // Fluent API for chaining.
         
         $engine->allow_pipe( false ); 
      });

      // Ensure you return the instance.
      return $blade;
   })
   // Rest of setup
   ->boot();

Compact BladeOne Config

It is possible to do the Module config in a much more concise fashion, using the fluent API and PHP Arrow functions

$app = ( new App_Factory('path/to/project/root') )
   ->default_config()
   ->module(BladeOne::class, fn( BladeOne $blade ) => $blade
      ->template_path('path/to/custom/views')
      ->compiled_path('path/to/custom/cache')
      ->mode( BladeOne::MODE_DEBUG )
      ->config( fn( BladeOne_Engine $engine ) => $engine
         ->set_compiled_extension('.php')
         ->directive('test', fn($e) =>'test')
         ->allow_pipe( false )
      )
   )
->boot();

You can also hold the config in its own class and use that.

/** Some Class */
class BladeOneConfig {
   public function __invoke( BladeOne $blade ): BladeOne {
      return $blade
         // The setup.
   }
}

$app = ( new App_Factory('path/to/project/root') )
   ->default_config()
   ->module(BladeOne::class, new BladeOneConfig() )
   ->boot();

BladeOne_Module Config

You can call the following methods on the BladeOne Module to configure the BladeOne Module.

BladeOne_Engine Config

You can call the following methods on the BladeOne_Engine to configure the BladeOne_Engine.

Blade Templating

Most Blade features are present, to see the full docs please visit the EFTEC/BladeOne wiki

Echo data escaped or unescaped
Call PHP Function
Running PHP Block
Conditionals
- if, elseif, else
- switch
Loops
- for
- foreach
- forelse
- while
include
form
auth
permissions

Included Components

Out of the box PinkCrab_BladeOne comes with the BladeOneHTML trait added, giving access all HTML components.

Magic Call Methods

The BladeOne class has a large selection of Static and regular methods, these can all be accessed from BladeOne_Engine. These can be called as follows.

// None static
$this->view->engine()->some_method($data);

// As static 
BladeOne_Engine::some_method($data);

The can also be called in templates.

{$this->some_method($data)}

// Or
{BladeOne_Engine::some_method($data)}

For the complete list of methods, please visit https://github.com/EFTEC/BladeOne/wiki/Methods-of-the-class

Static Access

// Using the App's View method to access none static methods on the fly.
App::view()->engine()->some_method($data);

calling engine() on view, will return the underlying rendering engine used, in this case PinkCrab_BladeOne.

Of course you can set the engine it self as a global variable using $provider->share('view_helper', [App::view(), 'engine']). Then you can use {$view_helper->some_method(\$data)} in your view.

Extending

It is possible to extend BladeOne via other plugins, if you would like to add additional functionality by adding custom directives, or adding additional methods to the BladeOne_Engine class. You can do this by using the PinkCrab_BladeOne::SETUP_CONFIG action and add any additional configs such as directives.

add_action( PinkCrab_BladeOne::SETUP_CONFIG, function( PinkCrab_BladeOne $engine ) {
    $engine->directive( 'my_directive', function( $expression ) {
        return "<?php echo 'Hello World'; ?>";
    } );
} );

Dependencies

Requires

PinkCrab Perique Framework V2 and above.
PHP7.4+

License

MIT License

http://www.opensource.org/licenses/mit-license.html

Previous Perique Support

For support of all versions before Perique V2, please use the BladeOne_Provider

Change Log

1.0.0 - Migrated over from the Perique V2 Prep branch of BladeOne_Provider.
- New Features
- Auth and Permissions now hooked up and based on the current user.
- Perique V2 Module structure.
- WP Nonce support.

pinkcrab / bladeone-engine

Maintainers

Details