Ledger Reports

Ledger currently offers only one preset report, the Trial Balance Report.

Applications can add and configure their own reports through the ledger configuration file's reports and reportApiOptions settings (thanks to GitHub user @ivanmazep for introducing this capability).

If there is no reports setting, then all native reports are available to the JSON API. If there is a reports setting, it must list all reports available to the JSON API. Any reports omitted from this list (e.g. trialBalance) will be inaccessible to the JSON API.

The reports setting is an array indexed by report name that references the reporting class (which should extend Abivia\Ledger\Reports\AbstractReport):

// in config/ledger.php
'reports' => [
    'customReport' => YourAppNamespace\CustomReport::class
    'trialBalance' => Abivia\Ledger\Reports\TrialBalanceReport::class,
],

It is often desirable to limit report attributes when accessed via the external API. To pass options to a report when being called via the JSON API, use the reportApiOptions setting:

// in config/ledger.php
'reportApiOptions' => [
    'customReport' => [
        'someOption' => 'someValue',
    ],
    'trialBalance' => [
        'maxDepth' => 3,
    ],
],

Extending the Abstract Report class

The AbstractReport class requires two methods. The collect method is responsible for gathering the raw information required to produce a report and the prepare method converts the raw data into a format suitable for display. The collect method takes a Report message and returns a ReportData object; the prepare method then processes the ReportData, typically returning a Collection.

Cached reports through the Report Controller

Since financial reports are frequently a snapshot of the state of the ledger at a particular point in time, it is often possible to save this snapshot, speeding subsequent report generation.

The report controller maintains a cache of these snapshots. As long as no transactions have been posted to the journal inside the date range covered by the report since it was cached, the report controller will utilize the cache to reduce processing time. The cache contains the complete ReportData set used to create the report. This full data set is then passed to the report's prepare method, which is responsible for any consolidation or filtering. Using this approach, a single snapshot can be used to prepare several reports from the same data.