From 1a992c4a6ba285de06c6723676e01d490fbc7055 Mon Sep 17 00:00:00 2001 From: Daniel Opitz Date: Sat, 13 Jul 2024 11:19:49 +0200 Subject: [PATCH 1/5] Update readme --- README.md | 119 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 84 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 7432f36..af1145d 100644 --- a/README.md +++ b/README.md @@ -12,12 +12,13 @@ This is a renderer for rendering PHP view scripts into a PSR-7 Response object. ### Cross-site scripting (XSS) risks -Note that PHP-View has no built-in mitigation from XSS attacks. It is the developer's responsibility to use `htmlspecialchars()` or a component like [laminas-escaper](https://github.com/laminas/laminas-escaper). Alternatively, consider [Twig-View](https://github.com/slimphp/Twig-View). - +Note that PHP-View has no built-in mitigation from XSS attacks. +It is the developer's responsibility to use `htmlspecialchars()` +or a component like [laminas-escaper](https://github.com/laminas/laminas-escaper). Alternatively, consider [Twig-View](https://github.com/slimphp/Twig-View). ## Installation -Install with [Composer](http://getcomposer.org): +Install with Composer: ``` composer require slim/php-view @@ -28,13 +29,14 @@ composer require slim/php-view ```php use Slim\Views\PhpRenderer; -include "vendor/autoload.php"; +include 'vendor/autoload.php'; $app = Slim\AppFactory::create(); $app->get('/hello/{name}', function ($request, $response, $args) { $renderer = new PhpRenderer('path/to/templates'); - return $renderer->render($response, "hello.php", $args); + + return $renderer->render($response, 'hello.php', $args); }); $app->run(); @@ -46,87 +48,134 @@ Note that you could place the PhpRenderer instantiation within your DI Container ```php //Construct the View -$phpView = new PhpRenderer("path/to/templates"); +$renderer = new PhpRenderer('path/to/templates'); + +$viewData = [ + 'key1' => 'value1', + 'key2' => 'value2', +]; -//Render a Template -$response = $phpView->render(new Response(), "hello.php", $yourData); +// Render a template +$response = $renderer->render(new Response(), 'hello.php', $viewData); ``` ## Template Variables + You can now add variables to your renderer that will be available to all templates you render. ```php -// via the constructor -$templateVariables = [ - "title" => "Title" +// Via the constructor +$globalViewData = [ + 'title' => 'Title' ]; -$phpView = new PhpRenderer("path/to/templates", $templateVariables); + +$renderer = new PhpRenderer('path/to/templates', $globalViewData); // or setter -$phpView->setAttributes($templateVariables); +$viewData = [ + 'key1' => 'value1', + 'key2' => 'value2', +]; +$renderer->setAttributes($viewData); // or individually -$phpView->addAttribute($key, $value); +$renderer->addAttribute($key, $value); ``` -Data passed in via `->render()` takes precedence over attributes. +Data passed in via the `render()` method takes precedence over attributes. ```php -$templateVariables = [ - "title" => "Title" +$viewData = [ + 'title' => 'Title' ]; -$phpView = new PhpRenderer("path/to/templates", $templateVariables); +$renderer = new PhpRenderer('path/to/templates', $viewData); //... -$phpView->render($response, $template, [ - "title" => "My Title" +$response = $renderer->render($response, $template, [ + 'title' => 'My Title' ]); + // In the view above, the $title will be "My Title" and not "Title" ``` ## Sub-templates Inside your templates you may use `$this` to refer to the PhpRenderer object to render sub-templates. -If using a layout the `fetch()` method can be used instead of `render()` to avoid appling the layout to the sub-template. +If using a layout the `fetch()` method can be used instead of `render()` to avoid applying the layout to the sub-template. -```phtml -fetch('./path/to/partial.phtml', ["name" => "John"])?> +```php +fetch('./path/to/partial.phtml', ['name' => 'John'])?> ``` ## Rendering in Layouts -You can now render view in another views called layouts, this allows you to compose modular view templates + +You can now render view in another views called layouts, +this allows you to compose modular view templates and help keep your views DRY. -Create your layout `path/to/templates/layout.php`. -```phtml +Create your layout `path/to/templates/layout.php` + +```php <?=$title?> ``` -Create your view template `path/to/templates/hello.php`. -```phtml +Create your view template `path/to/templates/hello.php` + +```php Hello ! ``` Rendering in your code. + ```php -$phpView = new PhpRenderer("path/to/templates", ["title" => "My App"]); -$phpView->setLayout("layout.php"); +$renderer = new PhpRenderer('path/to/templates', ['title' => 'My App']); +$renderer->setLayout('layout.php'); + +$viewData = [ + 'title' => 'Hello - My App', + 'name' => 'John', +]; //... -$phpview->render($response, "hello.php", ["title" => "Hello - My App", "name" => "John"]); +$response = $renderer->render($response, 'hello.php', $viewData); ``` Response will be + ```html Hello - My AppHello John! ``` -Please note, the $content is special variable used inside layouts to render the wrapped view and should not be set -in your view paramaters. +Please note, the `$content` is special variable used inside layouts +to render the wrapped view and should not be set in your view parameters. + +## Escaping values + +It's essential to ensure that the HTML output is secure to +prevent common web vulnerabilities like Cross-Site Scripting (XSS). +This package has no built-in mitigation from XSS attacks. + +The following function uses the `htmlspecialchars` function +with specific flags to ensure proper encoding: + +```php +function html(string $text = null): string +{ + return htmlspecialchars($text, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8'); +} +``` + +You could consider setting it up as a global function in [composer.json](https://getcomposer.org/doc/04-schema.md#files). + +**Usage** + +```php +Hello +``` ## Exceptions -`\RuntimeException` - if template does not exist -`\InvalidArgumentException` - if $data contains 'template' +* `\RuntimeException` - If template does not exist +* `\InvalidArgumentException` - If $data contains 'template' From 33bc081a023b7f8ef8432182cce657341d39dfed Mon Sep 17 00:00:00 2001 From: Daniel Opitz Date: Sat, 13 Jul 2024 11:26:46 +0200 Subject: [PATCH 2/5] Update readme --- README.md | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index af1145d..b36eafa 100644 --- a/README.md +++ b/README.md @@ -27,22 +27,42 @@ composer require slim/php-view ## Usage with Slim 4 ```php +use Slim\AppFactory; use Slim\Views\PhpRenderer; include 'vendor/autoload.php'; -$app = Slim\AppFactory::create(); +$app = AppFactory::create(); -$app->get('/hello/{name}', function ($request, $response, $args) { +$app->get('/hello/{name}', function ($request, $response) { $renderer = new PhpRenderer('path/to/templates'); - return $renderer->render($response, 'hello.php', $args); + return $renderer->render($response, 'hello.php'); }); $app->run(); ``` -Note that you could place the PhpRenderer instantiation within your DI Container. +## DI Container Setup + +You can place the `PhpRenderer` instantiation within your DI Container. + +```php + function (ContainerInterface $container) { + $renderer = new PhpRenderer('path/to/templates'); + + return $renderer; + }, +]; + +``` ## Usage with any PSR-7 Project From d01d93b1a1cd71f2230aac12c0d4d07a90fd4b46 Mon Sep 17 00:00:00 2001 From: Daniel Opitz Date: Sat, 13 Jul 2024 11:28:06 +0200 Subject: [PATCH 3/5] Update readme --- README.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index b36eafa..e0eddf9 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,21 @@ Install with Composer: composer require slim/php-view ``` +## Usage with any PSR-7 Project + +```php +//Construct the View +$renderer = new PhpRenderer('path/to/templates'); + +$viewData = [ + 'key1' => 'value1', + 'key2' => 'value2', +]; + +// Render a template +$response = $renderer->render(new Response(), 'hello.php', $viewData); +``` + ## Usage with Slim 4 ```php @@ -64,21 +79,6 @@ return [ ``` -## Usage with any PSR-7 Project - -```php -//Construct the View -$renderer = new PhpRenderer('path/to/templates'); - -$viewData = [ - 'key1' => 'value1', - 'key2' => 'value2', -]; - -// Render a template -$response = $renderer->render(new Response(), 'hello.php', $viewData); -``` - ## Template Variables You can now add variables to your renderer that will be available to all templates you render. From 418060dd2959bf15a50c2f0a170f661aa9e6110c Mon Sep 17 00:00:00 2001 From: Daniel Opitz Date: Sat, 13 Jul 2024 11:31:07 +0200 Subject: [PATCH 4/5] Update readme --- README.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index e0eddf9..cbb9105 100644 --- a/README.md +++ b/README.md @@ -45,14 +45,18 @@ $response = $renderer->render(new Response(), 'hello.php', $viewData); use Slim\AppFactory; use Slim\Views\PhpRenderer; -include 'vendor/autoload.php'; +require __DIR__ . '/../vendor/autoload.php'; $app = AppFactory::create(); -$app->get('/hello/{name}', function ($request, $response) { +$app->get('/hello', function ($request, $response) { $renderer = new PhpRenderer('path/to/templates'); - return $renderer->render($response, 'hello.php'); + $viewData = [ + 'name' => 'John', + ]; + + return $renderer->render($response, 'hello.php', $viewData); }); $app->run(); From f3d9f7aea3aec490fa9f3e0394a6f7070aa5aa31 Mon Sep 17 00:00:00 2001 From: Daniel Opitz Date: Sat, 13 Jul 2024 11:34:50 +0200 Subject: [PATCH 5/5] Update readme --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index cbb9105..05cd234 100644 --- a/README.md +++ b/README.md @@ -18,8 +18,6 @@ or a component like [laminas-escaper](https://github.com/laminas/laminas-escaper ## Installation -Install with Composer: - ``` composer require slim/php-view ```