add phpstan extensions

Author: cristoforocervino

README.md

@@ -268,6 +268,92 @@ The `analyze` method of your processor must return one of two values from the `R
 *   `Result::SHOULD_BE_NULL`: Indicates that the embeddable object should be treated as null. Note that "should" is used because the parent entity might have the embeddable class defined as not nullable. There is no guarantee the parent class accepts `null` as a value; this depends on database consistency and the user's data model.
 *   `Result::KEEP_INITIALIZED`: Indicates that the embeddable object should remain initialized.
 
+## PHPStan Extension
+
+This bundle includes a PHPStan extension that validates `#[NullableEmbeddable]` classes to ensure they follow best practices for working with Doctrine's nullable embeddable behavior.
+
+### Why This Extension is Important
+
+When Doctrine determines that an entire embeddable object should be null (which is what this bundle does), it sets **all** the embeddable's database columns to `NULL`. This has important implications for how you structure your embeddable classes:
+
+1. **Property Initialization**: Properties with non-null default values should be initialized in the constructor, not outside it. This is because Doctrine hydrates entities by skipping the constructor. For example:
+   ```php
+   // BAD - Don't do this:
+   private bool $enabled = true;  // Doctrine gets NULL from DB but property shows true
+
+   // GOOD - Do this instead:
+   public function __construct(
+       private bool $enabled = true,
+   ) {}
+   ```
+
+2. **Nullable Columns**: All properties mapped to database columns must be nullable. This can be achieved either by using a PHP nullable type (`?string`) which Doctrine automatically infers as `nullable: true`, or by explicitly setting `nullable: true` in the `#[Column]` attribute. This is required because when the embeddable object is null, Doctrine will set all its database columns to `NULL`.
+
+3. **Nested Embeddables with Defaults**: Embedded objects that have explicit non-null default values must be typed as nullable. Uninitialized embedded properties are fine since they remain uninitialized when the parent is null.
+
+### Automatic Installation (Recommended)
+
+If you have `phpstan/extension-installer` installed (which is included in `require-dev`), the extension will be automatically registered. No additional configuration needed!
+
+```bash
+composer require --dev phpstan/phpstan phpstan/extension-installer
+```
+
+### Manual Installation
+
+If you don't have `phpstan/extension-installer`, you can manually include the extension in your `phpstan.neon` or `phpstan.neon.dist`:
+
+```neon
+includes:
+    - vendor/andanteproject/nullable-embeddable-bundle/extension.neon
+```
+
+### What the Extension Checks
+
+The PHPStan extension will report errors for:
+
+1. **Properties with non-null default values outside the constructor** - These should be moved to the constructor to avoid hydration issues
+2. **Non-nullable column mappings** - Properties with `#[Column]` must be nullable, either via PHP nullable type (`?Type`) or explicit `nullable: true`
+3. **Embedded objects with non-null default values** - Embedded properties with explicit defaults must be nullable (uninitialized embedded properties are allowed)
+
+### Example
+
+```php
+#[ORM\Embeddable]
+#[NullableEmbeddable(processor: /* ... */)]
+class Address
+{
+    // ERROR: Property has non-null default outside constructor
+    // private bool $isPrimary = false;
+
+    // ERROR: Column is not nullable (neither PHP type nor explicit attribute)
+    // #[ORM\Column(type: Types::STRING)]
+    // private string $street;
+
+    // CORRECT: Column is nullable via PHP type (Doctrine infers nullable: true)
+    #[ORM\Column(type: Types::STRING)]
+    private ?string $street = null;
+
+    // ALSO CORRECT: Column explicitly nullable (even with non-nullable PHP type)
+    #[ORM\Column(type: Types::STRING, nullable: true)]
+    private string $city;
+
+    // CORRECT: Uninitialized embedded property (will remain uninitialized when parent is null)
+    #[ORM\Embedded(class: Country::class)]
+    private Country $country;
+
+    // ALSO CORRECT: Embedded property initialized to null
+    #[ORM\Embedded(class: Region::class)]
+    private ?Region $region = null;
+
+    // CORRECT: Default value in constructor
+    public function __construct(
+        #[ORM\Column(type: Types::BOOLEAN, nullable: true)]
+        private bool $isPrimary = false,
+    ) {}
+}
+```
+
 ## Configuration
 
 The bundle provides a configuration option to enable a cache warmer for improved performance in production environments.

composer.json

@@ -55,5 +55,16 @@
             "composer/package-versions-deprecated": true,
             "phpstan/extension-installer": true
         }
