add dedicated exceptions

Author: michalsn

docs/relations.md

@@ -93,7 +93,7 @@ class PostModel extends Model
 
     public function user(): Relation
     {
-        return $this->belongTo(UserModel::class);
+        return $this->belongsTo(UserModel::class);
     }
 }
 ```

src/Enums/RelationTypes.php

@@ -8,5 +8,5 @@ enum RelationTypes
 {
     case hasOne;
     case hasMany;
-    case belongTo;
+    case belongsTo;
 }

src/Exceptions/NestedModelException.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace Michalsn\CodeIgniterNestedModel\Exceptions;
+
+use RuntimeException;
+
+final class NestedModelException extends RuntimeException
+{
+    public static function forMethodNotSupported(string $name): static
+    {
+        return new self(lang('NestedModel.methodNotSupported', [$name]));
+    }
+
+    public static function forParentRelationNotDeclared(string $name): static
+    {
+        return new self(lang('NestedModel.parentRelationNotDeclared', [$name]));
+    }
+
+    public static function forRelationNotDefined(string $name): static
+    {
+        return new self(lang('NestedModel.relationNotDefined', [$name]));
+    }
+
+    public static function forMissingReturnType(string $name): static
+    {
+        return new self(lang('NestedModel.missingReturnType', [$name]));
+    }
+
+    public static function forIncorrectReturnType(string $name): static
+    {
+        return new self(lang('NestedModel.incorrectReturnType', [$name]));
+    }
+}

src/Language/en/NestedModel.php

@@ -0,0 +1,9 @@
+<?php
+
+return [
+    'methodNotSupported' => 'This method is not supported for the "{0}" relation.',
+    'parentRelationNotDeclared' => 'Parent relation "{0}" has not been declared yet.',
+    'relationNotDefined' => 'Relation "{0}" is not defined.',
+    'missingReturnType' => 'Method "{0}()" is missing a required return type declaration.',
+    'incorrectReturnType' => 'Method "{0}()" returned an incorrect type.'
+];

src/Relation.php

@@ -10,6 +10,7 @@
 use CodeIgniter\Model;
 use Michalsn\CodeIgniterNestedModel\Enums\OrderTypes;
 use Michalsn\CodeIgniterNestedModel\Enums\RelationTypes;
+use Michalsn\CodeIgniterNestedModel\Exceptions\NestedModelException;
 use ReflectionObject;
 
 class Relation
@@ -126,7 +127,7 @@ public function ofMany(string $field, OrderTypes $order): static
     private function setOrder(string $field, OrderTypes $order): void
     {
         if ($this->type !== RelationTypes::hasOne) {
-            throw new BadMethodCallException("This method is not supported for the '{$this->type->name}' relation.");
+            throw NestedModelException::forMethodNotSupported($this->type->name);
         }
 
         $this->model->orderBy($field, $order->value);

src/Traits/HasLazyRelations.php

@@ -41,7 +41,7 @@ private function handleRelation(string $name)
 
         $relation->model->where($relation->foreignKey, $this->attributes[$relation->primaryKey]);
 
-        if (in_array($relation->type, [RelationTypes::hasOne, RelationTypes::belongTo], true)) {
+        if (in_array($relation->type, [RelationTypes::hasOne, RelationTypes::belongsTo], true)) {
             $this->attributes[$name] = $relation->model->first();
         } else {
             $this->attributes[$name] = $relation->model->findAll();

src/Traits/HasRelations.php

@@ -9,6 +9,7 @@
 use InvalidArgumentException;
 use LogicException;
 use Michalsn\CodeIgniterNestedModel\Enums\RelationTypes;
+use Michalsn\CodeIgniterNestedModel\Exceptions\NestedModelException;
 use Michalsn\CodeIgniterNestedModel\Relation;
 use Michalsn\CodeIgniterNestedModel\With;
 use ReflectionClass;
@@ -43,7 +44,7 @@ public function with(string $relation, ?Closure $closure = null): static
             [$relation, $name] = explode('.', $relation, 2);
 
             if (! isset($this->relations[$relation])) {
-                throw new InvalidArgumentException(sprintf('Parent relation "%s" has not been declared yet.', $relation));
+                throw NestedModelException::forParentRelationNotDeclared($relation);
             }
 
             $this->relations[$relation]->setWith(new With($name, $closure));
@@ -65,18 +66,18 @@ public function with(string $relation, ?Closure $closure = null): static
     private function checkReturnType(string $methodName): bool
     {
         if (! method_exists($this, $methodName)) {
-            throw new InvalidArgumentException(sprintf('Relation "%s" is not defined.', $methodName));
+            throw NestedModelException::forRelationNotDefined($methodName);
         }
 
         $reflectionMethod = new ReflectionMethod($this, $methodName);
         $returnType       = $reflectionMethod->getReturnType();
 
         if (! $returnType instanceof ReflectionNamedType) {
-            throw new LogicException(sprintf('Method "%s()" is missing a required return type declaration.', $methodName));
+            throw NestedModelException::forMissingReturnType($methodName);
         }
 
         if ($returnType->getName() !== Relation::class) {
-            throw new UnexpectedValueException(sprintf('Method "%s()" returned an incorrect type.', $methodName));
+            throw NestedModelException::forIncorrectReturnType($methodName);
         }
 
         return true;
@@ -97,8 +98,8 @@ private function addRelation(Model|string $model, RelationTypes $relationType, ?
         $this->relations[$relation] = new Relation(
             $relationType,
             $model,
-            $foreignKey ?? ($relationType === RelationTypes::belongTo ? $this->relationsGetBelongForeignKey($model) : $this->relationsGetHasForeignKey()),
-            $primaryKey ?? ($relationType === RelationTypes::belongTo ? $this->relationsGetBelongPrimaryKey($model) : $this->relationsGetHasPrimaryKey())
+            $foreignKey ?? ($relationType === RelationTypes::belongsTo ? $this->relationsGetBelongForeignKey($model) : $this->relationsGetHasForeignKey()),
+            $primaryKey ?? ($relationType === RelationTypes::belongsTo ? $this->relationsGetBelongPrimaryKey($model) : $this->relationsGetHasPrimaryKey())
         );
 
         return $this->relations[$relation];
@@ -123,9 +124,9 @@ protected function hasMany(Model|string $model, ?string $foreignKey = null, ?str
     /**
      * @throws ReflectionException
      */
-    protected function belongTo(Model|string $model, ?string $primaryKey = null, ?string $foreignKey = null): Relation
+    protected function belongsTo(Model|string $model, ?string $primaryKey = null, ?string $foreignKey = null): Relation
     {
-        return $this->addRelation($model, RelationTypes::belongTo, $foreignKey, $primaryKey);
+        return $this->addRelation($model, RelationTypes::belongsTo, $foreignKey, $primaryKey);
     }
 
     /*
@@ -177,6 +178,7 @@ protected function belongsToMany(Model|string $model, Model|string $through, ?st
             $this->relations[$relation]->setThrough($through, $throughForeignKey, $throughPrimaryKey);
         }
     */
+
     /**
      * @throws ReflectionException
      */
@@ -387,7 +389,7 @@ protected function getDataForRelationById(int|string $id, Relation $relation)
 
         $relation->applyConditions();
 
-        return in_array($relation->type, [RelationTypes::hasOne, RelationTypes::belongTo], true) ?
+        return in_array($relation->type, [RelationTypes::hasOne, RelationTypes::belongsTo], true) ?
             $query->first() :
             $query->findAll();
     }
@@ -431,7 +433,7 @@ protected function getDataForRelationByIds(array $id, Relation $relation): array
 
         $relationData = [];
 
-        if (in_array($relation->type, [RelationTypes::hasOne, RelationTypes::belongTo], true)) {
+        if (in_array($relation->type, [RelationTypes::hasOne, RelationTypes::belongsTo], true)) {
             foreach ($results as $row) {
                 $relationData[$this->tempReturnType === 'array' ? $row[$relation->foreignKey] : $row->{$relation->foreignKey}] = $row;
             }

tests/ModelTest.php

@@ -8,6 +8,7 @@
 use CodeIgniter\Model;
 use CodeIgniter\Test\CIUnitTestCase;
 use CodeIgniter\Test\DatabaseTestTrait;
+use Michalsn\CodeIgniterNestedModel\Exceptions\NestedModelException;
 use Tests\Support\Database\Seeds\SeedTests;
 use Tests\Support\Entities\Post;
 use Tests\Support\Entities\Profile;
@@ -32,6 +33,46 @@ public function testModelInstance(): void
         $this->assertInstanceOf(UserModel::class, $model);
     }
 
+    public function testRelationNotDefined(): void
+    {
+        $this->expectException(NestedModelException::class);
+        $this->expectExceptionMessage('Relation "notExist" is not defined.');
+
+        model(UserModel::class)->with('notExist')->find(1);
+    }
+
+    public function testMissingReturnType(): void
+    {
+        $this->expectException(NestedModelException::class);
+        $this->expectExceptionMessage('Method "missingReturnType()" is missing a required return type declaration.');
+
+        model(UserModel::class)->with('missingReturnType')->find(1);
+    }
+
+    public function testIncorrectReturnType(): void
+    {
+        $this->expectException(NestedModelException::class);
+        $this->expectExceptionMessage('Method "incorrectReturnType()" returned an incorrect type.');
+
+        model(UserModel::class)->with('incorrectReturnType')->find(1);
+    }
+
+    public function testParentRelationNotDeclared(): void
+    {
+        $this->expectException(NestedModelException::class);
+        $this->expectExceptionMessage('Parent relation "posts" has not been declared yet.');
+
+        model(UserModel::class)->with('posts.something')->find(1);
+    }
+
+    public function testMethodNotSupported(): void
+    {
+        $this->expectException(NestedModelException::class);
+        $this->expectExceptionMessage('This method is not supported for the "hasMany" relation.');
+
+        model(UserModel::class)->posts()->latestOfMany();
+    }
+
     public function testFindHasOne()
     {
         // Load normal model
@@ -135,7 +176,7 @@ public function testFindHasManyAsArray()
         $this->assertSame('Title 1', $user->posts[0]['title']);
     }
 
-    public function testFindBelongTo()
+    public function testFindbelongsTo()
     {
         // Load normal model
         $post = model(PostModel::class)->find(1);

tests/_support/Models/CommentModel.php

@@ -56,11 +56,11 @@ protected function initialize(): void
 
     public function user(): Relation
     {
-        return $this->belongTo(UserModel::class);
+        return $this->belongsTo(UserModel::class);
     }
 
     public function post(): Relation
     {
-        return $this->belongTo(PostModel::class);
+        return $this->belongsTo(PostModel::class);
     }
 }

tests/_support/Models/PostModel.php

@@ -56,7 +56,7 @@ protected function initialize(): void
 
     public function user(): Relation
     {
-        return $this->belongTo(UserModel::class);
+        return $this->belongsTo(UserModel::class);
     }
 
     public function comments(): Relation