README

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

low maps to strtolower
up maps to strtoupper
env maps to env
pluralize maps to Cake\Utility\Inflector::pluralize
singularize maps to Cake\Utility\Inflector::singularize
camelize maps to Cake\Utility\Inflector::camelize
underscore maps to Cake\Utility\Inflector::underscore
humanize maps to Cake\Utility\Inflector::humanize
tableize maps to Cake\Utility\Inflector::tableize
classify maps to Cake\Utility\Inflector::classify
variable maps to Cake\Utility\Inflector::variable
slug maps to Cake\Utility\Inflector::slug
toReadableSize maps to Cake\I18n\Number::toReadableSize
toPercentage maps to Cake\I18n\Number::toPercentage
cake_number_format maps to Cake\I18n\Number::format
formatDelta maps to Cake\I18n\Number::formatDelta
currency maps to Cake\I18n\Number::currency
substr maps to substr
tokenize maps to Cake\Utility\Text::tokenize
insert maps to Cake\Utility\Text::insert
cleanInsert maps to Cake\Utility\Text::cleanInsert
wrap maps to Cake\Utility\Text::wrap
wrapBlock maps to Cake\Utility\Text::wrapBlock
wordWrap maps to Cake\Utility\Text::wordWrap
highlight maps to Cake\Utility\Text::highlight
tail maps to Cake\Utility\Text::tail
truncate maps to Cake\Utility\Text::truncate
excerpt maps to Cake\Utility\Text::excerpt
toList maps to Cake\Utility\Text::toList
stripLinks maps to Cake\Utility\Text::stripLinks
isMultibyte maps to Cake\Utility\Text::isMultibyte
utf8 maps to Cake\Utility\Text::utf8
ascii maps to Cake\Utility\Text::ascii
parseFileSize maps to Cake\Utility\Text::parseFileSize
serialize maps to serialize
unserialize maps to unserialize
md5 maps to md5
base64_encode maps to base64_encode
base64_decode maps to base64_decode
string cast to string

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

Extension Functions

in_array maps to in_array
explode maps to explode
array cast to array
array_push maps to push
array_prev maps to prev
array_next maps to next
array_current maps to current
__ maps to __
__d maps to __d
__n maps to __n
__x maps to __x
__dn maps to __dn
defaultCurrency maps to Cake\I18n\Number::getDefaultCurrency
uuid maps to Cake\Utility\Text::uuid
time passed the first and optional second argument into new \Cake\I18n\DateTime()
timezones maps to Cake\I18n\DateTime::listTimezones()

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

cakephp / twig-view

Maintainers

Details