Merge pull request #124 from wol-soft/attributes

Attribute support

Author: wol-soft

docs/source/generator/custom/customPostProcessor.rst

@@ -28,6 +28,7 @@ What can you do inside your custom post processor?
 
 * Add additional traits and interfaces to your models
 * Add additional methods and properties to your models
+* Add PHP attributes to the generated class or to individual properties (see `PHP Attributes`_ below)
 * Hook via **SchemaHooks** into the generated source code and add your snippets at defined places inside the model:
 
     * Implement the **ConstructorBeforeValidationHookInterface** to add code to the beginning of your constructor
@@ -44,3 +45,61 @@ What can you do inside your custom post processor?
     This behaviour also applies also to properties changed via the *populate* method added by the `PopulatePostProcessor <#populatepostprocessor>`__ and the *setAdditionalProperty* method added by the `AdditionalPropertiesAccessorPostProcessor <#additionalpropertiesaccessorpostprocessor>`__
 
 To execute code before/after the processing of the schemas override the methods **preProcess** and **postProcess** inside your custom post processor.
+
+PHP Attributes
+--------------
+
+You can attach PHP 8.0 `attributes <https://www.php.net/manual/en/language.attributes.overview.php>`__ to the generated class and to individual properties using **PHPModelGenerator\\Model\\PhpAttribute**.
+
+**Class-level attribute** (placed before the ``class`` keyword in the generated file):
+
+.. code-block:: php
+
+    use PHPModelGenerator\Model\PhpAttribute;
+    use PHPModelGenerator\SchemaProcessor\PostProcessor\PostProcessor;
+
+    class ORM_EntityPostProcessor extends PostProcessor
+    {
+        public function process(Schema $schema, GeneratorConfiguration $generatorConfiguration): void
+        {
+            // No arguments
+            $schema->addAttribute(new PhpAttribute(\Doctrine\ORM\Mapping\Entity::class));
+
+            // With positional arguments (pre-rendered PHP expression strings)
+            $schema->addAttribute(new PhpAttribute(\Doctrine\ORM\Mapping\Table::class, ["'users'"]));
+
+            // With named arguments
+            $schema->addAttribute(new PhpAttribute(
+                \Doctrine\ORM\Mapping\Table::class,
+                ['name' => "'users'", 'schema' => "'public'"],
+            ));
+        }
+    }
+
+**Property-level attribute** (placed before the property declaration in the generated file):
+
+.. code-block:: php
+
+    use PHPModelGenerator\Model\PhpAttribute;
+    use PHPModelGenerator\SchemaProcessor\PostProcessor\PostProcessor;
+
+    class ORM_ColumnPostProcessor extends PostProcessor
+    {
+        public function process(Schema $schema, GeneratorConfiguration $generatorConfiguration): void
+        {
+            foreach ($schema->getProperties() as $property) {
+                $property->addAttribute(new PhpAttribute(
+                    \Doctrine\ORM\Mapping\Column::class,
+                    ['name' => "'" . $property->getName() . "'"],
+                ));
+            }
+        }
+    }
+
+The constructor of **PhpAttribute** accepts:
+
+* ``$fqcn`` — the fully-qualified class name of the attribute (e.g. ``'Doctrine\\ORM\\Mapping\\Column'``)
+* ``$arguments`` — an optional array of pre-rendered PHP expression strings:
+
+  * **Integer keys** → positional arguments (rendered as-is)
+  * **String keys** → named arguments (rendered as ``key: value``)

src/Model/AttributesTrait.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPModelGenerator\Model;
+
+trait AttributesTrait
+{
+    /** @var PhpAttribute[] */
+    private array $phpAttributes = [];
+
+    public function addAttribute(PhpAttribute $attribute): static
+    {
+        $this->phpAttributes[] = $attribute;
+
+        return $this;
+    }
+
+    /**
+     * @return PhpAttribute[]
+     */
+    public function getAttributes(): array
+    {
+        return $this->phpAttributes;
+    }
+}

src/Model/PhpAttribute.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPModelGenerator\Model;
+
+final class PhpAttribute
+{
+    /**
+     * @param string  $fqcn      Fully-qualified class name of the attribute.
+     * @param array   $arguments Pre-rendered PHP expression strings.
+     *                           String keys  → named arguments  (key: value)
+     *                           Integer keys → positional arguments (value)
+     */
+    public function __construct(
+        private readonly string $fqcn,
+        private readonly array $arguments = [],
+    ) {}
+
+    public function getFqcn(): string
+    {
+        return $this->fqcn;
+    }
+
+    /**
+     * Render the attribute body — the content that appears inside #[...].
+     * Uses the simple (unqualified) class name; the FQCN is added via use-import separately.
+     */
+    public function render(): string
+    {
+        $parts = explode('\\', $this->fqcn);
+        $shortName = end($parts);
+
+        if (empty($this->arguments)) {
+            return $shortName;
+        }
+
+        $args = [];
+        foreach ($this->arguments as $key => $value) {
+            $args[] = is_string($key) ? "$key: $value" : $value;
+        }
+
+        return $shortName . '(' . implode(', ', $args) . ')';
+    }
+}

src/Model/Property/AbstractProperty.php

@@ -5,6 +5,8 @@
 namespace PHPModelGenerator\Model\Property;
 
 use PHPModelGenerator\Exception\SchemaException;
+use PHPModelGenerator\Model\AttributesTrait;
+use PHPModelGenerator\Model\PhpAttribute;
 use PHPModelGenerator\Model\SchemaDefinition\JsonSchema;
 use PHPModelGenerator\Model\SchemaDefinition\JsonSchemaTrait;
 use PHPModelGenerator\Utils\NormalizedName;
