Add Active Record Segregation Properties

Author: Admin

README.md

@@ -124,7 +124,7 @@ Optionally if you don't want to expose some models as resources but, you want to
     ];
 ````
 
-For model properties autocomplete:
+**Active Record Segregation of Properties:** for model attributes(columns) autocomplete and to avoid clashes with the model properties or relations:
 
 - extend BaseModelAttributes following the same FQN structure as the parent's:
 
@@ -133,7 +133,18 @@ For model properties autocomplete:
 
 - add in its class dock block using **@property** all the models properties/attributes/columns
 - add in the model's class dock block **@property ChildBaseModelAttributes $a** and **@mixin ChildBaseModelAttributes**
-- use **$model->a->** instead of **$model->**
+- use `$model->a->` instead of `$model->` _(this will work without autocomplete even if you don't do the above)_
+
+**Active Record Segregation of Properties:** for model relation autocomplete and to avoid clashes with the model properties and attributes(columns):
+
+- extend BaseModelRelations following the same FQN structure as the parent's:
+
+      \App\Models\ChildBaseModel paired with \App\Models\Attributes\ChildBaseModelRelations
+      \App\Models\Folder\ChildBaseModel paired with \App\Models\Folder\Attributes\ChildBaseModelRelations
+
+- add in its class dock block using **@property-read** all the models relations
+- add in the model's class dock block **@property ChildBaseModelRelations $r** and **@mixin ChildBaseModelRelations**
+- use `$model->r->` instead of `$model->` _(this will work without autocomplete even if you don't do the above)_
 - BaseModelFrozenAttributes can be also extended on the same logic and used for model read only situations - DTO without setters (Reflection or Closure binding usage will retrieve/set protected stdClass not Model - but the model can be retrieved from DB by its primary key that is readable in this frozen model):
 ```php
 #OperationModel example for BaseModelFrozenAttributes
@@ -279,7 +290,7 @@ for example for lumen:
 
 OBS
 
-Set `$returnNullOnInvalidColumnAttributeAccess = false;` in model if you want exception instead of null on accessing invalid model attributes (It also needs error_reporting = E_ALL in php ini file).
+Set `$returnNullOnInvalidColumnAttributeAccess = false;` in model if you want exception instead of null on accessing invalid model attributes or invalid relations (It also needs error_reporting = E_ALL in php ini file).
 
 Set LIVE_MODE=false in your .env file for non prod environments.
 

src/Models/Attributes/AbstractBaseModelAttributes.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace MacropaySolutions\LaravelCrudWizard\Models\Attributes;
+
+use MacropaySolutions\LaravelCrudWizard\Models\BaseModel;
+
+abstract class AbstractBaseModelAttributes
+{
+    public function __construct(
+        protected BaseModel $ownerBaseModel
+    ) {
+    }
+
+    /**
+     * @throws \Throwable
+     */
+    public function __call(string $method, array $parameters): mixed
+    {
+        try {
+            return $this->ownerBaseModel->{$method}(...$parameters);
+        } catch (\Error | \BadMethodCallException $e) {
+            $pattern = '~^Call to undefined method (?P<class>[^:]+)::(?P<method>[^\(]+)\(\)$~';
+
+            if (
+                0 === (int)\preg_match($pattern, $e->getMessage(), $matches)
+                || $matches['class'] !== \get_class($this->ownerBaseModel)
+                || $matches['method'] !== $method
+            ) {
+                throw $e;
+            }
+
+            throw new \BadMethodCallException(
+                \sprintf('Call to undefined method %s::%s()', static::class, $method)
+            );
+        }
+    }
+}

src/Models/Attributes/BaseModelAttributes.php

@@ -7,16 +7,15 @@
 /**
  * For properties autocompletion declare in the children classes (with @ property) all the model's parameters (columns)
  */
-class BaseModelAttributes
+class BaseModelAttributes extends AbstractBaseModelAttributes
 {
-    public function __construct(
-        private BaseModel $ownerBaseModel
-    ) {
-    }
-
+    /**
+     * @throws \Exception
+     * @see BaseModel::$returnNullOnInvalidColumnAttributeAccess
+     */
     public function __get(string $key): mixed
     {
-        return $this->ownerBaseModel->getAttribute($key);
+        return $this->ownerBaseModel->getAttributeValue($key);
     }
 
     public function __set(string $key, mixed $value): void
@@ -26,35 +25,11 @@ public function __set(string $key, mixed $value): void
 
     public function __isset(string $key): bool
     {
-        return $this->ownerBaseModel->__isset($key);
+        return $this->ownerBaseModel->attributeOffsetExists($key);
     }
 
     public function __unset(string $key): void
     {
-        $this->ownerBaseModel->__unset($key);
-    }
-
-    /**
-     * @throws \Throwable
-     */
-    public function __call(string $method, array $parameters): mixed
-    {
-        try {
-            return $this->ownerBaseModel->{$method}(...$parameters);
-        } catch (\Error | \BadMethodCallException $e) {
-            $pattern = '~^Call to undefined method (?P<class>[^:]+)::(?P<method>[^\(]+)\(\)$~';
-
-            if (
-                0 === (int)\preg_match($pattern, $e->getMessage(), $matches)
-                || $matches['class'] !== \get_class($this->ownerBaseModel)
-                || $matches['method'] !== $method
-            ) {
-                throw $e;
-            }
-
-            throw new \BadMethodCallException(
-                \sprintf('Call to undefined method %s::%s()', static::class, $method)
-            );
-        }
+        $this->ownerBaseModel->attributeOffsetUnset($key);
     }
 }

src/Models/Attributes/BaseModelRelations.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace MacropaySolutions\LaravelCrudWizard\Models\Attributes;
+
+use MacropaySolutions\LaravelCrudWizard\Models\BaseModel;
+
+/**
+ * For properties autocompletion declare in the children classes (with @ property-read) all the model's relations
+ */
+class BaseModelRelations extends AbstractBaseModelAttributes
+{
+    /**
+     * @throws \Exception
+     * @see BaseModel::$returnNullOnInvalidColumnAttributeAccess
+     */
+    public function __get(string $key): mixed
+    {
+        return $this->ownerBaseModel->getRelationValue($key);
+    }
+
+    public function __set(string $key, mixed $value): void
+    {
+        $this->ownerBaseModel->setRelation($key, $value);
+    }
+
+    public function __isset(string $key): bool
+    {
+        return $this->ownerBaseModel->relationLoaded($key);
+    }
+
+    public function __unset(string $key): void
+    {
+        $this->ownerBaseModel->unsetRelation($key);
+    }
+}

src/Models/BaseModel.php

@@ -14,6 +14,7 @@
 use MacropaySolutions\LaravelCrudWizard\Helpers\GeneralHelper;
 use MacropaySolutions\LaravelCrudWizard\Models\Attributes\BaseModelAttributes;
 use MacropaySolutions\LaravelCrudWizard\Models\Attributes\BaseModelFrozenAttributes;
+use MacropaySolutions\LaravelCrudWizard\Models\Attributes\BaseModelRelations;
 
 /**
  * For properties autocompletion declare in the children classes (with @ property) ChildBaseModelAttributes $a
@@ -30,6 +31,7 @@ abstract class BaseModel extends Model
     public $timestamps = false;
     public static $snakeAttributes = false;
     public BaseModelAttributes $a;
+    public BaseModelRelations $r;
     protected bool $returnNullOnInvalidColumnAttributeAccess = true;
     protected array $ignoreUpdateFor = [];
     protected array $ignoreExternalCreateFor = [];
@@ -47,12 +49,7 @@ public function __construct(array $attributes = [])
     {
         parent::__construct($attributes);
 
-        $attributes = \substr($class = static::class, 0, $l = (-1 * (\strlen($class) - \strrpos($class, '\\') - 1))) .
-            'Attributes\\' . \substr($class, $l) . 'Attributes';
-
-        if (\class_exists($attributes)) {
-            $this->a = new $attributes($this);
-        }
+        $this->initializeActiveRecordSegregationProperties();
 
         $this->append('primary_key_identifier');
     }
@@ -306,27 +303,6 @@ protected function setKeysForSaveQuery($query)
         return $query->where($this->getPrimaryKeyFilter());
     }
 
-    /**
-     * @inheritDoc
-     */
-    public function getAttribute($key)
-    {
-        if ($this->exists && isset($this->incrementsToRefresh[$key])) {
-            $this->attributes = \array_merge(
-                $this->attributes,
-                (array)($this->setKeysForSelectQuery($this->newQueryWithoutScopes())
-                    ->useWritePdo()
-                    ->select($attributes = \array_keys($this->incrementsToRefresh))
-                    ->first()
-                    ?->toArray())
-            );
-            $this->syncOriginalAttributes($attributes);
-            $this->incrementsToRefresh = [];
-        }
-
-        return parent::getAttribute($key);
-    }
-
     /**
      * @throws \Exception
      */
@@ -355,6 +331,19 @@ public function shouldReturnNullOnInvalidColumnAttributeAccess(): bool
      */
     public function getAttributeValue($key): mixed
     {
+        if ($this->exists && isset($this->incrementsToRefresh[$key])) {
+            $this->attributes = \array_merge(
+                $this->attributes,
+                (array)($this->setKeysForSelectQuery($this->newQueryWithoutScopes())
+                    ->useWritePdo()
+                    ->select($attributes = \array_keys($this->incrementsToRefresh))
+                    ->first()
+                    ?->toArray())
+            );
+            $this->syncOriginalAttributes($attributes);
+            $this->incrementsToRefresh = [];
+        }
+
         $return = parent::getAttributeValue($key);
 
         if (
@@ -382,6 +371,48 @@ public function shouldEscapeWhenCastingToString(): bool
         return $this->escapeWhenCastingToString;
     }
 
+    public function attributeOffsetUnset(string $offset): void
+    {
+        unset($this->attributes[$offset]);
+    }
+
+    public function attributeOffsetExists(string $offset): bool
+    {
+        return isset($this->attributes[$offset]);
+    }
+
+    /**
+     * @inheritDoc
+     * @throws \Exception
+     * @see static::returnNullOnInvalidColumnAttributeAccess
+     */
+    public function getRelationValue($key): mixed
+    {
+        // If the key already exists in the relationships array, it just means the
+        // relationship has already been loaded, so we'll just return it out of
+        // here because there is no need to query within the relations twice.
+        if ($this->relationLoaded($key)) {
+            return $this->relations[$key];
+        }
+
+        if (!$this->isRelation($key)) {
+            if (!$this->returnNullOnInvalidColumnAttributeAccess) {
+                throw new \Exception('Undefined relation: ' . $key . ' in model: ' . static::class);
+            }
+
+            return null;
+        }
+
+        if ($this->preventsLazyLoading) {
+            $this->handleLazyLoadingViolation($key);
+        }
+
+        // If the "attribute" exists as a method on the model, we will just assume
+        // it is a relationship and will load and return results from the query
+        // and hydrate the relationship's value on the "relationships" array.
+        return $this->getRelationshipFromMethod($key);
+    }
+
     /**
      * This will mass update the whole table if the model does not exist!
      * @inheritDoc
@@ -397,4 +428,27 @@ protected function incrementOrDecrement($column, $amount, $extra, $method): int
 
         return $return;
     }
+
+    /**
+     * @see static::a
+     * @see static::p
+     */
+    protected function initializeActiveRecordSegregationProperties(): void
+    {
+        $prefix = \substr($class = static::class, 0, $l = (-1 * (\strlen($class) - \strrpos($class, '\\') - 1))) .
+            'Attributes\\' . \substr($class, $l);
+
+        foreach (
+            [
+                'a' => ['p' => 'Attributes', 'c' => BaseModelAttributes::class],
+                'r' => ['p' => 'Relations', 'c' => BaseModelRelations::class]
+            ] as $p => $propertyMap
+        ) {
+            try {
+                $this->$p = new ($prefix . $this->$propertyMap['p'])($this);
+            } catch (\Throwable) {
+                $this->$p = new ($this->$propertyMap['c'])($this);
+            }
+        }
+    }
 }