<?php

namespace Spatie\Permission\Contracts;

use BackedEnum;
use Illuminate\Database\Eloquent\Relations\BelongsToMany;
use Spatie\Permission\Exceptions\PermissionDoesNotExist;

/**
 * @property int|string $id
 * @property string $name
 * @property string|null $guard_name
 *
 * @mixin \Spatie\Permission\Models\Permission
 *
 * @phpstan-require-extends \Spatie\Permission\Models\Permission
 */
interface Permission
{
    /**
     * A permission can be applied to roles.
     */
    public function roles(): BelongsToMany;

    /**
     * Find a permission by its name.
     *
     *
     * @throws PermissionDoesNotExist
     */
    public static function findByName(BackedEnum|string $name, ?string $guardName): self;

    /**
     * Find a permission by its id.
     *
     *
     * @throws PermissionDoesNotExist
     */
    public static function findById(int|string $id, ?string $guardName): self;

    /**
     * Find or Create a permission by its name and guard name.
     */
    public static function findOrCreate(BackedEnum|string $name, ?string $guardName): self;
}
