Add Events

composer-require-checker.json

@@ -1,10 +1,15 @@
 {
     "symbol-whitelist": [
+        "Psr\\EventDispatcher\\EventDispatcherInterface",
+        "Psr\\EventDispatcher\\StoppableEventInterface",
         "Psr\\Http\\Message\\ResponseInterface",
         "Psr\\Http\\Message\\ServerRequestInterface",
         "Psr\\Http\\Server\\MiddlewareInterface",
         "Psr\\Http\\Server\\RequestHandlerInterface",
         "Yiisoft\\Arrays\\ArrayableTrait",
+        "Yiisoft\\EventDispatcher\\Dispatcher\\Dispatcher",
+        "Yiisoft\\EventDispatcher\\Provider\\ListenerCollection",
+        "Yiisoft\\EventDispatcher\\Provider\\Provider",
         "Yiisoft\\Factory\\Factory"
     ]
 }

composer.json

@@ -44,6 +44,7 @@
         "yiisoft/cache": "^3.0",
         "yiisoft/db-sqlite": "dev-master",
         "yiisoft/di": "^1.3",
+        "yiisoft/event-dispatcher": "^1.1",
         "yiisoft/factory": "^1.3",
         "yiisoft/middleware-dispatcher": "^5.2"
     },
@@ -55,6 +56,7 @@
         "yiisoft/db-mssql": "For MSSQL database support",
         "yiisoft/db-oracle": "For Oracle database support",
         "yiisoft/factory": "For factory support",
+        "yiisoft/event-dispatcher": "For events support",
         "yiisoft/middleware-dispatcher": "For middleware support"
     },
     "autoload": {

src/ActiveQuery.php

@@ -823,7 +823,7 @@ public function findByPk(array|float|int|string $values): array|ActiveRecordInte
             }
         }
 
-        return $this->setWhere(array_combine($primaryKey, $values))->one();
+        return (clone $this)->andWhere(array_combine($primaryKey, $values))->one();
     }
 
     public function on(array|string|null $value): static

src/Event/AbstractEvent.php

@@ -0,0 +1,88 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\ActiveRecord\Event;
+
+use Psr\EventDispatcher\StoppableEventInterface;
+use Yiisoft\ActiveRecord\ActiveRecordInterface;
+
+/**
+ * Base class for events in Active Record models.
+ */
+abstract class AbstractEvent implements StoppableEventInterface
+{
+    /** @var bool Whether the default action of the event should be prevented. */
+    private bool $isDefaultPrevented = false;
+    /** @var bool Whether the propagation of the event should be stopped. */
+    private bool $isPropagationStopped = false;
+    /** @var mixed The return value if the default action is prevented. */
+    private mixed $returnValue = null;
+
+    /**
+     * @param ActiveRecordInterface $model The target model associated with this event.
+     */
+    public function __construct(private readonly ActiveRecordInterface $model)
+    {
+    }
+
+    /**
+     * @return ActiveRecordInterface The target model associated with this event.
+     */
+    public function getModel(): ActiveRecordInterface
+    {
+        return $this->model;
+    }
+
+    /**
+     * Returns the value that will be returned by the method that triggered this event
+     * if the {@see isDefaultPrevented() default action is prevented}.
+     */
+    public function getReturnValue(): mixed
+    {
+        return $this->returnValue;
+    }
+
+    /**
+     * Checks if the default action associated with this event has been prevented.
+     */
+    public function isDefaultPrevented(): bool
+    {
+        return $this->isDefaultPrevented;
+    }
+
+    public function isPropagationStopped(): bool
+    {
+        return $this->isPropagationStopped;
+    }
+
+    /**
+     * Prevents the default action associated with this event from being executed.
+     *
+     * @see returnValue()
+     */
+    public function preventDefault(): void
+    {
+        $this->isDefaultPrevented = true;
+    }
+
+    /**
+     * Sets the return value which will be returned by the method that triggered this event
+     * if the {@see isDefaultPrevented() default action is prevented}.
+     *
+     * @see preventDefault()
+     */
+    public function returnValue(mixed $returnValue): void
+    {
+        $this->returnValue = $returnValue;
+    }
+
+    /**
+     * Stops the propagation of the event to further listeners.
+     * No further listeners will be notified after this method is called.
+     */
+    public function stopPropagation(): void
+    {
+        $this->isPropagationStopped = true;
+    }
+}

src/Event/AfterCreateQuery.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\ActiveRecord\Event;
+
+use Yiisoft\ActiveRecord\ActiveQueryInterface;
+use Yiisoft\ActiveRecord\ActiveRecordInterface;
+
+/**
+ * Event triggered after the query has been created for the {@see ActiveRecordInterface} model.
+ *
+ * @see ActiveRecordInterface::query()
+ */
+final class AfterCreateQuery extends AbstractEvent
+{
+    public function __construct(
+        ActiveRecordInterface $model,
+        public ActiveQueryInterface &$query,
+    ) {
+        parent::__construct($model);
+    }
+}

src/Event/AfterDelete.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\ActiveRecord\Event;
+
+use Yiisoft\ActiveRecord\ActiveRecordInterface;
+
+/**
+ * Event triggered after the record has been deleted from the database.
+ *
+ * @see ActiveRecordInterface::delete()
+ */
+final class AfterDelete extends AbstractEvent
+{
+    /**
+     * @param ActiveRecordInterface $model The model that was deleted.
+     * @param int $count Number of deleted rows.
+     */
+    public function __construct(ActiveRecordInterface $model, public int &$count)
+    {
+        parent::__construct($model);
+    }
+}

