README

Filament App Version Manager

A comprehensive Filament plugin for managing mobile app versions with multilingual support, API endpoints, advanced configuration system, and production-ready features.

📚 Documentation

For comprehensive documentation, examples, and guides, visit the docs directory:

📖 Complete Documentation - Full documentation index
🚀 Quick Start Guide - Get started in 5 minutes
📦 Installation Guide - Step-by-step installation
⚙️ Configuration Examples - Basic and advanced configuration examples

✨ Features

🚀 Complete Version Management: Create, edit, and manage app versions for iOS, Android, and cross-platform releases
🌍 Multilingual Support: Full localization with JSON multilingual fields and API locale support
📱 Platform Support: iOS and Android platforms with Filament enum integration
🔄 Version Rollback: Built-in rollback functionality with proper validation
📊 API Integration: RESTful API endpoints with localization, caching, and rate limiting
⚡ Force Updates: Configure mandatory updates for critical releases
🧪 Beta Versions: Support for beta releases and testing
📈 Metadata Support: Store additional version metadata as JSON
🔒 Audit Trail: Track who created and updated versions with timestamps
🎨 Modern UI: Beautiful Filament interface with tabs, actions, and notifications
⚙️ Advanced Configuration: Fluent API with closure support for dynamic configuration
🔧 Highly Customizable: Override any configuration programmatically with method chaining
🌐 Navigation Localization: Proper localization support for navigation groups and labels
🔐 Production Ready: Comprehensive testing, error handling, and performance optimization

Requirements

PHP 8.1+
Laravel 10.0+ or 11.0+
Filament 3.0+

📦 Installation

Step 1: Install via Composer

composer require alareqi/filament-app-version-manager

Step 2: Publish Configuration

php artisan vendor:publish --tag="filament-app-version-manager-config"

Step 3: Publish and Run Migrations

php artisan vendor:publish --tag="filament-app-version-manager-migrations"
php artisan migrate

Step 4: Publish Translations (Optional)

php artisan vendor:publish --tag="filament-app-version-manager-translations"

Step 5: Register the Plugin

Add the plugin to your Filament panel provider:

use Alareqi\FilamentAppVersionManager\FilamentAppVersionManagerPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        // ... other configuration
        ->plugins([
            FilamentAppVersionManagerPlugin::make(),
        ]);
}

Step 6: Quick Setup Command (Optional)

Run the setup command for guided installation:

php artisan filament-app-version-manager:install

This command will:

Publish configuration files
Publish and run migrations
Provide setup instructions

⚙️ Configuration

The plugin configuration file is published to config/filament-app-version-manager.php. Here are the key configuration sections:

API Configuration

'api' => [
    'enabled' => true,                    // Enable/disable API endpoints
    'prefix' => 'api/version',           // API route prefix
    'middleware' => ['throttle:60,1'],   // Rate limiting middleware
    'cache_ttl' => 300,                  // Cache TTL in seconds
    'enable_stats' => false,             // Enable statistics endpoint
],

Navigation Configuration

'navigation' => [
    'group' => null,                     // Navigation group (null uses localized default)
    'sort' => 1,                         // Sort order in navigation
    'icon' => 'heroicon-o-rocket-launch', // Navigation icon
],

Feature Flags

'features' => [
    'multilingual_release_notes' => true, // Enable multilingual release notes
    'version_rollback' => true,           // Enable version rollback functionality
    'beta_versions' => true,              // Enable beta version support
    'force_update' => true,               // Enable force update functionality
    'metadata_storage' => true,           // Enable metadata storage
    'audit_trail' => true,                // Enable audit trail (created_by, updated_by)
],

Localization Settings

'localization' => [
    'supported_locales' => ['en', 'ar'],  // Supported locales for multilingual fields
    'default_locale' => 'en',             // Default locale for API fallback
    'fallback_locale' => 'en',            // Fallback locale when default is not available
],

