{"id":13399318,"url":"https://github.com/soberwp/controller","last_synced_at":"2025-03-14T04:31:21.664Z","repository":{"id":40680493,"uuid":"82174892","full_name":"soberwp/controller","owner":"soberwp","description":"Composer package to enable a controller when using Blade with Sage 9","archived":true,"fork":false,"pushed_at":"2021-05-27T14:51:06.000Z","size":225,"stargazers_count":368,"open_issues_count":7,"forks_count":44,"subscribers_count":26,"default_branch":"master","last_synced_at":"2024-12-22T06:02:42.802Z","etag":null,"topics":["blade","blade-template","controller","php","sage","wordpress","wordpress-plugin"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/soberwp.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-02-16T11:45:44.000Z","updated_at":"2024-07-22T02:55:40.000Z","dependencies_parsed_at":"2022-08-24T05:21:26.920Z","dependency_job_id":null,"html_url":"https://github.com/soberwp/controller","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soberwp%2Fcontroller","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soberwp%2Fcontroller/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soberwp%2Fcontroller/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soberwp%2Fcontroller/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/soberwp","download_url":"https://codeload.github.com/soberwp/controller/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243526652,"owners_count":20305108,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blade","blade-template","controller","php","sage","wordpress","wordpress-plugin"],"created_at":"2024-07-30T19:00:36.286Z","updated_at":"2025-03-14T04:31:16.650Z","avatar_url":"https://github.com/soberwp.png","language":"PHP","readme":"# Controller\n\nWordPress 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.)\n\n* [Installation](#installation)\n* [Setup](#setup)\n* [Usage](#usage)\n    * [Overview](#overview)\n    * [Basic Controller](#basic-controller)\n    * [Using Functions](#using-functions)\n    * [Using Components](#using-components)\n    * [Inheriting the Tree/Hierarchy](#inheriting-the-treehierarchy)\n    * [Creating Global Properties](#creating-global-properties)\n    * [Advanced Custom Fields Module](#advanced-custom-fields-module)\n    * [Template Override Option](#template-override-option)\n    * [Lifecycles](#lifecycles)\n    * [Disable Option](#disable-option)\n* [Blade Debugger](#blade-debugger)\n* [Blade Coder](#blade-coder)\n\n\u003cbr\u003e\n\n## Installation\n\n### Composer:\n\n[Sage](https://roots.io/sage/) ships with Controller. However, should you need to install, browse into the Sage theme directory and run;\n\n```shell\n$ composer require soberwp/controller:2.1.2\n```\n\n### Upgrading to 2.x.x:\n\nPlease 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.\n\nController 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. \n\nFolder `controllers/` changes to `Controllers/`, class file names changes to camelcase `App.php` and `FrontPage.php`. Controller namespaces changes to `namespace App\\Controllers;`\n\n### Requirements:\n\n* [PHP](http://php.net/manual/en/install.php) \u003e= 7.0\n\n## Setup\n\nBy default Controller uses namespace `Controllers`.\n\nController 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`\n\n```php\n\nadd_filter('sober/controller/namespace', function () {\n    return 'Data';\n});\n```\n\n## Usage\n\n### Overview:\n\n* Controller class names follow the same hierarchy as WordPress.\n* The Controller class name should match the filename\n    * For example `App.php` should define class as `class App extends Controller`\n* Create methods within the Controller Class;\n    * Use `public function` to return data to the Blade views/s\n        * The method name becomes the variable name in Blade\n        * Camel case is converted to snake case. `public function ExampleForUser` in the Controller becomes `$example_for_user` in the Blade template\n        * If the same method name is declared twice, the latest instance will override the previous\n    * Use `public static function` to use run the method from your Blade template which returns data. This is useful for loops\n        * The method name is not converted to snake case\n        * 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()`\n        * If the same method name is declared twice, the latest instance will override the previous\n    * Use `protected function` for internal methods. These will not be exposed to Blade. You can run them within `__construct`\n        * Dependency injection with type hinting is available through `__construct`\n\n\nThe above may sound complicated on first read, so let's take a look at some examples to see how simple Controller is to use.\n\n### Basic Controller;\n\nThe following example will expose `$images` to `resources/views/single.blade.php`\n\n**app/Controllers/Single.php**\n\n```php\n\u003c?php\n\nnamespace App\\Controllers;\n\nuse Sober\\Controller\\Controller;\n\nclass Single extends Controller\n{\n    /**\n     * Return images from Advanced Custom Fields\n     *\n     * @return array\n     */\n    public function images()\n    {\n        return get_field('images');\n    }\n}\n```\n\n**resources/views/single.blade.php**\n\n```php\n@if($images)\n  \u003cul\u003e\n    @foreach($images as $image)\n      \u003cli\u003e\u003cimg src=\"{{$image['sizes']['thumbnail']}}\" alt=\"{{$image['alt']}}\"\u003e\u003c/li\u003e\n    @endforeach\n  \u003c/ul\u003e\n@endif\n```\n\n### Using Functions;\n\nYou can use static methods to run a function from within your view.\n\nThis is useful if you are within the loop and want to return data for each post item.\n\n**app/Controllers/Archive.php**\n\n```php\n\u003c?php\n\nnamespace App\\Controllers;\n\nuse Sober\\Controller\\Controller;\n\nclass Archive extends Controller\n{\n    public static function title()\n    {\n        return get_post()-\u003epost_title;\n    }\n}\n```\n\n**resources/views/archive.php**\n\n```php\n@extends('layouts.app')\n\n@section('content')\n\n  @while (have_posts()) @php the_post() @endphp\n    {{ Archive::title() }}\n  @endwhile\n\n@endsection\n```\n\n### Using Components;\n\nYou can also create reusable components and include them in any Controller class using PHP traits.\n\n**app/Controllers/Partials/Images.php**\n\n```php\n\u003c?php\n\nnamespace App\\Controllers\\Partials;\n\ntrait Images\n{\n    public function images()\n    {\n        return get_field('images');\n    }\n}\n```\n\nYou can now include the Images trait into any view to pass on variable $images;\n\n**app/Controllers/Single.php**\n\n```php\n\u003c?php\n\nnamespace App\\Controllers;\n\nuse Sober\\Controller\\Controller;\n\nclass Single extends Controller\n{\n    use Partials\\Images;\n}\n```\n\n### Inheriting the Tree/Hierarchy;\n\nBy default, each Controller overrides its template hierarchy depending on the specificity of the Controller (the same way WordPress templates work).\n\nYou can inherit the data from less specific Controllers in the hierarchy by implementing the Tree.\n\nFor example, the following `app/Controllers/Single.php` example will inherit methods from `app/Controllers/Singular.php`;\n\n**app/Controllers/Single.php**\n\n```php\n\u003c?php\n\nnamespace App\\Controllers;\n\nuse Sober\\Controller\\Controller;\nuse Sober\\Controller\\Module\\Tree;\n\nclass Single extends Controller implements Tree\n{\n\n}\n```\n\nIf you prefer you can also do this;\n\n```php\n\u003c?php\n\nnamespace App\\Controllers;\n\nuse Sober\\Controller\\Controller;\n\nclass Single extends Controller\n{\n    protected $tree = true;\n}\n```\n\nYou can override a `app/Controllers/Singular.php` method by declaring the same method name in `app/Controllers/Single.php`;\n\n### Creating Global Properties;\n\nMethods 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.\n\n**app/Controllers/App.php**\n\n```php\n\u003c?php\n\nnamespace App\\Controllers;\n\nuse Sober\\Controller\\Controller;\n\nclass App extends Controller\n{\n    public function siteName()\n    {\n        return get_bloginfo('name');\n    }\n}\n```\n\n### Advanced Custom Fields Module;\n\nController has an useful Advanced Custom Fields helper module to automate passing on fields.\n\nThe 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.\n\n```php\n\u003c?php\n\nnamespace App\\Controllers;\n\nuse Sober\\Controller\\Controller;\n\nclass Single extends Controller\n{\n    // Pass on all fields from Advanced Custom Fields to the view\n    protected $acf = true;\n\n    // Pass on only field_1 from Advanced Custom Fields to the view\n    protected $acf = 'field_1';\n\n    // Pass on multiple fields from Advanced Custom Fields to the view\n    protected $acf = ['field_1', 'field_2'];\n}\n```\n\nClone 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.\n\nThe values are returned as objects, however you can disable this to keep them as arrays.\n\n```php\nadd_filter('sober/controller/acf/array', function () {\n    return true;\n});\n```\n\n### Template Override Option;\n\nYou should only use overrides in edge-case scenarios. Sticking to the WordPress hierarchy is recommended usage. However, one edge-case is the 404 template.\n\nIn 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';`\n\n```php\n\u003c?php\n\nnamespace App\\Controllers;\n\nuse Sober\\Controller\\Controller;\n\nclass FourZeroFour extends Controller\n{\n    protected $template = '404';\n}\n```\n\n### Lifecycles;\n\nController Classes come with two lifecycle hooks for greater control. \n\n```php\npublic function __before()\n{\n    // runs after this-\u003edata is set up, but before the class methods are run\n}\n\npublic function __after()\n{\n    // runs after all the class methods have run\n}\n```\n\n### Disable Option;\n\n```php\nprotected $active = false;\n```\n\n### Blade Debugger;\n\nIn your Blade views, `resources/views`, you can use the following to assist with debugging;\n\n* `@debug`\n* `@dump(__var__)`\n\n### Blade Coder;\n\nIn your Blade views, `resources/views`, you can use the following to assist with jump-starting coding;\n\n* `@code`\n* `@code('__name of variable as string__')`\n\nTo wrap the code in if statements, use `@codeif`\n\n* `@codeif`\n* `@codeif('__name of variable as string__')`\n\n## Support\n\n* Follow [@withjacoby](https://twitter.com/withjacoby) on Twitter\n* Buy me a beer or pay my rent, [paypal.me/darrenjacoby](https://paypal.me/darrenjacoby)\n\n## Updates\n\n* Change the composer.json version to 2.1.2\n* Check [CHANGELOG.md](CHANGELOG.md) for any breaking changes before updating.\n\n```shell\n$ composer update\n```\n","funding_links":["https://paypal.me/darrenjacoby"],"categories":["PHP","WordPress Libraries","Documentation","Features"],"sub_categories":["Build commands"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoberwp%2Fcontroller","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoberwp%2Fcontroller","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoberwp%2Fcontroller/lists"}