From 2a87c65994811a1eb26a59f58ecbf663445e8739 Mon Sep 17 00:00:00 2001
From: Simon Wisselink <wisskid@users.noreply.github.com>
Date: Wed, 29 May 2024 15:32:47 +0200
Subject: [PATCH] implemented and documented prependTemplateDir. (#1025)

---
 changelog/1022.md                             |  1 +
 docs/api/configuring.md                       | 23 +++++++++++--------
 src/Smarty.php                                | 15 ++++++++++++
 .../FileIndexed/FileResourceIndexedTest.php   |  9 ++++++++
 4 files changed, 38 insertions(+), 10 deletions(-)
 create mode 100644 changelog/1022.md

diff --git a/changelog/1022.md b/changelog/1022.md
new file mode 100644
index 000000000..5833ce028
--- /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 4c1c91fa7..ee2ebf7e9 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 5af9c9b36..4f1bf425d 100644
--- a/src/Smarty.php
+++ b/src/Smarty.php
@@ -684,6 +684,21 @@ public function setTemplateDir($template_dir, $isConfig = false) {
 		return $this;
 	}
 
+	/**
+	 * 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)
 	 *
diff --git a/tests/UnitTests/ResourceTests/FileIndexed/FileResourceIndexedTest.php b/tests/UnitTests/ResourceTests/FileIndexed/FileResourceIndexedTest.php
index 9065c10d5..4bba6a277 100644
--- a/tests/UnitTests/ResourceTests/FileIndexed/FileResourceIndexedTest.php
+++ b/tests/UnitTests/ResourceTests/FileIndexed/FileResourceIndexedTest.php
@@ -91,4 +91,13 @@ public function testGetCachedFilepath()
 
 	    $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));
+	}
+
 }