Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/soberwp/controller

Composer package to enable a controller when using Blade with Sage 9
https://github.com/soberwp/controller

blade blade-template controller php sage wordpress wordpress-plugin

Last synced: about 2 months ago
JSON representation

Composer package to enable a controller when using Blade with Sage 9

Awesome Lists containing this project

README 

        
# Controller



WordPress package to enable a controller when using Blade with [Sage 9](https://roots.io/sage/) (Please note, Sage 10 uses Composers and not this package.)



* [Installation](#installation)

* [Setup](#setup)

* [Usage](#usage)

    * [Overview](#overview)

    * [Basic Controller](#basic-controller)

    * [Using Functions](#using-functions)

    * [Using Components](#using-components)

    * [Inheriting the Tree/Hierarchy](#inheriting-the-treehierarchy)

    * [Creating Global Properties](#creating-global-properties)

    * [Advanced Custom Fields Module](#advanced-custom-fields-module)

    * [Template Override Option](#template-override-option)

    * [Lifecycles](#lifecycles)

    * [Disable Option](#disable-option)

* [Blade Debugger](#blade-debugger)

* [Blade Coder](#blade-coder)







## Installation



### Composer:



[Sage](https://roots.io/sage/) ships with Controller. However, should you need to install, browse into the Sage theme directory and run;



```shell

$ composer require soberwp/controller:2.1.2

```



### 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](https://www.php-fig.org/psr/psr-4/) to load Controller classes. This is considered best practice. You will need to [update the following files](https://github.com/roots/sage/pull/2025/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](http://php.net/manual/en/install.php) >= 7.0



## Setup



By default Controller uses namespace `Controllers`.



Controller takes advantage of [PSR-4 autoloading](https://www.php-fig.org/psr/psr-4/). To change the namespace, use the filter below within `functions.php`



```php



add_filter('sober/controller/namespace', function () {

    return 'Data';

});

```



## 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**



```php



    @foreach($images as $image)

      
  • {{$image['alt']}}
    • 

        @endforeach

      

    @endif

    ```
    


    ### 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**
    


    ```php

    post_title;

        }

    }

    ```
    


    **resources/views/archive.php**
    


    ```php

    @extends('layouts.app')
    


    @section('content')
    


      @while (have_posts()) @php the_post() @endphp

        {{ Archive::title() }}

      @endwhile
    


    @endsection

    ```
    


    ### Using Components;
    


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


    **app/Controllers/Partials/Images.php**
    


    ```php

    data is set up, but before the class methods are run

    }
    


    public function __after()

    {

        // runs after all the class methods have run

    }

    ```
    


    ### Disable Option;
    


    ```php

    protected $active = false;

    ```
    


    ### 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](https://twitter.com/withjacoby) on Twitter

    * Buy me a beer or pay my rent, [paypal.me/darrenjacoby](https://paypal.me/darrenjacoby)
    


    ## Updates
    


    * Change the composer.json version to 2.1.2

    * Check [CHANGELOG.md](CHANGELOG.md) for any breaking changes before updating.
    


    ```shell

    $ composer update

    ```