PHPackages azaharizaman/nexus-statutory - 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-statutory ActiveLibrary[Utility & Helpers](/categories/utility) azaharizaman/nexus-statutory ============================ Statutory reporting engine for generating tax and regulatory reports in country-specific formats v0.1.0-alpha1(1mo ago)00MITPHPPHP ^8.3 Since May 5Pushed 1mo agoCompare [ Source](https://github.com/azaharizaman/nexus-statutory)[ Packagist](https://packagist.org/packages/azaharizaman/nexus-statutory)[ RSS](/packages/azaharizaman-nexus-statutory/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependencies (2)Versions (2)Used By (0) Nexus\\Statutory ================ [](#nexusstatutory) Statutory reporting engine for generating tax and regulatory reports in country-specific formats (XBRL, JSON, XML, CSV). Overview -------- [](#overview) The Statutory package provides a framework-agnostic engine for generating statutory reports required by regulatory authorities. It supports multiple output formats and can be extended with country-specific adapters for compliance with local regulations. Features -------- [](#features) - **Report Generation**: Generate statutory reports (P&L, Balance Sheet, Tax Forms, Payroll Reports) - **Multiple Formats**: Support for JSON, XML, XBRL, CSV, PDF, Excel - **Default Adapters**: Built-in default implementations for basic accounting and payroll - **Country-Specific Adapters**: Extensible architecture for country-specific requirements - **Metadata Management**: Comprehensive report metadata (schema, validation, filing frequency) - **Validation Engine**: Schema validation before report submission - **Framework-Agnostic**: Pure PHP with no Laravel dependencies Installation ------------ [](#installation) ``` composer require azaharizaman/nexus-statutory ``` Architecture ------------ [](#architecture) This package follows the Nexus architecture principles: - **Framework-Agnostic**: No Laravel dependencies in core services - **Contract-Driven**: All external dependencies defined via interfaces - **Adapter Pattern**: Country-specific implementations via adapters - **Default Implementations**: Safe defaults for basic functionality - **Value Objects**: Immutable objects for domain concepts (FilingFrequency, ReportFormat) ### Package Structure [](#package-structure) ``` packages/Statutory/ ├── composer.json ├── LICENSE ├── README.md └── src/ ├── Contracts/ # Interfaces │ ├── PayrollStatutoryInterface.php │ ├── ReportMetadataInterface.php │ ├── StatutoryReportInterface.php │ ├── StatutoryReportRepositoryInterface.php │ └── TaxonomyReportGeneratorInterface.php ├── Adapters/ # Default implementations │ ├── DefaultAccountingAdapter.php │ └── DefaultPayrollStatutoryAdapter.php ├── Services/ # Business logic │ └── StatutoryReportManager.php ├── ValueObjects/ # Immutable domain objects │ ├── FilingFrequency.php │ └── ReportFormat.php └── Exceptions/ # Domain exceptions ├── CalculationException.php ├── DataExtractionException.php ├── InvalidDeductionTypeException.php ├── InvalidReportTypeException.php ├── ReportNotFoundException.php └── ValidationException.php ``` Usage ----- [](#usage) ### Generating Statutory Reports [](#generating-statutory-reports) ``` use Nexus\Statutory\Services\StatutoryReportManager; use Nexus\Statutory\ValueObjects\ReportFormat; // Generate a profit & loss report $reportId = $reportManager->generateReport( tenantId: 'tenant-123', reportType: 'profit_loss', startDate: new DateTimeImmutable('2025-01-01'), endDate: new DateTimeImmutable('2025-12-31'), format: ReportFormat::JSON, options: ['include_details' => true] ); // Get the generated report $report = $reportManager->getReport($reportId); // Get all reports for a tenant $reports = $reportManager->getReports( tenantId: 'tenant-123', reportType: 'profit_loss', from: new DateTimeImmutable('2025-01-01'), to: new DateTimeImmutable('2025-12-31') ); ``` ### Payroll Statutory Calculations [](#payroll-statutory-calculations) ``` use Nexus\Statutory\Adapters\DefaultPayrollStatutoryAdapter; // Calculate statutory deductions (default: zero deductions) $deductions = $payrollAdapter->calculateDeductions( tenantId: 'tenant-123', employeeId: 'emp-001', grossSalary: 5000.00, payDate: new DateTimeImmutable('2025-11-30'), employeeData: [ 'citizenship' => 'MYS', 'tax_exemption' => false, ] ); ``` ### Report Metadata [](#report-metadata) ``` use Nexus\Statutory\Adapters\DefaultAccountingAdapter; $adapter = new DefaultAccountingAdapter($logger); $metadata = $adapter->getReportMetadata('profit_loss'); echo $metadata->getReportName(); // "Profit & Loss Statement" echo $metadata->getCountryCode(); // "DEFAULT" echo $metadata->getFilingFrequency()->value; // "On-Demand" echo $metadata->getSchemaVersion(); // "v1.0" $formats = $metadata->getSupportedFormats(); foreach ($formats as $format) { echo $format->getMimeType(); // "application/json", "text/csv" } ``` Supported Report Formats ------------------------ [](#supported-report-formats) ``` use Nexus\Statutory\ValueObjects\ReportFormat; ReportFormat::JSON; // application/json (.json) ReportFormat::XML; // application/xml (.xml) ReportFormat::XBRL; // application/xbrl+xml (.xbrl) ReportFormat::CSV; // text/csv (.csv) ReportFormat::PDF; // application/pdf (.pdf) ReportFormat::EXCEL; // application/vnd...spreadsheetml.sheet (.xlsx) // Check format capabilities $format = ReportFormat::XBRL; $format->isMachineReadable(); // true $format->supportsDigitalSignature(); // true ``` Filing Frequencies ------------------ [](#filing-frequencies) ``` use Nexus\Statutory\ValueObjects\FilingFrequency; FilingFrequency::MONTHLY; // 12 filings per year FilingFrequency::QUARTERLY; // 4 filings per year FilingFrequency::SEMI_ANNUALLY; // 2 filings per year FilingFrequency::ANNUALLY; // 1 filing per year FilingFrequency::BIENNIAL; // Every 2 years FilingFrequency::ON_DEMAND; // No scheduled filing // Get filing details $frequency = FilingFrequency::QUARTERLY; $frequency->getMonthInterval(); // 3 $frequency->getFilingsPerYear(); // 4 $frequency->isScheduled(); // true ``` Default Adapters ---------------- [](#default-adapters) The package includes two default adapters: 1. **DefaultAccountingAdapter**: Basic P&L, Balance Sheet, Trial Balance (JSON/CSV only) 2. **DefaultPayrollStatutoryAdapter**: Zero deductions (safe default for testing) These adapters provide safe defaults when no country-specific adapter is configured. Creating Country-Specific Adapters ---------------------------------- [](#creating-country-specific-adapters) To create a country-specific adapter (e.g., Malaysia): ``` namespace Nexus\Statutory\Adapters; use Nexus\Statutory\Contracts\PayrollStatutoryInterface; final class MalaysiaPayrollAdapter implements PayrollStatutoryInterface { public function calculateDeductions( string $tenantId, string $employeeId, float $grossSalary, \DateTimeImmutable $payDate, array $employeeData = [] ): array { return [ 'epf_employee' => $this->calculateEPF($grossSalary, 'employee'), 'epf_employer' => $this->calculateEPF($grossSalary, 'employer'), 'socso_employee' => $this->calculateSOCSO($grossSalary, 'employee'), 'socso_employer' => $this->calculateSOCSO($grossSalary, 'employer'), 'eis_employee' => $this->calculateEIS($grossSalary, 'employee'), 'eis_employer' => $this->calculateEIS($grossSalary, 'employer'), 'pcb' => $this->calculatePCB($grossSalary, $employeeData), ]; } public function getCountryCode(): string { return 'MYS'; } // ... implement other methods } ``` Integration with Applications ----------------------------- [](#integration-with-applications) This package defines contracts that must be implemented by the consuming application: 1. **Repository Implementations**: Implement all repository interfaces with Eloquent models 2. **Entity Implementations**: Implement all entity interfaces 3. **Database Migrations**: Create required tables in application layer 4. **Service Provider Bindings**: Bind interfaces to implementations in IoC container 5. **Adapter Registration**: Register country-specific adapters based on feature flags ### Required Tables (Application Layer) [](#required-tables-application-layer) ``` -- Statutory reports statutory_reports (id, tenant_id, report_type, start_date, end_date, format, status, file_path, metadata, created_at, updated_at) -- Report instances (for versioning) statutory_report_instances (id, report_id, version, generated_at, generated_by, file_path, checksum) -- Rate tables (for payroll calculations) statutory_rate_tables (id, country_code, deduction_type, effective_from, effective_to, rate_config, created_at, updated_at) ``` Dependencies ------------ [](#dependencies) - **PHP**: ^8.3 - **azaharizaman/nexus-finance**: \*@dev (for financial data extraction) - **azaharizaman/nexus-period**: \*@dev (for period management) - **psr/log**: ^3.0 (for logging interface) Development ----------- [](#development) ### Running Tests [](#running-tests) ``` composer test ``` ### Code Style [](#code-style) This package follows PSR-12 coding standards. --- 📖 Documentation --------------- [](#-documentation) ### Quick Links [](#quick-links) - 📘 [Getting Started Guide](docs/getting-started.md) - Setup, core concepts, and first integration - 📚 [API Reference](docs/api-reference.md) - Complete interface and service documentation - 🔧 [Integration Guide](docs/integration-guide.md) - Laravel and Symfony integration examples - 💡 [Basic Examples](docs/examples/basic-usage.php) - Report generation basics - 🚀 [Advanced Examples](docs/examples/advanced-usage.php) - Country adapters, XBRL, multi-format ### Package Documentation [](#package-documentation) - 📋 [Requirements](REQUIREMENTS.md) - Detailed requirements specifications (61 requirements) - 📊 [Implementation Summary](IMPLEMENTATION_SUMMARY.md) - Development progress and metrics - ✅ [Test Suite Summary](TEST_SUITE_SUMMARY.md) - Test coverage and strategy (55 tests planned) - 💰 [Valuation Matrix](VALUATION_MATRIX.md) - Package valuation and ROI analysis ($95K) ### Additional Resources [](#additional-resources) - 🏗️ [Architecture Guidelines](../../ARCHITECTURE.md) - Nexus architecture principles - 📖 [Package Reference](../../docs/NEXUS_PACKAGES_REFERENCE.md) - All Nexus packages overview - 📑 [Compliance/Statutory Analysis](../../docs/COMPLIANCE_STATUTORY_READINESS_ANALYSIS.md) - Package separation rationale Integration with Other Packages ------------------------------- [](#integration-with-other-packages) This package integrates with: - **Nexus\\Finance** - Financial data extraction (GL accounts, trial balance) - **Nexus\\Period** - Period validation and fiscal year management - **Nexus\\Tenant** - Multi-tenancy context - **Nexus\\Payroll** - Payroll statutory calculation delegation - **Nexus\\Accounting** - Financial statement generation - **Nexus\\Compliance** - Operational compliance (separate from statutory reporting) License ------- [](#license) MIT License. See [LICENSE](LICENSE) file for details. Contributing ------------ [](#contributing) Contributions are welcome! Please follow the Nexus architecture principles: 1. Keep the package framework-agnostic 2. Define all dependencies via interfaces 3. Use immutable Value Objects for domain concepts 4. Place all business logic in services 5. No database access or migrations in this package 6. Country-specific logic belongs in separate adapter packages Support ------- [](#support) For issues, questions, or contributions, please refer to the main Nexus monorepo documentation. ### Health Score 35 — LowBetter than 77% of packages Maintenance93 Actively maintained with recent releases Popularity0 Limited adoption so far Community9 Small or concentrated contributor base Maturity34 Early-stage or recently created project Bus Factor1 Top contributor holds 76.7% 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 (463 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)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/azaharizaman-nexus-statutory/health.svg) ``` [![Health](https://phpackages.com/badges/azaharizaman-nexus-statutory/health.svg)](https://phpackages.com/packages/azaharizaman-nexus-statutory) ``` ### Alternatives [symfony/lock Creates and manages locks, a mechanism to provide exclusive access to a shared resource 515135.1M619](/packages/symfony-lock)[matomo/matomo Matomo is the leading Free/Libre open analytics platform 21.6k38.2k](/packages/matomo-matomo)[phpro/soap-client A general purpose SoapClient library 8895.9M52](/packages/phpro-soap-client)[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)[civicrm/civicrm-core Open source constituent relationship management for non-profits, NGOs and advocacy organizations. 744284.3k34](/packages/civicrm-civicrm-core)[illuminate/broadcasting The Illuminate Broadcasting package. 7126.9M199](/packages/illuminate-broadcasting) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)