Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cakephp/twig-view
Twig View for CakePHP
https://github.com/cakephp/twig-view
cakephp twig twig-template-engine
Last synced: 3 months ago
JSON representation
Twig View for CakePHP
- Host: GitHub
- URL: https://github.com/cakephp/twig-view
- Owner: cakephp
- License: mit
- Created: 2020-03-07T20:30:34.000Z (over 4 years ago)
- Default Branch: 2.x
- Last Pushed: 2024-07-02T20:43:11.000Z (4 months ago)
- Last Synced: 2024-07-04T23:28:16.228Z (4 months ago)
- Topics: cakephp, twig, twig-template-engine
- Language: PHP
- Size: 1.44 MB
- Stars: 13
- Watchers: 18
- Forks: 6
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-cakephp - TwigView plugin - A plugin to use the Twig Templating Language for views. (Templating)
README
# TwigView plugin for CakePHP
[](https://github.com/cakephp/twig-view/actions/workflows/ci.yml)
[](https://packagist.org/packages/cakephp/twig-view)
[](https://packagist.org/packages/cakephp/twig-view/stats)
[](https://coveralls.io/r/cakephp/twig-view?branch=master)
[](LICENSE)
This plugin allows you to use the [Twig Templating Language](https://twig.symfony.com/doc/) 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](https://getcomposer.org/), use the command below.
```bash
composer require cakephp/twig-view
```
Then, [load the `Cake/TwigView` plugin](https://book.cakephp.org/4/en/plugins.html#loading-a-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`.
```php
// 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](https://twig.symfony.com/doc/3.x/api.html#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](https://packagist.org/packages/twig/markdown-extra) `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()`.
```php
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.
```php
class AppView extends TwigView
{
protected $extensions = [
'.custom',
];
}
```
- Twig Loader
You can override the template loader used by Twig.
```php
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`.
```php
protected function initializeExtensions(): void
{
// Load only specific extensions
}
- Twig Profiler
You can override the Twig profiler used when `DebugKit` is loaded.
```php
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.
```twig
{% 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`:
```twig
{{ fetch('title') }}
{{ fetch('meta') }}
{{ fetch('css') }}
{{ fetch('script') }}
{{ fetch('content') }}
```
The layout can be set from the template using the `layout` tag.
```twig
{% 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.
```twig
{{ fetch('content')}}
{{ cell('myCell')}}
{{ element('myElement') }}
```
`TwigView` also provides wrappers for any loaded helper using a special naming convention - `helper_Name_function()`.
```twig
{{ 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]((https://twig.symfony.com/doc/3.x/templates.html#whitespace-control)) on how to remove the extra white space when needed.
### Extension Filters
* `low` maps to [`strtolower`](https://php.net/strtolower)
* `up` maps to [`strtoupper`](https://php.net/strtoupper)
* `env` maps to [`env`](https://book.cakephp.org/4/en/core-libraries/global-constants-and-functions.html#global-functions)
* `pluralize` maps to [`Cake\Utility\Inflector::pluralize`](https://book.cakephp.org/4/en/core-libraries/inflector.html#Cake\\Utility\\Inflector::pluralize)
* `singularize` maps to [`Cake\Utility\Inflector::singularize`](https://book.cakephp.org/4/en/core-libraries/inflector.html#Cake\\Utility\\Inflector::singularize)
* `camelize` maps to [`Cake\Utility\Inflector::camelize`](https://book.cakephp.org/4/en/core-libraries/inflector.html#Cake\\Utility\\Inflector::camelize)
* `underscore` maps to [`Cake\Utility\Inflector::underscore`](https://book.cakephp.org/4/en/core-libraries/inflector.html#Cake\\Utility\\Inflector::underscore)
* `humanize` maps to [`Cake\Utility\Inflector::humanize`](https://book.cakephp.org/4/en/core-libraries/inflector.html#Cake\\Utility\\Inflector::humanize)
* `tableize` maps to [`Cake\Utility\Inflector::tableize`](https://book.cakephp.org/4/en/core-libraries/inflector.html#Cake\\Utility\\Inflector::tableize)
* `classify` maps to [`Cake\Utility\Inflector::classify`](https://book.cakephp.org/4/en/core-libraries/inflector.html#Cake\\Utility\\Inflector::classify)
* `variable` maps to [`Cake\Utility\Inflector::variable`](https://book.cakephp.org/4/en/core-libraries/inflector.html#Cake\\Utility\\Inflector::variable)
* `slug` maps to [`Cake\Utility\Inflector::slug`](https://book.cakephp.org/4/en/core-libraries/inflector.html#Cake\\Utility\\Inflector::slug)
* `toReadableSize` maps to [`Cake\I18n\Number::toReadableSize`](https://book.cakephp.org/4/en/core-libraries/number.html#Cake\\I18n\\Number::toReadableSize)
* `toPercentage` maps to [`Cake\I18n\Number::toPercentage`](https://book.cakephp.org/4/en/core-libraries/number.html#Cake\\I18n\\Number::toPercentage)
* `cake_number_format` maps to [`Cake\I18n\Number::format`](https://book.cakephp.org/4/en/core-libraries/number.html#Cake\\I18n\\Number::format)
* `formatDelta` maps to [`Cake\I18n\Number::formatDelta`](https://book.cakephp.org/4/en/core-libraries/number.html#Cake\\I18n\\Number::formatDelta)
* `currency` maps to [`Cake\I18n\Number::currency`](https://book.cakephp.org/4/en/core-libraries/number.html#Cake\\I18n\\Number::currency)
* `substr` maps to [`substr`](https://php.net/substr)
* `tokenize` maps to [`Cake\Utility\Text::tokenize`](https://book.cakephp.org/4/en/core-libraries/text.html#simple-string-parsing)
* `insert` maps to [`Cake\Utility\Text::insert`](https://book.cakephp.org/4/en/core-libraries/text.html#formatting-strings)
* `cleanInsert` maps to [`Cake\Utility\Text::cleanInsert`](https://book.cakephp.org/4/en/core-libraries/text.html#formatting-strings)
* `wrap` maps to [`Cake\Utility\Text::wrap`](https://book.cakephp.org/4/en/core-libraries/text.html#wrapping-text)
* `wrapBlock` maps to [`Cake\Utility\Text::wrapBlock`](https://book.cakephp.org/4/en/core-libraries/text.html#wrapping-text)
* `wordWrap` maps to [`Cake\Utility\Text::wordWrap`](https://book.cakephp.org/4/en/core-libraries/text.html#wrapping-text)
* `highlight` maps to [`Cake\Utility\Text::highlight`](https://book.cakephp.org/4/en/core-libraries/text.html#highlighting-substrings)
* `tail` maps to [`Cake\Utility\Text::tail`](https://book.cakephp.org/4/en/core-libraries/text.html#truncating-the-tail-of-a-string)
* `truncate` maps to [`Cake\Utility\Text::truncate`](https://book.cakephp.org/4/en/core-libraries/text.html#truncating-text)
* `excerpt` maps to [`Cake\Utility\Text::excerpt`](https://book.cakephp.org/4/en/core-libraries/text.html#extracting-an-excerpt)
* `toList` maps to [`Cake\Utility\Text::toList`](https://book.cakephp.org/4/en/core-libraries/text.html#converting-an-array-to-sentence-)
* `stripLinks` maps to [`Cake\Utility\Text::stripLinks`](https://book.cakephp.org/4/en/core-libraries/text.html#removing-links)
* `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`](https://book.cakephp.org/4/en/core-libraries/text.html#simple-string-parsing)
* `serialize` maps to [`serialize`](https://php.net/serialize)
* `unserialize` maps to [`unserialize`](https://php.net/unserialize)
* `md5` maps to [`md5`](https://php.net/md5)
* `base64_encode` maps to [`base64_encode`](https://php.net/base64_encode)
* `base64_decode` maps to [`base64_decode`](https://php.net/base64_decode)
* `string` cast to [`string`](https://php.net/manual/en/language.types.type-juggling.php)
See `jasny/twig-extensions` for the filters they provide.
### Extension Functions
* `in_array` maps to [`in_array`](https://php.net/in_array)
* `explode` maps to [`explode`](https://php.net/explode)
* `array` cast to [`array`](https://php.net/manual/en/language.types.type-juggling.php)
* `array_push` maps to [`push`](https://php.net/array_push)
* `array_prev` maps to [`prev`](https://php.net/prev)
* `array_next` maps to [`next`](https://php.net/next)
* `array_current` maps to [`current`](https://php.net/current)
* `__` maps to [`__`](https://book.cakephp.org/4/en/core-libraries/internationalization-and-localization.html)
* `__d` maps to [`__d`](https://book.cakephp.org/4/en/core-libraries/internationalization-and-localization.html)
* `__n` maps to [`__n`](https://book.cakephp.org/4/en/core-libraries/internationalization-and-localization.html)
* `__x` maps to [`__x`](https://book.cakephp.org/4/en/core-libraries/internationalization-and-localization.html)
* `__dn` maps to [`__dn`](https://book.cakephp.org/4/en/core-libraries/internationalization-and-localization.html)
* `defaultCurrency` maps to [`Cake\I18n\Number::getDefaultCurrency`](https://book.cakephp.org/4/en/core-libraries/number.html#Cake\\I18n\\Number::getDefaultCurrency)
* `uuid` maps to [`Cake\Utility\Text::uuid`](https://book.cakephp.org/4/en/core-libraries/text.html#generating-uuids)
* `time` passed the first and optional second argument into [`new \Cake\I18n\DateTime()`](https://book.cakephp.org/4/en/core-libraries/time.html#creating-time-instances)
* `timezones` maps to `Cake\I18n\DateTime::listTimezones()`
See `jasny/twig-extensions` for the functions they provide.