Download the PHP package alareqi/filament-app-version-manager without Composer

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+
• Filament 3.0+

📦 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

Add the plugin to your Filament panel provider:

Step 6: Quick Setup Command (Optional)

Run the setup command for guided installation:

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

Navigation Configuration

Feature Flags

Localization Settings

Validation Rules

Default Values

🔧 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

Dynamic Configuration with Closures

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

Configuration Override Methods

All configuration values can be overridden using fluent methods:

Navigation Configuration

API Configuration

Feature Configuration

Validation Configuration

Default Values Configuration

Localization Configuration

Bulk Configuration

You can also configure multiple values at once:

📱 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:

Response (without locale parameter):

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:

Localized Response (with locale specified):

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:

Error Response:

Version Stats Endpoint (Optional)

GET /api/version/stats

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

Response:

API Configuration

Configure API behavior in your plugin registration:

🌍 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:

Or configure dynamically:

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):

With locale parameter (single localized string):

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:

Example Requests:

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

Programmatic Usage

Create versions with multilingual release notes:

🎨 Customization

Model Relationships

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

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

Creating Sample Data

Create sample app versions for testing:

Test Configuration

For testing purposes, you can override configuration:

🔧 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:

1. Ensure the plugin is registered in your panel provider:

2. Clear your application cache:

3. Ensure migrations have been run:

API Endpoints Not Working

Problem: API endpoints return 404 or are not accessible.

Solutions:

1. Ensure API routes are enabled:

2. Check your route cache:

3. 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:

1. Ensure multilingual feature is enabled:

2. Configure supported locales:

3. Clear configuration cache:

Navigation Group Not Localized

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

Solutions:

1. Publish and configure translations:

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

3. Or set a custom localized group:

Configuration Overrides Not Working

Problem: Plugin configuration overrides are not taking effect.

Solutions:

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

2. For closure-based configuration, ensure closures return the expected type:

3. Clear all caches after configuration changes:

Database Migration Issues

Problem: Migration fails or tables are not created properly.

Solutions:

1. Ensure you have proper database permissions.

2. Check for conflicting table names:

3. Run migrations with verbose output:

Performance Issues

Problem: Admin panel or API responses are slow.

Solutions:

1. Enable API caching:

2. Add database indexes if you have many records:

3. Use pagination for large datasets in the admin panel.

Debug Mode

Enable debug mode to get more detailed error information:

Getting Help

If you're still experiencing issues:

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

🤝 Contributing

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

Development Setup

1. Clone the repository
2. Install dependencies: composer install
3. Run tests: vendor/bin/pest
4. 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:

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