+    },
+    "extra": {
+        "phpstan": {
+            "includes": [
+                "extension.neon"
+            ]
+        }
+    },
+    "suggest": {
+        "phpstan/phpstan": "To validate NullableEmbeddable classes at static analysis time",
+        "phpstan/extension-installer": "To automatically register the PHPStan extension (recommended)"
     }
 }

extension.neon

@@ -0,0 +1,5 @@
+services:
+	-
+		class: Andante\NullableEmbeddableBundle\PHPStan\Rules\NullableEmbeddablePropertyRule
+		tags:
+			- phpstan.rules.rule

phpstan-8.5-plus.neon

@@ -1,3 +1,6 @@
+includes:
+    - extension.neon
+
 parameters:
     level: 9
     bootstrapFiles:
@@ -7,3 +10,6 @@ parameters:
         - tests
         - phpstan-stubs
         - tests/Fixtures/ValidClosureProcessorEntity
+    excludePaths:
+        - tests/PHPStan
+        - tests/Functional/PHPStanRulesIssuesTests/Fixtures

phpstan-lt-8.5.neon

@@ -1,3 +1,6 @@
+includes:
+    - extension.neon
+
 parameters:
     level: 9
     bootstrapFiles:
@@ -8,3 +11,5 @@ parameters:
         - phpstan-stubs
     excludePaths:
         - tests/Fixtures/ValidClosureProcessorEntity
+        - tests/PHPStan
+        - tests/Functional/PHPStanRulesIssuesTests/Fixtures

src/PHPStan/Rules/NullableEmbeddablePropertyRule.php

