Download the PHP package / without Composer

Controller

WordPress package to enable a controller when using Blade with Sage 9 (Please note, Sage 10 uses Composers and not this package.)

• Installation
• Setup
• Usage
  • Overview
  • Basic Controller
  • Using Functions
  • Using Components
  • Inheriting the Tree/Hierarchy
  • Creating Global Properties
  • Advanced Custom Fields Module
  • Template Override Option
  • Lifecycles
  • Disable Option
• Blade Debugger
• Blade Coder

Installation

Composer:

Sage ships with Controller. However, should you need to install, browse into the Sage theme directory and run;

Upgrading to 2.x.x:

Please 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;

Requirements:

• PHP >= 7.0

Setup

By default Controller uses namespace Controllers.

Controller takes advantage of PSR-4 autoloading. To change the namespace, use the filter below within functions.php

Usage

Overview:

• Controller class names follow the same hierarchy as WordPress.
• The Controller class name should match the filename
  • For example App.php should define class as class App extends Controller
• Create methods within the Controller Class;
  • Use public function to 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 ExampleForUser in the Controller becomes $example_for_user in the Blade template
    • If the same method name is declared twice, the latest instance will override the previous
  • Use public static function to 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 Example in App.php can be run in Blade using App::Example()
    • If the same method name is declared twice, the latest instance will override the previous
  • Use protected function for internal methods. These will not be exposed to Blade. You can run them within __construct
    • Dependency injection with type hinting is available through __construct

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.

Basic Controller;

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

app/Controllers/Single.php

resources/views/single.blade.php

Using Functions;

You 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

resources/views/archive.php

Using Components;

You can also create reusable components and include them in any Controller class using PHP traits.

app/Controllers/Partials/Images.php

You can now include the Images trait into any view to pass on variable $images;

app/Controllers/Single.php

Inheriting the Tree/Hierarchy;

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

If you prefer you can also do this;

You can override a app/Controllers/Singular.php method by declaring the same method name in app/Controllers/Single.php;

Creating Global Properties;

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

Advanced Custom Fields Module;

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.

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.

Template Override Option;

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';

Lifecycles;

Controller Classes come with two lifecycle hooks for greater control.

Disable Option;

Blade Debugger;

In your Blade views, resources/views, you can use the following to assist with debugging;

• @debug
• @dump(__var__)

Blade Coder;

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__')

Support

• Follow @withjacoby on Twitter
• Buy me a beer or pay my rent, paypal.me/darrenjacoby

Updates

• Change the composer.json version to 2.1.2
• Check CHANGELOG.md for any breaking changes before updating.