README

Report generation and export management for Craft CMS with extensible data source support.

License

This is a commercial plugin licensed under the Craft License. It will be available on the Craft Plugin Store soon. See LICENSE.md for details.

⚠️ Pre-Release

This plugin is in active development and not yet available on the Craft Plugin Store. Features and APIs may change before the initial public release.

Features

Report Management

Saved Reports - Create and save report configurations for repeated use
Multiple Data Sources - Extensible architecture starting with Formie integration
Field Selection - Choose which fields to include in exports
Date Range Filtering - Filter data by today, last 7/30/90/365 days, or custom range
Multi-Site Support - Filter exports by site

Scheduled Reports

Automatic Generation - Schedule reports to run automatically
Flexible Scheduling - Every 6 hours, 12 hours, daily, or weekly
Queue Integration - Uses Craft's queue system for reliable background processing
Self-Rescheduling - Jobs automatically reschedule after completion

Export Formats

CSV - Universal format with BOM support for Excel compatibility
Excel (XLSX) - Native Excel format with styled headers, auto-sized columns, and frozen header row
JSON - Structured data for developers and API integrations

Export Management

Dashboard - View all generated exports with status, size, and download links
Automatic Cleanup - Configurable retention period for old exports
Flexible Storage - Store exports locally or in a Craft volume
Combined Exports - Merge multiple forms/entities into a single export file

Formie Integration

Form Selection - Export submissions from any Formie form
Field Mapping - Automatic field detection and selection
Submission Filtering - Filter by date range and site

Requirements

PHP 8.2+
Craft CMS 5.0+
LindemannRock Logging Library ^5.0 (installed automatically)
LindemannRock Base Plugin ^5.0 (installed automatically)
PhpSpreadsheet ^2.0 || ^3.0 (installed automatically)

Optional

Formie - Required for Formie data source

Installation

Via Composer (Development)

Until published on Packagist, install directly from the repository:

cd /path/to/project
composer config repositories.report-manager vcs https://github.com/LindemannRock/craft-report-manager
composer require lindemannrock/craft-report-manager:dev-main
./craft plugin/install report-manager

Via Composer (Production - Coming Soon)

Once published on Packagist:

cd /path/to/project
composer require lindemannrock/craft-report-manager
./craft plugin/install report-manager

Via Plugin Store (Future)

Go to the Plugin Store in your Craft control panel
Search for "Report Manager"
Click "Install"

Configuration

Config File

Create a config/report-manager.php file to override default settings:

<?php

use craft\helpers\App;

return [
    // Plugin name (displayed in CP)
    'pluginName' => 'Report Manager',

    // Scheduled Reports
    'enableScheduledReports' => true,
    'defaultSchedule' => 'daily2am',  // every6hours, every12hours, daily, daily2am, weekly

    // Export Settings
    'defaultExportFormat' => 'csv',  // csv, xlsx, json
    'maxExportBatchSize' => 10000,
    'exportRetention' => 30,  // days (0 = keep forever)
    'autoCleanupExports' => true,

    // CSV Settings
    'csvDelimiter' => ',',
    'csvEnclosure' => '"',
    'csvIncludeBom' => true,  // BOM for Excel compatibility

    // Storage
    'exportVolumeUid' => null,  // Volume UID for exports (null = local storage)
    'exportPath' => '@storage/report-manager/exports',  // Local path when not using volume

    // Display
    'defaultDateRange' => 'last30days',
    'itemsPerPage' => 50,
    'dashboardRefreshInterval' => 0,  // seconds (0 = disabled)

    // Logging
    'logLevel' => 'error',  // error, warning, info, debug
];

Environment-Specific Configuration

<?php

return [
    '*' => [
        'enableScheduledReports' => true,
        'defaultExportFormat' => 'xlsx',
    ],
    'production' => [
        'logLevel' => 'error',
        'exportRetention' => 90,
    ],
    'dev' => [
        'logLevel' => 'debug',
        'exportRetention' => 7,
    ],
];

Usage

Creating a Report

Navigate to Report Manager → Reports
Click New Report
Configure:
- Name - Descriptive name for the report
- Data Source - Select data source (e.g., Formie)
- Entity - Select form(s) to include
- Export Mode - Separate (one file per form) or Combined (all in one file)
- Fields - Select which fields to export
- Date Range - Filter by date
- Export Format - CSV, XLSX, or JSON
Save the report

Generating Exports

Manual Generation:

Go to Report Manager → Reports
Click on a report
Click Generate Export
Download from the exports list

Scheduled Generation:

Enable Auto Generate on a report
Set the schedule in Settings → General → Default Schedule
Exports generate automatically via queue

Viewing Exports

Navigate to Report Manager → Dashboard
View all generated exports
Filter by status (completed, failed, pending)
Download completed exports

Export Storage

Local Storage (default):

Exports saved to storage/report-manager/exports/
Configure path via exportPath setting

Volume Storage:

