README

A comprehensive Laravel SaaS package with Filament admin panel, user management, and subscription billing.

🚀 Recent Updates

v0.2.5 - Fixed Packagist version synchronization and improved auto-release workflow
v0.2.4 - Enhanced Git identity configuration in CI/CD pipeline
v0.2.0 - Added multi-panel support with admin, tenant, and member panels
v0.1.0 - Initial release with core SaaS functionality

Features

🔥 Filament Admin Panel - Beautiful, modern admin interface
👥 User Management - Complete user registration, authentication, and profile management
🔐 Role & Permission System - Powered by Spatie Laravel Permission
💳 Subscription Billing - Laravel Cashier integration with Stripe
🏢 Multi-tenancy Ready - Optional multi-tenant architecture
📧 Email Verification - Built-in email verification system
🔒 Two-Factor Authentication - Optional 2FA support
🚀 API Ready - RESTful API endpoints
📊 Dashboard Widgets - MRR charts, subscription stats, and product analytics
🎨 Customizable UI - Publishable views and configurable themes
🔧 Automated Releases - CI/CD pipeline with automated versioning and deployment
📦 Packagist Integration - Automatic package updates and distribution

Requirements

PHP 8.1 or higher
Laravel 10.0 or higher
MySQL/PostgreSQL database

User Model Requirements

The package uses your application's default User model (configured in config/auth.php). Your User model must include the Spatie Permission traits to enable role management:

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Spatie\Permission\Traits\HasRoles;

class User extends Authenticatable
{
    use HasRoles;

    // ... your existing code
}

If you don't have the Spatie Permission package installed, the installation command will install it for you.

Installation

1. Install the Package

composer require fullstack/redbird

2. Run the Installation Command

php artisan redbird:install

This command will:

Publish configuration files
Publish and run migrations
Seed roles and permissions from config
Generate Filament panel providers from config
Register panel providers in bootstrap/providers.php (Laravel 11+) or config/app.php
Publish Filament assets (CSS, JS) for proper styling
Configure Laravel Permissions
Set up Laravel Cashier (optional)

3. Create an Admin User

php artisan make:filament-user

4. Configure Your Environment

Add the following to your .env file:

# Redbird Configuration
REDBIRD_APP_NAME="Your SaaS App"
REDBIRD_ADMIN_PATH=admin

# Stripe Configuration (if using subscriptions)
STRIPE_KEY=your-stripe-publishable-key
STRIPE_SECRET=your-stripe-secret-key
STRIPE_WEBHOOK_SECRET=your-stripe-webhook-secret

# Feature Flags
REDBIRD_SUBSCRIPTIONS_ENABLED=true
REDBIRD_USER_REGISTRATION=true
REDBIRD_EMAIL_VERIFICATION=true

5. Troubleshooting CSS Issues

If you experience broken CSS in the admin panel, ensure Filament assets are properly published:

# Publish Filament assets manually if needed
php artisan vendor:publish --tag=filament-assets

# Clear cache and recompile assets
php artisan config:clear
php artisan cache:clear
php artisan view:clear

Usage

Accessing the Admin Panel

Visit /admin (or your configured admin path) to access the Filament admin panel.

Dashboard Widgets

Redbird includes several built-in dashboard widgets for SaaS analytics:

MRR Stats Widget - Monthly Recurring Revenue tracking
MRR Chart Widget - Visual MRR trends over time
Active Subscriptions Widget - Real-time subscription count
Product Stats Widget - Product performance metrics
Price Stats Widget - Pricing analytics

Subscription Management

The package includes comprehensive subscription management:

// Create a subscription
$user->newSubscription('default', 'price_123')->create();

// Check subscription status
if ($user->subscription('default')->active()) {
    // User has active subscription
}

// Handle subscription changes
$user->subscription('default')->swap('price_456');

Multi-Panel Architecture

Redbird supports multiple Filament panels for different user types:

Admin Panel (/admin) - For super admins and system management
Tenant Panel (/tenant) - For tenant/organization management
Member Panel (/member) - For end users and customers

Each panel can have its own:

Authentication guard
Domain/subdomain
Custom styling
Specific permissions

Configuration

The package configuration can be found in config/redbird.php. You can customize:

Panel Settings - Define multiple Filament panels with paths, domains, and guards
Subscription management
Multi-tenancy options
Feature flags
Default permissions and roles

Panel Configuration

Define your Filament panels in the panels section of the config:

'panels' => [
    'admin' => [
        'path' => env('REDBIRD_ADMIN_PATH', 'admin'),
        'domain' => env('REDBIRD_ADMIN_DOMAIN', null),
        'guard' => ['admin'],
    ],
    'tenant' => [
        'path' => env('REDBIRD_TENANT_PATH', 'tenant'),
        'domain' => env('REDBIRD_TENANT_DOMAIN', null),
        'guard' => ['tenant'],
    ],
    'member' => [
        'path' => env('REDBIRD_MEMBER_PATH', 'member'),
        'domain' => env('REDBIRD_MEMBER_DOMAIN', null),
        'guard' => ['web'],
    ],
],

During installation, this will generate:

app/Providers/Filament/AdminPanelProvider.php → /admin
app/Providers/Filament/TenantPanelProvider.php → /tenant
app/Providers/Filament/MemberPanelProvider.php → /member

Publishing Assets

You can publish specific assets using tags:

# Publish configuration only
php artisan vendor:publish --tag=redbird-config

# Publish migrations only
php artisan vendor:publish --tag=redbird-migrations

# Publish seeders only
php artisan vendor:publish --tag=redbird-seeders

# Publish views only
php artisan vendor:publish --tag=redbird-views

# Publish Filament assets (CSS, JS)
php artisan vendor:publish --tag=filament-assets

# Publish Filament resources for customization
php artisan vendor:publish --tag=redbird-filament

# Publish view components for customization
php artisan vendor:publish --tag=redbird-components

# Publish attributes for customization
php artisan vendor:publish --tag=redbird-attributes

# Force overwrite existing files
php artisan redbird:install --force

Note: The installation command will offer to publish Filament resources automatically. These resources include all the admin panel components and can be customized after publishing.

Commands

php artisan redbird:install - Install the package
php artisan redbird:install --force - Reinstall and overwrite existing files

Testing

vendor/bin/phpunit

Troubleshooting

Common Issues

User Model Missing HasRoles Trait If you get "Call to undefined method assignRole()" errors:

Ensure your User model includes use Spatie\Permission\Traits\HasRoles;
Run php artisan redbird:install again to set up roles

Existing Application Conflicts The installation command will detect potential conflicts in existing applications:

Existing User models
Already installed packages (Filament, Spatie Permissions, Cashier)
Conflicting database tables
Existing roles and permissions

Filament Panel Not Loading

Ensure you've run php artisan redbird:install
Check that panel providers are registered in your app
Verify your .env configuration matches the panel settings

License

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

fullstack / redbird

Maintainers

Details