+ API: Added Dwoo_Compiler->setAutoEscape() and getAutoEscape() to modify the…

CHANGELOG

 [2008--] 0.9.1
++ API: Added Dwoo_Compiler->setAutoEscape() and getAutoEscape() to modify the
+  automatic html entity escaping setting. This is disabled by default, and when
+  enabled can be overriden with the {safe $var} plugin or the 
+  {auto_escape disable} block plugin. The block plugin can also be used to 
+  enable this mode from within a template
 + Syntax: Mixing named and unnamed parameters is now allowed, as long as the
   unnamed ones appear first
 + Syntax: Added {/} shortcut that closes the last opened block

lib/Dwoo/Compiler.php

@@ -82,9 +82,20 @@ class Dwoo_Compiler implements Dwoo_ICompiler
 	 * turn to true if you want to be sloppy with the syntax, but when set to false it allows
 	 * to skip javascript and css tags as long as they are in the form "{ something", which is
 	 * nice. default is false.
+	 * 
+	 * @var bool
 	 */
 	protected $allowLooseOpenings = false;
-
+	
+	/**
+	 * defines whether the compiler will automatically html-escape variables or not
+	 * 
+	 * default is false
+	 * 
+	 * @var bool
+	 */
+	protected $autoEscape = false;
+	
 	/**
 	 * security policy object
 	 *
@@ -249,6 +260,34 @@ class Dwoo_Compiler implements Dwoo_ICompiler
 	{
 		return $this->allowLooseOpenings;
 	}
+	
+	/**
+	 * changes the auto escape setting
+	 * 
+	 * if enabled, the compiler will automatically html-escape variables, 
+	 * unless they are passed through the safe function such as {$var|safe} 
+	 * or {safe $var}
+	 * 
+	 * default setting is disabled/false
+	 * 
+	 * @param bool $enabled set to true to enable, false to disable
+	 */
+	public function setAutoEscape($enabled)
+	{
+		$this->autoEscape = $enabled;
+	}
+
+	/**
+	 * returns the auto escape setting
+	 * 
+	 * default setting is disabled/false
+	 * 
+	 * @return bool
+	 */
+	public function getAutoEscape()
+	{
+		return $this->autoEscape;
+	}
 
 	/**
 	 * adds a preprocessor to the compiler, it will be called
@@ -1663,6 +1702,11 @@ class Dwoo_Compiler implements Dwoo_ICompiler
 				$assign = true;
 			}
 
+			if($this->autoEscape === true)
+			{	
+				$output = 'htmlspecialchars('.$output.', ENT_QUOTES, $this->charset)';
+			}
+			
 			// handle modifiers
 			if($curBlock !== 'modifier' && $hasModifiers)
 			{

lib/plugins/builtin/blocks/auto_escape.php

+<?php
+
+/**
+ * Overrides the compiler auto-escape setting within the block
+ *
+ * This software is provided 'as-is', without any express or implied warranty.
+ * In no event will the authors be held liable for any damages arising from the use of this software.
+ *
+ * This file is released under the LGPL
+ * "GNU Lesser General Public License"
+ * More information can be found here:
+ * {@link http://www.gnu.org/copyleft/lesser.html}
+ *
+ * @author     Jordi Boggiano <j.boggiano@seld.be>
+ * @copyright  Copyright (c) 2008, Jordi Boggiano
+ * @license    http://www.gnu.org/copyleft/lesser.html  GNU Lesser General Public License
+ * @link       http://dwoo.org/
+ * @version    0.9.0
+ * @date       2008-05-10
+ * @package    Dwoo
+ */
+class Dwoo_Plugin_auto_escape extends Dwoo_Block_Plugin implements Dwoo_ICompilable_Block
+{
+	protected static $stack = array();
+
+	public function init($enabled)
+	{
+	}
+
+	public static function preProcessing(Dwoo_Compiler $compiler, array $params, $prepend='', $append='', $type)
+	{
+		$params = $compiler->getCompiledParams($params);
+		switch(strtolower(trim((string) $params['enabled'], '"\'')))
+		{
+			case 'on':
+			case 'true':
+			case 'enabled':
+			case 'enable':
+			case '1':
+				$enable = true;
+				break;
+			case 'off':
+			case 'false':
+			case 'disabled':
+			case 'disable':
+			case '0':
+				$enable = false;
+				break;
+			default:
+				throw new Dwoo_Compilation_Exception('Auto_Escape : Invalid parameter ('.$params['enabled'].'), valid parameters are "enable"/true or "disable"/false');
+		}
+		
+		self::$stack[] = $compiler->getAutoEscape();
+		$compiler->setAutoEscape($enable);
+		return '';
+	}
+
+	public static function postProcessing(Dwoo_Compiler $compiler, array $params, $prepend='', $append='')
+	{
+		$compiler->setAutoEscape(array_pop(self::$stack));
+		return '';
+	}
+}

