README

A microservice‑friendly Laravel package that adds a secure, configurable Manager (admin) panel with OAuth login delegated to the Esanj Auth Bridge, static/expirable access tokens, and granular, role‑based permissions.

Supports: Laravel 10 · 11 · 12 · 13 — PHP 8.2+

🧠 Overview

esanj/managers plugs a complete Manager subsystem into your Laravel app:

• 👤 Manager accounts with roles (admin, manager, operator) and per‑manager permissions stored in the DB.
• 🔐 Login via the Auth Bridge (OAuth), with an optional per‑manager static token as a second factor.
• 🪪 Stateless API access tokens (HMAC‑signed) for the JSON API, plus session login for the web panel.
• 🧱 A ready‑made web panel (list / create / edit / activity log) and a matching JSON API.
• 🚦 Built‑in caching, rate‑limiting, configurable route prefixes, and activity logging.

ℹ️ This package depends on esanj/auth-bridge, which performs the actual OAuth handshake. Configure it as well (its ACCOUNTING_BRIDGE_* env keys are listed below).

⚙️ Installation

composer require esanj/managers

Run the installer:

php artisan manager:install

The installer will:

1. Publish assets (vendor:publish --tag=esanj-manager-assets).
2. Optionally run php artisan migrate, then import default permissions (manager:permissions-import).
3. Append any missing .env keys (listed below) so you can fill them in.

Then create your first admin:

php artisan manager:create {esanj_id}

This prints a one‑time static token — copy it; it's stored hashed and can't be shown again.

🔐 Environment Variables

The installer ensures these keys exist in .env:

Other optional keys (all have sensible defaults — see Configuration): MANAGER_AUTH_ROUTE_PREFIX, MANAGER_LOGO_PATH, MANAGER_ACCESS_TOKEN_TTL, MANAGER_TOKEN_LENGTH, MANAGER_JUST_API, MANAGER_CACHE_ENABLED, MANAGER_CACHE_PREFIX, MANAGER_CACHE_TTL, MANAGER_RATE_LIMIT_ENABLED, MANAGER_RATE_LIMIT_MAX_ATTEMPTS, MANAGER_RATE_LIMIT_DECAY_SECONDS.

⚙️ Configuration

The config file is src/config/manager.php, merged under the key esanj.manager and publishable to config/esanj/manager.php:

php artisan vendor:publish --tag=esanj-manager-config

Default permissions

'permissions' => [
    'managers.list'   => ['display_name' => 'List Managers',   'description' => '...'],
    'managers.create' => ['display_name' => 'Create Manager',  'description' => '...'],
    'managers.edit'   => ['display_name' => 'Edit Managers',   'description' => '...'],
    'managers.delete' => ['display_name' => 'Delete Managers', 'description' => '...'],
],

Imported into the permissions table with php artisan manager:permissions-import.

🧰 Artisan Commands

🔐 Authentication Flows

API flow

• code (step 2) is the authorization code the Auth Bridge gives the user after OAuth login.
• requires_token tells you whether this manager needs to supply their static token in step 3.
• The access_token is an HMAC‑signed token (not a JWT), valid for access_token_expires_in minutes.

Web flow

1. Unauthenticated managers are redirected to the Auth Bridge (auth-bridge.redirect).
2. After OAuth, GET /{auth_prefix}/managers/token either logs them in (no static token needed) or shows the token form.
3. POST /{auth_prefix}/managers/token validates the static token and logs them into the manager session guard.
4. POST /{auth_prefix}/managers/logout logs out.

🌐 API Endpoints

All under the api_prefix (default api) and guarded by manager.auth:api (Bearer token) plus per‑action permission checks.

With defaults that means /api/managers, /api/managers/{manager}, etc.

🛡️ Middleware & Authorization

The package registers two middleware aliases:

It also defines a Gate for every permission key, so Blade @can and Gate checks work out of the box:

// Routes
Route::middleware(['manager.auth:web', 'manager.permission:managers.edit'])->group(function () {
    Route::get('/dashboard', [DashboardController::class, 'index']);
});

Route::middleware('manager.auth:api')->group(function () {
    Route::get('/reports', [ReportController::class, 'index']);
});

@can('managers.edit')
    <a href="...">Edit</a>
@endcan

Admins (role = admin) implicitly pass all permission checks.

📚 Documentation

For a complete, beginner‑friendly, step‑by‑step walkthrough — installing, the auth flows explained simply, adding a new permission, protecting your own page, injecting extra fields into the edit panel, API‑only mode, customizing views/translations, and troubleshooting — see docs/GUIDE.md.

📜 License

Released under the MIT License.