Filament plugin for managing help articles

This plugin adds help article management to Filament with admin, frontend, and guest panel capabilities.

Version Compatibility

Filament	Filament Help
4.x	1.x

Installation

You can install the package via Composer:

composer require tapp/filament-help

You can publish the config file with:

php artisan vendor:publish --tag="filament-help-config"

This is the contents of the published config file:

return [

    /*
    |--------------------------------------------------------------------------
    | Help Article Model
    |--------------------------------------------------------------------------
    |
    | If you extend the HelpArticle model in your application to add custom
    | relationships (e.g., tenant relationships), specify your extended model here.
    | This ensures Filament resources use your extended model instead of the base model.
    |
    | Example: \App\Models\HelpArticle::class
    |
    */

    'model' => \Tapp\FilamentHelp\Models\HelpArticle::class,

    /*
    |--------------------------------------------------------------------------
    | Tenancy Configuration
    |--------------------------------------------------------------------------
    |
    | Configure multi-tenancy settings for help articles.
    |
    */

    'tenancy' => [
        /*
         * Enable or disable tenancy features globally.
         * When enabled, a team_id column will be added to the help_articles table
         * and articles will be scoped to the current tenant.
         */
        'enabled' => env('FILAMENT_HELP_TENANCY_ENABLED', false),

        /*
         * The column name for the tenant relationship.
         * This column will be added to the help_articles table if tenancy is enabled.
         * E.g. 'team_id'
         */
        'column' => env('FILAMENT_HELP_TENANCY_COLUMN', null),

        /*
         * The tenant model class.
         * This should be the same model you use for Filament's tenant feature.
         * E.g. \App\Models\Team::class
         */
        'model' => null,

        /*
         * The relationship name on the HelpArticle model.
         * This is used for Filament's tenant ownership relationship.
         * E.g. 'team'
         *
         */
        'relationship' => env('FILAMENT_HELP_TENANCY_RELATIONSHIP', null),

        /*
         * The foreign key constraint configuration.
         */
        'foreign_key' => [
            'on_delete' => env('FILAMENT_HELP_TENANCY_ON_DELETE', 'cascade'), // cascade, set null, restrict
            'on_update' => env('FILAMENT_HELP_TENANCY_ON_UPDATE', 'cascade'), // cascade, set null, restrict
        ],

        /*
         * Enable tenancy scoping per panel type.
         * When false, articles will not be scoped by tenant even if global tenancy is enabled.
         */
        'scoping' => [
            'admin' => env('FILAMENT_HELP_TENANCY_SCOPE_ADMIN', true),
            'frontend' => env('FILAMENT_HELP_TENANCY_SCOPE_FRONTEND', true),
            'guest' => env('FILAMENT_HELP_TENANCY_SCOPE_GUEST', true),
        ],

        /*
         * Automatically assign tenant on creation.
         * When enabled, new articles will automatically get the current tenant ID assigned.
         */
        'auto_assign' => env('FILAMENT_HELP_TENANCY_AUTO_ASSIGN', true),
    ],

];

You can publish the migrations with:

php artisan vendor:publish --tag="filament-help-migrations"

Warning

If you are using multi-tenancy please see the "Multi-Tenancy Support" instructions below before publishing and running migrations.

You can run the migrations with:

php artisan migrate

Using the Plugins

Admin Plugin (for editing help articles)

Add this plugin to your admin panel for full CRUD operations. E.g. in app/Providers/Filament/AdminPanelProvider.php:

use Tapp\FilamentHelp\FilamentHelpPlugin;
 
public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->plugins([
            FilamentHelpPlugin::make(),
            //...
        ]);
}

Location: Admin panel (typically /admin/help-articles)
Access: Authenticated admin users only
Features: Create, edit, delete, and manage all help articles

Frontend Plugin (for authenticated users)

Add this plugin to your authenticated user panel for read-only access:

use Tapp\FilamentHelp\FilamentHelpFrontendPlugin;
 
public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->plugins([
            FilamentHelpFrontendPlugin::make(),
            // Default slug is 'help-articles', so articles will be at {panel-path}/help-articles
            // Customize with:
            // ->slug('custom-slug')
        ]);
}

Configuration Options:

• Plugin method: ->slug('custom-slug') - Set the URL slug when registering the plugin (defaults to 'help-articles' if not specified)

Location: App panel (defaults to {panel-path}/help-articles, configurable via ->slug())
Access: Authenticated users only
Features: Read-only access to public help articles

Guest Plugin (for public access)

Add this plugin to a guest panel (without authentication) for public access:

use Tapp\FilamentHelp\FilamentHelpGuestPlugin;
 
public function panel(Panel $panel): Panel
{
    return $panel
        ->id('guest')
        ->path('') // Panel path (empty = root, or set to your desired base path)
        // ... other panel configuration
        // Note: Do NOT add authMiddleware() for guest access
        ->plugins([
            FilamentHelpGuestPlugin::make(),
            // Default slug is 'help', so articles will be at /help (or {panel-path}/help)
            // Customize with:
            // ->slug('custom-slug')
        ]);
}

Configuration Options:

• Plugin method: ->slug('custom-slug') - Set the URL slug when registering the plugin (defaults to 'help' if not specified)
• Slug requirement: Slug must be a non-empty string

Location: Guest panel (defaults to {panel-path}/help, configurable via ->slug())
Access: Public (no authentication required)
Features: Read-only access to public help articles for guests

Help Article Locations

