A non-breaking solution for (#45)

lib/Model.php

@@ -1492,25 +1492,6 @@ public function reset_dirty(): void
         $this->__dirty = [];
     }
 
-    /**
-     * A list of valid finder options.
-     *
-     * @var array<string>
-     */
-    public static array $VALID_OPTIONS = [
-        'conditions',
-        'limit',
-        'offset',
-        'order',
-        'select',
-        'joins',
-        'include',
-        'readonly',
-        'group',
-        'from',
-        'having'
-    ];
-
     /**
      * Enables the use of dynamic finders.
      *
@@ -1622,24 +1603,118 @@ public function __call($method, $args)
         throw new ActiveRecordException("Call to undefined method: $method");
     }
 
+    public static function select(string $columns='*'): Relation
+    {
+        $relation = new Relation(get_called_class(), static::$alias_attribute);
+        $relation->select($columns);
+
+        return $relation;
+    }
+
+    /**
+     * @param string|array<string> $joins
+     */
+    public static function joins(string|array $joins): Relation
+    {
+        $relation = new Relation(get_called_class(), static::$alias_attribute);
+        $relation->joins($joins);
+
+        return $relation;
+    }
+
+    public static function order(string $order): Relation
+    {
+        $relation = new Relation(get_called_class(), static::$alias_attribute);
+        $relation->order($order);
+
+        return $relation;
+    }
+
+    public static function group(string $columns): Relation
+    {
+        $relation = new Relation(get_called_class(), static::$alias_attribute);
+        $relation->group($columns);
+
+        return $relation;
+    }
+
+    public static function limit(int $limit): Relation
+    {
+        $relation = new Relation(get_called_class(), static::$alias_attribute);
+        $relation->limit($limit);
+
+        return $relation;
+    }
+
+    public static function offset(int $offset): Relation
+    {
+        $relation = new Relation(get_called_class(), static::$alias_attribute);
+        $relation->offset($offset);
+
+        return $relation;
+    }
+
+    public static function having(string $having): Relation
+    {
+        $relation = new Relation(get_called_class(), static::$alias_attribute);
+        $relation->having($having);
+
+        return $relation;
+    }
+
+    public static function from(string $from): Relation
+    {
+        $relation = new Relation(get_called_class(), static::$alias_attribute);
+        $relation->from($from);
+
+        return $relation;
+    }
+
+    /**
+     * @param string|array<string|mixed> $include
+     */
+    public static function include(string|array $include): Relation
+    {
+        $relation = new Relation(get_called_class(), static::$alias_attribute);
+        $relation->include($include);
+
+        return $relation;
+    }
+
+    /**
+     * @param string|array<string|mixed> $where
+     */
+    public static function where(string|array $where): Relation
+    {
+        $relation = new Relation(get_called_class(), static::$alias_attribute);
+
+        return $relation->where($where);
+    }
+
     /**
-     * Alias for self::find('all').
+     * needle is one of:
      *
-     * @see find
+     * array of primary keys    all([1, 3, 5, 8]) WHERE author_id in (1, 3, 5, 8)
+     * mapping of column names  all(["name"=>"Philip", "publisher"=>"Random House"]) WHERE name=Philip AND publisher=Random House
+     * raw WHERE statement      all(['name = (?) and publisher <> (?)', 'Bill Clinton', 'Random House'])
+     *
+     * @param array<number|mixed|string> $needle An array containing values for the pk
      *
-     * @return array<int,static>
+     * @return array<Model> All the rows that matches query. If no rows match, returns []
      */
