From a326caae5307e5dc4528c616630f34da6b97f16b Mon Sep 17 00:00:00 2001
From: Chris Brown <code@drbyte.dev>
Date: Fri, 18 Aug 2023 22:17:45 -0400
Subject: [PATCH 1/6] Update contracts to allow for UUID

Also updates to declare `?string` as `$guardName` signature
---
 src/Contracts/Permission.php | 17 +++++++++--------
 src/Contracts/Role.php       | 20 +++++++++++---------
 src/Models/Permission.php    | 12 ++++++------
 src/Models/Role.php          | 14 +++++++-------
 4 files changed, 33 insertions(+), 30 deletions(-)

diff --git a/src/Contracts/Permission.php b/src/Contracts/Permission.php
index 8b3d14e18..9d1d288bc 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,26 @@ public function roles(): BelongsToMany;
     /**
      * Find a permission by its name.
      *
-     * @param  string|null  $guardName
+     * @param string|null $guardName
      *
      * @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
+     * @param int|string $id
+     * @param string|null $guardName
      *
      * @throws \Spatie\Permission\Exceptions\PermissionDoesNotExist
      */
-    public static function findById(int $id, $guardName): self;
+    public static function findById($id, ?string $guardName): self;
 
     /**
      * Find or Create a permission by its name and guard name.
      *
-     * @param  string|null  $guardName
+     * @param string|null $guardName
      */
-    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..7fe3b9383 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,37 @@ public function permissions(): BelongsToMany;
     /**
      * Find a role by its name and guard name.
      *
-     * @param  string|null  $guardName
+     * @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
+     * @param int|string $id
+     * @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($id, ?string $guardName): self;
 
     /**
      * Find or create a role by its name and guard name.
      *
-     * @param  string|null  $guardName
+     * @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
+     * @param string|null $guardName
      */
-    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..9c475516b 100644
--- a/src/Models/Permission.php
+++ b/src/Models/Permission.php
@@ -82,12 +82,12 @@ public function users(): BelongsToMany
     /**
      * Find a permission by its name (and optionally guardName).
      *
-     * @param  string|null  $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]);
@@ -102,12 +102,12 @@ 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
+     * @param string|null $guardName
      * @return PermissionContract|Permission
      *
      * @throws PermissionDoesNotExist
      */
-    public static function findById($id, $guardName = null): PermissionContract
+    public static function findById($id, ?string $guardName = null): PermissionContract
     {
         $guardName = $guardName ?? Guard::getDefaultName(static::class);
         $permission = static::getPermission([(new static())->getKeyName() => $id, 'guard_name' => $guardName]);
@@ -122,10 +122,10 @@ public static function findById($id, $guardName = null): PermissionContract
     /**
      * Find or create permission by its name (and optionally guardName).
      *
-     * @param  string|null  $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 025147864..4839c4858 100644
--- a/src/Models/Role.php
+++ b/src/Models/Role.php
@@ -91,12 +91,12 @@ public function users(): BelongsToMany
     /**
      * Find a role by its name and guard name.
      *
-     * @param  string|null  $guardName
+     * @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);
 
@@ -113,10 +113,10 @@ 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
+     * @param string|null $guardName
      * @return RoleContract|Role
      */
-    public static function findById($id, $guardName = null): RoleContract
+    public static function findById($id, ?string $guardName = null): RoleContract
     {
         $guardName = $guardName ?? Guard::getDefaultName(static::class);
 
@@ -132,10 +132,10 @@ public static function findById($id, $guardName = null): RoleContract
     /**
      * Find or create role by its name (and optionally guardName).
      *
-     * @param  string|null  $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);
 
@@ -181,7 +181,7 @@ protected static function findByParam(array $params = []): ?RoleContract
      *
      * @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);

From 724ecf250e48fe117c48d5d7eb299b8b7e66119d Mon Sep 17 00:00:00 2001
From: drbyte <drbyte@users.noreply.github.com>
Date: Sat, 19 Aug 2023 02:18:48 +0000
Subject: [PATCH 2/6] Fix styling

---
 src/Contracts/Permission.php |  6 +-----
 src/Contracts/Role.php       |  6 +-----
 src/Models/Permission.php    |  9 +++------
 src/Models/Role.php          | 12 ++++--------
 4 files changed, 9 insertions(+), 24 deletions(-)

diff --git a/src/Contracts/Permission.php b/src/Contracts/Permission.php
index 9d1d288bc..ed8e3bdc4 100644
--- a/src/Contracts/Permission.php
+++ b/src/Contracts/Permission.php
@@ -21,7 +21,6 @@ public function roles(): BelongsToMany;
     /**
      * Find a permission by its name.
      *
-     * @param string|null $guardName
      *
      * @throws \Spatie\Permission\Exceptions\PermissionDoesNotExist
      */
@@ -30,8 +29,7 @@ public static function findByName(string $name, ?string $guardName): self;
     /**
      * Find a permission by its id.
      *
-     * @param int|string $id
-     * @param string|null $guardName
+     * @param  int|string  $id
      *
      * @throws \Spatie\Permission\Exceptions\PermissionDoesNotExist
      */
@@ -39,8 +37,6 @@ public static function findById($id, ?string $guardName): self;
 
     /**
      * Find or Create a permission by its name and guard name.
-     *
-     * @param string|null $guardName
      */
     public static function findOrCreate(string $name, ?string $guardName): self;
 }
diff --git a/src/Contracts/Role.php b/src/Contracts/Role.php
index 7fe3b9383..e7daf273d 100644
--- a/src/Contracts/Role.php
+++ b/src/Contracts/Role.php
@@ -21,7 +21,6 @@ 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
@@ -31,8 +30,7 @@ public static function findByName(string $name, ?string $guardName): self;
     /**
      * Find a role by its id and guard name.
      *
-     * @param int|string $id
-     * @param string|null $guardName
+     * @param  int|string  $id
      * @return \Spatie\Permission\Contracts\Role
      *
      * @throws \Spatie\Permission\Exceptions\RoleDoesNotExist
@@ -42,7 +40,6 @@ public static function findById($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, ?string $guardName): self;
@@ -51,7 +48,6 @@ 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
-     * @param string|null $guardName
      */
     public function hasPermissionTo($permission, ?string $guardName): bool;
 }
diff --git a/src/Models/Permission.php b/src/Models/Permission.php
index 9c475516b..29b86268a 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, ?string $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]);
@@ -102,12 +101,11 @@ public static function findByName(string $name, ?string $guardName = null): Perm
      * 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, ?string $guardName = null): PermissionContract
+    public static function findById($id, string $guardName = null): PermissionContract
     {
         $guardName = $guardName ?? Guard::getDefaultName(static::class);
         $permission = static::getPermission([(new static())->getKeyName() => $id, 'guard_name' => $guardName]);
@@ -122,10 +120,9 @@ public static function findById($id, ?string $guardName = null): PermissionContr
     /**
      * Find or create permission by its name (and optionally guardName).
      *
-     * @param string|null $guardName
      * @return PermissionContract|Permission
      */
-    public static function findOrCreate(string $name, ?string $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 4839c4858..f5c58cda3 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, ?string $guardName = null): RoleContract
+    public static function findByName(string $name, string $guardName = null): RoleContract
     {
         $guardName = $guardName ?? Guard::getDefaultName(static::class);
 
@@ -113,10 +112,9 @@ public static function findByName(string $name, ?string $guardName = null): Role
      * 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, ?string $guardName = null): RoleContract
+    public static function findById($id, string $guardName = null): RoleContract
     {
         $guardName = $guardName ?? Guard::getDefaultName(static::class);
 
@@ -132,10 +130,9 @@ public static function findById($id, ?string $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, ?string $guardName = null): RoleContract
+    public static function findOrCreate(string $name, string $guardName = null): RoleContract
     {
         $guardName = $guardName ?? Guard::getDefaultName(static::class);
 
@@ -177,11 +174,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, ?string $guardName = null): bool
+    public function hasPermissionTo($permission, string $guardName = null): bool
     {
         if ($this->getWildcardClass()) {
             return $this->hasWildcardPermission($permission, $guardName);

From 017de42840117e171687fd4e731ebe029ab1b92d Mon Sep 17 00:00:00 2001
From: Chris Brown <code@drbyte.dev>
Date: Fri, 18 Aug 2023 22:38:00 -0400
Subject: [PATCH 3/6] [Docs] Upgrade notes: syntax changes in v6 interfaces

---
 docs/upgrading.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/upgrading.md b/docs/upgrading.md
index f44ec1172..197e912dc 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. Contract/Interface updates. Both the Permission and Role contracts have been updated with minor syntax changes, so if you have implemented those contracts in any models, you will need to update the function signatures. Further, 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, ?string $guardName = null):bool`. See PR #2380.
 
 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`**

From 05372f966d1f2dfc05dd4b58afa9f678b0f7f757 Mon Sep 17 00:00:00 2001
From: Chris Brown <code@drbyte.dev>
Date: Mon, 21 Aug 2023 13:10:00 -0400
Subject: [PATCH 4/6] Use union types on contracts and models

---
 src/Contracts/Permission.php | 8 ++++++--
 src/Contracts/Role.php       | 3 +--
 src/Models/Permission.php    | 3 +--
 src/Models/Role.php          | 3 +--
 4 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/src/Contracts/Permission.php b/src/Contracts/Permission.php
index ed8e3bdc4..27fd169bd 100644
--- a/src/Contracts/Permission.php
+++ b/src/Contracts/Permission.php
@@ -21,6 +21,7 @@ public function roles(): BelongsToMany;
     /**
      * Find a permission by its name.
      *
+     * @return \Spatie\Permission\Contracts\Permission
      *
      * @throws \Spatie\Permission\Exceptions\PermissionDoesNotExist
      */
@@ -29,14 +30,17 @@ public static function findByName(string $name, ?string $guardName): self;
     /**
      * Find a permission by its id.
      *
-     * @param  int|string  $id
+     * @return \Spatie\Permission\Contracts\Permission
      *
      * @throws \Spatie\Permission\Exceptions\PermissionDoesNotExist
      */
-    public static function findById($id, ?string $guardName): self;
+    public static function findById(int|string $id, ?string $guardName): self;
 
     /**
      * Find or Create a permission by its name and guard name.
+     *
+     * @return \Spatie\Permission\Contracts\Permission
+     *
      */
     public static function findOrCreate(string $name, ?string $guardName): self;
 }
diff --git a/src/Contracts/Role.php b/src/Contracts/Role.php
index e7daf273d..5745dd6b3 100644
--- a/src/Contracts/Role.php
+++ b/src/Contracts/Role.php
@@ -30,12 +30,11 @@ public static function findByName(string $name, ?string $guardName): self;
     /**
      * Find a role by its id and guard name.
      *
-     * @param  int|string  $id
      * @return \Spatie\Permission\Contracts\Role
      *
      * @throws \Spatie\Permission\Exceptions\RoleDoesNotExist
      */
-    public static function findById($id, ?string $guardName): self;
+    public static function findById(int|string $id, ?string $guardName): self;
 
     /**
      * Find or create a role by its name and guard name.
diff --git a/src/Models/Permission.php b/src/Models/Permission.php
index 29b86268a..95df94fb6 100644
--- a/src/Models/Permission.php
+++ b/src/Models/Permission.php
@@ -100,12 +100,11 @@ public static function findByName(string $name, string $guardName = null): Permi
     /**
      * Find a permission by its id (and optionally guardName).
      *
-     * @param  int|string  $id
      * @return PermissionContract|Permission
      *
      * @throws PermissionDoesNotExist
      */
-    public static function findById($id, string $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]);
diff --git a/src/Models/Role.php b/src/Models/Role.php
index ed23a0915..4fd6e782e 100644
--- a/src/Models/Role.php
+++ b/src/Models/Role.php
@@ -111,10 +111,9 @@ public static function findByName(string $name, string $guardName = null): RoleC
     /**
      * Find a role by its id (and optionally guardName).
      *
-     * @param  int|string  $id
      * @return RoleContract|Role
      */
-    public static function findById($id, string $guardName = null): RoleContract
+    public static function findById(int|string $id, string $guardName = null): RoleContract
     {
         $guardName = $guardName ?? Guard::getDefaultName(static::class);
 

From ce567c961abb18677737b0c551a6458b8afdac99 Mon Sep 17 00:00:00 2001
From: drbyte <drbyte@users.noreply.github.com>
Date: Mon, 21 Aug 2023 17:10:30 +0000
Subject: [PATCH 5/6] Fix styling

---
 src/Contracts/Permission.php | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/Contracts/Permission.php b/src/Contracts/Permission.php
index 27fd169bd..a2444adeb 100644
--- a/src/Contracts/Permission.php
+++ b/src/Contracts/Permission.php
@@ -40,7 +40,6 @@ public static function findById(int|string $id, ?string $guardName): self;
      * Find or Create a permission by its name and guard name.
      *
      * @return \Spatie\Permission\Contracts\Permission
-     *
      */
     public static function findOrCreate(string $name, ?string $guardName): self;
 }

From 894631b1893e687f0a2ee535a517e5cf31770c24 Mon Sep 17 00:00:00 2001
From: Chris Brown <code@drbyte.dev>
Date: Mon, 21 Aug 2023 13:17:21 -0400
Subject: [PATCH 6/6] [Docs] make contract fixes explanation more generic

---
 docs/upgrading.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/upgrading.md b/docs/upgrading.md
index 197e912dc..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. Contract/Interface updates. Both the Permission and Role contracts have been updated with minor syntax changes, so if you have implemented those contracts in any models, you will need to update the function signatures. Further, 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, ?string $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`**