Validation Rules

'validation' => [
    'max_version_length' => 20,           // Maximum version string length
    'max_build_number' => 99999,          // Maximum build number
    'max_release_notes_length' => 1000,   // Maximum release notes length per locale
],

Default Values

'defaults' => [
    'platform' => 'ios',                 // Default platform for new versions
    'is_active' => true,                  // Default active status
    'is_beta' => false,                   // Default beta status
    'force_update' => false,              // Default force update status
],

🔧 Advanced Plugin Configuration

The plugin supports a powerful fluent API with closure support for dynamic configuration. You can override any configuration value programmatically:

Basic Fluent API Usage

FilamentAppVersionManagerPlugin::make()
    ->navigationGroup('App Management')
    ->navigationSort(5)
    ->navigationIcon('heroicon-o-rocket-launch')
    ->enableApiRoutes(true)
    ->apiPrefix('api/v1/version')
    ->apiCacheTtl(600)
    ->maxVersionLength(25)
    ->defaultPlatform('ios')
    ->enableBetaVersions(false)
    ->enableForceUpdate(true)

Dynamic Configuration with Closures

Closures are evaluated at runtime, enabling dynamic configuration based on environment, user context, or other runtime conditions:

FilamentAppVersionManagerPlugin::make()
    // Dynamic navigation group based on user role
    ->navigationGroup(fn() => auth()->user()->isAdmin() ? 'Admin Tools' : 'App Management')

    // Environment-based API configuration
    ->enableApiRoutes(fn() => config('app.env') !== 'local')
    ->apiCacheTtl(fn() => config('app.env') === 'production' ? 3600 : 60)

    // Localized navigation group
    ->navigationGroup(fn() => __('filament-app-version-manager::app_version.navigation_group'))

    // Dynamic feature flags
    ->enableBetaVersions(fn() => config('app.debug'))
    ->enableForceUpdate(fn() => !app()->environment('testing'))

    // Complex validation rules
    ->maxVersionLength(fn() => config('app.env') === 'production' ? 20 : 50)

Configuration Override Methods

All configuration values can be overridden using fluent methods:

Navigation Configuration

->navigationGroup(string|Closure $group)
->navigationSort(int|Closure $sort)
->navigationIcon(string|Closure $icon)

API Configuration

->enableApiRoutes(bool|Closure $enabled)
->apiPrefix(string|Closure $prefix)
->apiCacheTtl(int|Closure $ttl)
->enableApiStats(bool|Closure $enabled)

Feature Configuration

->enableMultilingualReleaseNotes(bool|Closure $enabled)
->enableVersionRollback(bool|Closure $enabled)
->enableBetaVersions(bool|Closure $enabled)
->enableForceUpdate(bool|Closure $enabled)
->enableMetadataStorage(bool|Closure $enabled)
->enableAuditTrail(bool|Closure $enabled)

Validation Configuration

->maxVersionLength(int|Closure $length)
->maxBuildNumber(int|Closure $number)
->maxReleaseNotesLength(int|Closure $length)

Default Values Configuration

->defaultPlatform(string|Closure $platform)
->defaultIsActive(bool|Closure $active)
->defaultIsBeta(bool|Closure $beta)
->defaultForceUpdate(bool|Closure $forceUpdate)

Localization Configuration

->supportedLocales(array|Closure $locales)
->defaultLocale(string|Closure $locale)
->fallbackLocale(string|Closure $locale)

Bulk Configuration

You can also configure multiple values at once:

FilamentAppVersionManagerPlugin::make()
    ->configureUsing('api.enabled', true)
    ->configureUsing('api.cache_ttl', 3600)
    ->configureWith([
        'navigation.group' => 'System',
        'navigation.sort' => 10,
        'features.beta_versions' => false,
        'validation.max_version_length' => 30,
    ])

📱 Usage

Admin Panel

Once installed, you'll find the "App Versions" resource in your Filament admin panel. You can:

