WordPress package to enable a controller when using Blade with Sage 9 (Please note, Sage 10 uses Composers and not this package.)
Sage ships with Controller. However, should you need to install, browse into the Sage theme directory and run;
$ composer require soberwp/controller:2.1.2Please note that versions 2.x.x are newer releases than 9.x.x-beta. The 9 was used to match Sage 9 versioning at the time.
Controller 2.x.x uses PSR4 autoloading to load Controller classes. This is considered best practice. You will need to update the following files from 9.0.0-beta versions.
Folder controllers/ changes to Controllers/, class file names changes to camelcase App.php and FrontPage.php. Controller namespaces changes to namespace App\Controllers;
- PHP >= 7.0
By default Controller uses namespace Controllers.
Controller takes advantage of PSR-4 autoloading. To change the namespace, use the filter below within functions.php
add_filter('sober/controller/namespace', function () {
return 'Data';
});- Controller class names follow the same hierarchy as WordPress.
- The Controller class name should match the filename
- For example
App.phpshould define class asclass App extends Controller
- For example
- Create methods within the Controller Class;
- Use
public functionto return data to the Blade views/s- The method name becomes the variable name in Blade
- Camel case is converted to snake case.
public function ExampleForUserin the Controller becomes$example_for_userin the Blade template - If the same method name is declared twice, the latest instance will override the previous
- Use
public static functionto use run the method from your Blade template which returns data. This is useful for loops- The method name is not converted to snake case
- You access the method using the class name, followed by the method.
public static function ExampleinApp.phpcan be run in Blade usingApp::Example() - If the same method name is declared twice, the latest instance will override the previous
- Use
protected functionfor internal methods. These will not be exposed to Blade. You can run them within__construct- Dependency injection with type hinting is available through
__construct
- Dependency injection with type hinting is available through
- Use
The above may sound complicated on first read, so let's take a look at some examples to see how simple Controller is to use.
The following example will expose $images to resources/views/single.blade.php
app/Controllers/Single.php
<?php
namespace App\Controllers;
use Sober\Controller\Controller;
class Single extends Controller
{
/**
* Return images from Advanced Custom Fields
*
* @return array
*/
public function images()
{
return get_field('images');
}
}resources/views/single.blade.php
@if($images)
<ul>
@foreach($images as $image)
<li><img src="{{$image['sizes']['thumbnail']}}" alt="{{$image['alt']}}"></li>
@endforeach
</ul>
@endifYou can use static methods to run a function from within your view.
This is useful if you are within the loop and want to return data for each post item.
app/Controllers/Archive.php
<?php
namespace App\Controllers;
use Sober\Controller\Controller;
class Archive extends Controller
{
public static function title()
{
return get_post()->post_title;
}
}resources/views/archive.php
@extends('layouts.app')
@section('content')
@while (have_posts()) @php the_post() @endphp
{{ Archive::title() }}
@endwhile
@endsectionYou can also create reusable components and include them in any Controller class using PHP traits.
app/Controllers/Partials/Images.php
<?php
namespace App\Controllers\Partials;
trait Images
{
public function images()
{
return get_field('images');
}
}You can now include the Images trait into any view to pass on variable $images;
app/Controllers/Single.php
<?php
namespace App\Controllers;
use Sober\Controller\Controller;
class Single extends Controller
{
use Partials\Images;
}By default, each Controller overrides its template hierarchy depending on the specificity of the Controller (the same way WordPress templates work).
You can inherit the data from less specific Controllers in the hierarchy by implementing the Tree.
For example, the following app/Controllers/Single.php example will inherit methods from app/Controllers/Singular.php;
app/Controllers/Single.php
<?php
namespace App\Controllers;
use Sober\Controller\Controller;
use Sober\Controller\Module\Tree;
class Single extends Controller implements Tree
{
}If you prefer you can also do this;
<?php
namespace App\Controllers;
use Sober\Controller\Controller;
class Single extends Controller
{
protected $tree = true;
}You can override a app/Controllers/Singular.php method by declaring the same method name in app/Controllers/Single.php;
Methods created in app/Controllers/App.php will be inherited by all views and can not be disabled as resources/views/layouts/app.php extends all views.
app/Controllers/App.php
<?php
namespace App\Controllers;
use Sober\Controller\Controller;
class App extends Controller
{
public function siteName()
{
return get_bloginfo('name');
}
}Controller has an useful Advanced Custom Fields helper module to automate passing on fields.
The automated fields will use the variable names from Advanced Custom Fields and pass them onto the view. Controller also passes on options values by default.
<?php
namespace App\Controllers;
use Sober\Controller\Controller;
class Single extends Controller
{
// Pass on all fields from Advanced Custom Fields to the view
protected $acf = true;
// Pass on only field_1 from Advanced Custom Fields to the view
protected $acf = 'field_1';
// Pass on multiple fields from Advanced Custom Fields to the view
protected $acf = ['field_1', 'field_2'];
}Clone fields will return the value of each the fields in a separate variable, unless the Prefix Field Names option is enabled in which case the the cloned fields will be returned in an object with the field name given to the clone field.
The values are returned as objects, however you can disable this to keep them as arrays.
add_filter('sober/controller/acf/array', function () {
return true;
});You should only use overrides in edge-case scenarios. Sticking to the WordPress hierarchy is recommended usage. However, one edge-case is the 404 template.
In your Blade view, you would have 404.blade.php as it begins with a number. In this case, you could rename your Controller class FourZeroFour.php and use parameter $template = '404';
<?php
namespace App\Controllers;
use Sober\Controller\Controller;
class FourZeroFour extends Controller
{
protected $template = '404';
}Controller Classes come with two lifecycle hooks for greater control.
public function __before()
{
// runs after this->data is set up, but before the class methods are run
}
public function __after()
{
// runs after all the class methods have run
}protected $active = false;In your Blade views, resources/views, you can use the following to assist with debugging;
@debug@dump(__var__)
In your Blade views, resources/views, you can use the following to assist with jump-starting coding;
@code@code('__name of variable as string__')
To wrap the code in if statements, use @codeif
@codeif@codeif('__name of variable as string__')
- Follow @withjacoby on Twitter
- Buy me a beer or pay my rent, paypal.me/darrenjacoby
- Change the composer.json version to 2.1.2
- Check CHANGELOG.md for any breaking changes before updating.
$ composer update
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent