README

English · 中文

Laravel 12 + Filament 4 out-of-the-box admin base package (free base, P1): ships 11 system modules + a menu engine + public persistence APIs.

FilamentForge treats the menus table as the single source of truth. Navigation, permissions, and resources are all derived from menu nodes, turning admin "assembly" into configuration rather than coding. The generator service-oriented client (P2 filament-forge-pro) depends on a remote D8 service. This package is the free base, providing a complete, runnable admin skeleton.

Features

Menu engine: the menus table drives the sidebar (four node types: directory / module / page / link). Navigation and permission gating are derived uniformly, eliminating orphan menu items.
11 system modules: Users, Tenants, Departments, Roles (Filament Shield), Dictionaries, Menu Management, System Logs (activitylog), Login Logs, Online Users, System Announcements, Invitation Management.
Multi-tenancy isolation: consolidated via TenantManager + TenantScope + HasTenant; super-admin has tenant_id = 0.
Department data permissions: 5 tiers (all / dept_tree / dept / self / deny), taking the broadest across multiple roles.
Permission bridge: resources/pages are registered through Shield; module nodes inject schema.methods to narrow permission points, avoiding the default 12 redundant entries.
Code generator core (P1): Skeleton\SkeletonWriter path gate + atomic writes + idempotent overwrite protection.
Audit & session governance: login auditing, online users, session tracking middleware.
Operational reach: system announcements + homepage message cards, with tenant/role targeting.
i18n & appearance: built-in 5 languages (Simplified Chinese / English / Traditional Chinese / Japanese / Korean) + top-bar language switcher + light/dark theme toggle.
Public persistence API: invitation acceptance public route /invitations/{token} (no login required).
Optional media library integration: once raise-studio/filament-media-library is installed, media fields such as avatars are automatically upgraded to MediaPicker; otherwise it falls back to native FileUpload (both work, the package does not hard-depend on it).

Requirements

Dependency	Version
PHP	`^8.2`
Laravel	`^12.0`
Filament	`^4.0`
ext deps	`bezhansalleh/filament-shield`, `spatie/laravel-permission`, `solution-forest/filament-tree`, `spatie/laravel-activitylog`, `spatie/laravel-translatable`, `raise-studio/filament-icon-picker`, `filament/spatie-laravel-settings-plugin` (all pulled in automatically by composer)

⚠️ raise-studio/filament-icon-picker is a hard dependency of this package (currently ^1.0, published on Packagist). Make sure it resolves, otherwise composer require will fail (see "Pre-release checklist" at the end).

Installation

One-command install (recommended)

# 1. Require the package (auto-registers ForgeServiceProvider)
composer require raise-studio/filament-forge

# 2. One-shot init: migrate → seed → Shield permissions → publish panel/config
php artisan raise:forge-install

After the command finishes:

Automatically generates (if not present) App\Providers\Filament\AdminPanelProvider extending ForgePanelProvider, and registers it in bootstrap/app.php;
Switches config/auth.php's providers.users.driver to forge-eloquent (login account lookup must be tenant-agnostic, Fix A);
Publishes filament-shield / spatie-permission / filament-forge config;
Syncs filament-tree front-end assets.

Visit /admin and log in with the default super-admin account:

Email: admin@example.com
Password: password

raise:forge-install is idempotent and can be run repeatedly (to re-run migrations/seed, add --force: php artisan raise:forge-install --force).

Manual installation (without the one-command)

If you want to control each step yourself:

composer require raise-studio/filament-forge

Publish config: php artisan vendor:publish --tag=filament-forge-config
Run migrations: php artisan migrate
Seed the base data: php artisan db:seed --class=RaiseStudio\\FilamentForge\\Database\\Seeders\\ForgeSeeder --force
Generate Shield permissions: php artisan shield:generate --all --panel=admin
Sync all permissions to the super_admin role (Shield does not grant full access by default)
Create a panel Provider extending RaiseStudio\FilamentForge\Panel\ForgePanelProvider (see "Panel integration" below)
Change config/auth.php's providers.users.driver to forge-eloquent
Clear caches: php artisan optimize:clear

Panel integration

The host's panel Provider only needs to extend ForgePanelProvider to get the standard admin (default id=admin / path=/admin / login page / Shield plugin / menu engine):

<?php

namespace App\Providers\Filament;

use RaiseStudio\FilamentForge\Panel\ForgePanelProvider;