Create new app versions with release notes in multiple languages
Set platform-specific versions (iOS, Android)
Configure force updates and beta releases
Manage version rollbacks
View comprehensive version history
Export version data
Bulk actions for managing multiple versions

🌐 API Endpoints

The plugin provides RESTful API endpoints for version checking and management. All endpoints support caching and rate limiting.

Version Check Endpoint

POST /api/version/check

Check for available updates for a specific platform and version.

Request:

POST /api/version/check
Content-Type: application/json

{
    "platform": "ios",           // Required: "ios" or "android"
    "current_version": "1.0.0",  // Required: Current app version
    "locale": "en"               // Optional: Preferred locale for release notes
}

Response (without locale parameter):

{
    "success": true,
    "current_version": "1.0.0",
    "platform": "ios",
    "platform_label": "iOS",
    "update_available": true,
    "latest_version": "1.1.0",
    "force_update": false,
    "is_beta": false,
    "download_url": "https://apps.apple.com/app/yourapp",
    "release_date": "2025-07-01T10:00:00.000000Z",
    "release_notes": {
        "en": "Bug fixes and improvements",
        "ar": "إصلاح الأخطاء والتحسينات"
    },
    "metadata": {
        "app_size": "45.2 MB",
        "features": ["New UI", "Performance improvements"]
    },
    "checked_at": "2025-07-01T12:00:00.000000Z"
}

Localized API Responses

When a locale parameter is provided, the API returns localized content for that specific language. The key difference is that release_notes returns a single string value instead of an object.

Request with locale:

POST /api/version/check
Content-Type: application/json

{
    "platform": "ios",
    "current_version": "1.0.0",
    "locale": "ar"
}

Localized Response (with locale specified):

{
    "success": true,
    "current_version": "1.0.0",
    "platform": "ios",
    "platform_label": "iOS",
    "update_available": true,
    "latest_version": "1.1.0",
    "force_update": false,
    "download_url": "https://apps.apple.com/app/yourapp",
    "release_date": "2025-07-01T10:00:00.000000Z",
    "release_notes": "إصلاح الأخطاء والتحسينات",
    "checked_at": "2025-07-01T12:00:00.000000Z"
}

API Response Format Summary:

Without locale: release_notes is an object containing all available translations
With locale: release_notes is a string containing the localized text for the requested locale

Fallback Logic:

If the requested locale is not available, falls back to the default locale
If the default locale is not available, falls back to the fallback locale
If no locales are available, returns the first available translation
Maintains backward compatibility when no locale is specified

Response when no update available:

{
    "success": true,
    "current_version": "1.1.0",
    "platform": "ios",
    "platform_label": "iOS",
    "update_available": false,
    "latest_version": "1.1.0",
    "message": "You are using the latest version",
    "checked_at": "2025-07-01T12:00:00.000000Z"
}

Error Response:

{
    "success": false,
    "error": "Invalid platform specified",
    "message": "Platform must be one of: ios, android",
    "code": 422
}

Version Stats Endpoint (Optional)

GET /api/version/stats

Get version statistics and analytics (when enabled in configuration).

Response:

{
    "success": true,
    "total_versions": 15,
    "active_versions": 8,
    "beta_versions": 2,
    "platforms": {
        "ios": 6,
        "android": 7
    },
    "latest_versions": {
        "ios": "2.1.0",
        "android": "2.0.5"
    },
    "generated_at": "2025-07-01T12:00:00.000000Z"
}

API Configuration

Configure API behavior in your plugin registration:

FilamentAppVersionManagerPlugin::make()
    ->enableApiRoutes(true)
    ->apiPrefix('api/v1/version')           // Custom API prefix
    ->apiCacheTtl(3600)                     // Cache responses for 1 hour
    ->enableApiStats(true)                  // Enable stats endpoint
    ->apiMiddleware(['throttle:100,1'])     // Custom rate limiting