src/Event/AfterInsert.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\ActiveRecord\Event;
+
+use Yiisoft\ActiveRecord\ActiveRecordInterface;
+
+/**
+ * Event triggered after the record has been inserted into the database.
+ *
+ * @see ActiveRecordInterface::insert
+ */
+final class AfterInsert extends AbstractEvent
+{
+    /**
+     * @param ActiveRecordInterface $model The model that has been inserted.
+     * @param bool $isSuccessful Whether the insert operation is successful.
+     */
+    public function __construct(ActiveRecordInterface $model, public bool &$isSuccessful)
+    {
+        parent::__construct($model);
+    }
+}

src/Event/AfterPopulate.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\ActiveRecord\Event;
+
+use Yiisoft\ActiveRecord\ActiveRecordInterface;
+
+/**
+ * Event triggered after the model has been populated with data.
+ *
+ * @see ActiveRecordInterface::populate()
+ */
+final class AfterPopulate extends AbstractEvent
+{
+    /**
+     * @param ActiveRecordInterface $model The model that has been populated.
+     * @param array $data The data used to populate the model.
+     */
+    public function __construct(ActiveRecordInterface $model, public readonly array $data)
+    {
+        parent::__construct($model);
+    }
+}

src/Event/AfterSave.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\ActiveRecord\Event;
+
+use Yiisoft\ActiveRecord\ActiveRecordInterface;
+
+/**
+ * Event triggered after the model has been saved to the database.
+ *
+ * @see ActiveRecordInterface::afterSave()
+ */
+final class AfterSave extends AbstractEvent
+{
+    /**
+     * @param ActiveRecordInterface $model The model that was saved.
+     * @param bool $isSuccessful Whether the save operation was successful.
+     */
+    public function __construct(ActiveRecordInterface $model, public bool &$isSuccessful)
+    {
+        parent::__construct($model);
+    }
+}

src/Event/AfterUpdate.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\ActiveRecord\Event;
+
+use Yiisoft\ActiveRecord\ActiveRecordInterface;
+
+/**
+ * Event triggered after the record has been updated in the database.
+ *
+ * @see ActiveRecordInterface::update()
+ */
+final class AfterUpdate extends AbstractEvent
+{
+    /**
+     * @param ActiveRecordInterface $model The model that was updated.
+     * @param int $count The number of rows that were updated.
+     */
+    public function __construct(ActiveRecordInterface $model, public int &$count)
+    {
+        parent::__construct($model);
+    }
+}

src/Event/AfterUpsert.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\ActiveRecord\Event;
+
+use Yiisoft\ActiveRecord\ActiveRecordInterface;
+
+/**
+ * Event triggered after the model has been upserted (inserted or updated).
+ *
+ * @see ActiveRecordInterface::upsert()
+ */
+final class AfterUpsert extends AbstractEvent
+{
+    /**
+     * @param ActiveRecordInterface $model The model that was upserted.
+     * @param bool $isSuccessful Whether the upsert operation was successful.
+     */
+    public function __construct(ActiveRecordInterface $model, public bool &$isSuccessful)
+    {
+        parent::__construct($model);
+    }
+}

src/Event/BeforeCreateQuery.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\ActiveRecord\Event;
+
+use Yiisoft\ActiveRecord\ActiveRecordInterface;
+
+/**
+ * Event triggered before creating the query for the {@see ActiveRecordInterface} model.
+ *
+ * @see ActiveRecordInterface::query()
+ */
+final class BeforeCreateQuery extends AbstractEvent
+{
+    public function __construct(
+        ActiveRecordInterface $model,
+    ) {
+        parent::__construct($model);
+    }
+}

src/Event/BeforeDelete.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\ActiveRecord\Event;
+
+/**
+ * Event triggered before the record is deleted from the database.
+ *
+ * @see ActiveRecordInterface::delete()
+ */
+final class BeforeDelete extends AbstractEvent
+{
+}

src/Event/BeforeInsert.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\ActiveRecord\Event;
+
+use Yiisoft\ActiveRecord\ActiveRecordInterface;
+
+/**
+ * Event triggered before a new record is inserted into the database.
+ * It allows to modify properties that will be used for {@see ActiveRecordInterface::insert()} operation.
+ *
+ * @see ActiveRecordInterface::insert()
+ */
+final class BeforeInsert extends AbstractEvent
+{
+    /**
+     * @param ActiveRecordInterface $model The model that is being inserted.
+     * @param array|null &$properties The properties that will be used for the insert operation.
+     */
+    public function __construct(ActiveRecordInterface $model, public array|null &$properties)
+    {
+        parent::__construct($model);
+    }
+}

src/Event/BeforePopulate.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\ActiveRecord\Event;
+
+use Yiisoft\ActiveRecord\ActiveRecordInterface;
+
+/**
+ * Event triggered before the model is populated with data.
+ * It allows to modify the data that will be used for {@see ActiveRecordInterface::populateRecord()} operation.
+ *
+ * @see ActiveRecordInterface::populateRecord()
+ */
+final class BeforePopulate extends AbstractEvent
+{
+    /**
+     * @param ActiveRecordInterface $model The model that will be populated.
+     * @param array &$data The data that will be used to populate the model.
+     */
+    public function __construct(ActiveRecordInterface $model, public array &$data)
+    {
+        parent::__construct($model);
+    }
+}