class AdminPanelProvider extends ForgePanelProvider
{
    // In the subclass, you may call parent::panel($panel) inside panel() and append brand color, domain, extra plugins, etc.
}

raise:forge-install auto-generates the above starter and registers it in bootstrap/app.php when the host lacks this file.

Published assets

This package can override the following resources via vendor:publish (still auto-resolved from within the package when not published):

Tag	Content	Target path
`filament-forge-config`	Package config	`config/filament-forge.php`
`filament-forge-translations`	Translations	`resources/lang/vendor/forge`
`filament-forge-views`	Blade views	`resources/views/vendor/forge`

php artisan vendor:publish --tag=filament-forge-config
php artisan vendor:publish --tag=filament-forge-translations
php artisan vendor:publish --tag=filament-forge-views

Migrations run automatically via loadMigrationsFrom (landed by the migrate step of raise:forge-install; table prefix is determined by the DB connection prefix, resulting in rs_*). Do not copy migrations into the host's database/migrations, otherwise they would run twice with the auto-loading.

Configuration

config/filament-forge.php:

Key	Default	Description
`locales`	`en,zh_CN,zh_TW,ja,ko`	Enabled languages (override via `.env` `FILAMENT_FORGE_LOCALES`, e.g. `zh_CN,en`)
`tenancy_enabled`	`false`	Multi-tenancy switch (`.env`: `FILAMENT_FORGE_TENANCY_ENABLED`)
`menu_cache_ttl`	`60`	Menu navigation cache TTL (seconds)
`icon_fallback`	`heroicon-o-rectangle-stack`	Tree/fallback nav icon (heroicons has no `o-tree`/`sitemap`)
`generated_path`	`app/Filament/Generated`	Code generator output dir (generated zone, isolated from hand-written Custom zone)

Menu engine

The sidebar is fully driven by the menus table. node_type determines the node shape:

node_type	Meaning	Render target
`directory`	Group	Navigation group only
`module`	Module	Corresponding Filament Resource (built-in mapping or `App\Filament\Generated\Resources\{Module}Resource`)
`page`	Standalone page	Corresponding Filament Page (settings / dashboard / wizard / custom)
`link`	External link	Reuses Shield permission `View:ExternalLink{id}`, visible in the role editor's "Custom" group

Super-admins always see all nodes; non-super-admins are gated by canViewAny / canAccess / external-link permissions.
The Dashboard home is always shown to all logged-in users.
Generated outputs (app/Filament/Generated/{Resources,Pages,Settings}) are auto-registered via discoverResources / discoverPages, no manual Provider changes needed.

Optional dependency: media library

Once raise-studio/filament-media-library is installed, media fields such as user avatars are automatically upgraded to the media library picker (storing media_id); if not installed, it falls back to native FileUpload (storing a public disk path). Forge does not hard-depend on this package; both work.

composer require raise-studio/filament-media-library

Localization / i18n

5 languages enabled by default; the top-bar language switcher sits to the right of the global search box; the current language is highlighted.
The translation namespace is forge::; Shield override translation namespace is filament-shield:: (see resources/lang/shield-overrides).
To add a language: append the code to locales in config/filament-forge.php, and add the corresponding resources/lang/{code} files (you may copy the en directory and translate).

Upgrade

composer update raise-studio/filament-forge
php artisan raise:forge-install --force

--force re-runs migrations and seeds (idempotent writes do not break existing data), and re-syncs Shield permission points and panel assets.

Testing & development

composer test       # Run the Pest test suite (SQLite :memory:)
composer analyse    # PHPStan static analysis (level 5; pre-existing errors see phpstan-baseline.neon)
composer lint       # Batch php -l syntax check

The test suite is self-contained (orchestra/testbench + SQLite :memory:). Just run composer test; see CONTRIBUTING.md for details.

Pre-release checklist

Before publishing this package to Packagist (or your private source), confirm:

Internal hard dependency resolves: raise-studio/filament-icon-picker (^1.0, published on Packagist) must resolve, otherwise composer require fails.
Optional dependency resolves: raise-studio/filament-media-library is in require-dev (for tests) and listed as an optional runtime dependency in suggest; it must resolve or be documented as optional.
composer validate passes with no errors, and the version number and CHANGELOG.md are bumped per SemVer.
LICENSE / README.md / CHANGELOG.md / SECURITY.md are present, and the root contains .gitattributes (export-ignore to slim the dist).

raise-studio / filament-forge

Maintainers

Package info

Statistics

Security