🌍 Multilingual Release Notes

The plugin provides comprehensive multilingual support for release notes with a user-friendly tabbed interface.

Configuration

Configure supported locales in your configuration file:

'localization' => [
    'supported_locales' => ['en', 'ar', 'fr', 'es', 'de'],
    'default_locale' => 'en',
],

Or configure dynamically:

FilamentAppVersionManagerPlugin::make()
    ->supportedLocales(['en', 'ar', 'fr'])
    ->defaultLocale('en')

Usage in Admin Panel

When creating or editing app versions, you'll see:

Language Tabs: Separate tabs for each configured locale
Individual Text Areas: Dedicated textarea for each language
Language Labels: Proper language names (e.g., "English", "العربية", "Français")
Validation: Ensure required locales have content

API Response

The format of release notes in API responses depends on whether a locale is specified:

Without locale parameter (all translations):

{
    "release_notes": {
        "en": "Bug fixes and performance improvements",
        "ar": "إصلاح الأخطاء وتحسينات الأداء",
        "fr": "Corrections de bugs et améliorations des performances"
    }
}

With locale parameter (single localized string):

{
    "release_notes": "Bug fixes and performance improvements"
}

Understanding API Response Formats

The Filament App Version Manager API returns different formats for the release_notes field depending on whether you specify a locale in your request:

Request Type	`release_notes` Format	Use Case
No locale parameter	Object with all translations	When you want to handle multiple languages client-side
With locale parameter	Single localized string	When you want pre-localized content for a specific language

Example Requests:

# Returns all translations
curl -X POST /api/version/check -d '{"platform":"ios","current_version":"1.0.0"}'

# Returns only English translation
curl -X POST /api/version/check -d '{"platform":"ios","current_version":"1.0.0","locale":"en"}'

This design allows maximum flexibility - use the format that best fits your application's localization strategy.

Programmatic Usage

Create versions with multilingual release notes:

use Alareqi\FilamentAppVersionManager\Models\AppVersion;
use Alareqi\FilamentAppVersionManager\Enums\Platform;

// Creating a version with multilingual release notes
AppVersion::create([
    'version' => '2.0.0',
    'platform' => Platform::IOS,
    'release_notes' => [
        'en' => 'Major update with new features',
        'ar' => 'تحديث كبير مع ميزات جديدة',
        'fr' => 'Mise à jour majeure avec de nouvelles fonctionnalités'
    ],
    'release_date' => now(),
    'download_url' => 'https://apps.apple.com/app/yourapp',
    'is_active' => true,
]);

// Note: The release_notes are stored as an array in the database,
// but the API response format depends on whether a locale is specified:
// - Without locale: returns the full array
// - With locale: returns the localized string for that locale

🎨 Customization

Model Relationships

If you have an Admin model, the plugin will automatically create relationships:

// In your Admin model
public function createdAppVersions()
{
    return $this->hasMany(AppVersion::class, 'created_by');
}

public function updatedAppVersions()
{
    return $this->hasMany(AppVersion::class, 'updated_by');
}

Database Schema

The plugin creates an app_versions table with the following structure:

id - Primary key
version - Version string (e.g., "1.0.0")
build_number - Optional build number
platform - Enum: ios, android
minimum_required_version - Minimum version required
release_notes - JSON multilingual field
release_date - Release date
download_url - App store URL
force_update - Boolean flag
is_active - Boolean flag
is_beta - Boolean flag
is_rollback - Boolean flag
metadata - JSON field for additional data
created_by - Foreign key to admin users
updated_by - Foreign key to admin users
created_at - Timestamp
updated_at - Timestamp

Translations

The plugin supports full bilingual functionality with translations for:

English (en)
Arabic (ar)

Translation files are located in:

lang/vendor/filament-app-version-manager/en/app_version.php
lang/vendor/filament-app-version-manager/ar/app_version.php

🧪 Testing