Create a volume in Craft (Settings → Filesystems → Volumes)
Go to Report Manager → Settings → Export
Select the volume
Exports saved to report-manager/exports/ within the volume

Scheduled Reports

Report Manager uses Craft's queue system for scheduled report generation.

How It Works

When enabled, the plugin pushes a ProcessScheduledReportsJob to the queue
The job checks for reports due for generation
After processing, it reschedules itself based on your schedule setting
Jobs appear in the queue as: Report Manager: Processing scheduled reports (Jan 24, 3:00am)

Queue Worker

Ensure your queue worker is running:

# Run queue listener
php craft queue/listen

# Or via cron (every minute)
* * * * * /path/to/craft queue/run

Schedule Options

Schedules use fixed time slots to prevent drift:

Setting	Fixed Times
`every6hours`	00:00, 06:00, 12:00, 18:00
`every12hours`	00:00, 12:00
`daily`	00:00 (midnight)
`daily2am`	02:00 (default)
`weekly`	Monday 00:00

Note: Manual report generation updates "Last Generated" but does not affect the schedule.

Export Formats

CSV

Universal compatibility
Optional BOM for Excel
Configurable delimiter and enclosure

Excel (XLSX)

Native Excel format
Bold headers with gray background
Auto-sized columns
Frozen header row (stays visible when scrolling)
Sheet name from entity/form name

JSON

Pretty-printed output
UTF-8 encoded
Array of objects with field names as keys

Permissions

Permission	Description
View Dashboard	View exports dashboard
View Reports	View saved reports
Manage Reports	Create, edit, delete reports (nested under View Reports)
View Exports	View export records
Create Exports	Generate new exports (nested under View Exports)
Download Exports	Download export files (nested under View Exports)
Delete Exports	Delete export records (nested under View Exports)
View Logs	Access plugin logs
Download Logs	Download log files (nested under View Logs)

Logging

Report Manager uses the LindemannRock Logging Library for centralized logging.

Log Levels

Error: Critical errors only (default)
Warning: Errors and warnings
Info: General information
Debug: Detailed debugging (requires devMode)

Configuration

// config/report-manager.php
return [
    'logLevel' => 'error',  // error, warning, info, debug
];

Note: Debug level requires Craft's devMode to be enabled. If set to debug with devMode disabled, it automatically falls back to info level.

Log Files

Location: storage/logs/report-manager-YYYY-MM-DD.log
Retention: 30 days (automatic cleanup via Logging Library)
Web Interface: View and filter logs at Report Manager → Logs

Data Sources

Report Manager uses an extensible data source architecture. Currently supported:

Formie

Export form submissions
Field-level selection
Date range filtering
Multi-site support
Combined exports from multiple forms

Adding Custom Data Sources

Data sources implement the DataSourceInterface:

interface DataSourceInterface
{
    public function getHandle(): string;
    public function getName(): string;
    public function getEntities(): array;
    public function getEntity(int $id): ?array;
    public function getEntityFields(int $entityId): array;
    public function exportToArray(int $entityId, array $fieldHandles, array $options): array;
}

Troubleshooting

Exports Not Generating

Check queue is running:
```
php craft queue/info
```
Check for failed jobs:
```
php craft queue/retry-all
```
Check logs:
```
CP → Report Manager → Logs
```

Enable debug logging:

// config/report-manager.php
return [
    'logLevel' => 'debug',
];

Scheduled Reports Not Running

Check Settings → General → Enable Scheduled Reports is enabled
Ensure queue worker is running
Check if job exists in queue (Utilities → Queue Manager)

XLSX Export Issues

Ensure PhpSpreadsheet is installed:
```
composer show phpoffice/phpspreadsheet
```
Check PHP memory limit for large exports
Try reducing maxExportBatchSize setting

Storage Permission Errors

Local storage: Ensure storage/report-manager/exports/ is writable
Volume storage: Check volume filesystem permissions

Support

Documentation: https://github.com/LindemannRock/craft-report-manager
Issues: https://github.com/LindemannRock/craft-report-manager/issues
Email: support@lindemannrock.com

License

This plugin is licensed under the Craft License. See LICENSE.md for details.

Developed by LindemannRock

lindemannrock / craft-report-manager

Maintainers

Details

README

License

⚠️ Pre-Release

Features

Report Management

Scheduled Reports

Export Formats

Export Management

Formie Integration

Requirements

Optional

Installation

Via Composer (Development)

Via Composer (Production - Coming Soon)

Via Plugin Store (Future)

Configuration

Config File

Environment-Specific Configuration

Usage

Creating a Report

Generating Exports

Viewing Exports

Export Storage

Scheduled Reports

How It Works

Queue Worker

Schedule Options

Export Formats

CSV

Excel (XLSX)

JSON

Permissions

Logging

Log Levels

Configuration

Log Files

Data Sources

Formie

Adding Custom Data Sources

Troubleshooting

Exports Not Generating

Scheduled Reports Not Running

XLSX Export Issues

Storage Permission Errors

Support

License