-    public static function all(/* ... */): array
+    public static function all(array $needle = []): array
     {
-        /* @phpstan-ignore-next-line */
-        return static::find('all', ...func_get_args());
+        $relation = new Relation(get_called_class(), static::$alias_attribute);
+
+        return $relation->all($needle);
     }
 
     /**
      * Get a count of qualifying records.
      *
      * ```
-     * YourModel::count(['conditions' => 'amount > 3.14159265']);
+     * YourModel::count('amount > 3.14159265');
+     * YourModel::count(['name' => 'Tito', 'author_id' => 1]));
      * ```
      *
      * @see find
@@ -1650,7 +1725,6 @@ public static function count(/* ... */): int
     {
         $args = func_get_args();
         $options = static::extract_and_validate_options($args);
-        $options['select'] = 'COUNT(*)';
 
         if (!empty($args) && !is_null($args[0]) && !empty($args[0])) {
             if (is_hash($args[0])) {
@@ -1660,13 +1734,13 @@ public static function count(/* ... */): int
             }
         }
 
-        $table = static::table();
-        $sql = $table->options_to_sql($options);
-        $values = $sql->get_where_values();
+        $relation = new Relation(get_called_class(), static::$alias_attribute);
 
-        $res = static::connection()->query_and_fetch_one($sql->to_s(), $values);
+        if (0 === count($options)) {
+            $options['conditions'] = [];
+        }
 
-        return $res;
+        return $relation->count($options['conditions']);
     }
 
     /**
@@ -1766,22 +1840,22 @@ public static function last(/* ... */): static|null
      *
      * @throws RecordNotFound if no options are passed or finding by pk and no records matched
      *
-     * @return static|static[]|null
+     * @return Model|Model[]|null
      *
      * The rules for what gets returned are complex, but predictable:
      *
      * /-------------------------------------------------------------------------------------------
      * 	First Argument								Return Type			Example
      * --------------------------------------------------------------------------------------------
-     *	int|string									static				User::find(3);
-     * 	array<string, int|string>					static				User::find(["name"=>"Philip"]);
-     * 	"first"										static|null			User::find("first", ["name"=>"Waldo"]);
-     * 	"last"										static|null			User::find("last", ["name"=>"William"]);
-     *  "all"										static[]			User::find("all", ["name"=>"Stephen"]
-     *  ...int|string								static[]			User::find(1, 3, 5, 8);
-     *  array<int,int|string>						static[]			User::find([1,3,5,8]);
+     *	int|string									Model				User::find(3);
+     * 	array<string, int|string>					Model				User::find(["name"=>"Philip"]);
+     * 	"first"										Model|null			User::find("first", ["name"=>"Waldo"]);
+     * 	"last"										Model|null			User::find("last", ["name"=>"William"]);
+     *  "all"										Model[]			    User::find("all", ["name"=>"Stephen"]
+     *  ...int|string								Model[]			    User::find(1, 3, 5, 8);
+     *  array<int,int|string>						Model[]			    User::find([1,3,5,8]);
      */
-    public static function find(/* $type, $options */): static|array|null
+    public static function find(/* $type, $options */): Model|array|null
     {
         $class = get_called_class();
 
@@ -1791,6 +1865,15 @@ public static function find(/* $type, $options */): static|array|null
         }
         $options = static::extract_and_validate_options($args);
 
+        $relation = new Relation(get_called_class(), static::$alias_attribute);
+
+        foreach (Relation::$VALID_OPTIONS as $key) {
+            if ('conditions'!= $key && array_key_exists($key, $options)) {
+                $relation->$key($options[$key]);
+                unset($options[$key]);
+            }
+        }
+
         $num_args = count($args);
         $single = true;
 
@@ -1801,18 +1884,13 @@ public static function find(/* $type, $options */): static|array|null
                     break;
 
                 case 'last':
-                    if (!array_key_exists('order', $options)) {
-                        $options['order'] = join(' DESC, ', static::table()->pk) . ' DESC';
-                    } else {
-                        $options['order'] = SQLBuilder::reverse_order($options['order']);
-                    }
+                    $relation->last(1);
 
                     // fall thru
-
                     // no break
                 case 'first':
-                    $options['limit'] = 1;
-                    $options['offset'] = 0;
+                    $relation->limit(1);
+                    $relation->offset(0);
                     break;
             }
 
@@ -1831,86 +1909,30 @@ public static function find(/* $type, $options */): static|array|null
             }
         }
 
-        // anything left in $args is a find by pk
-        if ($num_args > 0 && !isset($options['conditions'])) {
-            $list = static::find_by_pk($args, $options, true);
-        } else {
-            $options['mapped_names'] = static::$alias_attribute;
-            $list = static::table()->find($options);
-        }
-
-        return $single ? ($list[0] ?? null) : $list;
-    }
-
-    /**
-     * Will look up a list of primary keys from cache
-     *
-     * @param array<PrimaryKey> $pks An array of primary keys
-     *
-     * @return array<Model>
-     */
-    protected static function get_models_from_cache(array $pks): array
-    {
-        $models = [];
-        $table = static::table();
-
-        foreach ($pks as $pk) {
-            $options = ['conditions' => static::pk_conditions($pk)];
-            $models[] = Cache::get($table->cache_key_for_model($pk), function () use ($table, $options) {
-                $res = $table->find($options);
-
-                return $res ? $res[0] : [];
-            }, $table->cache_model_expire);
-        }
-
-        return array_filter($models);
-    }
-
-    /**
-     * Finder method which will find by a single or array of primary keys for this model.
-     *
-     * @see find
-     *
-     * @param PrimaryKey   $values  An array containing values for the pk
-     * @param array<mixed> $options An options array
-     *
-     * @throws RecordNotFound if a record could not be found
-     *
-     * @return Model|Model[]
-     */
-    public static function find_by_pk(array|string|int|null $values, array $options, bool $forceArray = false): Model|array
-    {
-        $single = !is_array($values) && !$forceArray;
-        if (null === $values) {
-            throw new RecordNotFound("Couldn't find " . get_called_class() . ' without an ID');
-        }
-
-        $table = static::table();
-
-        if ($table->cache_individual_model ?? false) {
-            $pks = is_array($values) ? $values : [$values];
-            $list = static::get_models_from_cache($pks);
-        } else {
-            // int|string|array<int|string>
-            $options['conditions'] = static::pk_conditions($values);
-            $list = $table->find($options);
+        if (is_array($args) && 0 === count($args)) {
+            if (array_key_exists('conditions', $options) && $single) {
+                $args = $options['conditions'];
+                if (!is_array($args)) {
+                    $args = [$args];
+                }
+            } else {
+                $args = $options;
+            }
         }
-        $results = count($list);
 
-        if ($results != ($expected = @count((array) $values))) {
-            $class = get_called_class();
-            if (is_array($values)) {
-                $values = join(',', $values);
+        if ($single) {
+            if (1 === $num_args && is_array($args) && array_is_list($args)) {
+                $args = $args[0];
             }
 
-            if (1 == $expected) {
-                throw new RecordNotFound("Couldn't find $class with ID=$values");
-            }
+            return $relation->whereToBeReplacedByFind($args, true);
+        }
 
-            throw new RecordNotFound("Couldn't find all $class with IDs ($values) (found $results, but was looking for $expected)");
+        if (array_key_exists('conditions', $options)) {
+            $args = $options;
         }
 
-        return $single ? $list[0] : $list;
+        return $relation->all($args);
     }
 
     /**
@@ -1954,12 +1976,12 @@ public static function is_options_hash(mixed $options, bool $throw = true): bool
     {
         if (is_hash($options)) {
             $keys = array_keys($options);
-            $diff = array_diff($keys, self::$VALID_OPTIONS);
+            $diff = array_diff($keys, Relation::$VALID_OPTIONS);
 
             if (!empty($diff) && $throw) {
                 throw new ActiveRecordException('Unknown key(s): ' . join(', ', $diff));
             }
-            $intersect = array_intersect($keys, self::$VALID_OPTIONS);
+            $intersect = array_intersect($keys, Relation::$VALID_OPTIONS);
 
             if (!empty($intersect)) {
                 return true;