progress

phpstan.neon

@@ -9,4 +9,46 @@ parameters:
 	stubFiles:
 	ignoreErrors:
 		- identifier: missingType.generics
-		- '#Interface must be located in "Contract" or "Contracts" namespace#'
+		- '#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\(\).#'
+		# bunch of false positives from Eloquent
+		# ---------------------------------------------------------------------------------------- 
+		- '#Parameter .* \$models .* of method .*::initRelation\(\) should be contravariant with parameter \$models .* of method .*::initRelation\(\)#'
+		- '#Parameter .* \$models .* of method .*::addEagerConstraints\(\) should be contravariant with parameter \$models .* of method .*::addEagerConstraints\(\)#'
+		- '#Parameter .* \$models .* of method .*::match\(\) should be contravariant with parameter \$models .* of method .*::match\(\)#'
+
+		# - '#Method .*::ancestorsOf\(\) should return Illuminate\\Database\\Eloquent\\Collection<.*, .* Illuminate\\Database\\Eloquent\\Model> but returns Illuminate\\Database\\Eloquent\\Collection<int, Illuminate\\Database\\Eloquent\\Model>.#'
+		# - '#Method .*::ancestorsAndSelf\(\) should return Illuminate\\Database\\Eloquent\\Collection<.*, .* Illuminate\\Database\\Eloquent\\Model> but returns Illuminate\\Database\\Eloquent\\Collection<int, Illuminate\\Database\\Eloquent\\Model>.#'
+		# - '#Method .*::descendantsOf\(\) should return Illuminate\\Database\\Eloquent\\Collection<.*, .* Illuminate\\Database\\Eloquent\\Model> but returns Illuminate\\Database\\Eloquent\\Collection<int, Illuminate\\Database\\Eloquent\\Model>.#'
+		# - '#Method .*::descendantsAndSelf\(\) should return Illuminate\\Database\\Eloquent\\Collection<.*, .* Illuminate\\Database\\Eloquent\\Model> but returns Illuminate\\Database\\Eloquent\\Collection<int, Illuminate\\Database\\Eloquent\\Model>.#'
+		# - '#Parameter #1 $query of method Kalnoy\Nestedset\BaseRelation<Tmodel of                    
+        #  Illuminate\Database\Eloquent\Model&Kalnoy\Nestedset\Node>::addEagerConstraint() expects  
+        #  Kalnoy\Nestedset\QueryBuilder, Illuminate\Database\Eloquent\Builder given.#'
+		# - '#Parameter \#1 \$model \(Illuminate\\Database\\Eloquent\\Model&Kalnoy\\Nestedset\\Node\) of method Kalnoy\\Nestedset\\AncestorsRelation::matches\(\) should be contravariant with parameter \$model \(Illuminate\\Database\\Eloquent\\Model\) of method Kalnoy\\Nestedset\\BaseRelation::matches\(\)#'
+		# - '#Parameter \#2 \$related \(Kalnoy\\Nestedset\\Node\) of method Kalnoy\\Nestedset\\AncestorsRelation::matches\(\) should be contravariant with parameter \$related \(mixed\) of method Kalnoy\\Nestedset\\BaseRelation::matches\(\)#'
+		# - '#Parameter \#1 \$models \(array<int, Tmodel>\) of method Kalnoy\\Nestedset\\BaseRelation::initRelation\(\) should be contravariant with parameter \$models \(array\) of method Illuminate\\Database\\Eloquent\\Relations\\Relation<Illuminate\\Database\\Eloquent\\Model>::initRelation\(\)#'
+		# - '#Dynamic call to static method (Illuminate\\Database\\Query\\Builder|Illuminate\\Database\\Eloquent\\(Builder|Relations\\.*))(<.*>)?::from\(\).#'
+		# - '#Dynamic call to static method (Illuminate\\Database\\Query\\Builder|Illuminate\\Database\\Eloquent\\(Builder|Relations\\.*))(<.*>)?::limit\(\).#'
+		# - '#Dynamic call to static method (Illuminate\\Database\\Query\\Builder|Illuminate\\Database\\Eloquent\\(Builder|Relations\\.*))(<.*>)?::offset\(\).#'
+		# - '#Dynamic call to static method (Illuminate\\Database\\Query\\Builder|Illuminate\\Database\\Eloquent\\(Builder|Relations\\.*))(<.*>)?::take\(\).#'
+		# - '#Dynamic call to static method (Illuminate\\Database\\Query\\Builder|Illuminate\\Database\\Eloquent\\(Builder|Relations\\.*))(<.*>)?::truncate\(\).#'
+		# - '#Dynamic call to static method (Illuminate\\Database\\Query\\Builder|Illuminate\\Database\\Eloquent\\(Builder|Relations\\.*))(<.*>)?::insert\(\).#'
+		# - '#Dynamic call to static method (Illuminate\\Database\\Query\\Builder|Illuminate\\Database\\Eloquent\\(Builder|Relations\\.*))(<.*>)?::select\(\).#'
+		# - '#Dynamic call to static method (Illuminate\\Database\\Query\\Builder|Illuminate\\Database\\Eloquent\\(Builder|Relations\\.*))(<.*>)?::orderBy\(\)#'
+		# - '#Dynamic call to static method (Illuminate\\Database\\Query\\Builder|Illuminate\\Database\\Eloquent\\(Builder|Relations\\.*))(<.*>)?::where(Not)?(Null|In|Between|Exists|Column|Year|Month|Day)?\(\).#'
+		# - '#Dynamic call to static method (Illuminate\\Database\\Query\\Builder|Illuminate\\Database\\Eloquent\\(Builder|Relations\\.*))(<.*>)?::delete\(\)#'
+		# - '#Dynamic call to static method (Illuminate\\Database\\Query\\Builder|Illuminate\\Database\\Eloquent\\(Builder|Relations\\.*))(<.*>)?::without\(\)#'
+		# - '#Dynamic call to static method (Illuminate\\Database\\Query\\Builder|Illuminate\\Database\\Eloquent\\(Builder|Relations\\.*))(<.*>)?::with\(\)#'
+		# - '#Dynamic call to static method (Illuminate\\Database\\Query\\Builder|Illuminate\\Database\\Eloquent\\(Builder|Relations\\.*))(<.*>)?::count\(\).#'
+		# - '#Dynamic call to static method (Illuminate\\Database\\Query\\Builder|Illuminate\\Database\\Eloquent\\(Builder|Relations\\.*))(<.*>)?::update\(\).#'
+		# - '#Dynamic call to static method (Illuminate\\Database\\Query\\Builder|Illuminate\\Database\\Eloquent\\(Builder|Relations\\.*))(<.*>)?::inRandomOrder\(\).#'
+		# - '#Dynamic call to static method (Illuminate\\Database\\Query\\Builder|Illuminate\\Database\\Eloquent\\(Builder|Relations\\.*))(<.*>)?::groupBy\(\).#'
+		# - '#Dynamic call to static method (Illuminate\\Database\\Query\\Builder|Illuminate\\Database\\Eloquent\\(Builder|Relations\\.*))(<.*>)?::latest\(\).#'
+		# - '#Dynamic call to static method (Illuminate\\Database\\Query\\Builder|Illuminate\\Database\\Eloquent\\(Builder|Relations\\.*))(<.*>)?::first\(\).#'
+		# - '#Dynamic call to static method (Illuminate\\Database\\Query\\Builder|Illuminate\\Database\\Eloquent\\(Builder|Relations\\.*))(<.*>)?::skip\(\).#'
+		# - '#Call to an undefined method Illuminate\\Database\\Eloquent\\.*::with(Only)?\(\)#'
+		# - '#Call to an undefined method Illuminate\\Database\\Eloquent\\Builder|Illuminate\\Database\\Eloquent\\Relations\\Relation::whereNotNull\(\).#'
+		# - '#Call to protected method asDateTime\(\) of class Illuminate\\Database\\Eloquent\\Model.#'

