Component binder (#472)

* build: upgrade dom requirement and loosen version range

* docs: update examples

* feature: trim whitespace when there are only template children
closes #363

* maintenance: phpstorm analysis improvements

* tweak: remove data-element attribute

* feature: implement ComponentBinder and abstract Binder class
for #470

* fix: bindable cache allows nested nullable objects
closes #474

* refactor: all domtemplate classes set their dependencies outside of the constructor
for #470

* tweak: stricter reflection type checking

* wip: better exception on missing list element

* tweak: handle nullable iterables
closes #473

* tweak: handle binding of outer list item

* tidy: improve types and coverage

* ci: php 8.2

* ci: phpstan level 6

.github/workflows/ci.yml

@@ -18,7 +18,7 @@ jobs:
       - name: Composer install
         uses: php-actions/composer@v6
         with:
-          php_version: 8.1
+          php_version: 8.2
 
       - name: Archive build
         run: mkdir /tmp/github-actions/ && tar -cvf /tmp/github-actions/build.tar ./
@@ -50,7 +50,7 @@ jobs:
         env:
           XDEBUG_MODE: cover
         with:
-          php_version: 8.1
+          php_version: 8.2
           php_extensions: xdebug
           configuration: test/phpunit/phpunit.xml
           bootstrap: vendor/autoload.php
@@ -97,7 +97,9 @@ jobs:
       - name: PHP Static Analysis
         uses: php-actions/phpstan@v3
         with:
+          php_version: 8.2
           path: src/
+          level: 6
 
   remove_old_artifacts:
     runs-on: ubuntu-latest

src/BindableCache.php

@@ -8,6 +8,7 @@
 use ReflectionNamedType;
 use ReflectionObject;
 use ReflectionProperty;
+use ReflectionType;
 use stdClass;
 use Stringable;
 
@@ -69,8 +70,7 @@ public function isBindable(object $object):bool {
 
 			foreach($refAttributes as $refAttr) {
 				$bindKey = $this->getBindKey($refAttr, $refMethod);
-				$attributeCache[$bindKey] = fn(object $object):null|iterable|string
-					=> $this->nullableStringOrIterable($object->$methodName());
+				$attributeCache[$bindKey] = fn(object $object):null|iterable|string => $this->nullableStringOrIterable($object->$methodName());
 				if(class_exists($refReturnName)) {
 					$cacheObjectKeys[$bindKey] = $refReturnName;
 				}
@@ -91,11 +91,17 @@ public function isBindable(object $object):bool {
 			elseif($refProp->isPublic()) {
 				$bindKey = $propName;
 
-				/** @var ?ReflectionNamedType $refType */
+				$refTypeName = null;
 				$refType = $refProp->getType();
-				$refTypeName = $refType?->getName();
-				$attributeCache[$bindKey]
-					= fn(object $object, $key):null|iterable|string => isset($object->$key) ? $this->nullableStringOrIterable($object->$key) : null;
+				if($refType instanceof ReflectionNamedType) {
+					$refTypeName = $refType->getName();
+				}
+				$attributeCache[$bindKey] =
+					fn(object $object, $key):null|iterable|string =>
+					isset($object->$key)
+						? $this->nullableStringOrIterable($object->$key)
+						: null;
+
 				if(class_exists($refTypeName)) {
 					$cacheObjectKeys[$bindKey] = $refTypeName;
 				}
@@ -143,9 +149,15 @@ private function expandObjects(array $cache, array $objectKeys):array {
 		return $cache;
 	}
 
-	/** @return array<string, string> */
-	public function convertToKvp(object $object):array {
+	/**
+	 * @param object|array<string, string> $object
+	 * @return array<string, string>
+	 */
+	public function convertToKvp(object|array $object):array {
 		$kvp = [];
+		if(is_array($object)) {
+			return $object;
+		}
 
 		if($object instanceof stdClass) {
 			foreach(get_object_vars($object) as $key => $value) {
@@ -178,10 +190,21 @@ public function convertToKvp(object $object):array {
 // TODO: This "get*()" function should not be hard coded here - it should load the appropriate
 // Bind/BindGetter by matching the correct Attribute.
 				$bindFunc = "get" . ucfirst($propName);
-				$objectToExtract = $objectToExtract->$propName ?? $objectToExtract->$bindFunc();
+				if($objectToExtract) {
+					if(property_exists($objectToExtract, $propName)) {
+						$objectToExtract = $objectToExtract->$propName;
+					}
+					elseif(method_exists($objectToExtract, $bindFunc)) {
+						$objectToExtract = $objectToExtract->$bindFunc();
+					}
+				}
+			}
+
+			$value = null;
+			if($objectToExtract) {
+				$value = $closure($objectToExtract, $deepestKey);
 			}
 
-			$value = $closure($objectToExtract, $deepestKey);
 			if(is_null($value)) {
 				$kvp[$key] = null;
 			}
@@ -200,8 +223,7 @@ public function convertToKvp(object $object):array {
 	private function getBindAttributes(ReflectionMethod|ReflectionProperty $ref):array {
 		return array_filter(
 			$ref->getAttributes(),
-			fn(ReflectionAttribute $refAttr) =>
-				$refAttr->getName() === Bind::class
+			fn(ReflectionAttribute $refAttr) => $refAttr->getName() === Bind::class
 				|| $refAttr->getName() === BindGetter::class
 		);
 	}

src/Binder.php

@@ -0,0 +1,53 @@
+<?php
+namespace Gt\DomTemplate;
+
+use Gt\Dom\Element;
+
+abstract class Binder {
+	abstract public function bindValue(
+		mixed $value,
+		?Element $context = null
+	):void;
+
+	/**
+	 * Applies the string value of $value to any elements within $context
+	 * that have the data-bind attribute matching the provided key.
+	 */
+	abstract public function bindKeyValue(
+		string $key,
+		mixed $value,
+		?Element $context = null
+	):void;
+
+	/**
+	 * Binds multiple key-value-pairs to any matching elements within
+	 * the $context element.
+	 */
+	abstract public function bindData(
+		mixed $kvp,
+		?Element $context = null
+	):void;
+
+	abstract public function bindTable(
+		mixed $tableData,
+		?Element $context = null,
+		?string $bindKey = null
+	):void;
+
+	/**
+	 * @param iterable<int, mixed> $listData
+	 */
+	abstract public function bindList(
+		iterable $listData,
+		?Element $context = null,
+		?string $templateName = null
+	):int;
+
+	/** @param iterable<int, mixed> $listData */
+	abstract public function bindListCallback(
+		iterable $listData,
+		callable $callback,
+		?Element $context = null,
+		?string $templateName = null
+	):int;
+}

src/CommentIni.php

@@ -36,7 +36,9 @@ public function __construct(
 			$data = trim($commentNode->data);
 
 			try {
-				$ini = parse_ini_string($data, true);
+// We know that sometimes this data will not be correct ini format, and it might actually be a textual comment.
+// Therefore, we must suppress the warning that is emitted by parse_ini_string:
+				$ini = @parse_ini_string($data, true);
 				$commentNodeToRemove = $commentNode;
 			}
 			catch(Throwable) {

src/ComponentBinder.php

@@ -0,0 +1,56 @@
+<?php
+namespace Gt\DomTemplate;
+
+use Gt\Dom\Document;
+use Gt\Dom\Element;
+
+class ComponentBinder extends DocumentBinder {
+	private Element $componentElement;
+
+	public function setComponentBinderDependencies(Element $componentElement):void {
+		$this->componentElement = $componentElement;
+	}
+
+	public function bindList(
+		iterable $listData,
+		?Element $context = null,
+		?string $templateName = null
+	):int {
+		if($context) {
+			$this->checkElementContainedWithinComponent($context);
+		}
+		else {
+			$context = $this->componentElement;
+		}
+
+		return parent::bindList($listData, $context, $templateName);
+	}
+
+	protected function bind(
+		?string $key,
+		mixed $value,
+		?Element $context = null
+	):void {
+		if($context) {
+			$this->checkElementContainedWithinComponent($context);
+		}
+		else {
+			$context = $this->componentElement;
+		}
+
+		if(is_callable($value) && !is_string($value)) {
+			$value = call_user_func($value);
+		}
+
+		$this->elementBinder->bind($key, $value, $context);
+		$this->placeholderBinder->bind($key, $value, $context);
+	}
+
+	private function checkElementContainedWithinComponent(Element $context):void {
+		if($this->componentElement !== $context && !$this->componentElement->contains($context)) {
+			throw new ComponentDoesNotContainContextException(
+				"<{$this->componentElement->tagName}> does not contain requested <$context->tagName>."
+			);
+		}
+	}
+}

src/ComponentDoesNotContainContextException.php

@@ -0,0 +1,4 @@
+<?php
+namespace Gt\DomTemplate;
+
+class ComponentDoesNotContainContextException extends DomTemplateException {}

src/DocumentBinder.php

@@ -5,41 +5,32 @@
 use Gt\Dom\Document;
 use Gt\Dom\Element;
 
-class DocumentBinder {
-	private ElementBinder $elementBinder;
-	private PlaceholderBinder $placeholderBinder;
-	private TableBinder $tableBinder;
-	private ListBinder $listBinder;
-	private ListElementCollection $templateCollection;
-	private BindableCache $bindableCache;
+class DocumentBinder extends Binder {
+	protected ElementBinder $elementBinder;
+	protected PlaceholderBinder $placeholderBinder;
+	protected TableBinder $tableBinder;
+	protected ListBinder $listBinder;
+	protected ListElementCollection $templateCollection;
+	protected BindableCache $bindableCache;
 
-	/**
-	 * @param array<string, string> $config
-	 */
 	public function __construct(
-		private readonly Document $document,
-		private array $config = [],
-		?ElementBinder $elementBinder = null,
-		?PlaceholderBinder $placeholderBinder = null,
-		?TableBinder $tableBinder = null,
-		?ListBinder $listBinder = null,
-		?ListElementCollection $templateCollection = null,
-		?BindableCache $bindableCache = null
-	) {
-		$this->templateCollection = $templateCollection ?? new ListElementCollection($document);
-		$this->elementBinder = $elementBinder ?? new ElementBinder();
-		$this->placeholderBinder = $placeholderBinder ?? new PlaceholderBinder();
-		$this->tableBinder = $tableBinder ?? new TableBinder($this->templateCollection);
-		$this->listBinder = $listBinder ?? new ListBinder($this->templateCollection);
-		$this->bindableCache = $bindableCache ?? new BindableCache();
-
-// This is temporary, to suppress PHPStan's complaints for declaring a variable
-// without using it. There are plans to use the config variable, but it is
-// currently not yet used, and this technique prevents the constructor
-// parameters from changing over time.
-		if(!$this->config) {
-			$this->config = [];
-		}
+		protected readonly Document $document,
+	) {}
+
+	public function setDependencies(
+		ElementBinder $elementBinder,
+		PlaceholderBinder $placeholderBinder,
+		TableBinder $tableBinder,
+		ListBinder $listBinder,
+		ListElementCollection $listElementCollection,
+		BindableCache $bindableCache,
+	):void {
+		$this->elementBinder = $elementBinder;
+		$this->placeholderBinder = $placeholderBinder;
+		$this->tableBinder = $tableBinder;
+		$this->listBinder = $listBinder;
+		$this->templateCollection = $listElementCollection;
+		$this->bindableCache = $bindableCache;
 	}
 
 	/**
@@ -87,7 +78,7 @@ public function bindData(
 			}
 		}
 
-		foreach($kvp as $key => $value) {
+		foreach($kvp ?? [] as $key => $value) {
 			$this->bindKeyValue($key, $value, $context);
 		}
 	}
@@ -163,7 +154,7 @@ public function cleanupDocument():void {
 		}
 	}
 
-	private function bind(
+	protected function bind(
 		?string $key,
 		mixed $value,
 		?Element $context = null
@@ -177,7 +168,6 @@ private function bind(
 		}
 
 		$this->elementBinder->bind($key, $value, $context);
-		$this->placeholderBinder->bind($key, $value, $context);
 	}
 
 	private function isIndexedArray(mixed $data):bool {

src/ElementBinder.php

@@ -8,14 +8,14 @@ class ElementBinder {
 	private HTMLAttributeCollection $htmlAttributeCollection;
 	private PlaceholderBinder $placeholderBinder;
 
-	public function __construct(
-		?HTMLAttributeBinder $htmlAttributeBinder = null,
-		?HTMLAttributeCollection $htmlAttributeCollection = null,
-		?PlaceholderBinder $placeholderBinder = null,
-	) {
-		$this->htmlAttributeBinder = $htmlAttributeBinder ?? new HTMLAttributeBinder();
-		$this->htmlAttributeCollection = $htmlAttributeCollection ?? new HTMLAttributeCollection();
-		$this->placeholderBinder = $placeholderBinder ?? new PlaceholderBinder();
+	public function setDependencies(
+		HTMLAttributeBinder $htmlAttributeBinder,
+		HTMLAttributeCollection $htmlAttributeCollection,
+		PlaceholderBinder $placeholderBinder,
+	):void {
+		$this->htmlAttributeBinder = $htmlAttributeBinder;
+		$this->htmlAttributeCollection = $htmlAttributeCollection;
+		$this->placeholderBinder = $placeholderBinder;
 	}
 
 	/**

src/HTMLAttributeBinder.php

@@ -8,8 +8,14 @@
 use Gt\Dom\Element;
 
 class HTMLAttributeBinder {
+	private ListBinder $listBinder;
 	private TableBinder $tableBinder;
 
+	public function setDependencies(ListBinder $listBinder, TableBinder $tableBinder):void {
+		$this->listBinder = $listBinder;
+		$this->tableBinder = $tableBinder;
+	}
+
 	public function bind(
 		?string $key,
 		mixed $value,
@@ -202,9 +208,6 @@ private function setBindProperty(
 			break;
 
 		case "table":
-			if(!isset($this->tableBinder)) {
-				$this->tableBinder = new TableBinder();
-			}
 			$this->tableBinder->bindTableData(
 				$bindValue,
 				$element,
@@ -217,6 +220,7 @@ private function setBindProperty(
 			break;
 
 		case "list";
+			$this->listBinder->bindListData($bindValue, $element);
 			break;
 
 		default: