diff --git a/docs/upgrading.md b/docs/upgrading.md
index f44ec1172..3709250ff 100644
--- a/docs/upgrading.md
+++ b/docs/upgrading.md
@@ -32,7 +32,7 @@ There are a few breaking-changes when upgrading to v6, but most of them won't af
 eg: if you have a custom model you will need to make changes, including accessing the model using `$this->permissionClass::` syntax (eg: using `::` instead of `->`) in all the overridden methods that make use of the models.
 Be sure to compare your custom models with originals to see what else may have changed.
 
-2. If you have a custom Role model and (in the rare case that you might) have overridden the `hasPermissionTo()` method in it, you will need to update its method signature to `hasPermissionTo($permission, $guardName = null):bool`. See PR #2380.
+2. Model and Contract/Interface updates. Both the Permission and Role contracts have been updated with syntax changes to method signatures, so if you have implemented those contracts in any models, you will need to update the function signatures. Further, if you have extended the Role or Permission models you will need to check any methods you have overridden and update method signatures. See PR #2380 and #2480 especially.
 
 3. Migrations will need to be upgraded. (They have been updated to anonymous-class syntax that was introduced in Laravel 8, AND some structural coding changes in the registrar class changed the way we extracted configuration settings in the migration files.) If you had not customized it from the original then replacing the contents of the file should be straightforward. Usually the only customization is if you've switched to UUIDs or customized MySQL index name lengths. 
 **If you get the following error, it means your migration file needs upgrading: `Error: Access to undeclared static property Spatie\Permission\PermissionRegistrar::$pivotPermission`**
diff --git a/src/Contracts/Permission.php b/src/Contracts/Permission.php
index 8b3d14e18..a2444adeb 100644
--- a/src/Contracts/Permission.php
+++ b/src/Contracts/Permission.php
@@ -5,9 +5,9 @@
 use Illuminate\Database\Eloquent\Relations\BelongsToMany;
 
 /**
- * @property int $id
+ * @property int|string $id
  * @property string $name
- * @property string $guard_name
+ * @property string|null $guard_name
  *
  * @mixin \Spatie\Permission\Models\Permission
  */
@@ -21,25 +21,25 @@ public function roles(): BelongsToMany;
     /**
      * Find a permission by its name.
      *
-     * @param  string|null  $guardName
+     * @return \Spatie\Permission\Contracts\Permission
      *
      * @throws \Spatie\Permission\Exceptions\PermissionDoesNotExist
      */
-    public static function findByName(string $name, $guardName): self;
+    public static function findByName(string $name, ?string $guardName): self;
 
     /**
      * Find a permission by its id.
      *
-     * @param  string|null  $guardName
+     * @return \Spatie\Permission\Contracts\Permission
      *
      * @throws \Spatie\Permission\Exceptions\PermissionDoesNotExist
      */
-    public static function findById(int $id, $guardName): self;
+    public static function findById(int|string $id, ?string $guardName): self;
 
     /**
      * Find or Create a permission by its name and guard name.
      *
-     * @param  string|null  $guardName
+     * @return \Spatie\Permission\Contracts\Permission
      */
-    public static function findOrCreate(string $name, $guardName): self;
+    public static function findOrCreate(string $name, ?string $guardName): self;
 }
diff --git a/src/Contracts/Role.php b/src/Contracts/Role.php
index 04009de37..5745dd6b3 100644
--- a/src/Contracts/Role.php
+++ b/src/Contracts/Role.php
@@ -5,9 +5,9 @@
 use Illuminate\Database\Eloquent\Relations\BelongsToMany;
 
 /**
- * @property int $id
+ * @property int|string $id
  * @property string $name
- * @property string $guard_name
+ * @property string|null $guard_name
  *
  * @mixin \Spatie\Permission\Models\Role
  */
@@ -21,35 +21,32 @@ public function permissions(): BelongsToMany;
     /**
      * Find a role by its name and guard name.
      *
-     * @param  string|null  $guardName
      * @return \Spatie\Permission\Contracts\Role
      *
      * @throws \Spatie\Permission\Exceptions\RoleDoesNotExist
      */
-    public static function findByName(string $name, $guardName): self;
+    public static function findByName(string $name, ?string $guardName): self;
 
     /**
      * Find a role by its id and guard name.
      *
-     * @param  string|null  $guardName
      * @return \Spatie\Permission\Contracts\Role
      *
      * @throws \Spatie\Permission\Exceptions\RoleDoesNotExist
      */
-    public static function findById(int $id, $guardName): self;
+    public static function findById(int|string $id, ?string $guardName): self;
 
     /**
      * Find or create a role by its name and guard name.
      *
-     * @param  string|null  $guardName
      * @return \Spatie\Permission\Contracts\Role
      */
-    public static function findOrCreate(string $name, $guardName): self;
+    public static function findOrCreate(string $name, ?string $guardName): self;
 
     /**
      * Determine if the user may perform the given permission.
      *
      * @param  string|\Spatie\Permission\Contracts\Permission  $permission
      */
-    public function hasPermissionTo($permission): bool;
+    public function hasPermissionTo($permission, ?string $guardName): bool;
 }
diff --git a/src/Models/Permission.php b/src/Models/Permission.php
index 21ce630ea..95df94fb6 100644
--- a/src/Models/Permission.php
+++ b/src/Models/Permission.php
@@ -82,12 +82,11 @@ public function users(): BelongsToMany
     /**
      * Find a permission by its name (and optionally guardName).
      *
-     * @param  string|null  $guardName
      * @return PermissionContract|Permission
      *
      * @throws PermissionDoesNotExist
      */
-    public static function findByName(string $name, $guardName = null): PermissionContract
+    public static function findByName(string $name, string $guardName = null): PermissionContract
     {
         $guardName = $guardName ?? Guard::getDefaultName(static::class);
         $permission = static::getPermission(['name' => $name, 'guard_name' => $guardName]);
@@ -101,13 +100,11 @@ public static function findByName(string $name, $guardName = null): PermissionCo
     /**
      * Find a permission by its id (and optionally guardName).
      *
-     * @param  int|string  $id
-     * @param  string|null  $guardName
      * @return PermissionContract|Permission
      *
      * @throws PermissionDoesNotExist
      */
-    public static function findById($id, $guardName = null): PermissionContract
+    public static function findById(int|string $id, string $guardName = null): PermissionContract
     {
         $guardName = $guardName ?? Guard::getDefaultName(static::class);
         $permission = static::getPermission([(new static())->getKeyName() => $id, 'guard_name' => $guardName]);
@@ -122,10 +119,9 @@ public static function findById($id, $guardName = null): PermissionContract
     /**
      * Find or create permission by its name (and optionally guardName).
      *
-     * @param  string|null  $guardName
      * @return PermissionContract|Permission
      */
-    public static function findOrCreate(string $name, $guardName = null): PermissionContract
+    public static function findOrCreate(string $name, string $guardName = null): PermissionContract
     {
         $guardName = $guardName ?? Guard::getDefaultName(static::class);
         $permission = static::getPermission(['name' => $name, 'guard_name' => $guardName]);
diff --git a/src/Models/Role.php b/src/Models/Role.php
index d96102a2f..4fd6e782e 100644
--- a/src/Models/Role.php
+++ b/src/Models/Role.php
@@ -91,12 +91,11 @@ public function users(): BelongsToMany
     /**
      * Find a role by its name and guard name.
      *
-     * @param  string|null  $guardName
      * @return RoleContract|Role
      *
      * @throws RoleDoesNotExist
      */
-    public static function findByName(string $name, $guardName = null): RoleContract
+    public static function findByName(string $name, string $guardName = null): RoleContract
     {
         $guardName = $guardName ?? Guard::getDefaultName(static::class);
 
@@ -112,11 +111,9 @@ public static function findByName(string $name, $guardName = null): RoleContract
     /**
      * Find a role by its id (and optionally guardName).
      *
-     * @param  int|string  $id
-     * @param  string|null  $guardName
      * @return RoleContract|Role
      */
-    public static function findById($id, $guardName = null): RoleContract
+    public static function findById(int|string $id, string $guardName = null): RoleContract
     {
         $guardName = $guardName ?? Guard::getDefaultName(static::class);
 
@@ -132,10 +129,9 @@ public static function findById($id, $guardName = null): RoleContract
     /**
      * Find or create role by its name (and optionally guardName).
      *
-     * @param  string|null  $guardName
      * @return RoleContract|Role
      */
-    public static function findOrCreate(string $name, $guardName = null): RoleContract
+    public static function findOrCreate(string $name, string $guardName = null): RoleContract
     {
         $guardName = $guardName ?? Guard::getDefaultName(static::class);
 
@@ -177,11 +173,10 @@ protected static function findByParam(array $params = []): ?RoleContract
      * Determine if the role may perform the given permission.
      *
      * @param  string|int|Permission|\BackedEnum  $permission
-     * @param  string|null  $guardName
      *
      * @throws PermissionDoesNotExist|GuardDoesNotMatch
      */
-    public function hasPermissionTo($permission, $guardName = null): bool
+    public function hasPermissionTo($permission, string $guardName = null): bool
     {
         if ($this->getWildcardClass()) {
             return $this->hasWildcardPermission($permission, $guardName);