implemented and documented prependTemplateDir. (#1025)

4 files changed, 38 insertions, 10 deletions

diff --git a/changelog/1022.md b/changelog/1022.md
new file mode 100644
index 00000000..5833ce02
--- /dev/null
+++ b/changelog/1022.md
@@ -0,0 +1 @@
+- Added `$smarty->prependTemplateDir()` method [#1022](https://github.com/smarty-php/smarty/issues/1022)
\ No newline at end of file
diff --git a/docs/api/configuring.md b/docs/api/configuring.md
index 4c1c91fa..ee2ebf7e 100644
--- a/docs/api/configuring.md
+++ b/docs/api/configuring.md
@@ -12,24 +12,27 @@ Use `getTemplateDir()` to retrieve the configured paths.
 <?php
 
  // set a single directory where the config files are stored
-$smarty->setTemplateDir('./config');
+$smarty->setTemplateDir('./templates');
 
-// set multiple directories where config files are stored
-$smarty->setTemplateDir(['./config', './config_2', './config_3']);
+// set multiple directories where templates are stored
+$smarty->setTemplateDir(['./templates', './templates_2', './templates_3']);
 
-// add directory where config files are stored to the current list of dirs
-$smarty->addTemplateDir('./config_1');
+// add directory where templates files are stored to the current list of dirs
+$smarty->addTemplateDir('./templates_1');
 
 // add multiple directories to the current list of dirs
 $smarty->addTemplateDir([
-    './config_2',
-    './config_3',
+    './templates_2',
+    './templates_3',
 ]);
 
 // chaining of method calls
-$smarty->setTemplateDir('./config')
-       ->addTemplateDir('./config_1')
-       ->addTemplateDir('./config_2');
+$smarty->setTemplateDir('./templates')
+       ->addTemplateDir('./templates_1')
+       ->addTemplateDir('./templates_2');
+
+// insert a template dir before exising template dirs
+$smarty->prependTemplateDir('./more_important_templates')
 
 // get all directories where config files are stored
 $template_dirs = $smarty->getTemplateDir();
diff --git a/src/Smarty.php b/src/Smarty.php
index 5af9c9b3..4f1bf425 100644
--- a/src/Smarty.php
+++ b/src/Smarty.php
@@ -685,6 +685,21 @@ class Smarty extends \Smarty\TemplateBase {
 	}
 
 	/**
+	 * Adds a template directory before any existing directoires
+	 *
+	 * @param string $new_template_dir directory of template sources
+	 * @param bool $is_config true for config_dir
+	 *
+	 * @return static current Smarty instance for chaining
+	 */
+	public function prependTemplateDir($new_template_dir, $is_config = false) {
+		$current_template_dirs = $is_config ? $this->config_dir : $this->template_dir;
+		array_unshift($current_template_dirs, $new_template_dir);
+		$this->setTemplateDir($current_template_dirs, $is_config);
+		return $this;
+	}
+
+	/**
 	 * Add config directory(s)
 	 *
 	 * @param string|array $config_dir directory(s) of config sources
diff --git a/tests/UnitTests/ResourceTests/FileIndexed/FileResourceIndexedTest.php b/tests/UnitTests/ResourceTests/FileIndexed/FileResourceIndexedTest.php
index 9065c10d..4bba6a27 100644
--- a/tests/UnitTests/ResourceTests/FileIndexed/FileResourceIndexedTest.php
+++ b/tests/UnitTests/ResourceTests/FileIndexed/FileResourceIndexedTest.php
@@ -91,4 +91,13 @@ class FileResourceIndexedTest extends PHPUnit_Smarty
 
 	    $this->assertNotEquals($tpl->getCached()->filepath, $tpl2->getCached()->filepath);
     }
+
+	public function testPrependTemplatePath()
+	{
+		$this->smarty->setTemplateDir(__DIR__ . '/templates');
+		$this->smarty->prependTemplateDir(__DIR__ . '/templates_4');
+		$tpl = $this->smarty->createTemplate('dirname.tpl');
+		$this->assertEquals('templates_4', $this->smarty->fetch($tpl));
+	}
+
 }