<?php
namespace nur\b\authnz;

/**
 * Interface IAuthz: interface modélisant un utilisateur connecté et ses
 * autorisations
 */
interface IAuthzUser {
  /**
   * tester si cette instance est valide, c'est à dire si elle correspond à
   * un utilisateur valide. cette méthode retourne normalement toujours true.
   */
  function isValid(): bool;

  /**
   * obtenir le compte de l'utilisateur, ou "INVALID" si cette instance est
   * invalide
   */
  function getUsername(): string;

  /** vérifier si le mot de passe fourni est correct */
  function validatePassword(string $password): bool;

  /**
   * obtenir le nom complet de l'utilisateur ou null si l'information n'est pas
   * disponible.
   */
  function getDisplayName(): ?string;

  /**
   * obtenir le nom abrégé de l'utilisateur ou null si l'information n'est pas
   * disponible.
   */
  function getShortName(): ?string;

  /**
   * obtenir le mail de l'utilisateur ou null si l'information n'est pas
   * disponible.
   */
  function getMail(): ?string;

  /** @var string rôle virtuel d'un utilisateur qui n'est pas authentifié */
  const ROLE_ANON = "@anon";
  /** @var string rôle virtuel d'un utilisateur qui est authentifié */
  const ROLE_AUTH = "@auth";
  /**
   * @var string rôle virtuel d'un utilisateur qui a un rôle principal ou au
   * moins une permission attribuée
   */
  const ROLE_AUTHZ = "@authz";

  /**
   * obtenir le rôle principal de l'utilisateur ou null si l'utilisateur n'a pas
   * de rôle en particulier. un utilisateur ne peut avoir qu'un seul rôle
   * principal.
   *
   * le rôle principal ne peut pas être un rôle virtuel
   */
  function getRole(): ?string;

  /**
   * l'utilisateur a-t-il le rôle spécifié, qu'il soit principal ou virtuel?
   *
   * - si $role === null, retourner true
   * - $role peut être un tableau auquel cas on vérifie si l'utilisateur a au
   * moins un des rôles spécifiés
   *
   * @param string|array $role
   */
  function isRole($roles): bool;

  /**
   * l'utilisateur a-t-il la permission spécifiée?
   *
   * - si $perm === null, retourner true
   * - $perm peut être un tableau auquel cas on vérifie si l'utilisateur a au
   * moins une des permissions spécifiées
   *
   * @param string|array $perm
   */
  function isPerm($perms): bool;

  /** tester si une clé générique est présente */
  function has($key): bool;

  /** obtenir la valeur d'une clé générique */
  function get($key, $default=null);
}
