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
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
// 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
// in config/ledger.php 'reportApiOptions' => [ 'customReport' => [ 'someOption' => 'someValue', ], 'trialBalance' => [ 'maxDepth' => 3, ], ],
Extending the Abstract Report class
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
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.