feat: add AR::make() method

phpstan-baseline.neon

@@ -1,5 +1,30 @@
 parameters:
 	ignoreErrors:
+		-
+			message: "#^Method Cycle\\\\ActiveRecord\\\\ActiveRecord\\:\\:make\\(\\) should return static\\(Cycle\\\\ActiveRecord\\\\ActiveRecord\\) but returns object\\.$#"
+			count: 1
+			path: src/ActiveRecord.php
+
+		-
+			message: "#^Template type TEntity is declared as covariant, but occurs in contravariant position in parameter select of method Cycle\\\\ActiveRecord\\\\Repository\\\\ActiveRepository\\:\\:with\\(\\)\\.$#"
+			count: 1
+			path: src/Repository/ActiveRepository.php
+
+		-
+			message: "#^Type mixed in generic type Cycle\\\\ORM\\\\Select\\<mixed\\> in PHPDoc tag @return is not subtype of template type TEntity of object of class Cycle\\\\ORM\\\\Select\\.$#"
+			count: 1
+			path: src/Repository/ActiveRepository.php
+
+		-
+			message: "#^Return type \\(Cycle\\\\App\\\\Query\\\\UserQuery\\) of method Cycle\\\\App\\\\Entity\\\\User\\:\\:query\\(\\) should be covariant with return type \\(Cycle\\\\ActiveRecord\\\\Query\\\\ActiveQuery\\<static\\(Cycle\\\\ActiveRecord\\\\ActiveRecord\\)\\>\\) of method Cycle\\\\ActiveRecord\\\\ActiveRecord\\:\\:query\\(\\)$#"
+			count: 1
+			path: tests/app/Entity/User.php
+
+		-
+			message: "#^Call to static method PHPUnit\\\\Framework\\\\Assert\\:\\:assertInstanceOf\\(\\) with 'Cycle\\\\\\\\App\\\\\\\\Entity\\\\\\\\User' and Cycle\\\\App\\\\Entity\\\\User will always evaluate to true\\.$#"
+			count: 1
+			path: tests/src/Functional/ActiveRecordTest.php
+
 		-
 			message: "#^Call to an undefined method Cycle\\\\Database\\\\Driver\\\\DriverInterface\\:\\:setLogger\\(\\)\\.$#"
 			count: 1

psalm-baseline.xml

@@ -25,15 +25,45 @@
     </PossiblyUnusedMethod>
   </file>
   <file src="src/Repository/ActiveRepository.php">
-    <UnusedClass>
-      <code><![CDATA[ActiveRepository]]></code>
-    </UnusedClass>
+    <PossiblyUnusedMethod>
+      <code><![CDATA[findAll]]></code>
+      <code><![CDATA[forUpdate]]></code>
+    </PossiblyUnusedMethod>
+  </file>
+  <file src="tests/src/Functional/ActiveRecordTest.php">
+    <PossiblyUnusedMethod>
+      <code><![CDATA[it_creates_entity_instance_using_make]]></code>
+      <code><![CDATA[it_deletes_entity]]></code>
+      <code><![CDATA[it_deletes_multiple_entities_using_remove_method]]></code>
+      <code><![CDATA[it_finds_all_entities]]></code>
+      <code><![CDATA[it_finds_entity_by_primary_key]]></code>
+      <code><![CDATA[it_finds_one_entity]]></code>
+      <code><![CDATA[it_gets_default_repository_of_entity]]></code>
+      <code><![CDATA[it_persists_multiple_entities]]></code>
+      <code><![CDATA[it_saves_entity]]></code>
+      <code><![CDATA[it_triggers_exception_when_tries_to_save_entity_using_save_or_fail]]></code>
+      <code><![CDATA[it_uses_query_to_select_entity]]></code>
+    </PossiblyUnusedMethod>
+  </file>
+  <file src="tests/src/Functional/Bridge/Spiral/Bootloader/ActiveRecordBootloaderTest.php">
+    <PossiblyUnusedMethod>
+      <code><![CDATA[it_gets_container_from_static_origin_class]]></code>
+    </PossiblyUnusedMethod>
   </file>
   <file src="tests/src/Functional/DatabaseTestCase.php">
     <PossiblyUnusedProperty>
       <code><![CDATA[$orm]]></code>
     </PossiblyUnusedProperty>
   </file>