lib/plugins/builtin/blocks/block.php

 <?php
 
 /**
- * TOCOM
+ * This is used only when rendering a template that has blocks but is not extending anything, 
+ * it doesn't do anything by itself and should not be used outside of template inheritance context,
+ * see {@link http://wiki.dwoo.org/index.php/TemplateInheritance} to read more about it.
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/blocks/capture.php

 <?php
 
 /**
- * TOCOM
+ * Captures all the output within this block and saves it into {$.capture.default} by default, 
+ * or {$.capture.name} if you provide another name. If the cat parameter is true, the content 
+ * will be appended to the existing content
+ * 
+ * Example :
+ * 
+ * <code>
+ * {capture "foo"}
+ *   Anything in here won't show, it will be saved for later use..
+ * {/capture}
+ * Output was : {$.capture.foo}
+ * </code>
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/blocks/else.php

 <?php
 
 /**
- * TOCOM
+ * Generic else block, it supports all builtin optional-display blocks which are if/for/foreach/loop/with
+ * 
+ * If any of those block contains an else statement, the content between {else} and {/block} (you do not 
+ * need to close the else block) will be shown if the block's condition has no been met
+ * 
+ * Example :
+ * 
+ * <code>
+ * {foreach $array val}
+ *   $array is not empty so we display it's values : {$val}
+ * {else}
+ *   if this shows, it means that $array is empty or doesn't exist.
+ * {/foreach}
+ * </code>
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/blocks/elseif.php

 <?php
 
 /**
- * TOCOM
+ * Acts as a php elseif block, allowing you to add one more condition 
+ * if the previous one(s) didn't match. See the {if} plugin for syntax details
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/blocks/for.php

 <?php
+
 /**
- * TOCOM
+ * Similar to the php for block
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/blocks/foreach.php

 <?php
 
 /**
- * TOCOM
+ * Similar to the php foreach block, loops over an array
+ * 
+ * Note that if you don't provide the item parameter, the key will act as item
+ * 
+ * Example :
+ * 
+ * <code>
+ * {foreach $array val}
+ *   {$val.something}
+ * {/foreach}
+ * </code>
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/blocks/foreachelse.php

 <?php
+
 /**
- * TOCOM
+ * This plugin serves as a {else} block specifically for the {foreach} plugin.
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/blocks/forelse.php

 <?php
+
 /**
- * TOCOM
+ * This plugin serves as a {else} block specifically for the {for} plugin.
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/blocks/if.php

 <?php
+
 /**
- * TOCOM
- *
+ * Conditional block, the syntax is very similar to the php one, allowing () || && and 
+ * other php operators. Additional operators and their equivalent php syntax are as follow :
+ * 
+ * eq -> ==
+ * neq or ne -> !=
+ * gte or ge -> >=
+ * lte or le -> <=
+ * gt -> >
+ * lt -> <
+ * mod -> %
+ * not -> !
+ * X is [not] div by Y -> (X % Y) == 0 
+ * X is [not] even [by Y] -> (X % 2) == 0 or ((X/Y) % 2) == 0
+ * X is [not] odd [by Y] -> (X % 2) != 0 or ((X/Y) % 2) != 0 
+ * 
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.
  *

lib/plugins/builtin/blocks/loop.php

 <?php
 
 /**
- * TOCOM
- *
+ * Loops over an array and moves the scope into each value, allowing for shorter loop constructs
+ * 
+ * Note that to access the array key within a loop block, you have to use the {$_key} variable, 
+ * you can not specify it yourself.
+ * 
+ * Example :
+ * 
+ * instead of a foreach block such as :
+ * 
+ * <code>
+ * {foreach $variable value}
+ *   {$value.foo} {$value.bar}
+ * {/foreach}
+ * </code>
+ * 
+ * you can do :
+ * 
+ * <code>
+ * {loop $variable}
+ *   {$foo} {$bar}
+ * {/loop}
+ * </code>
+ * 
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.
  *

lib/plugins/builtin/blocks/smartyinterface.php

 <?php
 
 /**
- * TOCOM
+ * Smarty compatibility layer for block plugins, this is used internally and you should not call it
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/blocks/textformat.php

 <?php
 
 /**
- * TOCOM
- *
+ * Formats a string to the given format, you can wrap lines at a certain 
+ * length and indent them
+ * 
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.
  *

lib/plugins/builtin/blocks/topLevelBlock.php

 <?php
+
 /**
- * TOCOM
+ * Internal plugin used to wrap the template output, do not use in your templates as it will break them
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/blocks/with.php

 <?php
+
 /**
- * TOCOM
- *
+ * Moves the scope down into the provided variable, allowing you to use shorter
+ * variable names if you repeatedly access values into a single array
+ * 
+ * The with block won't display anything at all if the provided scope is empty, 
+ * so in effect it acts as {if $var}*content*{/if}
+ * 
+ * Example :
+ * 
+ * instead of the following :
+ * 
+ * <code>
+ * {if $long.boring.prefix}
+ *   {$long.boring.prefix.val} - {$long.boring.prefix.secondVal} - {$long.boring.prefix.thirdVal}
+ * {/if}
+ * </code>
+ *  
+ * you can use :
+ * 
+ * <code>
+ * {with $long.boring.prefix}
+ *   {$val} - {$secondVal} - {$thirdVal}
+ * {/with}
+ * </code>
+ * 
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.
  *

lib/plugins/builtin/blocks/withelse.php

 <?php
+
 /**
- * TOCOM
- *
+ * This plugin serves as a {else} block specifically for the {with} plugin.
+ * 
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.
  *

lib/plugins/builtin/filters/html_format.php

 <?php
 
 /**
- * TOCOM
+ * Formats any html output (must be valid xml where every tag opened is closed) 
+ * using a single tab for indenting. 'pre' and other whitespace sensitive
+ * tags should not be affected.
+ * 
+ * It is not recommended to use this on every template if you render multiple 
+ * templates per page, you should only use it once on the main page template so that 
+ * everything is formatted in one pass.
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/functions/safe.php

+<?php
+
+/**
+ * TOCOM
+ *
+ * This software is provided 'as-is', without any express or implied warranty.
+ * In no event will the authors be held liable for any damages arising from the use of this software.
+ *
+ * This file is released under the LGPL
+ * "GNU Lesser General Public License"
+ * More information can be found here:
+ * {@link http://www.gnu.org/copyleft/lesser.html}
+ *
+ * @author     Jordi Boggiano <j.boggiano@seld.be>
+ * @copyright  Copyright (c) 2008, Jordi Boggiano
+ * @license    http://www.gnu.org/copyleft/lesser.html  GNU Lesser General Public License
+ * @link       http://dwoo.org/
+ * @version    0.9.0
+ * @date       2008-05-10
+ * @package    Dwoo
+ */
+function Dwoo_Plugin_safe_compile(Dwoo_Compiler $compiler, $var)
+{
+	return preg_replace('#htmlspecialchars\((.+?), ENT_QUOTES, \$this->charset\)#', '$1', $var);
+}

