Release 3.5.1

Author: jturbide

CHANGELOG.md

@@ -15,6 +15,15 @@ history, the old changelog, and committed file changes. Older Zemit-era entries
 are summarized where the commit history is too granular to be useful as
 release notes.
 
+## 3.5.1 - 2026-06-19
+
+### Fixed
+
+- Fixed controller model inference so PHP built-in classes such as `Error` are
+  not treated as loadable Phalcon models, and `loadModel()` now fails with a
+  clear PhalconKit service exception before delegating invalid model names to
+  Phalcon's models manager.
+
 ## 3.5.0 - 2026-06-18
 
 ### Changed

src/Mvc/Controller/Traits/Model.php

@@ -132,7 +132,7 @@ public function getModelNameFromController(?array $namespaces = null, string $ne
             )
         );
 
-        if (class_exists($model)) {
+        if (class_exists($model) && is_subclass_of($model, ModelInterface::class)) {
             return $model;
         }
 
@@ -169,10 +169,21 @@ public function getControllerName(): string
      * @param string|null $modelName The name of the model to load. Default is null and will use $this->getModelName().
      *
      * @return ModelInterface The loaded model.
+     *
+     * @throws ServiceException When no model can be resolved or the resolved
+     *     class does not implement Phalcon's model contract.
      */
     public function loadModel(?string $modelName = null): ModelInterface
     {
-        $modelName ??= $this->getModelName() ?? '';
+        $modelName ??= $this->getModelName();
+        if (!$modelName || !is_a($modelName, ModelInterface::class, true)) {
+            throw new ServiceException(sprintf(
+                'Unable to load controller model "%s": expected a class implementing "%s".',
+                $modelName ?: '(none)',
+                ModelInterface::class
+            ));
+        }
+
         return $this->modelsManager->load($modelName);
     }
 

src/Support/Version.php

@@ -40,6 +40,6 @@ class Version extends \Phalcon\Support\Version
     #[\Override]
     protected function getVersion(): array
     {
-        return [3, 5, 0, 4, 0];
+        return [3, 5, 1, 4, 0];
     }
 }

tests/Unit/Mvc/Controller/Traits/Fixtures/Models/Error.php

@@ -0,0 +1,20 @@
+<?php
+
+/**
+ * This file is part of the Phalcon Kit.
+ *
+ * (c) Phalcon Kit Team
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace PhalconKit\Tests\Unit\Mvc\Controller\Traits\Fixtures\Models;
+
+use Phalcon\Mvc\Model;
+
+final class Error extends Model
+{
+}

tests/Unit/Mvc/Controller/Traits/ModelTraitTest.php

@@ -18,13 +18,53 @@
 use PhalconKit\Exception\ServiceException;
 use PhalconKit\Mvc\Controller\Restful;
 use PhalconKit\Tests\Unit\AbstractUnit;
+use PhalconKit\Tests\Unit\Mvc\Controller\Traits\Fixtures\Models\Error as ErrorModel;
 use PhalconKit\Tests\Unit\Mvc\Controller\Traits\Fixtures\ModelColumnAlternateModel;
 use PhalconKit\Tests\Unit\Mvc\Controller\Traits\Fixtures\ModelColumnMappedModel;
 use PhalconKit\Tests\Unit\Mvc\Controller\Traits\Fixtures\ModelColumnMetadataModel;
 use PhalconKit\Tests\Unit\Mvc\Model\Fixtures\FakeMetaData;
 
 class ModelTraitTest extends AbstractUnit
 {
+    public function testModelNameInferenceIgnoresNonModelGlobalClasses(): void
+    {
+        $controller = $this->newControllerNamed('Error');
+        $controller->setModelNamespaces([]);
+
+        $this->assertNull($controller->getModelNameFromController());
+    }
+
+    public function testModelNameInferenceResolvesNamespacedModelAfterGlobalClassCollision(): void
+    {
+        $controller = $this->newControllerNamed('Error');
+        $controller->setModelNamespaces([
+            substr(ErrorModel::class, 0, -strlen('Error')) => __DIR__ . '/Fixtures/Models/',
+        ]);
+
+        $this->assertSame(ErrorModel::class, $controller->getModelNameFromController());
+    }
+
+    public function testLoadModelRejectsMissingOrNonModelClassBeforeModelsManagerLoad(): void
+    {
+        $controller = $this->newControllerNamed('Error');
+        $controller->setModelName('Error');
+
+        $this->expectException(ServiceException::class);
+        $this->expectExceptionMessage(
+            'Unable to load controller model "Error": expected a class implementing "Phalcon\Mvc\ModelInterface".'
+        );
+
+        $controller->loadModel();
+    }
+
+    public function testLoadModelAcceptsNamespacedModelAfterGlobalClassCollision(): void
+    {
+        $controller = $this->newControllerNamed('Error');
+        $controller->setModelName(ErrorModel::class);
+
+        $this->assertInstanceOf(ErrorModel::class, $controller->loadModel());
+    }
+
     public function testGetModelNamespacesRejectsInvalidLoaderService(): void
     {
         $controller = new class extends Restful {
@@ -142,4 +182,33 @@ public function loadModel(?string $modelName = null): ModelInterface
 
         return $controller;
     }
+
+    private function newControllerNamed(string $controllerName): Restful
+    {
+        $controller = new class extends Restful {
+            public string $controllerName = '';
+
+            /**
+             * Disable normal REST initialization for this trait-focused test.
+             */
+            public function initialize(): void
+            {
+            }
+
+            public function getControllerName(): string
+            {
+                return $this->controllerName;
+            }
+        };
+
+        $di = $this->di;
+        if ($di === null) {
+            self::fail('DI container was not initialized.');
+        }
+
+        $controller->setDI($di);
+        $controller->controllerName = $controllerName;
+
+        return $controller;
+    }
 }

tests/Unit/Support/VersionTest.php

@@ -40,7 +40,7 @@ public function testVersion(): void
         $this->assertEquals($this->bootstrap->config->path('phalcon.version'), $phalconVersion->get());
 
         // Test version->get()
-        $this->assertSame('3.5.0', $version->get());
+        $this->assertSame('3.5.1', $version->get());
         $this->assertNotEmpty($version->get());
         $this->assertIsString($version->get());