Improve database driver extensions and generated-column support

src/database/extension.neon

@@ -2,7 +2,7 @@ services:
     -
         class: Hypervel\Database\PHPStan\ModelScopeMethodResolver
     -
-        class: Hypervel\Database\PHPStan\ForwardedFluentMethodExtension
+        class: Hypervel\Database\PHPStan\ForwardedBuilderMethodExtension
         tags:
             - phpstan.broker.methodsClassReflectionExtension
     -

src/database/src/Eloquent/Builder.php

@@ -644,6 +644,8 @@ public function firstOrNew(array $attributes = [], Closure|array $values = []):
      */
     public function firstOrCreate(array $attributes = [], Closure|array $values = []): Model
     {
+        $this->ensureCanCreateOrFirst();
+
         if (! is_null($instance = (clone $this)->where($attributes)->first())) {
             return $instance;
         }
@@ -658,13 +660,24 @@ public function firstOrCreate(array $attributes = [], Closure|array $values = []
      */
     public function createOrFirst(array $attributes = [], Closure|array $values = []): Model
     {
+        $this->ensureCanCreateOrFirst();
+
         try {
             return $this->withSavepointIfNeeded(fn () => $this->create(array_merge($attributes, value($values))));
         } catch (UniqueConstraintViolationException $e) {
             return $this->useWritePdo()->where($attributes)->first() ?? throw $e;
         }
     }
 
+    /**
+     * Validate first-or-create and create-or-first operations, including relationship calls.
+     *
+     * Helpers delegate to each other, so this may run more than once per operation; keep overrides side-effect-free.
+     */
+    public function ensureCanCreateOrFirst(): void
+    {
+    }
+
     /**
      * Create or update a record matching the attributes, and fill it with values.
      *

src/database/src/Eloquent/Relations/BelongsToMany.php

@@ -596,6 +596,8 @@ public function firstOrNew(array $attributes = [], Closure|array $values = []):
      */
     public function firstOrCreate(array $attributes = [], Closure|array $values = [], array $joining = [], bool $touch = true): Model
     {
+        $this->getQuery()->ensureCanCreateOrFirst();
+
         if (is_null($instance = (clone $this)->where($attributes)->first())) {
             if (is_null($instance = $this->related->where($attributes)->first())) {
                 $instance = $this->createOrFirst($attributes, $values, $joining, $touch);
@@ -620,6 +622,8 @@ public function firstOrCreate(array $attributes = [], Closure|array $values = []
      */
     public function createOrFirst(array $attributes = [], Closure|array $values = [], array $joining = [], bool $touch = true): Model
     {
+        $this->getQuery()->ensureCanCreateOrFirst();
+
         try {
             return $this->getQuery()->withSavepointIfNeeded(fn () => $this->create(array_merge($attributes, value($values)), $joining, $touch));
         } catch (UniqueConstraintViolationException $exception) {

src/database/src/Eloquent/Relations/HasOneOrMany.php

@@ -240,6 +240,8 @@ public function firstOrNew(array $attributes = [], Closure|array $values = []):
      */
     public function firstOrCreate(array $attributes = [], Closure|array $values = []): Model
     {
+        $this->getQuery()->ensureCanCreateOrFirst();
+
         if (is_null($instance = (clone $this)->where($attributes)->first())) {
             $instance = $this->createOrFirst($attributes, $values);
         }
@@ -254,6 +256,8 @@ public function firstOrCreate(array $attributes = [], Closure|array $values = []
      */
     public function createOrFirst(array $attributes = [], Closure|array $values = []): Model
     {
+        $this->getQuery()->ensureCanCreateOrFirst();
+
         try {
             return $this->getQuery()->withSavepointIfNeeded(fn () => $this->create(array_merge($attributes, value($values))));
         } catch (UniqueConstraintViolationException $e) {

src/database/src/Eloquent/Relations/HasOneOrManyThrough.php

@@ -205,6 +205,8 @@ public function firstOrNew(array $attributes = [], array $values = []): Model
      */
     public function firstOrCreate(array $attributes = [], Closure|array $values = []): Model
     {
+        $this->getQuery()->ensureCanCreateOrFirst();
+
         if (! is_null($instance = (clone $this)->where($attributes)->first())) {
             return $instance;
         }
@@ -219,6 +221,8 @@ public function firstOrCreate(array $attributes = [], Closure|array $values = []
      */
     public function createOrFirst(array $attributes = [], Closure|array $values = []): Model
     {
+        $this->getQuery()->ensureCanCreateOrFirst();
+
         try {
             return $this->getQuery()->withSavepointIfNeeded(fn () => $this->create(array_merge($attributes, value($values))));
         } catch (UniqueConstraintViolationException $exception) {

src/database/src/Migrations/DatabaseMigrationRepository.php

@@ -40,7 +40,9 @@ public function getRan(): array
     /**
      * Get the list of migrations.
      *
-     * @return object{id: int, migration: string, batch: int}[]
+     * Driver-owned migration schemas may omit id and return numeric-string batches.
+     *
+     * @return object{migration: string, batch: int|numeric-string}[]
      */
     public function getMigrations(int $steps): array
     {
@@ -56,7 +58,7 @@ public function getMigrations(int $steps): array
     /**
      * Get the list of the migrations by batch number.
      *
-     * @return object{id: int, migration: string, batch: int}[]
+     * @return object{migration: string, batch: int|numeric-string}[]
      */
     public function getMigrationsByBatch(int $batch): array
     {
@@ -70,7 +72,7 @@ public function getMigrationsByBatch(int $batch): array
     /**
      * Get the last migration batch.
      *
-     * @return object{id: int, migration: string, batch: int}[]
+     * @return object{migration: string, batch: int|numeric-string}[]
      */
     public function getLast(): array
     {
@@ -82,7 +84,7 @@ public function getLast(): array
     /**
      * Get the completed migrations with their batch numbers.
      *
-     * @return array<string, int>
+     * @return array<string, int|numeric-string>
      */
     public function getMigrationBatches(): array
     {
@@ -105,7 +107,7 @@ public function log(string $file, int $batch): void
     /**
      * Remove a migration from the log.
      *
-     * @param object{id?: int, migration: string, batch?: int} $migration
+     * @param object{migration: string} $migration
      */
     public function delete(object $migration): void
     {

src/database/src/Migrations/MigrationRepositoryInterface.php

@@ -16,28 +16,30 @@ public function getRan(): array;
     /**
      * Get the list of migrations.
      *
-     * @return object{id: int, migration: string, batch: int}[]
+     * Driver-owned migration schemas may omit id and return numeric-string batches.
+     *
+     * @return object{migration: string, batch: int|numeric-string}[]
      */
     public function getMigrations(int $steps): array;
 
     /**
      * Get the list of the migrations by batch.
      *
-     * @return object{id: int, migration: string, batch: int}[]
+     * @return object{migration: string, batch: int|numeric-string}[]
      */
     public function getMigrationsByBatch(int $batch): array;
 
     /**
      * Get the last migration batch.
      *
-     * @return object{id: int, migration: string, batch: int}[]
+     * @return object{migration: string, batch: int|numeric-string}[]
      */
     public function getLast(): array;
 
     /**
      * Get the completed migrations with their batch numbers.
      *
-     * @return array<string, int>
+     * @return array<string, int|numeric-string>
      */
     public function getMigrationBatches(): array;
 
@@ -49,7 +51,7 @@ public function log(string $file, int $batch): void;
     /**
      * Remove a migration from the log.
      *
-     * @param object{id?: int, migration: string, batch?: int} $migration
+     * @param object{migration: string} $migration
      */
     public function delete(object $migration): void;
 

src/database/src/Migrations/Migrator.php

@@ -265,7 +265,7 @@ public function rollback(array|string $paths = [], array $options = []): array
      * Get the migrations for a rollback operation.
      *
      * @param array<string, mixed> $options
-     * @return object{id: int, migration: string, batch: int}[]
+     * @return object{migration: string, batch: int|numeric-string}[]
      */
     protected function getMigrationsForRollback(array $options): array
     {
@@ -283,6 +283,7 @@ protected function getMigrationsForRollback(array $options): array
     /**
      * Rollback the given migrations.
      *
+     * @param object{migration: string}[] $migrations
      * @param string|string[] $paths
      * @param array<string, mixed> $options
      * @return string[]