Fix empty Phalcon message handling

Author: jturbide

CHANGELOG.md

@@ -15,6 +15,14 @@ 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.1.3 - 2026-06-12
+
+### Fixed
+
+- Fixed REST action failure status resolution so empty
+  `Phalcon\Messages\Messages` collections are treated as no-message failures
+  instead of generic validation failures.
+
 ## 3.1.2 - 2026-06-11
 
 ### Added

src/Modules/Cli/Tasks/DataLifeCycleTask.php

@@ -161,7 +161,7 @@ public function modelsAction(string ...$tables): array
                 $response[$source]['deleted'] += $deleted ? 1 : 0;
 
                 $messages = $record->getMessages();
-                if (!empty($messages)) {
+                if (count($messages) > 0) {
                     $response[$source]['messages'] = array_merge($response[$source]['messages'], $messages);
                 }
             };

src/Mvc/Controller/Traits/RestResponse.php

@@ -16,6 +16,7 @@
 use Phalcon\Http\ResponseInterface;
 use Phalcon\Messages\MessageInterface;
 use Phalcon\Mvc\Dispatcher;
+use Countable;
 use PhalconKit\Http\StatusCode as HttpStatusCode;
 use PhalconKit\Mvc\Controller\Traits\Abstracts\AbstractDebug;
 use PhalconKit\Mvc\Controller\Traits\Abstracts\AbstractInjectable;
@@ -184,7 +185,7 @@ protected function getRestActionFailureStatusCode(
         int $emptyStatusCode = 400,
         int $defaultStatusCode = 422
     ): int {
-        if (empty($messages)) {
+        if (!$this->hasRestActionMessages($messages)) {
             return $emptyStatusCode;
         }
 
@@ -198,6 +199,35 @@ protected function getRestActionFailureStatusCode(
         return $defaultStatusCode;
     }
 
+    /**
+     * Determine whether a REST action failure carried any message payload.
+     *
+     * PHP objects are never empty for `empty()`, even when they implement
+     * `Countable` and contain zero messages. Phalcon validation returns
+     * `Phalcon\Messages\Messages`, so status resolution must check the
+     * collection count instead of relying on PHP object truthiness.
+     */
+    protected function hasRestActionMessages(mixed $messages): bool
+    {
+        if ($messages instanceof Countable) {
+            return count($messages) > 0;
+        }
+
+        if (is_array($messages)) {
+            return count($messages) > 0;
+        }
+
+        if ($messages instanceof \Traversable) {
+            foreach ($messages as $_message) {
+                return true;
+            }
+
+            return false;
+        }
+
+        return (bool) $messages;
+    }
+
     /**
      * Return a normalized REST error response for an action failure.
      *

src/Mvc/Model/Behavior/Position.php

@@ -185,7 +185,7 @@ public function afterSave(ModelInterface $model, string $field, bool $rawSql): v
                             $modelPrimaryKeys,
                         ));
                         $messages = $save->getMessages();
-                        if (!empty($messages)) {
+                        if (count($messages) > 0) {
                             $model->appendMessages($messages, 'afterSave');
                         }
                     }

tests/Unit/Mvc/Controller/Traits/Fixtures/RestResponseControllerDouble.php

@@ -54,4 +54,15 @@ public function exposeRestViewVars(): array
     {
         return $this->getRestViewVars();
     }
+
+    /**
+     * Expose failure status resolution for message payload regression tests.
+     */
+    public function exposeRestActionFailureStatusCode(
+        mixed $messages,
+        int $emptyStatusCode = 400,
+        int $defaultStatusCode = 422
+    ): int {
+        return $this->getRestActionFailureStatusCode($messages, $emptyStatusCode, $defaultStatusCode);
+    }
 }

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

@@ -13,6 +13,8 @@
 
 namespace PhalconKit\Tests\Unit\Mvc\Controller\Traits;
 
+use Phalcon\Messages\Message;
+use Phalcon\Messages\Messages;
 use PhalconKit\Mvc\Controller\Traits\Interfaces\RestResponseInterface;
 use PhalconKit\Tests\Unit\AbstractUnit;
 use PhalconKit\Tests\Unit\Mvc\Controller\Traits\Fixtures\RestResponseControllerDouble;
@@ -84,6 +86,33 @@ public function testRestResponseConstantsMatchPublicInterfaceContract(): void
         }
     }
 
+    public function testRestActionFailureStatusTreatsEmptyPhalconMessagesCollectionAsEmpty(): void
+    {
+        $controller = $this->newController();
+
+        $this->assertSame(400, $controller->exposeRestActionFailureStatusCode(new Messages()));
+    }
+
+    public function testRestActionFailureStatusTreatsPopulatedPhalconMessagesCollectionAsMessages(): void
+    {
+        $controller = $this->newController();
+        $messages = new Messages([
+            new Message('Invalid value'),
+        ]);
+
+        $this->assertSame(422, $controller->exposeRestActionFailureStatusCode($messages));
+    }
+
+    public function testRestActionFailureStatusKeepsExplicitMessageHttpCode(): void
+    {
+        $controller = $this->newController();
+        $messages = new Messages([
+            new Message('Forbidden', code: 403),
+        ]);
+
+        $this->assertSame(403, $controller->exposeRestActionFailureStatusCode($messages));
+    }
+
     private function newController(): RestResponseControllerDouble
     {
         $controller = new RestResponseControllerDouble();