Installation
System Requirements
- PHP 8.2 or higher
- Filament 3.x, 4.x, or 5.x
Version Compatibility
- Filament 3.x: Use Data Lens ^1.0.0
- Filament 4.x: Use Data Lens ^2.0.0
- Filament 5.x: Use Data Lens ^3.0.0
Quick Start
1. Purchase License
Purchase a Data Lens license from Privato.
2. Configure Composer Repository & Authenticate
In your project root, run:
composer config repositories.padmission composer https://padmission.privato.pub/composer
composer config --auth http-basic.padmission.privato.pub "<your-email>" "<your-license-key>"
The first command writes the repository entry to composer.json. The second command writes your license credentials to auth.json (which should be gitignored).
Authentication Details
- Email: The email address associated with your Privato license. Find it in your Privato dashboard.
- License Key: Your license key from the Privato dashboard.
Fingerprinted licenses: Append the fingerprint to the key with a colon — pass "<your-license-key>:<your-fingerprint>" as the third argument to composer config --auth.
Unassigned licenses: If your license is not assigned to a specific licensee, substitute unlock for <your-email> in the command above.
3. Install Package
For Filament 3.x:
composer require padmission/data-lens:"^1.0.0"
For Filament 4.x:
composer require padmission/data-lens:"^2.0.0"
For Filament 5.x:
composer require padmission/data-lens:"^3.0.0"
4. Run Interactive Installer
php artisan data-lens:install
The installer will:
- Detect existing Filament panels
- Publish migrations and configuration
- Run database migrations
- Configure the plugin with your preferences
- Register the plugin in your panel provider(s)
- Suggest security configurations
5. Configure Theme
Add Data Lens to your Filament theme to ensure all styles are included. If you have not yet created a custom theme, follow the Filament theming documentation to create one.
Filament 4.x / 5.x (Tailwind CSS 4)
Add to your theme.css:
@source '../../../../vendor/padmission/data-lens';
Filament 3.x (Tailwind CSS 3)
Add to your theme CSS:
@import '../../../../vendor/awcodes/filament-table-repeater/resources/css/plugin.css';
Update tailwind.config.js:
content: [
// ... existing paths
'./vendor/awcodes/filament-table-repeater/resources/**/*.blade.php',
]
Then rebuild your theme assets:
npm run build
Upgrading Data Lens
Data Lens ships its database migrations as publishable files (the same model Laravel uses for first-party packages). They are copied into your application's database/migrations directory and run from there — they are not executed directly from the vendor directory. This means a new release that adds a migration requires you to publish it and run migrate.
Recommended: keep resources in sync automatically
Add data-lens:upgrade to your application's composer.json so new migrations are published and caches cleared after every composer update:
"scripts": {
"post-autoload-dump": [
"@php artisan data-lens:upgrade"
]
}
Then a normal upgrade is just:
composer update padmission/data-lens
php artisan migrate
data-lens:upgrade publishes new migrations and clears caches; it does not run migrations, so your deploy pipeline's php artisan migrate step stays in control.
Manual upgrade
If you prefer not to use the hook:
composer update padmission/data-lens
php artisan vendor:publish --tag=data-lens-migrations
php artisan migrate
Verify your schema is current
php artisan data-lens:check
Exits non-zero and lists any pending migrations when your schema is behind the installed version. php artisan about reports the same status. When the schema is behind, the panel also shows a warning banner (disable with data-lens.schema_check.show_admin_warning => false).
Configuration
Basic Configuration
use Padmission\DataLens\DataLensPlugin;
public function panel(Panel $panel): Panel
{
return $panel
->plugins([
DataLensPlugin::make()
]);
}
Multi-Panel Support
Data Lens fully supports multiple Filament panels with independent configurations.
Example: Different Panels with Different Settings
// AdminPanelProvider.php
public function panel(Panel $panel): Panel
{
return $panel
->id('admin')
->plugins([
DataLensPlugin::make()
->navigationLabel('Admin Reports')
->apiEnabled() // API enabled for admin panel
->modelDirectories([
'app/Models',
'app/Admin/Models',
])
]);
}
// UserPanelProvider.php
public function panel(Panel $panel): Panel
{
return $panel
->id('user')
->plugins([
DataLensPlugin::make()
->navigationLabel('My Reports')
// API not enabled for user panel
->modelDirectories([
'app/Models',
'app/User/Models',
])
]);
}
Full Configuration Example
->plugins([
DataLensPlugin::make()
->navigationLabel('Reports')
->navigationIcon('heroicon-o-chart-bar')
->navigationSort(10)
->navigationGroup('Analytics')
->cluster('analytics') // Optional cluster
->modelDirectories([
'app/Models',
'domain/Models',
])
->apiEnabled()
->exportsEnabled()
->exportFormats(['csv', 'xlsx'])
->defaultExportFormat('xlsx')
->useTimestampsInFilename(false)
->schedulingEnabled()
])
Plugin Configuration Options
Per-Panel Configuration
These settings can be configured independently for each panel:
Resource Configuration
- ->slug(string $slug) - URL slug (Filament 4.x / 5.x only - for v3 use config file)
- ->shouldRegisterNavigation(bool $register) - Show/hide in navigation
- ->navigationLabel(string $label) - Navigation menu label
- ->navigationIcon(string $icon) - Heroicon name
- ->navigationSort(int $sort) - Navigation order
- ->navigationGroup(string $group) - Navigation group
- ->cluster(string $cluster) - Assign to Filament cluster
Model Configuration
- ->modelDirectories(array $directories) - Configure model discovery per panel
API Configuration
- ->apiEnabled(bool $enabled) - Enable API access for this panel
Export Configuration
- ->exportsEnabled(bool $enabled) - Enable/disable exports
- ->exportFormats(array $formats) - Available formats: ['csv', 'xlsx']
- ->defaultExportFormat(string $format) - Default export format
- ->useTimestampsInFilename(bool $use) - Include timestamps in filenames
Scheduling Configuration
- ->schedulingEnabled(bool $enabled) - Enable report scheduling for this panel
Global Configuration
These settings are configured in the config/data-lens.php file and apply globally:
- Resource Slug (Filament v3 only) - Configure in slug (e.g., 'slug' => 'reports')
- API IP Whitelisting - Configure in api.ip_whitelist
- Export Queue Settings - Configure in exports.should_queue and exports.chunk_size
- Email Settings - Configure sender email/name in scheduling.from_email and scheduling.from_name
- Attachment Limits - Configure in scheduling.max_attachment_size
- Tenant Configuration - All tenant-related settings
- Cache Settings - All cache configuration
Manual Installation
If you prefer to manually configure Data Lens instead of using the interactive installer:
1. Configure Theme
Follow the theme configuration in Step 5 above.
2. Publish and Run Migrations
php artisan vendor:publish --tag="data-lens-migrations"
Important: For multi-tenant support, configure tenant_aware = true in the config file before running migrations.
📖 Setting up multi-tenancy? See the complete Multi-Tenant Setup Guide for step-by-step instructions.
php artisan migrate
3. Register the Plugin
In your Filament panel provider:
use Padmission\DataLens\DataLensPlugin;
public function panel(Panel $panel): Panel
{
return $panel
->plugins([
DataLensPlugin::make()
]);
}
4. Configure Scheduled Reports (Optional)
To enable scheduled reports, add this to your Laravel scheduler:
Use Illuminate\Support\Facades\Schedule;
Schedule::command('data-lens:check-scheduled-reports')->everyMinute();
Add to routes/console.php (Laravel 11) or app/Console/Kernel.php (Laravel 10 and earlier).
Verification
After installation:
- Visit your Filament admin panel
- Look for "Custom Reports" in the navigation
- Create your first report to test functionality