impulsephp/auth

Authentication provider for ImpulsePHP: session-based login, logout, and current-user management with a pluggable user repository and password hashing, resolved via the container through AuthInterface.

dev-main 2026-04-08 15:48 UTC

Requires

• php: >=8.2

Requires (Dev)

• phpunit/phpunit: ^10.0

MIT

• Guillaume Bouyer

README

impulsephp/auth fournit la brique d’authentification d’ImpulsePHP. Le package s’appuie sur les sessions PHP pour gérer la connexion, la déconnexion et la récupération de l’utilisateur courant, tout en laissant l’application libre de choisir son dépôt d’utilisateurs.

Ce que fait le package

• authentifie un utilisateur à partir d’un identifiant et d’un mot de passe ;
• conserve l’état de connexion en session ;
• expose l’utilisateur courant via AuthInterface ;
• délègue la recherche des utilisateurs à UserRepositoryInterface ;
• utilise PasswordHasher pour vérifier les mots de passe.

Prérequis

• PHP 8.2 ou supérieur.

Installation

composer require impulsephp/auth

Le provider est déclaré via extra.impulse-provider. Si votre application ne gère pas l’auto-découverte, ajoutez Impulse\Auth\AuthProvider à votre liste de providers.

Intégration dans l’application

Le package attend qu’une implémentation de Impulse\Auth\Contracts\UserRepositoryInterface soit disponible dans l’application. C’est cette implémentation qui relie l’authentification à votre base de données, votre ORM ou tout autre système de stockage.

use Impulse\Auth\Contracts\UserRepositoryInterface;
use Impulse\Auth\Domain\User;

final class UserRepository implements UserRepositoryInterface
{
    public function findByIdentifier(string $identifier): ?User
    {
        // Retourner l'utilisateur trouvé par email ou nom d'utilisateur.
    }

    public function findById(int|string $id): ?User
    {
        // Retourner l'utilisateur trouvé par identifiant technique.
    }

    public function save(User $user): void
    {
        // Persister l'utilisateur si votre workflow le demande.
    }
}

Exemple d’usage complet

L’exemple ci-dessous montre un scénario classique de formulaire de connexion puis d’accès à un espace protégé.

use Impulse\Auth\Contracts\AuthInterface;

$auth = $container->get(AuthInterface::class);

if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $identifier = (string) ($_POST['email'] ?? '');
    $password = (string) ($_POST['password'] ?? '');

    if ($auth->login($identifier, $password)) {
        header('Location: /account', true, 302);
        exit;
    }

    http_response_code(401);
    echo 'Identifiants invalides.';
}

if ($auth->check()) {
    $user = $auth->user();
    echo 'Bonjour ' . $user?->email;
}

Déconnexion

use Impulse\Auth\Contracts\AuthInterface;

$auth = $container->get(AuthInterface::class);
$auth->logout();

header('Location: /login', true, 302);
exit;

Protéger une page

use Impulse\Auth\Contracts\AuthInterface;

$auth = $container->get(AuthInterface::class);

if (!$auth->check()) {
    header('Location: /login', true, 302);
    exit;
}

$user = $auth->user();

API principale

• login(string $identifier, string $password): bool
• logout(): void
• check(): bool
• id(): int|string|null
• user(): ?Impulse\Auth\Domain\User

Bonnes pratiques de sécurité

Le SessionStore configure des cookies HttpOnly et régénère l’identifiant de session lors de la connexion et de la déconnexion. En production, il est recommandé de :

• servir l’application exclusivement en HTTPS ;
• conserver un cookie de session secure ;
• protéger les formulaires avec un mécanisme CSRF ;
• limiter les tentatives de connexion ;
• éviter de révéler précisément la cause d’un échec d’authentification.

Aller plus loin

impulsephp/auth s’intègre naturellement avec :

• impulsephp/db pour récupérer les utilisateurs ;
• impulsephp/validator pour valider les formulaires de connexion ;
• impulsephp/translation pour localiser les messages côté interface.

Intégration avec Cycle ORM (exemple)

Voici un exemple minimal d'implémentation d'un UserRepository utilisant Cycle ORM. Placez la classe dans votre application (par ex. src/Repository/UserRepository.php) et assurez-vous que Cycle ORM est correctement configuré dans votre container.

<?php
declare(strict_types=1);

namespace App\Repository;

use Impulse\Auth\Contracts\UserRepositoryInterface;
use Impulse\Auth\Domain\User;
use Cycle\ORM\ORM;

final class UserRepository implements UserRepositoryInterface
{
    public function __construct(private ORM $orm) {}

    public function findByIdentifier(string $identifier): ?User
    {
        $repo = $this->orm->getRepository(\App\Entity\User::class);
        $entity = $repo->findOne(['email' => $identifier]);
        if (!$entity) {
            return null;
        }
        return new User($entity->id, $entity->email, $entity->password_hash, $entity->roles ?? []);
    }

    public function findById(int|string $id): ?User
    {
        $repo = $this->orm->getRepository(\App\Entity\User::class);
        $entity = $repo->findByPK($id);
        if (!$entity) {
            return null;
        }
        return new User($entity->id, $entity->email, $entity->password_hash, $entity->roles ?? []);
    }

    public function save(User $user): void
    {
        $repo = $this->orm->getRepository(\App\Entity\User::class);
        // Transformez l'entité et persistez via Cycle selon votre schéma
    }
}

Note : adaptez selon votre entité (noms de colonnes, sérialisation des rôles, etc.). L'AuthProvider utilisera automatiquement \App\Repository\UserRepository si elle existe et implémente UserRepositoryInterface.

Tests

Le package contient maintenant des tests unitaires et un test fonctionnel utilisant un SQLite en mémoire (PDO). Pour exécuter :

cd /Users/guillaume/Sites/ImpulsePHP/auth
composer install
./vendor/bin/phpunit --testdox

Tests

composer test

Licence

MIT