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.
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.
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();
}
environment
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.
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
}
}
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()
}
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') }}
App.path.templates
not the current file.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' %}
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.
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.
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.