From 206bb3f06182908188edcc46b3dae41d4372800a Mon Sep 17 00:00:00 2001 From: Daniel Opitz Date: Mon, 15 Jul 2024 19:04:34 +0200 Subject: [PATCH] Add pages for Twig-View and PHP-View (#726) * Add Twig and PHP-View pages --- _config.yml | 2 + docs/v4/features/php-view.md | 71 ++++++++++++++++++ docs/v4/features/templates.md | 132 ++-------------------------------- docs/v4/features/twig-view.md | 89 +++++++++++++++++++++++ 4 files changed, 168 insertions(+), 126 deletions(-) create mode 100644 docs/v4/features/php-view.md create mode 100644 docs/v4/features/twig-view.md diff --git a/_config.yml b/_config.yml index 633a120c..6adee9b6 100644 --- a/_config.yml +++ b/_config.yml @@ -89,6 +89,8 @@ defaults: - title: Add Ons items: - [/docs/v4/features/templates.md, Templates] + - [/docs/v4/features/twig-view.md, Twig Templates] + - [/docs/v4/features/php-view.md, PHP Templates] - title: Contributing items: - [/docs/v4/contributors/strategy.md, Branching Strategy] diff --git a/docs/v4/features/php-view.md b/docs/v4/features/php-view.md new file mode 100644 index 00000000..97d6c0f4 --- /dev/null +++ b/docs/v4/features/php-view.md @@ -0,0 +1,71 @@ +--- +title: PHP Templates +--- + +## The slim/php-view component + +The [PHP-View](https://github.com/slimphp/PHP-View) PHP component helps you render PHP templates. + +## Installation + +``` +composer require slim/php-view +``` + +## Usage + +You can use it with Slim like this: + +```php +get('/hello', function ($request, $response) { + $renderer = new PhpRenderer(__DIR__ . '/../templates'); + + $viewData = [ + 'name' => 'John', + ]; + + return $renderer->render($response, 'hello.php', $viewData); +})->setName('profile'); + +$app->run(); +``` + +Create a directory in your project root: `templates/` + +Create a template file within the templates directory: `templates/hello.php` + +**Template content:** + +```php + + + + + + Slim Example + + +

Hello,

+ + +``` + +Output: + +``` +Hello John +``` + +**Security note:** It's important to ensure that the dynamic +output is properly [escaped](https://github.com/slimphp/PHP-View?tab=readme-ov-file#escaping-values). + diff --git a/docs/v4/features/templates.md b/docs/v4/features/templates.md index 8f6f3937..1b1a5d0b 100644 --- a/docs/v4/features/templates.md +++ b/docs/v4/features/templates.md @@ -8,133 +8,13 @@ Each Slim application route is responsible for preparing and returning an approp > Slim's "view" is the HTTP response. -That being said, the Slim project provides the [Twig-View](#the-slimtwig-view-component) and [PHP-View](#the-slimphp-view-component) components to help you render templates to a PSR7 Response object. - -## The slim/twig-view component - -The [Twig-View][twigview] PHP component helps you render [Twig][twig] templates in your application. -This component is available on Packagist, and it's easy to install with Composer like this: - -[twigview]: https://github.com/slimphp/Twig-View -[twig]: http://twig.symfony.com/ - -
-```bash -composer require slim/twig-view -``` -
Figure 1: Install slim/twig-view component.
-
- -Next, you need to add the slim/twig-view middleware to the Slim app: - -
-```php - false]); - -// Add Twig-View Middleware -$app->add(TwigMiddleware::create($app, $twig)); -``` -
Figure 2: Add slim/twig-view middleware.
-
- -**Note:** For production scenarios, `cache` should be set to some `'path/to/cache'` to store compiled templates (thus avoiding recomplication on every request). -For more information, see [Twig environment options](http://twig.symfony.com/doc/3.x/api.html#environment-options) - -Now you can use the `slim/twig-view` component service inside an app route to render a template and write it to a PSR-7 Response object like this: - -
-```php -$app->get('/hello/{name}', function ($request, $response, $args) { - $view = Twig::fromRequest($request); - return $view->render($response, 'profile.html', [ - 'name' => $args['name'] - ]); -})->setName('profile'); - -// Run app -$app->run(); -``` -
Figure 3: Render template with slim/twig-view container service.
-
- -In this example, `$view` invoked inside the route callback is a reference to the `\Slim\Views\Twig` instance returned by the `fromRequest` method. -The `\Slim\Views\Twig` instance's `render()` method accepts a PSR-7 Response object as its first argument, the Twig template path as its second argument, and an array of template variables as its final argument. -The `render()` method returns a new PSR-7 Response object whose body is the rendered Twig template. - -### The url_for() method - -The `slim/twig-view` component exposes a custom `url_for()` function to your Twig templates. -You can use this function to generate complete URLs to any named route in your Slim application. -The `url_for()` function accepts two arguments: - -1. A route name -2. A hash of route placeholder names and replacement values - -The second argument's keys should correspond to the selected route's pattern placeholders. -This is an example Twig template that draws a link URL for the "profile" named route shown in the example Slim application above. - -```html -{% raw %} -{% extends "layout.html" %} - -{% block body %} -

User List

- -{% endblock %} -{% endraw %} -``` - -## The slim/php-view component - -The [PHP-View][phpview] PHP component helps you render PHP templates. -This component is available on Packagist and can be installed using Composer like this: - -[phpview]: https://github.com/slimphp/PHP-View - -
-``` -composer require slim/php-view -``` -
Figure 6: Install slim/php-view component.
-
- -You can use it with Slim like this: - -
-```php -get('/hello/{name}', function ($request, $response, $args) { - $renderer = new PhpRenderer('path/to/templates'); - return $renderer->render($response, "hello.php", $args); -})->setName('profile'); - -$app->run(); -``` -
Figure 8: Render template with slim/php-view service.
-
+That being said, the Slim project provides the [Twig-View](twig-view.html) and [PHP-View](php-view.html) components +to help you render templates to a PSR-7 Response object. ## Other template systems You are not limited to the `Twig-View` and `PHP-View` components. -You can use any PHP template system provided that you ultimately write the rendered template output to the PSR-7 Response object's body. +You can use any PHP template system provided that you ultimately +write the rendered template output to the PSR-7 Response object's body. + + diff --git a/docs/v4/features/twig-view.md b/docs/v4/features/twig-view.md new file mode 100644 index 00000000..4f46efa7 --- /dev/null +++ b/docs/v4/features/twig-view.md @@ -0,0 +1,89 @@ +--- +title: Twig Templates +--- + +## The slim/twig-view component + +The [Twig-View][twigview] PHP component helps you render [Twig][twig] templates in your application. +This component is available on Packagist, and it's easy to install with Composer like this: + +[twigview]: https://github.com/slimphp/Twig-View +[twig]: https://twig.symfony.com/ + +## Installation + +``` +composer require slim/twig-view +``` + +## Usage + +Next, you need to add the middleware to the Slim app: + +```php + false]); + +// Add Twig-View Middleware +$app->add(TwigMiddleware::create($app, $twig)); +``` + +**Note:** For production scenarios, `cache` should be set to some +`'path/to/cache'` to store compiled templates (thus avoiding recompilation on every request). +For more information, see [Twig environment options](https://twig.symfony.com/doc/3.x/api.html#environment-options) + +Now you can use the `slim/twig-view` component service inside +an app route to render a template and write it to a PSR-7 Response object like this: + +```php +$app->get('/hello', function ($request, $response) { + $view = Twig::fromRequest($request); + + return $view->render($response, 'profile.html', [ + 'name' => 'John', + ]); +})->setName('profile'); + +// Run app +$app->run(); +``` + +In this example, `$view` invoked inside the route callback is a reference to the `\Slim\Views\Twig` instance returned by the `fromRequest` method. +The `\Slim\Views\Twig` instance's `render()` method accepts a PSR-7 Response object as its first argument, the Twig template path as its second argument, and an array of template variables as its final argument. +The `render()` method returns a new PSR-7 Response object whose body is the rendered Twig template. + +### The url_for() method + +The `slim/twig-view` component exposes a custom `url_for()` function to your Twig templates. +You can use this function to generate complete URLs to any named route in your Slim application. +The `url_for()` function accepts two arguments: + +1. A route name +2. A hash of route placeholder names and replacement values + +The second argument's keys should correspond to the selected route's pattern placeholders. +This is an example Twig template that draws a link URL for the "profile" named route shown in the example Slim application above. + +```html +{% raw %} +{% extends "layout.html" %} + +{% block body %} +

User List

+ +{% endblock %} +{% endraw %} +```