The plugin includes comprehensive test coverage with 58+ tests and 161+ assertions covering all functionality.

Running Tests

# Run all tests
vendor/bin/pest

# Run tests with coverage
vendor/bin/pest --coverage

# Run specific test file
vendor/bin/pest tests/ConfigurationOverrideTest.php

Creating Sample Data

Create sample app versions for testing:

use Alareqi\FilamentAppVersionManager\Models\AppVersion;
use Alareqi\FilamentAppVersionManager\Enums\Platform;

// Create a basic version
AppVersion::create([
    'version' => '1.0.0',
    'platform' => Platform::IOS,
    'release_date' => now(),
    'download_url' => 'https://apps.apple.com/app/yourapp',
    'release_notes' => [
        'en' => 'Initial release with core features',
        'ar' => 'الإصدار الأولي مع الميزات الأساسية'
    ],
    'is_active' => true,
]);

// Create a beta version
AppVersion::create([
    'version' => '2.0.0-beta',
    'build_number' => '200',
    'platform' => Platform::ANDROID,
    'release_date' => now()->addWeek(),
    'download_url' => 'https://play.google.com/store/apps/details?id=com.yourapp',
    'release_notes' => [
        'en' => 'Beta version with experimental features',
        'ar' => 'نسخة تجريبية مع ميزات تجريبية'
    ],
    'is_active' => true,
    'is_beta' => true,
    'metadata' => [
        'features' => ['New UI', 'Dark mode', 'Performance improvements'],
        'known_issues' => ['Minor UI glitches in landscape mode']
    ]
]);

// Create a force update version
AppVersion::create([
    'version' => '1.5.0',
    'platform' => Platform::IOS,
    'minimum_required_version' => '1.0.0',
    'release_date' => now(),
    'download_url' => 'https://yourapp.com/download',
    'release_notes' => [
        'en' => 'Critical security update - please update immediately',
        'ar' => 'تحديث أمني مهم - يرجى التحديث فوراً'
    ],
    'is_active' => true,
    'force_update' => true,
]);

Test Configuration

For testing purposes, you can override configuration:

// In your test setup
config([
    'filament-app-version-manager.api.enabled' => true,
    'filament-app-version-manager.api.cache_ttl' => 60,
    'filament-app-version-manager.localization.supported_locales' => ['en', 'ar'],
]);

🔧 Troubleshooting

Common Issues and Solutions

Plugin Not Appearing in Admin Panel

Problem: The App Versions resource doesn't appear in the Filament admin panel.

Solutions:

Ensure the plugin is registered in your panel provider:

->plugins([
    FilamentAppVersionManagerPlugin::make(),
])

Clear your application cache:

php artisan cache:clear
php artisan config:clear
php artisan view:clear

Ensure migrations have been run:
```
php artisan migrate
```

API Endpoints Not Working

Problem: API endpoints return 404 or are not accessible.

Solutions:

Ensure API routes are enabled:

FilamentAppVersionManagerPlugin::make()
    ->enableApiRoutes(true)

Check your route cache:

php artisan route:clear
php artisan route:cache

Verify the API prefix in your configuration matches your requests.

Multilingual Release Notes Not Showing

Problem: Language tabs are not appearing in the form.

Solutions:

Ensure multilingual feature is enabled:

'features' => [
    'multilingual_release_notes' => true,
],

Configure supported locales:

'localization' => [
    'supported_locales' => ['en', 'ar', 'fr'],
],

Clear configuration cache:
```
php artisan config:clear
```

Navigation Group Not Localized

Problem: Navigation group shows as "null" or doesn't use translations.

Solutions:

Publish and configure translations:

php artisan vendor:publish --tag="filament-app-version-manager-translations"

Set navigation group to null in config to use localized default:

'navigation' => [
    'group' => null, // Uses __('filament-app-version-manager::app_version.navigation_group')
],

Or set a custom localized group:

