cakephp/twig-view

Twig powered View for CakePHP

Installs: 2 873 692

Dependents: 7

Suggesters: 0

Security: 0

Stars: 13

Watchers: 19

Forks: 7

Open Issues: 2

Type:cakephp-plugin

2.0.3 2024-10-11 07:53 UTC

README

CI Latest Stable Version Total Downloads Code Coverage Software License

This plugin allows you to use the Twig Templating Language for your views.

It provides wrappers for common View opertions and many helpful extensions that expose CakePHP functions and jasny/twig-extensions helpers.

Installation

To install with Composer, use the command below.

composer require cakephp/twig-view

Then, load the Cake/TwigView plugin in your Application bootstrap just like other Cake plugins.

Configuration

TwigView allows you to configure the Twig Environment through View options. You can set these through ViewBuilder in the Controller or set them directly in TwigView.

// In controller
public function initialize(): void
{
    $this->viewBuilder()->setOption('environment', ['cache' => false]);
}

// In your AppView
public function initialize(): void
{
    $this->setConfig('environment', ['cache' => false]);

    // Call parent TwigView initialize
    parent::initialize();
}

Available Options

  • environment

    Twig Environment options.

    Defaults to empty.

  • markdown

    Which markdown engine is used for markdown_to_html filter. Set to default to use DefaultMarkdown or set custom Twig Markdown extension MarkdownInterface instance.

    If using default, require one of: - erusev/parsedown - league/commonmark - michelf/php-markdown

    Defaults to disabled.

AppView Setup

To start using Twig templates in your application, simply extend TwigView in your AppView. In general, it is safe to add your application's setup in AppView::initialize().

namespace App\View;

use Cake\TwigView\View\TwigView;

class AppView extends TwigView
{
    public function initialize(): void
    {
        parent::initialize();

        // Add application-specific extensions
    }
}

Customization

You can override several parts of TwigView initialization to create a custom Twig setup.

  • File Extensions

    You can specify the file extensions used to search for templates by overriding the $extensions property.

    class AppView extends TwigView
    {
        protected $extensions = [
            '.custom',
        ];
    }
  • Twig Loader

    You can override the template loader used by Twig.

    protected function createLoader(): \Twig\Loader\LoaderInterface
    {
        // Return a custom Twig template loader
    }
  • Twig Extensions

    You can override the Twig Extensions loading. If you want to use the built-in View wrappers, make sure you load Cake\TwigView\Twig\Extensions\ViewExtension.

    protected function initializeExtensions(): void
    {
        // Load only specific extensions
    }
  • Twig Profiler

    You can override the Twig profiler used when DebugKit is loaded.

        protected function initializeProfiler(): void
        {
            parent::initializeProfiler();
            // Add custom profiler logging using $this->getProfile()
        }

Templates

You can create views using Twig templates much like you can with standard CakePHP templates.

Templates are loaded the same way wherever they are used and follow the View path conventions.

{% extends 'Common/base' %}
{{ include('Common/helper') }}
  • Template names are always relative to App.path.templates not the current file.
  • File extensions are automatically generated. Defaults to '.twig'.
  • Templates can be loaded from plugins the same as View templates.

Layout templates are supported and loaded the same way as View layouts.

templates/layout/default.twig:

<!DOCTYPE html>
<html>
<head>
    <title>
        {{ fetch('title') }}
    </title>

    {{ fetch('meta') }}
    {{ fetch('css') }}
    {{ fetch('script') }}
</head>
<body>
    {{ fetch('content') }}
</body>
</html>

The layout can be set from the template using the layout tag.

{% layout 'Error' %}

Accessing View

You can access the View instance using the _view global.

TwigView provides wrappers for fetch(), cell() and element() rendering. Cell and element templates are always loaded from cell/ and element/ sub-directories the same as View templates.

{{ fetch('content')}}

{{ cell('myCell')}}
{{ element('myElement') }}

TwigView also provides wrappers for any loaded helper using a special naming convention - helper_Name_function().

{{ helper_Text_autoParagraph('some text for a paragarph') }}

All wrapper functions are pre-escaped and do not require using |raw filter. However, keep in mind that Twig keeps the whitespace when using {{ }} to print. Please read the Twig documentation on how to remove the extra white space when needed.

Extension Filters

See jasny/twig-extensions for the filters they provide.

Extension Functions

See jasny/twig-extensions for the functions they provide.