Download the PHP package equidna/caronte-client without Composer

Caronte Client v1.3.2

A robust PHP library for JWT-based authentication and permission management, purpose-built for Laravel applications. Caronte Client streamlines secure user authentication, role-based access control, and seamless integration with modern Laravel projects.

Note: Caronte Client supports Laravel 10.x, 11.x, and 12.x. PHP 8.0 or higher is required.

Coding Standards

• Follows PSR-12 with a 250-character line limit
• Uses 4-space indentation, LF line endings, and a final newline
• StyleCI uses the Laravel preset (see .gitattributes and ruleset.xml)
• Classes use StudlyCase; methods and variables use camelCase
• Functions are documented with PHPDoc and type hints

Blade Message Handling

The package supports displaying messages in views using both session variables and base64-encoded request parameters:

• Session keys: error, warning, success, info, message
• Request parameters: _err, _war, _suc (base64-encoded)

Example usage in Blade:

This allows for flexible error and success message display after redirects or API calls.

Error Handling & Message Display

Error and success messages are displayed in views using session variables and base64-encoded request parameters. See Blade Message Handling above for details. Always validate and sanitize user input before displaying.

Main Use Cases

• Secure user authentication using JWT tokens
• Fine-grained permission and role management
• Middleware for session and role validation in Laravel routes
• Helper utilities for user and permission logic
• Facade for easy access to authentication features
• Artisan commands for configuration and environment sync
• Publishing of config, views, assets, and migrations for customization

Installation

Install Caronte Client via Composer:

Usage Examples

Authenticating Users

Middleware Integration

Add Caronte middleware to your routes for session and role validation:

Permission Checks in Code

Technical Overview

Caronte Client is architected for seamless integration with Laravel applications:

• JWT Authentication: Securely validates and manages user sessions using JWT tokens.
• Middleware: ValidateSession and ValidateRoles ensure authentication and role-based access at the route level.
• Helpers: Utility classes for user and permission management.
• Facade: The Caronte facade provides a simple API for token and user operations.
• Configurable: Easily publish and customize configuration, views, assets, and migrations.
• Artisan Commands: Sync roles and configuration with the Caronte server.

[!TIP] All permission checks automatically include the root role for maximum flexibility.

Configuration

Set environment variables in .env:

Role Configuration

To define roles, edit src/config/caronte-roles.php. After making changes, notify the Caronte server:

Routes

Routes are defined in src/routes/web.php:

Middleware

ValidateSession

Class: Equidna\Caronte\Http\Middleware\ValidateSession
Alias: Caronte.ValidateSession

Validates user authentication and token validity. Token is auto-renewed if expired (see _new_token_ response header).

ValidateRoles

Class: Equidna\Caronte\Http\Middleware\ValidateRoles
Alias: Caronte.ValidateRoles
Parameters: Comma-separated list or array of roles

Validates user roles (always includes root).

Helpers

CaronteUserHelper

Static methods for user info:

• getUserName(string $uri_user): string — Get user name
• getUserEmail(string $uri_user): string — Get user email
• getUserMetadata(string $uri_user, string $key): ?string — Get user metadata

PermissionHelper

Static methods for permissions:

• hasApplication(): bool — User has any role for current app
• hasRoles(mixed $roles): bool — User has any of provided roles (comma-separated or array; always includes root)

Facade

Caronte

Provides static access to authentication features:

• getToken(): Plain — Get current JWT token
• getUser(): ?stdClass — Get current user
• getRouteUser(): string — Get user from route
• saveToken(string $token_str): void — Store token
• clearToken(): void — Clear token
• setTokenWasExchanged(): void — Mark token as exchanged
• tokenWasExchanged(): bool — Was token exchanged?
• echo(string $message): string — Echo message
• updateUserData(stdClass $user): void — Update user data

Artisan Commands

• caronte:notify-client-configuration — Sync roles with Caronte server

Publishing & Customization

You can publish config, views, assets, and migrations to customize the package for your app. See above for commands.

Upgrading

If upgrading to Laravel 12, update dependencies and review changelogs. Caronte Client is tested and compatible. Use the version helper for future BC logic.

Support & Issues

For issues, see the GitHub repository or open a new issue. Always check the changelog and documentation for updates.