src/AncestorsRelation.php

@@ -5,7 +5,7 @@
 use Illuminate\Database\Eloquent\Model;
 
 /**
- * @template T
+ * @disregard P1037
  */
 class AncestorsRelation extends BaseRelation
 {
@@ -25,12 +25,12 @@ public function addConstraints()
 	}
 
 	/**
-	 * @param Model $model
-	 * @param       $related
+	 * @param Model&Node $model
+	 * @param Node $related
 	 *
 	 * @return bool
 	 */
-	protected function matches(Model $model, $related)
+	protected function matches(Model $model, $related): bool
 	{
 		return $related->isAncestorOf($model);
 	}

src/BaseRelation.php

@@ -8,6 +8,14 @@
 use Illuminate\Database\Eloquent\Relations\Relation;
 use Illuminate\Database\Query\Builder;
 
+/**
+ * @template Tmodelkey
+ * @template Tmodel of Model&Node<Tmodelkey,Model>
+ * @extends Relation<Tmodel>
+ * @property Tmodel $related
+ * @property Tmodel $parent
+ * @method Tmodel getParent()
+ */
 abstract class BaseRelation extends Relation
 {
 	/**
@@ -43,12 +51,12 @@ public function __construct(QueryBuilder $builder, Model $model)
 	}
 
 	/**
-	 * @param Model $model
-	 * @param       $related
+	 * @param Model&Node $model
+	 * @param Node $related
 	 *
 	 * @return bool
 	 */
-	abstract protected function matches(Model $model, $related);
+	abstract protected function matches(Model&Node $model, Node $related): bool;
 
 	/**
 	 * @param QueryBuilder $query
@@ -71,14 +79,14 @@ abstract protected function relationExistenceCondition(string $hash, string $tab
 	/**
 	 * @param EloquentBuilder $query
 	 * @param EloquentBuilder $parent
-	 * @param string[]        $columns
+	 * @param mixed           $columns
 	 *
-	 * @return mixed
+	 * @return EloquentBuilder
 	 */
 	public function getRelationExistenceQuery(EloquentBuilder $query, EloquentBuilder $parent,
 		$columns = ['*']
 	) {
-		$query = $this->getParent()->replicate()->newScopedQuery()->select($columns);
+		$query = $this->getParent()->replicate()->newScopedQuery()->select($columns); 
 
 		$table = $query->getModel()->getTable();
 
@@ -100,10 +108,10 @@ public function getRelationExistenceQuery(EloquentBuilder $query, EloquentBuilde
 	/**
 	 * Initialize the relation on a set of models.
 	 *
-	 * @param array  $models
+	 * @param array<int,Tmodel>  $models
 	 * @param string $relation
 	 *
-	 * @return array
+	 * @return array<int,Tmodel>
 	 */
 	public function initRelation(array $models, $relation)
 	{
@@ -135,7 +143,7 @@ public function getResults()
 	/**
 	 * Set the constraints for an eager load of the relation.
 	 *
-	 * @param array $models
+	 * @param array<int,Tmodel> $models
 	 *
 	 * @return void
 	 */
@@ -160,11 +168,11 @@ public function addEagerConstraints(array $models)
 	/**
 	 * Match the eagerly loaded results to their parents.
 	 *
-	 * @param array              $models
+	 * @param array<int,Tmodel>              $models
 	 * @param EloquentCollection $results
 	 * @param string             $relation
 	 *
-	 * @return array
+	 * @return array<int,Tmodel>
 	 */
 	public function match(array $models, EloquentCollection $results, $relation)
 	{
@@ -178,15 +186,17 @@ public function match(array $models, EloquentCollection $results, $relation)
 	}
 
 	/**
-	 * @param Model              $model
+	 * @param Tmodel             $model
 	 * @param EloquentCollection $results
 	 *
 	 * @return Collection
 	 */
 	protected function matchForModel(Model $model, EloquentCollection $results)
 	{
+		/** @var Collection<int,Tmodel> */
 		$result = $this->related->newCollection();
 
+		/** @var Tmodel $related */
 		foreach ($results as $related) {
 			if ($this->matches($model, $related)) {
 				$result->push($related);

src/Collection.php

@@ -2,10 +2,16 @@
 
 namespace Kalnoy\Nestedset;
 
-use Illuminate\Database\Eloquent\Collection as BaseCollection;
+use Illuminate\Database\Eloquent\Collection as EloquentCollection;
 use Illuminate\Database\Eloquent\Model;
 
-final class Collection extends BaseCollection
+/**
+ * @template TKey of array-key
+ * @template TModel of Model&Node 
+ *
+ * @extends EloquentCollection<TKey, TModel>
+ */
+final class Collection extends EloquentCollection
 {
 	/**
 	 * Fill `parent` and `children` relationships for every node in the collection.
@@ -20,22 +26,24 @@ public function linkNodes()
 			return $this;
 		}
 
-		$groupedNodes = $this->groupBy($this->first()->getParentIdName());
+		/** @var Node */
+		$first = $this->first();
+		$groupedNodes = $this->groupBy($first->getParentIdName());
 
 		/** @var Node&Model $node */
 		foreach ($this->items as $node) {
 			if ($node->getParentId() === null) {
 				$node->setRelation('parent', null);
 			}
 
+			/** @var array<int,Model&Node> */
 			$children = $groupedNodes->get($node->getKey(), []);
 
-			/** @var Model&Node $child */
 			foreach ($children as $child) {
 				$child->setRelation('parent', $node);
 			}
 
-			$node->setRelation('children', BaseCollection::make($children));
+			$node->setRelation('children', EloquentCollection::make($children));
 		}
 
 		return $this;
@@ -77,7 +85,7 @@ public function toTree($root = false)
 	/**
 	 * @param mixed $root
 	 *
-	 * @return int|string|null
+	 * @return int|string
 	 */
 	protected function getRootNodeId($root = false)
 	{
@@ -101,6 +109,10 @@ protected function getRootNodeId($root = false)
 			}
 		}
 
+		if ($root === null || $root === false) {
+			throw new NestedSetException('root is null or false.');
+		}
+
 		return $root;
 	}
 
@@ -110,32 +122,37 @@ protected function getRootNodeId($root = false)
 	 *
 	 * @param bool $root
 	 *
-	 * @return static
+	 * @return Collection
 	 */
-	public function toFlatTree($root = false)
+	public function toFlatTree($root = false): Collection
 	{
-		$result = new static();
+		$result = new Collection();
 
 		if ($this->isEmpty()) {
 			return $result;
 		}
 
-		$groupedNodes = $this->groupBy($this->first()->getParentIdName());
+		/** @var Node */
+		$first = $this->first();
+		/** @var Collection<int|string,TModel> */
+		$groupedNodes = $this->groupBy($first->getParentIdName());
 
 		return $result->flattenTree($groupedNodes, $this->getRootNodeId($root));
 	}
 
 	/**
 	 * Flatten a tree into a non recursive array.
 	 *
-	 * @param Collection $groupedNodes
-	 * @param mixed      $parentId
+	 * @param Collection<int|string,TModel> $groupedNodes
+	 * @param int|string $parentId
 	 *
-	 * @return $this
+	 * @return Collection
 	 */
-	protected function flattenTree(self $groupedNodes, $parentId)
+	protected function flattenTree(Collection $groupedNodes, $parentId): Collection
 	{
-		foreach ($groupedNodes->get($parentId, []) as $node) {
+		/** @var array<int,TModel> */
+		$nodes = $groupedNodes->get($parentId, []);
+		foreach ($nodes as $node) {
 			$this->push($node);
 
 			$this->flattenTree($groupedNodes, $node->getKey());

src/DescendantsRelation.php

@@ -4,6 +4,9 @@
 
 use Illuminate\Database\Eloquent\Model;
 
+/**
+ * @disregard P1037
+ */
 class DescendantsRelation extends BaseRelation
 {
 	/**
@@ -31,12 +34,12 @@ protected function addEagerConstraint($query, $model)
 	}
 
 	/**
-	 * @param Model $model
-	 * @param       $related
+	 * @param Model&Node $model
+	 * @param Node $related
 	 *
-	 * @return mixed
+	 * @return bool
 	 */
-	protected function matches(Model $model, $related)
+	protected function matches(Model $model, $related): bool
 	{
 		return $related->isDescendantOf($model);
 	}

src/NestedSetException.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Kalnoy\Nestedset;
+
+use Throwable;
+
+/**
+ * Exception thrown when something really went wrong.
+ */
+class NestedSetException extends \Exception {
+
+	public function __construct(string $message, ?Throwable $previous = null) {
+        parent::__construct($message, 0, $previous);
+	}
+}

src/NestedSetServiceProvider.php

@@ -10,10 +10,12 @@ class NestedSetServiceProvider extends ServiceProvider
 	public function register()
 	{
 		Blueprint::macro('nestedSet', function () {
+			/** @disregard P1006 */
 			NestedSet::columns($this);
 		});
 
 		Blueprint::macro('dropNestedSet', function () {
+			/** @disregard P1006 */
 			NestedSet::dropColumns($this);
 		});
 	}