lib/plugins/builtin/helper.array.php

 <?php
 
 /**
- * TOCOM
+ * Builds an array with all the provided variables, use named parameters to make an associative array
+ * 
+ * Example :
+ * 
+ * <code>
+ * {array(a, b, c)} results in array(0=>'a', 1=>'b', 2=>'c')
+ * {array(a=foo, b=5, c=array(4,5))} results in array('a'=>'foo', 'b'=>5, 'c'=>array(0=>4, 1=>5))
+ * </code>
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/processors/pre.smarty_compat.php

 <?php
 
 /**
- * TOCOM
+ * Performs some template conversions to allow smarty templates to be used by
+ * the Dwoo compiler.
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

tests/BlockTests.php

@@ -14,6 +14,37 @@ class BlockTests extends PHPUnit_Framework_TestCase
 		$this->dwoo = new Dwoo();
 	}
 
+	public function testAutoEscape()
+	{
+		$cmp = new Dwoo_Compiler();
+		$cmp->setAutoEscape(true);
+		
+		$tpl = new Dwoo_Template_String('{$foo}{auto_escape off}{$foo}{/}');
+		$tpl->forceCompilation();
+
+		$this->assertEquals("a&lt;b&gt;ca<b>c", $this->dwoo->get($tpl, array('foo'=>'a<b>c'), $cmp));
+
+		$tpl = new Dwoo_Template_String('{$foo}{auto_escape true}{$foo}{/}');
+		$tpl->forceCompilation();
+
+		$this->assertEquals("a<b>ca&lt;b&gt;c", $this->dwoo->get($tpl, array('foo'=>'a<b>c')));
+		
+		// fixes the init call not being called (which is normal)
+		$fixCall = new Dwoo_Plugin_auto_escape($this->dwoo);
+		$fixCall->init('');
+	}
+
+	/**
+	 * @expectedException Dwoo_Compilation_Exception
+	 */
+	public function testAutoEscapeWrongParam()
+	{
+		$tpl = new Dwoo_Template_String('{$foo}{auto_escape slkfjsl}{$foo}{/}');
+		$tpl->forceCompilation();
+
+		$this->dwoo->get($tpl, array('foo'=>'a<b>c'));
+	}
+
 	public function testCapture()
 	{
 		$tpl = new Dwoo_Template_String('{capture name="foo" assign="foo"}BAR{/capture}{$dwoo.capture.foo}-{$foo}');

tests/CompilerTests.php

@@ -460,6 +460,18 @@ class CompilerTests extends PHPUnit_Framework_TestCase
 
 		$this->dwoo->get($tpl, array('foo'=>0), $this->compiler);
 	}
+	
+	public function testAutoEscape()
+	{
+		$cmp = new Dwoo_Compiler();
+		$cmp->setAutoEscape(true);
+		$this->assertEquals(true, $cmp->getAutoEscape());
+		
+		$tpl = new Dwoo_Template_String('{$foo}{$foo|safe}');
+		$tpl->forceCompilation();
+
+		$this->assertEquals("a&lt;b&gt;ca<b>c", $this->dwoo->get($tpl, array('foo'=>'a<b>c'), $cmp));
+	}
 }
 
 class MethodCallsHelper {