+  <file src="tests/src/Functional/FacadeTest.php">
+    <PossiblyUnusedMethod>
+      <code><![CDATA[it_fails_to_get_orm_from_facade_when_container_is_not_set]]></code>
+      <code><![CDATA[it_gets_entity_manager_from_facade]]></code>
+      <code><![CDATA[it_gets_orm_from_facade_when_container_has_orm]]></code>
+      <code><![CDATA[it_throws_exception_when_container_does_not_have_orm]]></code>
+      <code><![CDATA[it_throws_exception_when_container_does_not_have_orm_set]]></code>
+    </PossiblyUnusedMethod>
+  </file>
   <file src="tests/src/Functional/Loggable.php">
     <PossiblyUnusedMethod>
       <code><![CDATA[disableProfiling]]></code>
@@ -42,6 +72,22 @@
       <code><![CDATA[setLogger]]></code>
     </UndefinedInterfaceMethod>
   </file>
+  <file src="tests/src/Functional/Query/ActiveQueryTest.php">
+    <PossiblyUnusedMethod>
+      <code><![CDATA[it_gets_role_from_query]]></code>
+    </PossiblyUnusedMethod>
+  </file>
+  <file src="tests/src/Functional/Repository/ActiveRepositoryTest.php">
+    <MissingTemplateParam>
+      <code><![CDATA[class() extends ActiveRepository {]]></code>
+    </MissingTemplateParam>
+    <PossiblyUnusedMethod>
+      <code><![CDATA[it_extends_repository_constructor]]></code>
+      <code><![CDATA[it_fetches_one_entity]]></code>
+      <code><![CDATA[it_fetches_one_entity_by_pk]]></code>
+      <code><![CDATA[it_uses_custom_repository_with_active_query]]></code>
+    </PossiblyUnusedMethod>
+  </file>
   <file src="tests/src/Functional/TestLogger.php">
     <ImplicitToStringCast>
       <code><![CDATA[$message]]></code>

src/ActiveRecord.php

@@ -11,8 +11,36 @@
 use Cycle\ORM\RepositoryInterface;
 use Cycle\ORM\Transaction\StateInterface;
 
+/**
+ * A base class for entities that are managed by the ORM.
+ * Adds a set of ActiveRecord methods to the extending entity class.
+ */
 abstract class ActiveRecord
 {
+    /**
+     * Creates a new entity instance with the given data.
+     * It is preferable to use this method instead of the constructor because
+     * it uses ORM services to create the entity.
+     *
+     * @note Equals to calling {@see ORMInterface::make()}.
+     *
+     * Example:
+     *
+     * ```php
+     * $user = User::make([
+     *    'name' => 'John Doe',
+     *    'email' => '[email protected]',
+     * ]);
+     * ```
+     *
+     * @param array<non-empty-string, mixed> $data An associative array where keys are property names
+     *        and values are property values.
+     */
+    public static function make(array $data): static
+    {
+        return self::getOrm()->make(static::class, $data);
+    }
+
     /**
      * Finds a single record based on the given primary key.
      */
@@ -23,6 +51,8 @@
 
     /**
      * Finds the first single record based on the given scope.
+     *
+     * @note Limit of 1 will be added to the query.
      */
     final public static function findOne(array $scope = []): ?static
     {
@@ -59,13 +89,13 @@
      *
      * @throws \Throwable
      */
     final public function save(bool $cascade = true): StateInterface
     {
         /** @var EntityManager $entityManager */
         $entityManager = Facade::getEntityManager();
         $entityManager->persist($this, $cascade);
 
         return $entityManager->run(throwException: false);
     }
 
     /**
@@ -73,7 +103,7 @@
      *
      * @throws \Throwable
      */
     final public function saveOrFail(bool $cascade = true): StateInterface
     {
         /** @var EntityManager $entityManager */
         $entityManager = Facade::getEntityManager();
@@ -82,7 +112,7 @@
         return $entityManager->run();
     }
 
     final public function persist(bool $cascade = true): EntityManagerInterface
     {
         return Facade::getEntityManager()->persist($this, $cascade);
     }
@@ -90,13 +120,13 @@
     /**
      * @throws \Throwable
      */
     final public function delete(bool $cascade = true): StateInterface
     {
         /** @var EntityManager $entityManager */
         $entityManager = Facade::getEntityManager();
         $entityManager->delete($this, $cascade);
 
         return $entityManager->run(throwException: false);
     }
 
     /**
@@ -114,7 +144,7 @@
     /**
      * Prepares the current entity for deletion.
      */
     final public function remove(bool $cascade = true): EntityManagerInterface
     {
         /** @var EntityManager $entityManager */
         $entityManager = Facade::getEntityManager();

src/Repository/ActiveRepository.php

@@ -136,9 +136,11 @@ protected function with(Select $select): static
      * }
      * ```
      *
-     * @param class-string<TEntity> $role
+     * @template T
      *
-     * @return Select<TEntity>
+     * @param class-string<T> $role
+     *
+     * @return Select<T>
      */
     protected function initSelect(ORMInterface $orm, string $role): Select
     {

tests/src/Functional/ActiveRecordTest.php

@@ -6,8 +6,6 @@
 
 use Cycle\ActiveRecord\Facade;
 use Cycle\App\Entity\User;
-use Cycle\Database\Database;
-use Cycle\Database\DatabaseManager;
 use Cycle\ORM\Select\Repository;
 use PHPUnit\Framework\Attributes\Test;
 
@@ -53,6 +51,16 @@ public function it_uses_query_to_select_entity(): void
         self::assertSame('Antony', $user->name);
     }
 
+    #[Test]
+    public function it_creates_entity_instance_using_make(): void
+    {
+        $user = User::make(['name' => 'Alex']);
+
+        self::assertInstanceOf(User::class, $user);
+        self::assertNotSame(User::class, $user::class, 'An Entity Proxy is created');
+        self::assertSame('Alex', $user->name);
+    }
+
     /**
      * @throws \Throwable
      */
@@ -157,19 +165,4 @@ public function it_gets_default_repository_of_entity(): void
 
         self::assertInstanceOf(Repository::class, $repository);
     }
-
-    /**
-     * @throws \Throwable
-     */
-    public function tearDown(): void
-    {
-        parent::tearDown();
-
-        $databaseManager = $this->getContainer()->get(DatabaseManager::class);
-        /** @var Database $database */
-        $database = $databaseManager->database('default');
-
-        $this->dropDatabase($database);
-        Facade::reset();
-    }
 }

tests/src/Functional/DatabaseTestCase.php

@@ -4,8 +4,10 @@
 
 namespace Cycle\Tests\Functional;
 
+use Cycle\ActiveRecord\Facade;
 use Cycle\Database\Database;
 use Cycle\Database\DatabaseInterface;
+use Cycle\Database\DatabaseManager;
 use Cycle\Database\Driver\DriverInterface;
 use Cycle\Database\Driver\HandlerInterface;
 use Cycle\Database\Table;
@@ -56,6 +58,21 @@ protected function setUp(): void
         ]);
     }
 
+    /**
+     * @throws \Throwable
+     */
+    protected function tearDown(): void
+    {
+        parent::tearDown();
+
+        $databaseManager = $this->getContainer()->get(DatabaseManager::class);
+        /** @var Database $database */
+        $database = $databaseManager->database('default');
+
+        $this->dropDatabase($database);
+        Facade::reset();
+    }
+
     /**
      * @throws \Throwable
      */

tests/src/Functional/Query/ActiveQueryTest.php

@@ -4,10 +4,7 @@
 
 namespace Cycle\Tests\Functional\Query;
 
-use Cycle\ActiveRecord\Facade;
 use Cycle\App\Entity\User;
-use Cycle\Database\Database;
-use Cycle\Database\DatabaseManager;
 use Cycle\Tests\Functional\DatabaseTestCase;
 use PHPUnit\Framework\Attributes\Test;
 
@@ -20,19 +17,4 @@ public function it_gets_role_from_query(): void
 
         self::assertSame(User::class, $query->getRole());
     }
-
-    /**
-     * @throws \Throwable
-     */
-    public function tearDown(): void
-    {
-        parent::tearDown();
-
-        $databaseManager = $this->getContainer()->get(DatabaseManager::class);
-        /** @var Database $database */
-        $database = $databaseManager->database('default');
-
-        $this->dropDatabase($database);
-        Facade::reset();
-    }
 }