@@ -0,0 +1,216 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Andante\NullableEmbeddableBundle\PHPStan\Rules;
+
+use Andante\NullableEmbeddableBundle\Attribute\NullableEmbeddable;
+use Doctrine\ORM\Mapping\Column;
+use Doctrine\ORM\Mapping\Embeddable;
+use Doctrine\ORM\Mapping\Embedded;
+use PhpParser\Node;
+use PHPStan\Analyser\Scope;
+use PHPStan\Node\InClassNode;
+use PHPStan\Rules\Rule;
+use PHPStan\Rules\RuleErrorBuilder;
+
+/**
+ * @implements Rule<InClassNode>
+ */
+class NullableEmbeddablePropertyRule implements Rule
+{
+    public function getNodeType(): string
+    {
+        return InClassNode::class;
+    }
+
+    public function processNode(Node $node, Scope $scope): array
+    {
+        $classReflection = $node->getClassReflection();
+
+        // Only check classes with both Embeddable and NullableEmbeddable attributes
+        if (!$this->hasEmbeddableAttribute($classReflection->getName())) {
+            return [];
+        }
+
+        if (!$this->hasNullableEmbeddableAttribute($classReflection->getName())) {
+            return [];
+        }
+
+        $errors = [];
+        $reflectionClass = new \ReflectionClass($classReflection->getName());
+
+        foreach ($reflectionClass->getProperties() as $property) {
+            // Skip static properties
+            if ($property->isStatic()) {
+                continue;
+            }
+
+            // Rule 1: Properties with non-null default values outside constructor
+            if ($this->hasNonNullDefaultValue($property, $reflectionClass)) {
+                $errors[] = RuleErrorBuilder::message(
+                    \sprintf(
+                        'Property %s::$%s in a NullableEmbeddable class has a non-null default value outside the constructor. '.
+                        'Initialize it in the constructor instead to avoid issues with Doctrine hydration (Doctrine skips constructors during hydration).',
+                        $classReflection->getName(),
+                        $property->getName()
+                    )
+                )->identifier('nullableEmbeddable.propertyInitialization')->build();
+            }
+
+            // Rule 2: Properties with Column mapping must be nullable
+            // Either explicitly via nullable=true OR implicitly via PHP nullable type
+            $columnAttribute = $this->getColumnAttribute($property);
+            if (null !== $columnAttribute) {
+                $isExplicitlyNullable = $this->isColumnNullable($columnAttribute);
+                $propertyType = $property->getType();
+                $isPhpNullable = $propertyType instanceof \ReflectionNamedType && $propertyType->allowsNull();
+
+                // Only flag if both explicit attribute AND PHP type are not nullable
+                if (!$isExplicitlyNullable && !$isPhpNullable) {
+                    $errors[] = RuleErrorBuilder::message(
+                        \sprintf(
+                            'Property %s::$%s in a NullableEmbeddable class must be nullable (either via nullable=true in #[Column] or ?Type). '.
+                            'When the embeddable object is null, Doctrine will set all its database columns to NULL.',
+                            $classReflection->getName(),
+                            $property->getName()
+                        )
+                    )->identifier('nullableEmbeddable.columnNullable')->build();
+                }
+            }
+
+            // Rule 3: Embedded properties with explicit non-null defaults must be nullable
+            // Note: Uninitialized embedded properties are fine - they remain uninitialized when parent is null
+            $embeddedAttribute = $this->getEmbeddedAttribute($property);
+            if (null !== $embeddedAttribute && $property->hasDefaultValue()) {
+                $defaultValue = $property->getDefaultValue();
+                $propertyType = $property->getType();
+
+                // Only flag if there's an explicit non-null default value at class level
+                if (null !== $defaultValue && $propertyType instanceof \ReflectionNamedType && !$propertyType->allowsNull()) {
+                    $errors[] = RuleErrorBuilder::message(
+                        \sprintf(
+                            'Property %s::$%s in a NullableEmbeddable class is an embedded object with a non-null default value and must be nullable. '.
+                            'When the parent embeddable is null, all nested embeddables with default values must accept null.',
+                            $classReflection->getName(),
+                            $property->getName()
+                        )
+                    )->identifier('nullableEmbeddable.embeddedNullable')->build();
+                }
+            }
+        }
+
+        return $errors;
+    }
+
+    /**
+     * @param class-string $className
+     */
+    private function hasEmbeddableAttribute(string $className): bool
+    {
+        try {
+            $reflectionClass = new \ReflectionClass($className);
+
+            return !empty($reflectionClass->getAttributes(Embeddable::class));
+        } catch (\ReflectionException) {
+            return false;
+        }
+    }
+
+    /**
+     * @param class-string $className
+     */
+    private function hasNullableEmbeddableAttribute(string $className): bool
+    {
+        try {
+            $reflectionClass = new \ReflectionClass($className);
+
+            return !empty($reflectionClass->getAttributes(NullableEmbeddable::class));
+        } catch (\ReflectionException) {
+            return false;
+        }
+    }
+
+    /**
+     * @param \ReflectionClass<object> $reflectionClass
+     */
+    private function hasNonNullDefaultValue(\ReflectionProperty $property, \ReflectionClass $reflectionClass): bool
+    {
+        // Check if property has a default value
+        if (!$property->hasDefaultValue()) {
+            return false;
+        }
+
+        $defaultValue = $property->getDefaultValue();
+
+        // If default value is null, that's fine
+        if (null === $defaultValue) {
+            return false;
+        }
+
+        // Check if this property is initialized in the constructor
+        if ($this->isInitializedInConstructor($property, $reflectionClass)) {
+            return false;
+        }
+
+        // Non-null default value outside constructor
+        return true;
+    }
+
+    /**
+     * @param \ReflectionClass<object> $reflectionClass
+     */
+    private function isInitializedInConstructor(\ReflectionProperty $property, \ReflectionClass $reflectionClass): bool
+    {
+        $constructor = $reflectionClass->getConstructor();
+
+        if (null === $constructor) {
+            return false;
+        }
+
+        // Check if property is a constructor parameter (promoted property)
+        foreach ($constructor->getParameters() as $param) {
+            if ($param->getName() === $property->getName() && $param->isPromoted()) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * @return \ReflectionAttribute<Column>|null
+     */
+    private function getColumnAttribute(\ReflectionProperty $property): ?\ReflectionAttribute
+    {
+        $attributes = $property->getAttributes(Column::class);
+
+        return $attributes[0] ?? null;
+    }
+
+    /**
+     * @param \ReflectionAttribute<Column> $columnAttribute
+     */
+    private function isColumnNullable(\ReflectionAttribute $columnAttribute): bool
+    {
+        $arguments = $columnAttribute->getArguments();
+
+        // Check named argument
+        if (isset($arguments['nullable'])) {
+            return true === $arguments['nullable'];
+        }
+
+        // Column mapping defaults to nullable: false
+        return false;
+    }
+
+    /**
+     * @return \ReflectionAttribute<Embedded>|null
+     */
+    private function getEmbeddedAttribute(\ReflectionProperty $property): ?\ReflectionAttribute
+    {
+        $attributes = $property->getAttributes(Embedded::class);
+
+        return $attributes[0] ?? null;
+    }
+}