ksfraser/portfolio-math

Portfolio performance calculations: TWR, IRR, drawdown, volatility, asset allocation. Shared library for stockmarket, FrontAccounting, ksfii_app.

v1.0.1 2026-07-30 06:03 UTC

Requires

• php: >=7.4

Requires (Dev)

• phpunit/phpunit: ^9.6

MIT

• Kevin Fraser

Published on Packagist.org on 2026-07-30 06:03 UTC

README

Shared portfolio performance calculation library for the KSF stack.

What It Is

A Composer package implementing portfolio performance algorithms extracted from portfolio-performance/portfolio. All business logic lives here; app-layer wrappers (stockmarket, ksfii_app, FrontAccounting) only map data to the interfaces and display results.

Consuming Apps

App	Role
ksf_stockmarket	PHP/Apache bare-metal; computes TWR/IRR for holdings dashboard
ksfii_app	WealthSystem forecasting; consumes performance metrics for scenarios
FrontAccounting (ksf-fa)	Pulls GL transactions → feeds package → dashboard widget

Facilities

Feature	Class
TWR (True Time-Weighted Return)	KSF\Performance\Services\TWRCalculatorService
IRR (Internal Rate of Return)	KSF\Performance\Services\IRRCalculatorService
Max Drawdown	KSF\Performance\Services\DrawdownCalculatorService
Volatility / Semi-deviation	KSF\Performance\Services\VolatilityCalculatorService

Composability

Apps write an adapter that implements TransactionRepositoryInterface:

final class StockmarketRepository implements TransactionRepositoryInterface {
    public function findByPortfolioAndRange(string $id, DateTimeInterface $start, DateTimeInterface $end): array { ... }
    public function findValuationsByPortfolioAndRange(string $id, DateTimeInterface $start, DateTimeInterface $end): array { ... }
}

Then:

$twr = new TWRCalculatorService(new StockmarketRepository());
$result = $twr->calculate('P1', '2026-01-01', '2027-01-01');
echo $result->getTWR();

Installation

composer require ksfraser/portfolio-math

Tests

vendor/bin/phpunit --bootstrap tests/bootstrap.php tests/

Target: 16/16 pass.

Notes

• Follow ksf(report): commit prefix for any changes to reporting/math features.
• New requirements are individual files in ProjectDcs/.