From 3fff0813e80e00c207c31e26e54157eeb2394e09 Mon Sep 17 00:00:00 2001
From: Simon Wisselink <s.wisselink@iwink.nl>
Date: Fri, 2 Feb 2024 23:10:47 +0100
Subject: [PATCH] Explain escaping and auto-escaping in the docs. Fixes #865

---
 CHANGELOG.md            |  3 ++-
 docs/api/basics.md      |  3 ++-
 docs/api/configuring.md | 18 ++++++++++++++++++
 docs/getting-started.md | 18 +++++++++++++++++-
 4 files changed, 39 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 05718d2d..ea79a572 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,7 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - PHP8.3 support [#925](https://github.com/smarty-php/smarty/issues/925)
 - Backlink to GitHub in docs
-- 
+- Explain how to do escaping and set-up auto-escaping in docs [#865](https://github.com/smarty-php/smarty/issues/865)
+
 ### Fixed
 - The {debug} tag was broken in v5 [#922](https://github.com/smarty-php/smarty/issues/922)
 
diff --git a/docs/api/basics.md b/docs/api/basics.md
index 0b58c028..ef5292da 100644
--- a/docs/api/basics.md
+++ b/docs/api/basics.md
@@ -89,4 +89,5 @@ Run this, and you will see:
 ```
 
 Note how the [escape modifier](../designers/language-modifiers/language-modifier-escape.md) 
-translated the `&` character into the proper HTML syntax `&amp;`.
\ No newline at end of file
+translated the `&` character into the proper HTML syntax `&amp;`.
+Read more about auto-escaping in the [next section](./configuring.md).
\ No newline at end of file
diff --git a/docs/api/configuring.md b/docs/api/configuring.md
index 32144b39..4c1c91fa 100644
--- a/docs/api/configuring.md
+++ b/docs/api/configuring.md
@@ -122,6 +122,24 @@ $smarty->setCacheDir('/data/caches');
 $cacheDir = $smarty->getCacheDir();
 ```
 
+## Enabling auto-escaping
+By default, Smarty does not escape anything you render in your templates. If you use
+Smarty to render a HTML-page, this means that you will have to make sure that you do
+not render any characters that have a special meaning in HTML, such as `&`, `<` and `>`,
+or apply the [escape modifier](../designers/language-modifiers/language-modifier-escape.md) 
+to anything you want to render.
+
+If you forget to do so, you may break your HTML page, or even create a vulnerability for 
+attacks known as [XSS or Cross Site Scripting](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html).
+
+Luckily, you can tell Smarty to automatically apply the escape modifier to any dynamic part of your template.
+It's like Smarty magically adds `|escape` to every variable you use on a web page.
+
+Enable auto-escaping for HTML as follows:
+```php
+$smarty->setEscapeHtml(true);
+```
+
 ## Disabling compile check
 By default, Smarty tests to see if the
 current template has changed since the last time
diff --git a/docs/getting-started.md b/docs/getting-started.md
index ddf91b55..5b49fffd 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -86,7 +86,7 @@ needs to be located in the [`$template_dir`](./programmers/api-variables/variabl
 
 ```smarty
 {* Smarty *}
-Hello {$name}, welcome to Smarty!
+<h1>Hello {$name|escape}, welcome to Smarty!</h1>
 ```
 
 > **Note**
@@ -132,6 +132,20 @@ Now, run your PHP file. You should see *"Hello Ned, welcome to Smarty!"*
 
 You have completed the basic setup for Smarty!
 
+## Escaping
+You may have noticed that the example template above renders the `$name` variable using
+the [escape modifier](./designers/language-modifiers/language-modifier-escape.md).  This 
+modifier makes string 'safe' to use in the context of an HTML page.
+
+If you are primarily using Smarty for HTML-pages, it is recommended to enable automatic
+escaping. This way, you don't have to add `|escape` to every variable you use on a web page. 
+Smarty will handle it automatically for you!
+
+Enable auto-escaping for HTML as follows:
+```php
+$smarty->setEscapeHtml(true);
+```
+
 ## Extended Setup
 
 This is a continuation of the [basic installation](#installation), please read that first!
@@ -156,6 +170,8 @@ class My_GuestBook extends Smarty {
         $this->setCompileDir('/web/www.example.com/guestbook/templates_c/');
         $this->setConfigDir('/web/www.example.com/guestbook/configs/');
         $this->setCacheDir('/web/www.example.com/guestbook/cache/');
+        
+        $this->setEscapeHtml(true);
 
         $this->caching = Smarty::CACHING_LIFETIME_CURRENT;
         $this->assign('app_name', 'Guest Book');