@@ -19,6 +21,7 @@ abstract class AbstractProperty implements PropertyInterface
 {
     use JsonSchemaTrait;
     use ResolvableTrait;
+    use AttributesTrait;
 
     protected string $attribute;
 

src/Model/Property/PropertyInterface.php

@@ -4,6 +4,7 @@
 
 namespace PHPModelGenerator\Model\Property;
 
+use PHPModelGenerator\Model\PhpAttribute;
 use PHPModelGenerator\Model\Schema;
 use PHPModelGenerator\Model\SchemaDefinition\JsonSchema;
 use PHPModelGenerator\Model\Validator;
@@ -145,4 +146,11 @@ public function getNestedSchema(): ?Schema;
      * Get the JSON schema used to set up the property
      */
     public function getJsonSchema(): JsonSchema;
+
+    public function addAttribute(PhpAttribute $attribute): static;
+
+    /**
+     * @return PhpAttribute[]
+     */
+    public function getAttributes(): array;
 }

src/Model/Property/PropertyProxy.php

@@ -5,6 +5,7 @@
 namespace PHPModelGenerator\Model\Property;
 
 use PHPModelGenerator\Exception\SchemaException;
+use PHPModelGenerator\Model\PhpAttribute;
 use PHPModelGenerator\Model\SchemaDefinition\JsonSchema;
 use PHPModelGenerator\Model\SchemaDefinition\ResolvedDefinitionsCollection;
 use PHPModelGenerator\Model\Schema;
@@ -247,4 +248,22 @@ public function isInternal(): bool
     {
         return $this->getProperty()->isInternal();
     }
+
+    /**
+     * @inheritdoc
+     */
+    public function addAttribute(PhpAttribute $attribute): static
+    {
+        $this->getProperty()->addAttribute($attribute);
+
+        return $this;
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function getAttributes(): array
+    {
+        return $this->getProperty()->getAttributes();
+    }
 }

src/Model/RenderJob.php

@@ -9,6 +9,7 @@
 use PHPModelGenerator\Exception\FileSystemException;
 use PHPModelGenerator\Exception\RenderException;
 use PHPModelGenerator\Exception\ValidationException;
+use PHPModelGenerator\Model\PhpAttribute;
 use PHPModelGenerator\Model\Validator\AbstractComposedPropertyValidator;
 use PHPModelGenerator\SchemaProcessor\Hook\SchemaHookResolver;
 use PHPModelGenerator\SchemaProcessor\PostProcessor\PostProcessor;
@@ -146,10 +147,22 @@ protected function renderClass(GeneratorConfiguration $generatorConfiguration):
      */
     protected function getUseForSchema(GeneratorConfiguration $generatorConfiguration, string $namespace): array
     {
+        $attributeFqcns = array_map(
+            static fn(PhpAttribute $attr): string => $attr->getFqcn(),
+            $this->schema->getAttributes(),
+        );
+
+        foreach ($this->schema->getProperties() as $property) {
+            foreach ($property->getAttributes() as $attr) {
+                $attributeFqcns[] = $attr->getFqcn();
+            }
+        }
+
         return RenderHelper::filterClassImports(
             array_unique(
                 array_merge(
                     $this->schema->getUsedClasses(),
+                    $attributeFqcns,
                     $generatorConfiguration->collectErrors()
                         ? [$generatorConfiguration->getErrorRegistryClass()]
                         : [ValidationException::class],

src/Model/Schema.php

@@ -6,6 +6,7 @@
 
 use PHPModelGenerator\Interfaces\JSONModelInterface;
 use PHPModelGenerator\Model\Property\PropertyInterface;
+use PHPModelGenerator\Model\AttributesTrait;
 use PHPModelGenerator\Model\SchemaDefinition\JsonSchema;
 use PHPModelGenerator\Model\SchemaDefinition\JsonSchemaTrait;
 use PHPModelGenerator\Model\SchemaDefinition\SchemaDefinitionDictionary;
@@ -26,6 +27,7 @@
 class Schema
 {
     use JsonSchemaTrait;
+    use AttributesTrait;
 
     /** @var string */
     protected $description;

src/Templates/Model.phptpl

@@ -23,11 +23,17 @@ declare(strict_types = 1);
  * If you need to implement something in this class use inheritance. Else you will lose your changes if the classes
  * are re-generated.
  */
+{% foreach schema.getAttributes() as attribute %}
+#[{{ attribute.render() }}]
+{% endforeach %}
 class {{ schema.getClassName() }} {% if schema.getInterfaces() %}implements {{ viewHelper.joinClassNames(schema.getInterfaces()) }}{% endif %}
 {
     {% if schema.getTraits() %}use {{ viewHelper.joinClassNames(schema.getTraits()) }};{% endif %}
 
     {% foreach schema.getProperties() as property %}
+        {% foreach property.getAttributes() as attribute %}
+            #[{{ attribute.render() }}]
+        {% endforeach %}
         /**{% if viewHelper.getTypeHintAnnotation(property, true) %} @var {{ viewHelper.getTypeHintAnnotation(property, true) }}{% endif %}{% if property.getDescription() %} {{ property.getDescription() }}{% endif %} */
         {% if property.isInternal() %}private{% else %}protected{% endif %} ${{ property.getAttribute(true) }}{% if not viewHelper.isNull(property.getDefaultValue()) %} = {{ property.getDefaultValue() }}{% endif %};
     {% endforeach %}