From a066eb13caab0691a208bed4771c62a5c63f861e Mon Sep 17 00:00:00 2001
From: Joachim Noreiko <joachim@107701.no-reply.drupal.org>
Date: Fri, 13 Sep 2024 21:12:31 +0100
Subject: [PATCH] Added common interface for definitions which hold a list of
 properties.

---
 Definition/DataDefinition.php        | 38 ++++++------
 Definition/PropertyListInterface.php | 91 ++++++++++++++++++++++++++++
 Definition/VariantDefinition.php     | 50 ++++++++++++++-
 3 files changed, 157 insertions(+), 22 deletions(-)
 create mode 100644 Definition/PropertyListInterface.php

diff --git a/Definition/DataDefinition.php b/Definition/DataDefinition.php
index bc74595..ad86147 100644
--- a/Definition/DataDefinition.php
+++ b/Definition/DataDefinition.php
@@ -7,7 +7,7 @@
 /**
  * Defines a data property.
  */
-class DataDefinition {
+class DataDefinition implements PropertyListInterface {
 
   /**
    * The type of data the property holds.
@@ -263,6 +263,9 @@ public function getVariantProperties(string $type) {
     return $this->variants[$type]->getProperties();
   }
 
+  /**
+   * {@inheritdoc}
+   */
   public function setProperties(array $properties): self {
     // TODO! this won't catch child classes of SimpleData!!!
     // TODO we don't have access to the factory here. So we can't ask the
@@ -297,25 +300,22 @@ public function setProperties(array $properties): self {
     return $this;
   }
 
+  /**
+   * {@inheritdoc}
+   */
   public function getProperties() {
     return $this->properties;
   }
 
+  /**
+   * {@inheritdoc}
+   */
   public function getPropertyNames() {
     return array_keys($this->properties);
   }
 
   /**
-   * Gets a child property definition.
-   *
-   * @param string $name
-   *  The property name.
-   *
-   * @return static
-   *  The definition.
-   *
-   * @throws \Exception
-   *  Throws an exception if the property doesn't exit.
+   * {@inheritdoc}
    */
   public function getProperty(string $name): self {
     if (!isset($this->properties[$name])) {
@@ -378,6 +378,9 @@ public function getNestedProperty($address): self {
     return $property_definition;
   }
 
+  /**
+   * {@inheritdoc}
+   */
   public function addProperty(self $property): self {
     // TODO! this won't catch child classes of SimpleData!!!
     if ($this->type == 'string' || $this->type == 'boolean') {
@@ -403,15 +406,7 @@ public function addProperty(self $property): self {
   }
 
   /**
-   * Adds properties to this definition.
-   *
-   * @param array $properties
-   *  An array of data definitions. These are appended to existing properties.
-   *  If any keys in this array correspond to existing properties, the existing
-   *  definition is overwritten. The replacement property will be in the order
-   *  given in the $properties array, not in its original position.
-   *
-   * @return static
+   * {@inheritdoc}
    */
   public function addProperties(array $properties): self {
     if ($this->type == 'string') {
@@ -441,6 +436,9 @@ public function addProperties(array $properties): self {
     return $this;
   }
 
+  /**
+   * {@inheritdoc}
+   */
   public function removeProperty(string $name) {
     unset($this->properties[$name]);
 
diff --git a/Definition/PropertyListInterface.php b/Definition/PropertyListInterface.php
new file mode 100644
index 0000000..ec04a75
--- /dev/null
+++ b/Definition/PropertyListInterface.php
@@ -0,0 +1,91 @@
+<?php
+
+namespace MutableTypedData\Definition;
+
+/**
+ * Interface for definitions which hold lists of properties.
+ */
+interface PropertyListInterface {
+
+  /**
+   * Sets the properties for this definition.
+   *
+   * Previously-defined properties are removed.
+   *
+   * @param array $properties
+   *   An array of data definitions, keyed by the property name.
+   *
+   * @return self
+   */
+  public function setProperties(array $properties): self;
+
+  /**
+   * Adds a property to this definition.
+   *
+   * @param DataDefinition $property
+   *   The property to add. It must have its name set already.
+   *
+   * @return self
+   */
+  public function addProperty(DataDefinition $property): self;
+
+  /**
+   * Adds properties to this definition.
+   *
+   * @param array $properties
+   *  An array of data definitions. These are appended to existing properties.
+   *  If any keys in this array correspond to existing properties, the existing
+   *  definition is overwritten. The replacement property will be in the order
+   *  given in the $properties array, not in its original position.
+   *
+   * @return self
+   */
+  public function addProperties(array $properties): self;
+
+  /**
+   * Removes a property.
+   *
+   * @param string $name
+   *   The name of the property to remove.
+   *
+   * @return self
+   *
+   * TODO: Add return type in 2.0.0
+   */
+  public function removeProperty(string $name);
+
+  /**
+   * Gets a child property definition.
+   *
+   * @param string $name
+   *  The property name.
+   *
+   * @return \MutableTypedData\Definition\DataDefinition
+   *  The definition.
+   *
+   * @throws \Exception
+   *  Throws an exception if the property doesn't exist.
+   */
+  public function getProperty(string $name): DataDefinition;
+
+  /**
+   * Gets this definition's properties.
+   *
+   * @return \MutableTypedData\Definition\DataDefinition[]
+   *  An array of property definitions, keyed by the property name.
+   *
+   * TODO: Add return type in 2.0.0
+   */
+  public function getProperties();
+
+  /**
+   * Gets the names of this definition's properties.
+   *
+   * @return string[]
+   *  An array of property names.
+   *
+   * TODO: Add return type in 2.0.0
+   */
+  public function getPropertyNames();
+
+}
\ No newline at end of file
diff --git a/Definition/VariantDefinition.php b/Definition/VariantDefinition.php
index 8f51b71..c079fde 100644
--- a/Definition/VariantDefinition.php
+++ b/Definition/VariantDefinition.php
@@ -16,7 +16,7 @@
  * When a mutable data item's variant controlling property is set, the variant's
  * properties are added to the mutable data.
  */
-class VariantDefinition {
+class VariantDefinition implements PropertyListInterface {
 
   protected $label;
 
@@ -35,7 +35,10 @@ public function getLabel() {
     return $this->label;
   }
 
-  public function setProperties(array $properties) {
+  /**
+   * {@inheritdoc}
+   */
+  public function setProperties(array $properties): self {
     $this->properties = $properties;
 
     // Fill in machine names as a convenience.
@@ -46,6 +49,16 @@ public function setProperties(array $properties) {
     return $this;
   }
 
+  /**
+   * {@inheritdoc}
+   */
+  public function addProperty(DataDefinition $property): self {
+    $this->properties[$property->getName()] = $property;
+  }
+
+  /**
+   * {@inheritdoc}
+   */
   public function addProperties(array $properties): self {
     foreach ($properties as $name => $property) {
       // Fill in machine names as a convenience.
@@ -57,8 +70,41 @@ public function addProperties(array $properties): self {
     return $this;
   }
 
+  /**
+   * {@inheritdoc}
+   */
   public function getProperties() {
     return $this->properties;
   }
 
+  /**
+   * {@inheritdoc}
+   */
+  public function getProperty(string $name): DataDefinition {
+    if (!isset($this->properties[$name])) {
+      throw new \Exception(sprintf("Property definition '%s' has no child property '$name' defined.",
+        $this->name,
+        $name
+      ));
+    }
+
+    return $this->properties[$name];
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function getPropertyNames() {
+    return array_keys($this->properties);
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function removeProperty(string $name) {
+    unset($this->properties[$name]);
+
+    return $this;
+  }
+
 }