feat: Observable Model Properties (#[Watches] attribute system)

src/Phaseolies/Console/Commands/MakeWatcherCommand.php

@@ -0,0 +1,89 @@
+<?php
+
+namespace Phaseolies\Console\Commands;
+
+use Phaseolies\Console\Schedule\Command;
+
+class MakeWatcherCommand extends Command
+{
+    /**
+     * The name and signature of the console command.
+     *
+     * @var string
+     */
+    protected $name = 'make:watcher {name}';
+
+    /**
+     * The description of the console command.
+     *
+     * @var string
+     */
+    protected $description = 'Create a new model property watcher listener class';
+
+    /**
+     * Execute the console command.
+     *
+     * @return int
+     */
+    public function handle(): int
+    {
+        return $this->executeWithTiming(function () {
+            $name      = $this->argument('name');
+            $parts     = explode('/', $name);
+            $className = array_pop($parts);
+            $namespace = 'App\\Watchers' . (count($parts) > 0 ? '\\' . implode('\\', $parts) : '');
+            $filePath  = base_path('app/Watchers/' . str_replace('/', DIRECTORY_SEPARATOR, $name) . '.php');
+
+            if (file_exists($filePath)) {
+                $this->displayError('Watcher already exists at:');
+                $this->line('<fg=white>' . str_replace(base_path(), '', $filePath) . '</>');
+                return Command::FAILURE;
+            }
+
+            $directoryPath = dirname($filePath);
+            if (!is_dir($directoryPath)) {
+                mkdir($directoryPath, 0755, true);
+            }
+
+            file_put_contents($filePath, $this->generateWatcherContent($namespace, $className));
+
+            $this->displaySuccess('Watcher created successfully');
+            $this->line('<fg=yellow>👁️  File:</> <fg=white>' . str_replace(base_path('/'), '', $filePath) . '</>');
+            $this->newLine();
+            $this->line('<fg=yellow>📌 Class:</> <fg=white>' . $className . '</>');
+
+            return Command::SUCCESS;
+        });
+    }
+
+    /**
+     * Generate watcher listener class content.
+     */
+    protected function generateWatcherContent(string $namespace, string $className): string
+    {
+        return <<<EOT
+<?php
+
+namespace {$namespace};
+
+use Phaseolies\Database\Entity\Model;
+
+class {$className}
+{
+    /**
+     * Handle the watched property change.
+     *
+     * @param mixed \$old
+     * @param mixed \$new
+     * @param Model \$model
+     * @return void
+     */
+    public function handle(mixed \$old, mixed \$new, Model \$model): void
+    {
+        //
+    }
+}
+
+EOT;
+    }
+}

src/Phaseolies/Database/Entity/Attributes/Watches.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Phaseolies\Database\Entity\Attributes;
+
+#[\Attribute(\Attribute::TARGET_PROPERTY | \Attribute::IS_REPEATABLE)]
+class Watches
+{
+    /**
+     * @param string $watcher
+     * @param string|null $when
+     */
+    public function __construct(
+        public readonly string $watcher,
+        public readonly ?string $when = null,
+    ) {}
+}

src/Phaseolies/Database/Entity/Model.php

@@ -8,6 +8,7 @@
 use Phaseolies\Database\Entity\Hooks\HookHandler;
 use Phaseolies\Database\Entity\Casts\InteractsWithCasting;
 use Phaseolies\Database\Temporal\InteractsWithTemporal;
+use Phaseolies\Database\Entity\Watches\InteractsWithWatches;
 use Phaseolies\Database\Database;
 use Phaseolies\Database\Contracts\Support\Jsonable;
 use PDO;
@@ -20,6 +21,7 @@ abstract class Model implements ArrayAccess, JsonSerializable, Stringable, Jsona
     use InteractsWithModelQueryProcessing;
     use InteractsWithTemporal;
     use InteractsWithCasting;
+    use InteractsWithWatches;
 
     /**
      * The name of the database table associated with the model.
@@ -191,6 +193,7 @@ protected function registerHooks(): void
 
         $this->registerAttributeHooks();
         $this->registerTemporalHooks();
+        $this->registerWatchesAttributes();
     }
 
     /**

src/Phaseolies/Database/Entity/Query/InteractsWithModelQueryProcessing.php

@@ -195,6 +195,7 @@ public function save(): bool
 
                 if (self::$isHookShouldBeCalled && $response) {
                     $this->fireAfterHooks('updated');
+                    $this->firePropertyWatches($dirtyAttributes);
                     $this->originalAttributes = $this->attributes;
                 }
 
@@ -502,6 +503,7 @@ public function update(array $attributes): bool
             if ($result) {
                 if (self::$isHookShouldBeCalled) {
                     $this->fireAfterHooks('updated');
+                    $this->firePropertyWatches($dirty);
                 }
                 $this->originalAttributes = $this->attributes;
             }

src/Phaseolies/Database/Entity/Watches/InteractsWithWatches.php

@@ -0,0 +1,101 @@
+<?php
+
+namespace Phaseolies\Database\Entity\Watches;
+
+use Phaseolies\Database\Entity\Attributes\Watches;
+
+trait InteractsWithWatches
+{
+    /**
+     * Per-class cache of scanned #[Watches] metadata so reflection only runs once.
+     *
+     * @var array<string, list<array{property: string, watcher: string, when: string|null}>>
+     */
+    private static array $watchesAttributeCache = [];
+
+    /**
+     * Scan #[Watches] attributes on the model's properties and register them with WatchesHandler.
+     *
+     * @return void
+     */
+    protected function registerWatchesAttributes(): void
+    {
+        $class = static::class;
+
+        if (!array_key_exists($class, self::$watchesAttributeCache)) {
+            self::$watchesAttributeCache[$class] = self::scanWatchesAttributes($class);
+        }
+
+        foreach (self::$watchesAttributeCache[$class] as $entry) {
+            WatchesHandler::register(
+                $class,
+                $entry['property'],
+                $entry['watcher'],
+                $entry['when']
+            );
+        }
+    }
+
+    /**
+     * Fire all registered property watches for the given set of dirty attributes.
+     *
+     * @param array $dirty
+     * @return void
+     */
+    public function firePropertyWatches(array $dirty): void
+    {
+        if (empty($dirty)) {
+            return;
+        }
+
+        WatchesHandler::fireForDirty($this, $dirty);
+    }
+
+    /**
+     * Reset the #[Watches] reflection cache for one or all model classes
+     *
+     * @param string|null $class
+     * @return void
+     */
+    public static function resetWatchesCache(?string $class = null): void
+    {
+        if ($class !== null) {
+            unset(self::$watchesAttributeCache[$class]);
+        } else {
+            self::$watchesAttributeCache = [];
+        }
+    }
+
+    /**
+     * Use reflection to collect all #[Watches] metadata from the model's properties
+     *
+     * @param  string $class
+     * @return list<array{property: string, watcher: string, when: string|null}>
+     */
+    private static function scanWatchesAttributes(string $class): array
+    {
+        $found      = [];
+        $reflection = new \ReflectionClass($class);
+
+        foreach ($reflection->getProperties() as $property) {
+            $watchAttrs = $property->getAttributes(Watches::class);
+
+            if (empty($watchAttrs)) {
+                continue;
+            }
+
+            foreach ($watchAttrs as $watchAttr) {
+                /** @var Watches $watches */
+                $watches = $watchAttr->newInstance();
+
+                $found[] = [
+                    'property' => $property->getName(),
+                    'watcher' => $watches->watcher,
+                    'when'     => $watches->when,
+                ];
+            }
+        }
+
+        return $found;
+    }
+}

src/Phaseolies/Database/Entity/Watches/WatchConditionInterface.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace Phaseolies\Database\Entity\Watches;
+
+use Phaseolies\Database\Entity\Model;
+
+interface WatchConditionInterface
+{
+    /**
+     * Evaluate whether the watch watcher should fire.
+     *
+     * @param mixed $old 
+     * @param mixed $new
+     * @param Model $model
+     * @return bool
+     */
+    public function evaluate(mixed $old, mixed $new, Model $model): bool;
+}