Prisma PHP Logo

Authentication & Security

Prisma PHP abstracts the complexity of modern security. Manage sessions, enforce Role-Based Access Control (RBAC), and handle OAuth strategies from a central configuration.

JWT Core

Stateless, auto-refreshing JSON Web Tokens handle the session lifecycle securely.

Central Config

Manage protection strategies and route whitelists in AuthConfig.php.

Granular RBAC

Protect specific routes or server functions using robust Role-Based Access Control.

1

Security Strategy

Define your application's security posture in src/Lib/Auth/AuthConfig.php. You can choose between two fundamental strategies.

Opt-In (Public Default)

Websites

Routes are public by default. You manually list private routes. Best for marketing sites or blogs.

IS_ALL_ROUTES_PRIVATE = false
public static $privateRoutes = [
    '/dashboard',
    '/profile'
];

Opt-Out (Private Default)

Apps / SaaS

All routes require login. You manually whitelist public routes. Best for dashboards and SaaS applications.

IS_ALL_ROUTES_PRIVATE = true
public static $publicRoutes = [
    '/',
    '/pricing'
];
2

The Auth Lifecycle

Signing In

Use the Auth::signIn method. You can pass an array or object containing user data. The framework automatically serializes this into the JWT payload. 

use Lib\Auth\Auth;

$auth = Auth::getInstance();

// 1. Validate credentials (your custom logic)
if ($user && password_verify($pass, $hash)) {
    
    // 2. Create Session (Valid for 2 hours)
    $auth->signIn(
        [
            'id' => $user->id,
            'role' => 'admin' // Crucial for RBAC
        ], 
        '2h'
    );
}

Signing Out

Auth::signOut destroys the server session and invalidates the client cookie. You can optionally pass a redirect path. 

// Logout and redirect to home
Auth::getInstance()->signOut('/');
3

Access Control (RBAC)

Prisma provides two layers of access control: Route Protection for pages and Attribute Protection for server functions.

Route-Level Protection

Enforce roles on specific URL paths in AuthConfig.php. 

public static array $roleBasedRoutes = [
  'dashboard/users' => [
    self::ROLE_IDENTIFIER => [AuthRole::Admin]
  ]
];

Function-Level Protection

Protect individual backend functions using the #[Exposed] attribute. 

#[Exposed(allowedRoles: ['admin'])]
function deleteRecord() { 
  // ... 
}

Defining Roles

Roles are type-safe. Define them in the AuthRole enum located in AuthConfig.php.

enum AuthRole: string { case Admin = 'Admin'; case User = 'User'; }
4

Social Login (OAuth)

Initialize providers in your login route logic. The framework handles the complex OAuth handshake, token exchange, and user profile retrieval. 

use Lib\Auth\{Auth, GoogleProvider, GithubProvider};

$auth = Auth::getInstance();

// Automatically handles redirects and callbacks
$auth->authProviders(
    new GoogleProvider(
        $_ENV['GOOGLE_CLIENT_ID'], 
        $_ENV['GOOGLE_SECRET'], 
        '/auth/callback'
    ),
    new GithubProvider(
        $_ENV['GITHUB_ID'], 
        $_ENV['GITHUB_SECRET']
    )
);

* Note: Ensure your route is dynamic (e.g., src/app/auth/[...ppauth]/index.php) to capture the provider callback.