Adjust documentation to explain usage of enums

Author: Bernhard Schmitt

Documentation/01_PresentationObjectsAndComponents.md

@@ -8,7 +8,7 @@
 
 # 1. PresentationObjects and Components
 
-> **Hint:** This section describes the manual creation of PresentationObjects and PresentationObject components. Both patterns can also be scaffolded by the [Kickstarter](./05_Kickstarter.md).
+> **Hint:** This section describes the manual creation of PresentationObjects, Pseudo-Enums and PresentationObject components. All these patterns can also be scaffolded by the [Kickstarter](./05_Kickstarter.md).
 
 In this tutorial, we're going to write a PresentationObject for an image component. Our image consists of a `src`, an `alt` and an optional `title` property.
 
@@ -139,6 +139,106 @@ myImage = Vendor.Site:Component.Image {
 
 An exception will be thrown, if `someObject` does not implement `Vendor\Site\Presentation\Image\ImageInterface`.
 
+## (Pseudo) Enums
+
+It is recommended to model discrete values for presentation object properties as objects themselves.
+Since PHP does not support enums yet, this package provides an interface to be implemented by classes that behave similarly to enums.
+> **Hint:** For more information on enums in PHP, see https://stitcher.io/blog/php-enums
+
+<small>*`EXAMPLE: Pseudo-enum`*<small>
+
+Given we have a presentation object Headline with properties type and content.
+While content can be an arbitrary string, in our project by specification we only support h1-h3 as types for headlines.
+To prevent accidental use of h4 (or other tag names) for headlines, we model the headline type as a pseudo enum as follows:
+
+```php
+<?php declare(strict_types=1);
+namespace Acme\Site\Presentation\Block\Headline;
+
+use Neos\Flow\Annotations as Flow;
+use PackageFactory\AtomicFusion\PresentationObjects\Domain\Enum\PseudoEnumInterface;
+
+/**
+ * @Flow\Proxy(false)
+ */
+final class HeadlineType implements PseudoEnumInterface
+{
+    const TYPE_H1 = 'h1';
+    const TYPE_H2 = 'h2';
+    const TYPE_H3 = 'h3';
+
+    private string $value;
+
+    private function __construct(string $value)
+    {
+        $this->value = $value;
+    }
+
+    public static function fromString(string $string): self
+    {
+        if ($string !== self::TYPE_H1 && $string !== self::TYPE_H2 && $string !== self::TYPE_H3) {
+            throw HeadlineTypeIsInvalid::becauseItMustBeOneOfTheDefinedConstants($string);
+        }
+
+        return new self($string);
+    }
+
+    public static function h1(): self
+    {
+        return new self(self::TYPE_H1);
+    }
+
+    public static function h2(): self
+    {
+        return new self(self::TYPE_H2);
+    }
+
+    public static function h3(): self
+    {
+        return new self(self::TYPE_H3);
+    }
+
+    /**
+     * @return array|self[]
+     */
+    public static function cases(): array
+    {
+        return [
+            new self(self::TYPE_H1),
+            new self(self::TYPE_H2),
+            new self(self::TYPE_H3)
+        ];
+    }
+
+    public function getValue(): string
+    {
+        return $this->value;
+    }
+
+    public function __toString(): string
+    {
+        return $this->value;
+    }
+}
+```
+
+Now instead of having a string typed property in our headline, we can model it as follows:
+
+```php
+<?php declare(strict_types=1);
+namespace Acme\Site\Presentation\Block\Headline;
+
+interface HeadlineInterface
+{
+    public function getType(): HeadlineType;
+
+    public function getContent(): string;
+}
+```
+
+> **Hint:** Pseudo-enums can also be used in Neos' inspector select box editor. Please refer to [Integration Recipes](./04_IntegrationRecipes.md) to learn how it is done.
+
+
 ---
 
 <div align="center">

Documentation/04_IntegrationRecipes.md

@@ -80,6 +80,139 @@ Resolves URIs with the special `asset://` and `node://` protocols.
 | $rawLinkUri | string | The string containing the URI | |
 | $subgraph | [ContentContext](https://github.com/neos/neos-development-collection/blob/master/Neos.Neos/Classes/Domain/Service/ContentContext.php) | A reference content context required to resolve `node://` URIs | |
 
+## The EnumProvider
+
+All pseudo-enums implementing the PseudoEnumInterface can be provided to the inspector or the Fusion runtime using the PseudoEnumProvider.
+This makes the enum itself the single source of discrete values a node or presentation object property may have, obsoleting value adjustments in Fusion, configuration etc.
+
+As an example, we use the following pseudo-enum:
+
+```php
+<?php declare(strict_types=1);
+namespace Acme\Site\Presentation\Block\Headline;
+
+use Neos\Flow\Annotations as Flow;
+use PackageFactory\AtomicFusion\PresentationObjects\Domain\Enum\PseudoEnumInterface;
+
+/**
+ * @Flow\Proxy(false)
+ */
+final class HeadlineType implements PseudoEnumInterface
+{
+    const TYPE_H1 = 'h1';
+    const TYPE_H2 = 'h2';
+    const TYPE_H3 = 'h3';
+
+    private string $value;
+
+    private function __construct(string $value)
+    {
+        $this->value = $value;
+    }
+
+    public static function h1(): self
+    {
+        return new self(self::TYPE_H1);
+    }
+
+    public static function h2(): self
+    {
+        return new self(self::TYPE_H2);
+    }
+
+    public static function h3(): self
+    {
+        return new self(self::TYPE_H3);
+    }
+
+    /**
+     * @return array|self[]
+     */
+    public static function cases(): array
+    {
+        return [
+            new self(self::TYPE_H1),
+            new self(self::TYPE_H2),
+            new self(self::TYPE_H3)
+        ];
+    }
+
+    public function getValue(): string
+    {
+        return $this->value;
+    }
+
+    public function __toString(): string
+    {
+        return $this->value;
+    }
+}
+
+```
+
+### As a node type postprocessor
+
+Due to cacheability and thus improved performance, it is recommended to use the EnumProvider's node type postprocessor capabilities to make the enum's cases available in the Inspector.
+
+When we now declare our NodeType property, we do this as follows:
+
+```yaml
+  properties:
+    headline:
+      type: string
+      ui:
+        inspector:
+          editor: Neos.Neos/Inspector/Editors/SelectBoxEditor
+          editorOptions:
+            values: []
+  postprocessors:
+    headline-types:
+      postprocessor: PackageFactory\AtomicFusion\PresentationObjects\Application\PseudoEnumProvider
+      postprocessorOptions:
+        enumName: Acme\Site\Presentation\Block\Headline\HeadlineType
+        propertyNames:
+          - headline
+```
+
+The initial values are left empty and will be completely populated by the postprocessor. While the postprocessor is the same for all enums, there are two configuration options available:
+* enumName: The enum's fully qualified PHP class name
+* propertyNames: A list of property names to apply this enum's values to
+
+### As a data source
+
+If for some reason the postprocessor does not suffice, there is also the possibility to use the provider as a data source.
+Be aware that though more flexible, data sources are called on each load of the inspector, impacting performance.
+The provider can be used as a data source as follows:
+
+```yaml
+  properties:
+    headline:
+      type: string
+      ui:
+        inspector:
+          editor: Neos.Neos/Inspector/Editors/SelectBoxEditor
+          editorOptions:
+            dataSourceIdentifier: packagefactory-atomicfusion-presentationobjects-enumcases
+            dataSourceAdditionalData:
+              enumName: Acme\Site\Presentation\Block\Headline\HeadlineType
+```
+
+### As an EEL helper
+
+If you need the enum's values in Fusion, you can declare the provider as an EEL helper
+
+```yaml
+Neos:
+  Fusion:
+    defaultContext:
+      Enum: PackageFactory\AtomicFusion\PresentationObjects\Application\PseudoEnumProvider
+```
+and use it in Fusion to get the cases or values.
+```neosfusion
+cases = ${Enum.getCases('Acme\Site\Presentation\Block\Headline\HeadlineType')}
+values = ${Enum.getValues('Acme\Site\Presentation\Block\Headline\HeadlineType')}
+```
+
 ---
 
 <div align="center">