Help articles are available in three different locations depending on your setup:

1. Admin Panel (/admin/help-articles): For editing and managing help articles
2. App Panel (configurable, default {panel-path}/help-articles): For authenticated users to view public help articles
3. Guest Panel (configurable, default {panel-path}/help): For public/guest users to view public help articles

The frontend and guest panel URLs can be customized using the plugin's ->slug() method when registering the plugin (see plugin documentation above).

Features

• Admin Panel: Full CRUD operations for help articles
• Frontend/Guest: Read-only access to public help articles
• Rich Content: HTML content support with iframe embedding
• Public/Private: Control article visibility with is_public flag
• Hidden/Draft: Hide articles from public view with is_hidden flag (useful for drafts or archived articles)
• Search & Filter: Find articles by name and filter by public/hidden status
• Multi-Tenancy Support: Optionally scope help articles to teams/organizations

Multi-Tenancy Support

This package supports Filament's multi-tenancy feature, allowing you to scope help articles to specific teams or organizations.

Setting Up Multi-Tenancy

⚠️ Important: Configure Before Migration

You MUST enable and configure tenancy BEFORE running migrations! The migrations check the tenancy configuration to determine whether to add tenant columns to the database tables. Enabling tenancy after running migrations will require manual database modifications.

1. Enable tenancy in the config file:

Publish the config file:

php artisan vendor:publish --tag="filament-help-config"

Then update config/filament-help.php:

return [
    'tenancy' => [
        'enabled' => true, // Enable tenancy
        'model' => \App\Models\Team::class, // Your tenant model
        'column' => 'team_id', // Column name in help_articles table
        'relationship' => 'team', // Relationship name
        
        // Scoping per panel type
        'scoping' => [
            'admin' => true,     // Scope articles in admin panel
            'frontend' => true,  // Scope articles in frontend panel
            'guest' => false,    // Don't scope in guest panel (shared articles)
        ],
        
        'auto_assign' => true, // Auto-assign current tenant to new articles
    ],
];

Or use environment variables in your .env file:

FILAMENT_HELP_TENANCY_ENABLED=true
FILAMENT_HELP_TENANCY_COLUMN=team_id
FILAMENT_HELP_TENANCY_RELATIONSHIP=team
FILAMENT_HELP_TENANCY_SCOPE_ADMIN=true
FILAMENT_HELP_TENANCY_SCOPE_FRONTEND=true
FILAMENT_HELP_TENANCY_SCOPE_GUEST=false

2. Add the tenant relationship to your HelpArticle model:

Since the package needs to support various tenant models (Team, Organization, etc.), you need to define the relationship in your application.

Extend the HelpArticle model in your application:

// app/Models/HelpArticle.php
<?php

declare(strict_types=1);

namespace App\Models;

use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Tapp\FilamentHelp\Models\HelpArticle as BaseHelpArticle;

final class HelpArticle extends BaseHelpArticle
{
    /**
     * Get the team that owns the help article.
     */
    public function team(): BelongsTo
    {
        return $this->belongsTo(\App\Models\Team::class);
    }
}

Or if you use a different tenant model:

public function organization(): BelongsTo
{
    return $this->belongsTo(\App\Models\Organization::class);
}

Important: Make sure the relationship name matches the relationship config value you set (e.g., 'team' or 'organization').

Then, update your config to use your extended model:

// config/filament-help.php
return [
    'model' => \App\Models\HelpArticle::class,
    
    'tenancy' => [
        'enabled' => true,
        'model' => \App\Models\Team::class,
        'column' => 'team_id',
        'relationship' => 'team',
        // ...
    ],
];

3. Run migrations:

When tenancy is enabled, the migration will automatically add the tenant column to the help_articles table:

php artisan migrate

4. Configure your Filament panel with tenancy:

// In your AdminPanelProvider.php (or wherever you configure your Filament panel)
use Tapp\FilamentHelp\FilamentHelpPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->tenant(\App\Models\Team::class) // Your tenant model
        // ... other configuration
        ->plugins([
            FilamentHelpPlugin::make(),
        ]);
}

How It Works

When tenancy is enabled:

• Migration: The team_id column (or your custom column name) is automatically added to the help_articles table during migration
• Admin Panel: Help articles are automatically scoped to the current tenant. Users can only see and manage articles belonging to their team.
• Auto-assignment: When creating a new help article, the tenant ID is automatically assigned to the current tenant.
• Frontend/Guest: You can control whether tenancy scoping applies to frontend and guest panels using the config.

Configuration Options

Tenancy Column

Change the column name if you use a different naming convention:

'column' => 'organization_id',

Tenant Model

Specify your tenant model:

'model' => \App\Models\Organization::class,

Scoping Control

Control which panels apply tenant scoping:

'scoping' => [
    'admin' => true,      // Articles scoped by tenant in admin
    'frontend' => true,   // Articles scoped by tenant in frontend
    'guest' => false,     // Articles shared across all tenants in guest panel
],

Foreign Key Constraints

Configure cascade behavior:

'foreign_key' => [
    'on_delete' => 'cascade', // or 'set null', 'restrict'
    'on_update' => 'cascade', // or 'set null', 'restrict'
],

Disabling Tenancy

By default, tenancy is disabled. Help articles are shared across all teams. To use this package without tenancy, simply leave the config as default or set:

FILAMENT_HELP_TENANCY_ENABLED=false

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Tapp Network
• All Contributors

License

The MIT License (MIT). Please see License File for more information.