PHPackages azaharizaman/nexus-reporting - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. azaharizaman/nexus-reporting ActiveLibrary[Utility & Helpers](/categories/utility) azaharizaman/nexus-reporting ============================ Presentation layer package for generating scheduled, multi-format reports with distribution and retention management v0.1.0-alpha1(1mo ago)02↓100%MITPHPPHP ^8.3 Since May 5Pushed 1mo agoCompare [ Source](https://github.com/azaharizaman/nexus-reporting)[ Packagist](https://packagist.org/packages/azaharizaman/nexus-reporting)[ RSS](/packages/azaharizaman-nexus-reporting/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependencies (8)Versions (2)Used By (0) Nexus\\Reporting ================ [](#nexusreporting) **Presentation layer package for generating scheduled, multi-format reports with automated distribution and compliance-driven retention management.** Overview -------- [](#overview) `Nexus\Reporting` transforms raw analytics data from `Nexus\QueryEngine` into user-facing reports with: - **Scheduled Generation**: Daily, weekly, monthly, and cron-based report scheduling - **Multi-Format Export**: PDF, Excel, CSV, JSON, HTML via `Nexus\Export` - **Automated Distribution**: Email, SFTP, storage via `Nexus\Notifier` - **Tiered Retention**: 90-day active → 7-year archive → purge lifecycle - **Custom Templates**: Brand-aligned reports with logo/CSS customization - **Batch Processing**: High-volume report generation with concurrency control - **Permission Inheritance**: RBAC enforcement from underlying Analytics queries Architecture ------------ [](#architecture) ### 4-Tier Report Lifecycle [](#4-tier-report-lifecycle) ``` 1. Definition → 2. Generation → 3. Distribution → 4. Retention (Template) (Analytics) (Notifier) (Storage Tiers) ``` ### Core Components [](#core-components) - **`ReportManager`**: Public API orchestrator - **`ReportGenerator`**: Query execution → Export rendering - **`ReportDistributor`**: Multi-channel delivery with failure resilience - **`ReportJobHandler`**: Scheduler integration for recurring jobs - **`ReportRetentionManager`**: Automated tier transitions (Active → Archive → Purge) Key Features ------------ [](#key-features) ### Security (SEC-REP-0401) [](#security-sec-rep-0401) - Permission checks inherit from `AnalyticsAuthorizerInterface` - Users can only generate reports from authorized queries - Tenant isolation enforced via `TenantContextInterface` ### Resilience (REL-REP-0305) [](#resilience-rel-rep-0305) - Failed distributions preserve PDF for manual retry - Scheduler-based retry with exponential backoff - Transient failure detection and auto-recovery ### Performance (PER-REP-0301) [](#performance-per-rep-0301) - Jobs >5 seconds offloaded to queue workers - Streaming export for datasets >10K rows - Batch generation with configurable concurrency (max 10/tenant) ### Compliance [](#compliance) - **Tier 1 (Active)**: 90 days in hot storage - **Tier 2 (Archive)**: 7 years in deep archive (S3 Glacier) - **Tier 3 (Purge)**: Irreversible deletion - Full audit trail via `AuditLogManagerInterface` (High severity) Installation ------------ [](#installation) ``` composer require azaharizaman/nexus-reporting:*@dev ``` Usage ----- [](#usage) ### Create Report Definition [](#create-report-definition) ``` use Nexus\Reporting\Services\ReportManager; use Nexus\Reporting\ValueObjects\ReportFormat; use Nexus\Reporting\ValueObjects\ScheduleType; use Nexus\Reporting\ValueObjects\ReportSchedule; $reportId = $reportManager->createReport([ 'name' => 'Monthly Sales Report', 'query_id' => $analyticsQueryId, 'owner_id' => $userId, 'format' => ReportFormat::PDF, 'schedule' => new ReportSchedule( type: ScheduleType::MONTHLY, cronExpression: '0 9 1 * *', // 9 AM on 1st of month startsAt: new \DateTimeImmutable('2025-12-01'), endsAt: null, maxOccurrences: null ), 'recipients' => [$customer, $manager], 'template_config' => [ 'logo_path' => 'storage://logos/company.png', 'css_path' => 'storage://templates/invoice.css' ] ]); ``` ### Generate On-Demand Report [](#generate-on-demand-report) ``` $result = $reportManager->generateReport($reportId, [ 'start_date' => '2025-01-01', 'end_date' => '2025-01-31' ]); if ($result->isSuccessful()) { $filePath = $result->getFilePath(); // storage://reports/active/xyz.pdf $fileSize = $result->getFileSize(); } ``` ### Interactive Preview (FUN-REP-0213) [](#interactive-preview-fun-rep-0213) ``` // Returns QueryResultInterface without storage $queryResult = $reportManager->previewReport($reportId, [ 'customer_id' => '12345' ]); // Send to AJAX endpoint for real-time dashboard return response()->json($queryResult->getData()); ``` ### Batch Generation [](#batch-generation) ``` // Generate invoices for 1,000 customers $jobIds = $reportManager->generateBatch($reportId, $customerIds); // Scheduler processes with max 10 concurrent workers // Each job tracked independently with retry logic ``` Integration Points ------------------ [](#integration-points) ### Analytics [](#analytics) - Consumes `QueryResultInterface` from `AnalyticsManager::runQuery()` - Enforces guards and RBAC via `AnalyticsAuthorizerInterface` ### Export [](#export) - Transforms `QueryResult` → `ExportDefinition` → formatted output - Supports streaming for large datasets ### Notifier [](#notifier) - Multi-channel distribution (Email with PDF attachment, SMS alert, In-App) - Delivery status tracking in `reports_distribution_log` ### Scheduler [](#scheduler) - Registers `ReportJobHandler` for `JobType::EXPORT_REPORT` - Cron-based recurring report execution - Daily retention policy job for tier transitions ### Storage [](#storage) - Stores generated PDFs with temporary URLs for secure access - Supports multi-tier storage (hot → archive → purge) ### AuditLogger [](#auditlogger) - Logs generation, distribution, access, and retention events - High severity for compliance (report\_generated, report\_purged) Database Schema --------------- [](#database-schema) ### `reports_definitions` [](#reports_definitions) - Report templates with scheduling configuration - Links to Analytics queries via `query_id` - Custom template assets in `template_config` JSON ### `reports_generated` [](#reports_generated) - Immutable execution history - Storage paths and retention tiers - Performance metrics (duration\_ms, file\_size\_bytes) ### `reports_distribution_log` [](#reports_distribution_log) - Delivery tracking per recipient - Links to Notifier notifications - Failure diagnostics for retry Retention Policy ---------------- [](#retention-policy) TierDurationStoragePurpose**Active**90 daysHot (S3 Standard)Frequent access**Archive**7 yearsDeep (S3 Glacier)Compliance/Legal**Purged**PermanentDeletedGDPR/Data minimizationAutomated transitions run daily via scheduled job. Template Customization ---------------------- [](#template-customization) ### Default Templates (Option A) [](#default-templates-option-a) Clean, professional formatting via `Nexus\Export` defaults. ### Custom Templates (Option C - Advanced) [](#custom-templates-option-c---advanced) ``` 'template_config' => [ 'logo_path' => 'storage://assets/logo-v2.png', 'css_path' => 'storage://templates/branded.css', 'header_html' => 'Company Inc.', 'footer_html' => 'Page {page}', 'template_version' => '2.1.0' // Version control for rollback ] ``` Template assets stored in `Nexus\Storage` with version audit trail. Error Handling -------------- [](#error-handling) ### Exceptions [](#exceptions) - `ReportNotFoundException`: Report ID not found - `ReportGenerationException`: Analytics or Export failure - `ReportDistributionException`: Notifier delivery failure - `UnauthorizedReportException`: Permission violation (SEC-REP-0401) - `InvalidReportScheduleException`: Malformed cron or date range ### Resilience Patterns [](#resilience-patterns) - Scheduler retry with exponential backoff (transient failures) - PDF preservation on distribution failure (manual retry) - Format fallback (PDF fail → CSV succeed with warning notification) - Double tenant validation (defense-in-depth) Performance Considerations -------------------------- [](#performance-considerations) - **Preview Mode**: No storage overhead, ideal for dashboards - **Streaming Export**: Prevents memory exhaustion for >10K rows - **Batch Concurrency**: Max 10 concurrent jobs per tenant - **Queue Offloading**: Jobs >5s run asynchronously Requirements Coverage --------------------- [](#requirements-coverage) CodeRequirementImplementationFUN-REP-0201Create/Edit Report Templates`ReportManager::createReport()`FUN-REP-0207Scheduled Report Delivery`ReportSchedule` + `ReportJobHandler`FUN-REP-0213Interactive Dashboard Generation`ReportManager::previewReport()`BUS-REP-0105Output Format Control`ReportFormat` enum (PDF/Excel/CSV/JSON/HTML)SEC-REP-0401Permission Inheritance`AnalyticsAuthorizerInterface::can()` checksREL-REP-0305Report Generation ResiliencePDF storage on distribution failurePER-REP-0301Scheduled Report OffloadingScheduler queue for >5s jobs📖 Documentation --------------- [](#-documentation) ### Package Documentation [](#package-documentation) - [Getting Started Guide](docs/getting-started.md) - [API Reference](docs/api-reference.md) - [Integration Guide](docs/integration-guide.md) - [Examples](docs/examples/) ### Additional Resources [](#additional-resources) - `IMPLEMENTATION_SUMMARY.md` - Implementation progress - `REQUIREMENTS.md` - Requirements - `TEST_SUITE_SUMMARY.md` - Tests - `VALUATION_MATRIX.md` - Valuation License ------- [](#license) MIT License - See LICENSE file for details. ### Health Score 36 — LowBetter than 79% of packages Maintenance93 Actively maintained with recent releases Popularity3 Limited adoption so far Community9 Small or concentrated contributor base Maturity34 Early-stage or recently created project Bus Factor1 Top contributor holds 77% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 36d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/117408?v=4)[Azahari Zaman](/maintainers/azaharizaman)[@azaharizaman](https://github.com/azaharizaman) --- Top Contributors [![azaharizaman](https://avatars.githubusercontent.com/u/117408?v=4)](https://github.com/azaharizaman "azaharizaman (471 commits)")[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (139 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (2 commits)") ### Embed Badge ![Health badge](/badges/azaharizaman-nexus-reporting/health.svg) ``` [![Health](https://phpackages.com/badges/azaharizaman-nexus-reporting/health.svg)](https://phpackages.com/packages/azaharizaman-nexus-reporting) ``` ### Alternatives [laravel/framework The Laravel Framework. 34.7k532.1M19.2k](/packages/laravel-framework)[ecotone/ecotone Enterprise architecture layer for Laravel and Symfony — CQRS, Event Sourcing, Durable Workflows (Sagas, Orchestrators), Projections, and Outbox messaging via PHP attributes. 562565.8k41](/packages/ecotone-ecotone)[tempest/framework The PHP framework that gets out of your way. 2.2k31.1k11](/packages/tempest-framework)[web-auth/webauthn-lib FIDO2/Webauthn Support For PHP 1237.8M117](/packages/web-auth-webauthn-lib)[sulu/sulu Core framework that implements the functionality of the Sulu content management system 1.3k1.4M195](/packages/sulu-sulu)[web-auth/webauthn-framework FIDO2/Webauthn library for PHP and Symfony Bundle. 51090.8k2](/packages/web-auth-webauthn-framework) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)