FilamentAppVersionManagerPlugin::make()
    ->navigationGroup(fn() => __('custom.navigation_group'))

Configuration Overrides Not Working

Problem: Plugin configuration overrides are not taking effect.

Solutions:

Ensure you're using the correct method names and syntax:

FilamentAppVersionManagerPlugin::make()
    ->navigationGroup('Custom Group')  // Correct
    ->setNavigationGroup('Custom Group') // Incorrect

For closure-based configuration, ensure closures return the expected type:
```
->enableApiRoutes(fn() => (bool) config('app.api_enabled'))
```
Clear all caches after configuration changes:
```
php artisan optimize:clear
```

Database Migration Issues

Problem: Migration fails or tables are not created properly.

Solutions:

Ensure you have proper database permissions.

Check for conflicting table names:

// In your configuration
'database' => [
    'table_name' => 'custom_app_versions',
],

Run migrations with verbose output:
```
php artisan migrate --verbose
```

Performance Issues

Problem: Admin panel or API responses are slow.

Solutions:

Enable API caching:

'api' => [
    'cache_ttl' => 3600, // Cache for 1 hour
],

Add database indexes if you have many records:

// In a new migration
Schema::table('app_versions', function (Blueprint $table) {
    $table->index(['platform', 'is_active']);
    $table->index(['version', 'platform']);
});

Use pagination for large datasets in the admin panel.

Debug Mode

Enable debug mode to get more detailed error information:

// In your .env file
APP_DEBUG=true

// Or temporarily in your plugin configuration
FilamentAppVersionManagerPlugin::make()
    ->configureUsing('debug', true)

Getting Help

If you're still experiencing issues:

Check the GitHub Issues for similar problems
Enable debug mode and check your Laravel logs
Ensure you're using compatible versions of PHP, Laravel, and Filament
Create a minimal reproduction case when reporting issues

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

Clone the repository
Install dependencies: composer install
Run tests: vendor/bin/pest
Check code style: vendor/bin/pint

Guidelines

Follow PSR-12 coding standards
Add tests for new features
Update documentation for any changes
Ensure all tests pass before submitting

📄 License

This package is open-sourced software licensed under the MIT license.

💬 Support

For support, please:

Check this documentation first
Search existing issues
Create a new issue with detailed information
Consider sponsoring the project for priority support

alareqi / filament-app-version-manager

Maintainers

Details

README

Filament App Version Manager

📚 Documentation

✨ Features

Requirements

📦 Installation

Step 1: Install via Composer

Step 2: Publish Configuration

Step 3: Publish and Run Migrations

Step 4: Publish Translations (Optional)

Step 5: Register the Plugin

Step 6: Quick Setup Command (Optional)

⚙️ Configuration

API Configuration

Navigation Configuration

Feature Flags

Localization Settings

Validation Rules

Default Values

🔧 Advanced Plugin Configuration

Basic Fluent API Usage

Dynamic Configuration with Closures

Configuration Override Methods

Navigation Configuration

API Configuration

Feature Configuration

Validation Configuration

Default Values Configuration

Localization Configuration

Bulk Configuration

📱 Usage

Admin Panel

🌐 API Endpoints

Version Check Endpoint

Localized API Responses

Version Stats Endpoint (Optional)

API Configuration

🌍 Multilingual Release Notes

Configuration

Usage in Admin Panel

API Response

Understanding API Response Formats

Programmatic Usage

🎨 Customization

Model Relationships

Database Schema

Translations

🧪 Testing

Running Tests

Creating Sample Data

Test Configuration

🔧 Troubleshooting

Common Issues and Solutions

Plugin Not Appearing in Admin Panel

API Endpoints Not Working

Multilingual Release Notes Not Showing

Navigation Group Not Localized

Configuration Overrides Not Working

Database Migration Issues

Performance Issues

Debug Mode

Getting Help

🤝 Contributing

Development Setup

Guidelines

📄 License

💬 Support