add types to ConditionalProxy (#113)

* add types to ConditionalProxy

* Override conditional query method return type

* use better type template name

Author: mringler

src/Propel/Runtime/ActiveQuery/Criteria.php

@@ -393,7 +393,7 @@ class Criteria
     protected CombineOperatorManager $filterOperatorManager;
 
     /**
-     * @var \Propel\Runtime\Util\PropelConditionalProxy|null
+     * @var \Propel\Runtime\Util\PropelConditionalProxy<static>|null
      */
     protected $conditionalProxy;
 
@@ -2273,15 +2273,20 @@ public function _and()
      *
      * @param mixed $cond Casts to bool for variable evaluation
      *
-     * @return \Propel\Runtime\ActiveQuery\Criteria|\Propel\Runtime\Util\PropelConditionalProxy
+     * @return static Actual return is static|PropelConditionalProxy<static>,
+     *                 but the proxy is transparent (delegates via __call),
+     *                 so we annotate as static for IDE/DX purposes.
      */
     public function _if($cond)
     {
         $cond = (bool)$cond; // Intentionally not typing the param to allow for evaluation inside this function
 
         $this->conditionalProxy = new PropelConditionalProxy($this, $cond, $this->conditionalProxy);
 
-        return $this->conditionalProxy->getCriteriaOrProxy();
+        /** @var static $queryOrProxy */
+        $queryOrProxy = $this->conditionalProxy->getCriteriaOrProxy();
+
+        return $queryOrProxy;
     }
 
     /**
@@ -2292,7 +2297,9 @@ public function _if($cond)
      *
      * @throws \Propel\Runtime\Exception\LogicException
      *
-     * @return \Propel\Runtime\ActiveQuery\Criteria|\Propel\Runtime\Util\PropelConditionalProxy
+     * @return static Actual return is static|PropelConditionalProxy<static>,
+     *                 but the proxy is transparent (delegates via __call),
+     *                 so we annotate as static for IDE/DX purposes.
      */
     public function _elseif($cond)
     {
@@ -2301,8 +2308,10 @@ public function _elseif($cond)
         if (!$this->conditionalProxy) {
             throw new LogicException(__METHOD__ . ' must be called after _if()');
         }
+        /** @var static $queryOrProxy */
+        $queryOrProxy = $this->conditionalProxy->_elseif($cond);
 
-        return $this->conditionalProxy->_elseif($cond);
+        return $queryOrProxy;
     }
 
     /**
@@ -2311,15 +2320,19 @@ public function _elseif($cond)
      *
      * @throws \Propel\Runtime\Exception\LogicException
      *
-     * @return \Propel\Runtime\ActiveQuery\Criteria|\Propel\Runtime\Util\PropelConditionalProxy
+     * @return static Actual return is static|PropelConditionalProxy<static>,
+     *                 but the proxy is transparent (delegates via __call),
+     *                 so we annotate as static for IDE/DX purposes.
      */
     public function _else()
     {
         if (!$this->conditionalProxy) {
             throw new LogicException(__METHOD__ . ' must be called after _if()');
         }
+        /** @var static $queryOrProxy */
+        $queryOrProxy = $this->conditionalProxy->_else();
 
-        return $this->conditionalProxy->_else();
+        return $queryOrProxy;
     }
 
     /**
@@ -2328,7 +2341,9 @@ public function _else()
      *
      * @throws \Propel\Runtime\Exception\LogicException
      *
-     * @return \Propel\Runtime\ActiveQuery\Criteria|\Propel\Runtime\Util\PropelConditionalProxy
+     * @return static Actual return is static|PropelConditionalProxy<static>,
+     *                 but the proxy is transparent (delegates via __call),
+     *                 so we annotate as static for IDE/DX purposes.
      */
     public function _endif()
     {
@@ -2337,13 +2352,10 @@ public function _endif()
         }
 
         $this->conditionalProxy = $this->conditionalProxy->getParentProxy();
+        /** @var static $queryOrNestedProxy */
+        $queryOrNestedProxy = $this->conditionalProxy?->getCriteriaOrProxy() ?? $this;
 
-        if ($this->conditionalProxy) {
-            return $this->conditionalProxy->getCriteriaOrProxy();
-        }
-
-        // reached last level
-        return $this;
+        return $queryOrNestedProxy;
     }
 
     /**

src/Propel/Runtime/Util/PropelConditionalProxy.php

@@ -26,16 +26,17 @@
  *     ->doOtherStuff() // executed
  *   ->_endif(); // returns $c
  * @see Criteria
+ * @template QueryClass of \Propel\Runtime\ActiveQuery\Criteria
  */
 class PropelConditionalProxy
 {
     /**
-     * @var \Propel\Runtime\ActiveQuery\Criteria
+     * @var QueryClass
      */
     protected $criteria;
 
     /**
-     * @var \Propel\Runtime\Util\PropelConditionalProxy|null
+     * @var \Propel\Runtime\Util\PropelConditionalProxy<QueryClass>|null
      */
     protected $parent;
 
@@ -55,22 +56,18 @@ class PropelConditionalProxy
     protected $parentState;
 
     /**
-     * @param \Propel\Runtime\ActiveQuery\Criteria $criteria
+     * @param QueryClass $criteria
      * @param mixed $cond
-     * @param self|null $proxy
+     * @param \Propel\Runtime\Util\PropelConditionalProxy<QueryClass>|null $proxy
      */
-    public function __construct(Criteria $criteria, $cond, ?self $proxy = null)
+    public function __construct(Criteria $criteria, $cond, ?PropelConditionalProxy $proxy = null)
     {
         $this->criteria = $criteria;
         $this->wasTrue = false;
         $this->setConditionalState($cond);
         $this->parent = $proxy;
 
-        if ($proxy === null) {
-            $this->parentState = true;
-        } else {
-            $this->parentState = $proxy->getConditionalState();
-        }
+        $this->parentState = $proxy?->getConditionalState() ?? true;
     }
 
     /**
@@ -79,12 +76,10 @@ public function __construct(Criteria $criteria, $cond, ?self $proxy = null)
      *
      * @param mixed $cond Casts to bool for variable evaluation
      *
-     * @return \Propel\Runtime\ActiveQuery\Criteria|\Propel\Runtime\Util\PropelConditionalProxy
+     * @return QueryClass|\Propel\Runtime\Util\PropelConditionalProxy<QueryClass>
      */
     public function _if($cond)
     {
-        $cond = (bool)$cond; // Intentionally not typing the param to allow for evaluation inside this function
-
         return $this->criteria->_if($cond);
     }
 
@@ -93,7 +88,7 @@ public function _if($cond)
      *
      * @param mixed $cond Casts to bool for variable evaluation
      *
-     * @return $this|\Propel\Runtime\ActiveQuery\Criteria
+     * @return $this|QueryClass
      */
     public function _elseif($cond)
     {
@@ -105,7 +100,7 @@ public function _elseif($cond)
     /**
      * Allows for conditional statements in a fluid interface.
      *
-     * @return $this|\Propel\Runtime\ActiveQuery\Criteria
+     * @return $this|QueryClass
      */
     public function _else()
     {
@@ -116,7 +111,7 @@ public function _else()
      * Returns the parent object
      * Allows for conditional statements in a fluid interface.
      *
-     * @return \Propel\Runtime\ActiveQuery\Criteria|\Propel\Runtime\Util\PropelConditionalProxy
+     * @return QueryClass|\Propel\Runtime\Util\PropelConditionalProxy<QueryClass>
      */
     public function _endif()
     {
@@ -136,7 +131,7 @@ protected function getConditionalState(): bool
     /**
      * @param mixed $cond
      *
-     * @return $this|\Propel\Runtime\ActiveQuery\Criteria
+     * @return $this|QueryClass
      */
     protected function setConditionalState($cond)
     {
@@ -147,23 +142,21 @@ protected function setConditionalState($cond)
     }
 
     /**
-     * @return self|null
+     * @return self<QueryClass>|null
      */
     public function getParentProxy(): ?self
     {
         return $this->parent;
     }
 
     /**
-     * @return $this|\Propel\Runtime\ActiveQuery\Criteria
+     * @return $this|QueryClass
      */
     public function getCriteriaOrProxy()
     {
-        if ($this->state && $this->parentState) {
-            return $this->criteria;
-        }
-
-        return $this;
+        return $this->state && $this->parentState
+            ? $this->criteria
+            : $this;
     }
 
     /**