refactor: add appOverridesFolder for namespaced view overrides

Author: datamweb

app/Config/View.php

@@ -59,4 +59,21 @@ class View extends BaseView
      * @var list<class-string<ViewDecoratorInterface>>
      */
     public array $decorators = [];
+
+    /**
+     * Subdirectory within app/Views for namespaced view overrides.
+     *
+     * Namespaced views will be searched in:
+     *
+     *   app/Views/{$appOverridesFolder}/{Namespace}/{view_path}.{php|html...}
+     *
+     * This allows application-level overrides for package or module views
+     * without modifying vendor source files.
+     *
+     * Examples:
+     *   'overrides' -> app/Views/overrides/Example/Blog/post/card.php
+     *   'vendor'    -> app/Views/vendor/Example/Blog/post/card.php
+     *   ''          -> app/Views/Example/Blog/post/card.php (direct mapping)
+     */
+    public string $appOverridesFolder = 'overrides';
 }

system/View/View.php

@@ -202,7 +202,13 @@ public function render(string $view, ?array $options = null, ?bool $saveData = n
         $this->renderVars['file'] = $this->viewPath . $this->renderVars['view'];
 
         if (str_contains($this->renderVars['view'], '\\')) {
-            $this->renderVars['file'] = $this->viewPath . ltrim(str_replace('\\', DIRECTORY_SEPARATOR, $this->renderVars['view']), DIRECTORY_SEPARATOR);
+            $overrideFolder = $this->config->appOverridesFolder !== ''
+                 ? trim($this->config->appOverridesFolder, DIRECTORY_SEPARATOR) . DIRECTORY_SEPARATOR
+                 : '';
+
+            $this->renderVars['file'] = $this->viewPath
+            . $overrideFolder
+            . ltrim(str_replace('\\', DIRECTORY_SEPARATOR, $this->renderVars['view']), DIRECTORY_SEPARATOR);
         } else {
             $this->renderVars['file'] = $this->viewPath . $this->renderVars['view'];
         }

tests/system/View/ViewTest.php

@@ -34,9 +34,10 @@ protected function setUp(): void
     {
         parent::setUp();
 
-        $this->loader   = service('locator');
-        $this->viewsDir = __DIR__ . '/Views';
-        $this->config   = new Config\View();
+        $this->loader                     = service('locator');
+        $this->viewsDir                   = __DIR__ . '/Views';
+        $this->config                     = new Config\View();
+        $this->config->appOverridesFolder = '';
     }
 
     public function testSetVarStoresData(): void
@@ -466,4 +467,23 @@ public function testRenderNamespacedViewWithExplicitExtension(): void
 
         $view->render($namespacedView);
     }
+
+    public function testOverrideWithCustomFolderChecksSubdirectory(): void
+    {
+        $this->config->appOverridesFolder = 'overrides';
+
+        $loader = $this->createMock(FileLocatorInterface::class);
+        $loader->expects($this->once())
+            ->method('locateFile')
+            ->with('Nested\simple.php', 'Views', 'php')
+            ->willReturn($this->viewsDir . '/simple.php');
+
+        $view = new View($this->config, $this->viewsDir, $loader);
+
+        $view->setVar('testString', 'Fallback Content');
+
+        $output = $view->render('Nested\simple');
+
+        $this->assertStringContainsString('<h1>Fallback Content</h1>', $output);
+    }
 }

user_guide_src/source/changelogs/v4.7.0.rst

@@ -125,7 +125,7 @@ Libraries
 - **Image:** Added ``ImageMagickHandler::clearMetadata()`` method to remove image metadata for privacy protection.
 - **ResponseTrait:** Added ``paginate``` method to simplify paginated API responses. See :ref:`ResponseTrait::paginate() <api_response_trait_paginate>` for details.
 - **Time:** added methods ``Time::addCalendarMonths()`` and ``Time::subCalendarMonths()``
-- **View:** Added the ability to override namespaced views (e.g., from modules) by placing a matching file structure within the **app/Views** directory. See :ref:`Overriding Namespaced Views <views-overriding-namespaced-views>` for details.
+- **View:** Added the ability to override namespaced views (e.g., from modules/packages) by placing a matching file structure within the **app/Views/overrides** directory. See :ref:`Overriding Namespaced Views <views-overriding-namespaced-views>` for details.
 
 
 Commands

user_guide_src/source/outgoing/views.rst

@@ -111,10 +111,24 @@ Overriding Namespaced Views
 
 .. versionadded:: 4.7.0
 
-You can override a namespaced view by creating a matching directory structure within your main **app/Views** directory.
-This allows you to customize the output of modules or packages without modifying their source code.
+You can override a namespaced view by creating a matching directory structure within your application's **app/Views** directory.
+This allows you to customize the output of modules or packages without modifying their core source code.
 
-For example, assume you have a module named Blog with the namespace ``Example\Blog``. The original view file is located at:
+Configuration
+-------------
+
+By default, overrides are looked for in the **app/Views/overrides** directory. You can configure this location via the ``$appOverridesFolder`` property in **app/Config/View.php**:
+
+.. code-block:: php
+
+    public string $appOverridesFolder = 'overrides';
+
+If you prefer to map namespaces directly to the root of **app/Views** (without a subdirectory), you can set this value to an empty string (``''``).
+
+Example
+-------
+
+Assume you have a module named **Blog** with the namespace ``Example\Blog``. The original view file is located at:
 
 .. code-block:: text
 
@@ -124,17 +138,18 @@ For example, assume you have a module named Blog with the namespace ``Example\Bl
             └── Views
                 └── blog_view.php
 
-To override this view, create a file at the matching path within your application's Views directory:
+To override this view (using the default configuration), create a file at the matching path within **app/Views/overrides**:
 
 .. code-block:: text
 
     /app
     └── Views
-        └── Example               <-- Matches the first part of namespace
-            └── Blog              <-- Matches the second part of namespace
-                └── blog_view.php <-- Your custom view
+        └── overrides                 <-- Configured $appOverridesFolder
+            └── Example               <-- Matches the first part of namespace
+                └── Blog              <-- Matches the second part of namespace
+                    └── blog_view.php <-- Your custom view
 
-Now, when you call ``view('Example\Blog\blog_view')``, CodeIgniter will automatically load your custom view from **app/Views/Example/Blog/blog_view.php** instead of the original view file.
+Now, when you call ``view('Example\Blog\blog_view')``, CodeIgniter will automatically load your custom view from **app/Views/overrides/Example/Blog/blog_view.php** instead of the original module view file.
 
 .. _caching-views: