WIP towards stricter types

Author: ildyria

phpstan.neon

@@ -3,16 +3,11 @@ includes:
 	- vendor/lychee-org/phpstan-lychee/phpstan.neon
 
 parameters:
-	level: 3
+	level: 2
 	paths:
 		- src
 	excludePaths:
 	stubFiles:
 	ignoreErrors:
 		# - identifier: missingType.generics
-		- '#Interface must be located in "Contract" or "Contracts" namespace#'
-		- '#Dynamic call to static method Kalnoy\\Nestedset\\QueryBuilder<.*>::select\(\).#'
-		- '#Dynamic call to static method Kalnoy\\Nestedset\\QueryBuilder<.*>::from\(\).#'
-		# - '#Dynamic call to static method Kalnoy\\Nestedset\\QueryBuilder<.*>::whereRaw\(\).#'
-		- '#Dynamic call to static method Kalnoy\\Nestedset\\QueryBuilder<.*>::whereNested\(\).#'
-		- '#Dynamic call to static method Kalnoy\\Nestedset\\QueryBuilder<.*>::whereIn\(\).#'
+		- '#Dynamic call to static method Kalnoy\\Nestedset\\QueryBuilder<Tmodel of Illuminate\\Database\\Eloquent\\Model>::whereRaw\(\).#'

src/AncestorsRelation.php

@@ -3,17 +3,17 @@
 namespace Kalnoy\Nestedset;
 
 use Illuminate\Database\Eloquent\Model;
+use Kalnoy\Nestedset\Contracts\Node;
+use Kalnoy\Nestedset\Contracts\NodeQueryBuilder;
 
 /**
  * @template Tmodel of Model
  *
- * @phpstan-type NodeModel Node<Tmodel>&Tmodel
- *
- * @disregard P1037
+ * @phpstan-type NodeModel \Kalnoy\Nestedset\Contracts\Node<Tmodel>&Tmodel
  *
  * @extends BaseRelation<Tmodel>
  */
-class AncestorsRelation extends BaseRelation
+final class AncestorsRelation extends BaseRelation
 {
 	/**
 	 * Set the base constraints on the relation query.
@@ -36,13 +36,13 @@ public function addConstraints()
 	 *
 	 * @return bool
 	 */
-	protected function matches(Model $model, $related): bool
+	protected function matches(Node $model, Node $related): bool
 	{
 		return $related->isAncestorOf($model);
 	}
 
 	/**
-	 * @param QueryBuilder<Tmodel> $query
+	 * @param NodeQueryBuilder<Tmodel> $query
 	 * @param NodeModel            $model
 	 *
 	 * @return void
@@ -57,6 +57,7 @@ protected function addEagerConstraint($query, $model)
 	 */
 	protected function relationExistenceCondition(string $hash, string $table, string $lft, string $rgt): string
 	{
+		/** @disregard P1013 */
 		$key = $this->getBaseQuery()->getGrammar()->wrap($this->parent->getKeyName());
 
 		return "{$table}.{$rgt} between {$hash}.{$lft} and {$hash}.{$rgt} and $table.$key <> $hash.$key";

src/BaseRelation.php

@@ -7,23 +7,23 @@
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\Relation;
 use Illuminate\Database\Query\Builder;
+use Kalnoy\Nestedset\Contracts\Node;
+use Kalnoy\Nestedset\Contracts\NodeQueryBuilder;
+use Kalnoy\Nestedset\Contracts\NestedSetCollection;
 
 /**
  * @template Tmodel of Model
  *
- * @phpstan-type NodeModel Node<Tmodel>&Tmodel
- *
- * @extends Relation<NodeModel,NodeModel,EloquentCollection<int,NodeModel>>
+ * @phpstan-type NodeModel  \Kalnoy\Nestedset\Contracts\Node<Tmodel>&Model
+ * @extends Relation<NodeModel,NodeModel,EloquentCollection<int,Node<Tmodel>>>
  *
  * @property NodeModel $related
  * @property NodeModel $parent
- *
- * @method NodeModel getParent()
  */
-abstract class BaseRelation extends Relation
+abstract class BaseRelation extends Relation // @phpstan-ignore generics.notSubtype (Phpstan does not recognise the require-extend on the interface)
 {
 	/**
-	 * @var QueryBuilder<Tmodel>
+	 * @var NodeQueryBuilder<Tmodel>
 	 */
 	protected $query;
 
@@ -60,10 +60,10 @@ public function __construct(QueryBuilder $builder, Model $model)
 	 *
 	 * @return bool
 	 */
-	abstract protected function matches(Model&Node $model, Node $related): bool;
+	abstract protected function matches(Node $model, Node $related): bool;
 
 	/**
-	 * @param QueryBuilder<Tmodel> $query
+	 * @param NodeQueryBuilder<Tmodel> $query
 	 * @param NodeModel            $model
 	 *
 	 * @return void
@@ -90,6 +90,7 @@ abstract protected function relationExistenceCondition(string $hash, string $tab
 	public function getRelationExistenceQuery(EloquentBuilder $query, EloquentBuilder $parentQuery,
 		$columns = ['*'],
 	) {
+		/** @disregard P1006 */
 		$query = $this->getParent()->replicate()->newScopedQuery()->select($columns);
 
 		$table = $query->getModel()->getTable();
@@ -106,7 +107,7 @@ public function getRelationExistenceQuery(EloquentBuilder $query, EloquentBuilde
 			$grammar->wrap($this->parent->getLftName()),
 			$grammar->wrap($this->parent->getRgtName()));
 
-		return $query->whereRaw($condition); /** @phpstan-ignore-line */
+		return $query->whereRaw($condition);
 	}
 
 	/**
@@ -137,11 +138,11 @@ public function getRelationCountHash($incrementJoinCount = true)
 	/**
 	 * Get the results of the relationship.
 	 *
-	 * @return Collection<NodeModel>
+	 * @return NestedSetCollection<NodeModel>
 	 */
 	public function getResults()
 	{
-		/** @var Collection<NodeModel> */
+		/** @disregard P1013 */
 		$result = $this->query->get();
 
 		return $result;
@@ -164,6 +165,7 @@ public function addEagerConstraints(array $models)
 		$this->query->whereNested(function (Builder $inner) use ($models) {
 			// We will use this query in order to apply constraints to the
 			// base query builder
+			/** @disregard P1013 */
 			$outer = $this->parent->newQuery()->setQuery($inner);
 
 			foreach ($models as $model) {
@@ -187,6 +189,7 @@ public function match(array $models, EloquentCollection $results, $relation)
 			/** @disregard P1006 */
 			$related = $this->matchForModel($model, $results);
 
+			/** @disregard P1013 */
 			$model->setRelation($relation, $related);
 		}
 
@@ -197,16 +200,16 @@ public function match(array $models, EloquentCollection $results, $relation)
 	 * @param NodeModel                         $model
 	 * @param EloquentCollection<int,NodeModel> $results
 	 *
-	 * @return Collection<Tmodel>
+	 * @return NestedSetCollection<Tmodel>
 	 */
 	protected function matchForModel(Model $model, EloquentCollection $results)
 	{
-		/** @var Collection<Tmodel> */
 		$result = $this->related->newCollection();
 
 		foreach ($results as $related) {
 			/** @disregard P1006 */
 			if ($this->matches($model, $related)) {
+				/** @disregard P1013 */
 				$result->push($related);
 			}
 		}

src/Collection.php

@@ -4,15 +4,18 @@
 
 use Illuminate\Database\Eloquent\Collection as EloquentCollection;
 use Illuminate\Database\Eloquent\Model;
+use Kalnoy\Nestedset\Contracts\NestedSetCollection;
+use Kalnoy\Nestedset\Exceptions\NestedSetException;
 
 /**
+ * 
  * @template Tmodel of Model
  *
- * @phpstan-type NodeModel Node<Tmodel>&Tmodel
+ * @phpstan-type NodeModel \Kalnoy\Nestedset\Contracts\Node<Tmodel>
  *
  * @extends EloquentCollection<array-key,NodeModel>
  */
-final class Collection extends EloquentCollection
+final class Collection extends EloquentCollection implements NestedSetCollection
 {
 	/**
 	 * Fill `parent` and `children` relationships for every node in the collection.
@@ -34,16 +37,19 @@ public function linkNodes()
 		/** @var NodeModel $node */
 		foreach ($this->items as $node) {
 			if ($node->getParentId() === null) {
+				/** @disregard */
 				$node->setRelation('parent', null);
 			}
 
 			/** @var array<int,NodeModel> */ 
-			$children = $groupedNodes->get($node->getKey(), []); /** @phpstan-ignore varTag.type */
+			$children = $groupedNodes->get($node->getKey(), []);
 
 			foreach ($children as $child) {
+				/** @disregard */
 				$child->setRelation('parent', $node);
 			}
 
+			/** @disregard */
 			$node->setRelation('children', EloquentCollection::make($children));
 		}
 
@@ -61,7 +67,7 @@ public function linkNodes()
 	 *
 	 * @return Collection<Tmodel>
 	 */
-	public function toTree($root = false)
+	public function toTree($root = false): Collection
 	{
 		if ($this->isEmpty()) {
 			return new static();
@@ -131,15 +137,15 @@ public function toFlatTree($root = false): Collection
 		$result = new Collection();
 
 		if ($this->isEmpty()) {
-			return $result; /** @phpstan-ignore-line */
+			return $result;
 		}
 
 		/** @var NodeModel */
 		$first = $this->first();
 		/** @var Collection<NodeModel> */
-		$groupedNodes = $this->groupBy($first->getParentIdName()); /** @phpstan-ignore varTag.type */
+		$groupedNodes = $this->groupBy($first->getParentIdName());
 
-		return $result->flattenTree($groupedNodes, $this->getRootNodeId($root)); /** @phpstan-ignore-line */
+		return $result->flattenTree($groupedNodes, $this->getRootNodeId($root));
 	}
 
 	/**
@@ -153,7 +159,7 @@ public function toFlatTree($root = false): Collection
 	protected function flattenTree(Collection $groupedNodes, $parentId): Collection
 	{
 		/** @var array<int,NodeModel> */
-		$nodes = $groupedNodes->get($parentId, []); /** @phpstan-ignore varTag.type */
+		$nodes = $groupedNodes->get($parentId, []);
 		foreach ($nodes as $node) {
 			$this->push($node);
 

src/Contracts/NestedSetCollection.php

@@ -0,0 +1,47 @@
+<?php
+
+
+namespace Kalnoy\Nestedset\Contracts;
+
+/**
+ * @template Tmodel of \Illuminate\Database\Eloquent\Model
+ *
+ * @phpstan-type NodeModel Node<Tmodel>
+ *
+ * @require-extends \Illuminate\Database\Eloquent\Collection
+ */
+interface NestedSetCollection
+{
+	/**
+	 * Fill `parent` and `children` relationships for every node in the collection.
+	 *
+	 * This will overwrite any previously set relations.
+	 *
+	 * @return $this
+	 */
+	public function linkNodes();
+
+
+	/**
+	 * Build a tree from a list of nodes. Each item will have set children relation.
+	 *
+	 * To successfully build tree "id", "_lft" and "parent_id" keys must present.
+	 *
+	 * If `$root` is provided, the tree will contain only descendants of that node.
+	 *
+	 * @param mixed $root
+	 *
+	 * @return Collection<NodeModel>
+	 */
+	public function toTree($root = false): NestedSetCollection;
+
+	/**
+	 * Build a list of nodes that retain the order that they were pulled from
+	 * the database.
+	 *
+	 * @param bool $root
+	 *
+	 * @return Collection<NodeModel>
+	 */
+	public function toFlatTree($root = false): NestedSetCollection;
+}