Merge pull request #1 from creative-commoners/pulls/1/new-repo

API Update API to suit its status as its own module

.editorconfig

@@ -0,0 +1,27 @@
+# For more information about the properties used in
+# this file, please see the EditorConfig documentation:
+# http://editorconfig.org/
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 4
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.{yml,js,json,css,scss,eslintrc,feature}]
+indent_size = 2
+indent_style = space
+
+[composer.json]
+indent_size = 4
+
+# Don't perform any clean-up on thirdparty files
+
+[thirdparty/**]
+trim_trailing_whitespace = false
+insert_final_newline = false

.gitattributes

@@ -0,0 +1,8 @@
+/tests/php export-ignore
+/.tx export-ignore
+/.gitattributes export-ignore
+/.gitignore export-ignore
+/.github export-ignore
+/*.dist export-ignore
+/phpcs.xml.dist export-ignore
+/.editorconfig export-ignore

.github/workflows/ci.yml

@@ -0,0 +1,10 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  ci:
+    uses: silverstripe/gha-ci/.github/workflows/ci.yml@v1

.gitignore

@@ -0,0 +1,3 @@
+/vendor/
+composer.lock
+silverstripe-cache/

composer.json

@@ -0,0 +1,39 @@
+{
+    "name": "silverstripe/template-engine",
+    "description": "Template engine for rendering templates in Silverstripe CMS projects",
+    "type": "silverstripe-vendormodule",
+    "license": "BSD-3-Clause",
+    "authors": [
+        {
+            "name": "Silverstripe",
+            "homepage": "https://silverstripe.com"
+        },
+        {
+            "name": "The Silverstripe Community",
+            "homepage": "https://silverstripe.org"
+        }
+    ],
+    "require": {
+        "php": "^8.3",
+        "silverstripe/framework": "^6"
+    },
+    "require-dev": {
+        "silverstripe/recipe-testing": "^4",
+        "silverstripe/standards": "^1",
+        "squizlabs/php_codesniffer": "^3",
+        "phpstan/extension-installer": "^1.3"
+    },
+    "autoload": {
+        "psr-4": {
+            "SilverStripe\\TemplateEngine\\": "src/",
+            "SilverStripe\\TemplateEngine\\Tests\\": "tests/php/"
+        }
+    },
+    "minimum-stability": "dev",
+    "prefer-stable": true,
+    "config": {
+        "allow-plugins": {
+            "dealerdirect/phpcodesniffer-composer-installer": true
+        }
+    }
+}

phpcs.xml.dist

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ruleset name="SilverStripe">
+	<description>CodeSniffer ruleset for SilverStripe coding conventions.</description>
+
+	<file>src</file>
+	<file>tests</file>
+
+    <!-- Show progress and output sniff names on violation, and add colours -->
+    <arg value="p" />
+    <arg name="colors" />
+    <arg value="s" />
+
+	<!-- base rules are PSR-12 -->
+	<rule ref="PSR12" >
+		<!-- Current exclusions -->
+        <exclude name="PSR1.Methods.CamelCapsMethodName" />
+	</rule>
+
+	<!-- PHP-PEG generated file not intended for human consumption -->
+	<exclude-pattern>*/SSTemplateParser.php$</exclude-pattern>
+</ruleset>
+

phpstan.neon.dist

@@ -0,0 +1,3 @@
+parameters:
+  paths:
+    - src

phpunit.xml.dist

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit bootstrap="vendor/silverstripe/framework/tests/bootstrap.php" colors="true">
+    <testsuites>
+        <testsuite name="Default">
+            <directory>tests/php</directory>
+        </testsuite>
+    </testsuites>
+</phpunit>

src/SSViewer_BasicIteratorSupport.php → src/BasicIteratorSupport.php

@@ -1,12 +1,12 @@
 <?php
 
-namespace SilverStripe\View;
+namespace SilverStripe\TemplateEngine;
 
 /**
  * Defines an extra set of basic methods that can be used in templates
  * that are not defined on sub-classes of {@link ModelData}.
  */
-class SSViewer_BasicIteratorSupport implements TemplateIteratorProvider
+class BasicIteratorSupport implements TemplateIteratorProvider
 {
     /**
      * @var int

src/SSTemplateParseException.php → src/Exception/SSTemplateParseException.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace SilverStripe\View;
+namespace SilverStripe\TemplateEngine\Exception;
 
 use Exception;
 
@@ -11,7 +11,6 @@
  */
 class SSTemplateParseException extends Exception
 {
-
     /**
      * SSTemplateParseException constructor.
      * @param string $message

src/SSTemplateEngine.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace SilverStripe\View;
+namespace SilverStripe\TemplateEngine;
 
 use InvalidArgumentException;
 use Psr\SimpleCache\CacheInterface;
@@ -14,6 +14,10 @@
 use SilverStripe\ORM\FieldType\DBHTMLText;
 use SilverStripe\Security\Permission;
 use SilverStripe\View\Exception\MissingTemplateException;
+use SilverStripe\View\SSViewer;
+use SilverStripe\View\TemplateEngine;
+use SilverStripe\View\ThemeResourceLoader;
+use SilverStripe\View\ViewLayerData;
 
 /**
  * Parses template files with an *.ss file extension, or strings representing templates in that format.
@@ -90,8 +94,12 @@ public function __construct(string|array $templateCandidates = [])
      * template as properties. These override properties and methods with the same name from $data and from global
      * template providers.
      */
-    public static function execute_template(array|string $template, ViewLayerData $data, array $overlay = [], ?SSViewer_Scope $scope = null): string
-    {
+    public static function execute_template(
+        array|string $template,
+        ViewLayerData $data,
+        array $overlay = [],
+        ?ScopeManager $scope = null
+    ): string {
         $engine = static::create($template);
         return $engine->render($data, $overlay, $scope);
     }
@@ -144,8 +152,12 @@ public function hasTemplate(array|string $templateCandidates): bool
         return (bool) $this->findTemplate($templateCandidates);
     }
 
-    public function renderString(string $template, ViewLayerData $model, array $overlay = [], bool $cache = true): string
-    {
+    public function renderString(
+        string $template,
+        ViewLayerData $model,
+        array $overlay = [],
+        bool $cache = true
+    ): string {
         $hash = sha1($template);
         $cacheFile = TEMP_PATH . DIRECTORY_SEPARATOR . ".cache.$hash";
 
@@ -167,7 +179,7 @@ public function renderString(string $template, ViewLayerData $model, array $over
         return $output;
     }
 
-    public function render(ViewLayerData $model, array $overlay = [], ?SSViewer_Scope $scope = null): string
+    public function render(ViewLayerData $model, array $overlay = [], ?ScopeManager $scope = null): string
     {
         SSTemplateEngine::$topLevel[] = $model;
         $template = $this->chosen;
@@ -221,7 +233,7 @@ public function render(ViewLayerData $model, array $overlay = [], ?SSViewer_Scop
                 // Select the right template and render if the template exists
                 $subtemplateViewer->setTemplate($sub);
                 // If there's no template for that underlay, just don't render anything.
-                // This mirrors how SSViewer_Scope handles null values.
+                // This mirrors how ScopeManager handles null values.
                 if (!$subtemplateViewer->chosen) {
                     return null;
                 }
@@ -293,27 +305,27 @@ public function getPartialCacheStore(): CacheInterface
      * @param ViewLayerData $model The model to use as the root scope for the template
      * @param array $overlay Any variables to layer on top of the scope
      * @param array $underlay Any variables to layer underneath the scope
-     * @param SSViewer_Scope|null $inheritedScope The current scope of a parent template including a sub-template
+     * @param ScopeManager|null $inheritedScope The current scope of a parent template including a sub-template
      */
     protected function includeGeneratedTemplate(
         string $cacheFile,
         ViewLayerData $model,
         array $overlay,
         array $underlay,
-        ?SSViewer_Scope $inheritedScope = null
+        ?ScopeManager $inheritedScope = null
     ): string {
         if (isset($_GET['showtemplate']) && $_GET['showtemplate'] && Permission::check('ADMIN')) {
             $lines = file($cacheFile ?? '');
             echo "<h2>Template: $cacheFile</h2>";
             echo '<pre>';
             foreach ($lines as $num => $line) {
-                echo str_pad($num+1, 5) . htmlentities($line, ENT_COMPAT, 'UTF-8');
+                echo str_pad($num + 1, 5) . htmlentities($line, ENT_COMPAT, 'UTF-8');
             }
             echo '</pre>';
         }
 
         $cache = $this->getPartialCacheStore();
-        $scope = new SSViewer_Scope($model, $overlay, $underlay, $inheritedScope);
+        $scope = new ScopeManager($model, $overlay, $underlay, $inheritedScope);
         $val = '';
 
         // Placeholder for values exposed to $cacheFile

src/SSTemplateParser.peg

@@ -9,29 +9,25 @@ parser.
 It gets run through the php-peg parser compiler to have those comments turned into code that match parts of the
 template language, producing the executable version SSTemplateParser.php
 
-To recompile after changing this file, run this from the 'framework/View' directory via command line (in most cases
-this is: framework/src/View):
+To recompile after changing this file, run this from the 'src' directory via command line:
 
-    php ../../thirdparty/php-peg/cli.php SSTemplateParser.peg > SSTemplateParser.php
+    php ../thirdparty/php-peg/cli.php SSTemplateParser.peg > SSTemplateParser.php
 
 See the php-peg docs for more information on the parser format, and how to convert this file into SSTemplateParser.php
 
 This comment will not appear in the output
 */
 
-namespace SilverStripe\View;
+namespace SilverStripe\TemplateEngine;
 
 use SilverStripe\Core\Injector\Injector;
 use Parser;
 use InvalidArgumentException;
+use SilverStripe\TemplateEngine\Exception\SSTemplateParseException;
 
-// We want this to work when run by hand too
-if (defined('THIRDPARTY_PATH')) {
-    require_once(THIRDPARTY_PATH . '/php-peg/Parser.php');
-} else {
-    $base = dirname(__FILE__);
-    require_once($base.'/../thirdparty/php-peg/Parser.php');
-}
+// Make sure to include the base parser code
+$base = dirname(__FILE__);
+require_once($base.'/../thirdparty/php-peg/Parser.php');
 
 /**
   * This is the parser for the SilverStripe template language. It gets called on a string and uses a php-peg parser
@@ -936,7 +932,7 @@ class SSTemplateParser extends Parser implements TemplateParser
         $arguments = $res['arguments'];
 
         // Note: 'type' here is important to disable subTemplates in SSTemplateEngine::getSubtemplateFor()
-        $res['php'] = '$val .= \\SilverStripe\\View\\SSTemplateEngine::execute_template([["type" => "Includes", '.$template.'], '.$template.'], $scope->getCurrentItem(), [' .
+        $res['php'] = '$val .= \\SilverStripe\\TemplateEngine\\SSTemplateEngine::execute_template([["type" => "Includes", '.$template.'], '.$template.'], $scope->getCurrentItem(), [' .
             implode(',', $arguments)."], \$scope, true);\n";
 
         if ($this->includeDebuggingComments) { // Add include filename comments on dev sites

src/SSTemplateParser.php

@@ -7,19 +7,16 @@
 
 
 
-namespace SilverStripe\View;
+namespace SilverStripe\TemplateEngine;
 
 use SilverStripe\Core\Injector\Injector;
 use Parser;
 use InvalidArgumentException;
+use SilverStripe\TemplateEngine\Exception\SSTemplateParseException;
 
-// We want this to work when run by hand too
-if (defined('THIRDPARTY_PATH')) {
-    require_once(THIRDPARTY_PATH . '/php-peg/Parser.php');
-} else {
-    $base = dirname(__FILE__);
-    require_once($base.'/../thirdparty/php-peg/Parser.php');
-}
+// Make sure to include the base parser code
+$base = dirname(__FILE__);
+require_once($base.'/../thirdparty/php-peg/Parser.php');
 
 /**
   * This is the parser for the SilverStripe template language. It gets called on a string and uses a php-peg parser
@@ -3894,7 +3891,7 @@ function Include__finalise(&$res)
         $arguments = $res['arguments'];
 
         // Note: 'type' here is important to disable subTemplates in SSTemplateEngine::getSubtemplateFor()
-        $res['php'] = '$val .= \\SilverStripe\\View\\SSTemplateEngine::execute_template([["type" => "Includes", '.$template.'], '.$template.'], $scope->getCurrentItem(), [' .
+        $res['php'] = '$val .= \\SilverStripe\\TemplateEngine\\SSTemplateEngine::execute_template([["type" => "Includes", '.$template.'], '.$template.'], $scope->getCurrentItem(), [' .
             implode(',', $arguments)."], \$scope, true);\n";
 
         if ($this->includeDebuggingComments) { // Add include filename comments on dev sites