T13947 model interface

CHANGELOG-4.0.md

@@ -1,17 +1,19 @@
 # [4.0.0-alpha.5](https://github.com/phalcon/cphalcon/releases/tag/v4.0.0-alpha.5) (2019-xx-xx)
+
 ## Added
 - Added `Phalcon\Cli\Router\Route::setDescription()` to sets the route's description [#13936](https://github.com/phalcon/cphalcon/pull/13936)
 - Added `Phalcon\Cli\Router\Route::getDescription()` returns the route's description [#13936](https://github.com/phalcon/cphalcon/pull/13936)
 
 ## Changed
-- Refactored `Phalcon\Events\Manager` to only use `SplPriorityQueue` to store events.
-- `Phalcon\Translate\InterpolatorInterface` now only accepts placeholder arrays.
-- `Phalcon\Dispatcher::forward()` and `Phalcon\Dispatcher::setParams()` now require an array as a parameter.
-- CLI Routes with bad classnames (eg. `MyApp\\Tasks\\`) now throw an exception instead of suppressing the error.
-- Refacted `Phalcon\Mvc\Collection\Behavior\SoftDelete` and `Phalcon\Mvc\Model\Behavior\SoftDelete`.
+- Refactored `Phalcon\Events\Manager` to only use `SplPriorityQueue` to store events. [#13924](https://github.com/phalcon/cphalcon/pull/13924)
+- `Phalcon\Translate\InterpolatorInterface` now only accepts placeholder arrays. [#13939](https://github.com/phalcon/cphalcon/pull/13939)
+- `Phalcon\Dispatcher::forward()` and `Phalcon\Dispatcher::setParams()` now require an array as a parameter. [#13935](https://github.com/phalcon/cphalcon/pull/13935)
+- CLI Routes with bad class names (eg. `MyApp\\Tasks\\`) now throw an exception instead of suppressing the error. [#13936](https://github.com/phalcon/cphalcon/pull/13936)
+- Refacted `Phalcon\Mvc\Collection\Behavior\SoftDelete` and `Phalcon\Mvc\Model\Behavior\SoftDelete`. [#13930](https://github.com/phalcon/cphalcon/pull/13930)
 
 ## Fixed
-- Fixed `Mvc\Collection::isInitialized()` now works as intended.
+- Fixed `Mvc\Collection::isInitialized()` now works as intended. [#13931](https://github.com/phalcon/cphalcon/pull/13931)
+- Fixed `Mvc\Model` and `Mvc\ModelInterface` `findFirst` to return `ModelInterface` or `bool [#13947](https://github.com/phalcon/cphalcon/issues/13947)
 
 ## Removed
 - Removed `arrayHelpers` property from the Volt compiler. [#13925](https://github.com/phalcon/cphalcon/pull/13925)

phalcon/Mvc/Model.zep

@@ -1359,7 +1359,7 @@ abstract class Model implements EntityInterface, ModelInterface, ResultInterface
      *
      * @param string|array parameters
      */
-    public static function findFirst(var parameters = null) -> <ModelInterface>
+    public static function findFirst(var parameters = null) -> <ModelInterface> | bool
     {
         var params, query;
 

phalcon/Mvc/ModelInterface.zep

@@ -98,7 +98,7 @@ interface ModelInterface
      *
      * @param array parameters
      */
-    public static function findFirst(parameters = null) -> <ModelInterface>;
+    public static function findFirst(parameters = null) -> <ModelInterface> | bool;
 
     /**
      * Fires an event, implicitly calls behaviors and listeners in the events

tests/_data/fixtures/models/RobotsExtended.php

@@ -0,0 +1,45 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * This file is part of the Phalcon Framework.
+ *
+ * (c) Phalcon Team <team@phalconphp.com>
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+namespace Phalcon\Test\Models;
+
+use Phalcon\Mvc\ModelInterface;
+
+/**
+ * Class RobotsExtended
+ *
+ * @package Phalcon\Test\Models
+ */
+class RobotsExtended extends Robots
+{
+    /**
+     * @param null $parameters
+     *
+     * @return ModelInterface|false
+     */
+    public static function findFirst($parameters = null)
+    {
+        if (is_string($parameters)) {
+            return parent::findFirstById($parameters);
+        }
+
+        return parent::findFirst($parameters);
+    }
+
+    /**
+     * @return string
+     */
+    public function getSource(): string
+    {
+        return 'robots';
+    }
+}

tests/integration/Mvc/Model/FindFirstCest.php

@@ -16,6 +16,7 @@
 use Phalcon\Mvc\Model\Exception;
 use Phalcon\Test\Fixtures\Traits\DiTrait;
 use Phalcon\Test\Models\Robots;
+use Phalcon\Test\Models\RobotsExtended;
 
 /**
  * Class FindFirstCest
@@ -52,6 +53,29 @@ public function mvcModelFindFirst(IntegrationTester $I)
         $I->assertInstanceOf($class, $robot);
     }
 
+    /**
+     * Tests Phalcon\Mvc\Model :: findFirst() - extended
+     *
+     * @param IntegrationTester $I
+     *
+     * @author Phalcon Team <team@phalconphp.com>
+     * @since  2018-11-13
+     */
+    public function mvcModelFindFirstExtended(IntegrationTester $I)
+    {
+        $I->wantToTest('Mvc\Model - findFirst() - extended');
+        $this->setNewFactoryDefault();
+        $this->setDiMysql();
+
+        $robot = RobotsExtended::findFirst(1);
+        $class = RobotsExtended::class;
+        $I->assertInstanceOf($class, $robot);
+        $I->assertEquals(1, $robot->id);
+
+        $robot = RobotsExtended::findFirst(0);
+        $I->assertFalse($robot);
+    }
+
     /**
      * Tests Phalcon\Mvc\Model :: findFirst() - exception
      *