PHPackages                             ameax/bgb-interest - 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. ameax/bgb-interest

ActiveLibrary[Utility & Helpers](/categories/utility)

ameax/bgb-interest
==================

Calculate default interest (Verzugszinsen) according to German Civil Code (BGB) §288. Framework-agnostic, PHP 7.4+ compatible with automatic base rate updates from Bundesbank.

015PHPCI failing

Since Oct 4Pushed 7mo agoCompare

[ Source](https://github.com/ameax/bgb-interest)[ Packagist](https://packagist.org/packages/ameax/bgb-interest)[ RSS](/packages/ameax-bgb-interest/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

BGB Interest Calculator
=======================

[](#bgb-interest-calculator)

A PHP library for calculating default interest (Verzugszinsen) according to German Civil Code (BGB) §288.

[![License](https://camo.githubusercontent.com/97f7dc4d8076775f0fb2754f4eedbd3714a622e2fb5a006b1e563b7431df0f9c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f616d6561782f6267622d696e746572657374)](https://packagist.org/packages/ameax/bgb-interest)

---

**Framework-agnostic** | **PHP 7.4 - 8.3 compatible** | **Auto-updates base rates from Bundesbank**

Features
--------

[](#features)

✅ **Accurate BGB §288 Calculations**

- Consumer rate: Base rate + 5 percentage points
- Business rate: Base rate + 9 percentage points
- Period-based calculation with automatic rate changes
- No compound interest (§289 BGB compliant)

✅ **Automatic Base Rate Updates**

- Fetches historical data from Deutsche Bundesbank API
- Caches rates locally for performance
- Only stores rate changes (optimized data)

✅ **Flexible Configuration**

- Configurable cache directory
- Optional calendar year breakdown
- Customizable surcharge rates
- Automatic cache refresh (monthly check)

Requirements
------------

[](#requirements)

- PHP 7.4 or higher
- ext-simplexml
- ext-json

Installation
------------

[](#installation)

```
composer require ameax/bgb-interest
```

Quick Start
-----------

[](#quick-start)

### 1. Fetch Base Rates

[](#1-fetch-base-rates)

First, fetch and cache the base interest rates from Bundesbank:

```
use Ameax\BgbInterest\BaseRateProvider;

$provider = new BaseRateProvider('./cache');
$provider->updateCache();
```

### 2. Calculate Default Interest

[](#2-calculate-default-interest)

```
use Ameax\BgbInterest\BgbInterest;
use Ameax\BgbInterest\Config;

// Configure
$config = new Config('./cache');
$calculator = new BgbInterest($config);

// Calculate interest
$result = $calculator->calculate(
    10000.00,                      // Amount in EUR
    new DateTime('2023-01-15'),    // Due date
    new DateTime('2025-10-02'),    // Payment date
    false                          // false = Business, true = Consumer
);

echo "Total Interest: {$result['total_interest']} EUR\n";
echo "Total Days: {$result['total_days']}\n";
```

### Result Structure

[](#result-structure)

```
[
    'total_interest' => 3154.20,
    'total_days' => 991,
    'amount' => 10000.00,
    'is_consumer' => false,
    'periods' => [
        [
            'from' => '2023-01-15',
            'to' => '2023-07-01',
            'days' => 167,
            'base_rate' => 1.62,
            'interest_rate' => 10.62,
            'interest' => 485.90
        ],
        // ... more periods
    ]
]
```

Advanced Usage
--------------

[](#advanced-usage)

### Calendar Year Breakdown

[](#calendar-year-breakdown)

Split calculations by calendar year for accounting purposes:

```
$result = $calculator->calculate(
    5000.00,
    new DateTime('2023-06-15'),
    new DateTime('2024-03-15'),
    true,   // Consumer
    true    // Split by year
);
```

### Partial Payments

[](#partial-payments)

Calculate interest with partial payments that reduce the principal amount:

```
$partialPayments = [
    [
        'date' => new DateTime('2023-06-01'),
        'amount' => 3000.00,
    ],
    [
        'date' => new DateTime('2023-10-15'),
        'amount' => 2000.00,
    ],
];

$result = $calculator->calculateWithPartialPayments(
    10000.00,                       // Initial amount
    new DateTime('2023-01-15'),     // Due date
    new DateTime('2024-01-15'),     // Payment date
    false,                          // Business transaction
    $partialPayments                // Array of partial payments
);

// Result includes partial payments and reduced principal per period
echo "Total interest: {$result['total_interest']} EUR\n";
echo "Partial payments: " . count($result['partial_payments']) . "\n";

// Each period shows the principal amount used for calculation
foreach ($result['periods'] as $period) {
    echo "Principal: {$period['principal']} EUR\n";
    if (isset($period['partial_payment'])) {
        echo "Payment: {$period['partial_payment']['amount']} EUR on {$period['partial_payment']['date']}\n";
    }
}
```

### Custom Configuration

[](#custom-configuration)

```
$config = new Config(
    '/custom/cache/path',  // Cache directory
    5.0,                   // Consumer surcharge (default: 5.0)
    9.0                    // Business surcharge (default: 9.0)
);
```

### Automatic Cache Refresh

[](#automatic-cache-refresh)

The calculator automatically checks the cache age when instantiated. If the cache is older than 1 month, it attempts to refresh from the Bundesbank API. If the refresh fails, it gracefully falls back to the existing cache.

```
// Cache is automatically refreshed if older than 1 month
$calculator = new BgbInterest($config);
```

### Manual Cache Update

[](#manual-cache-update)

You can also manually update the cache:

```
$provider = new BaseRateProvider('./cache');
$rates = $provider->updateCache();

// Check last update
$cacheFile = $provider->getCacheFilePath();
$data = json_decode(file_get_contents($cacheFile), true);
echo "Last updated: {$data['metadata']['last_updated']}\n";
```

**Note:** The Bundesbank updates base rates semi-annually (January & July).

Legal Information
-----------------

[](#legal-information)

### BGB §288 - Default Interest Rates

[](#bgb-288---default-interest-rates)

According to German law:

- **Consumers**: Base interest rate + 5 percentage points per year
- **Businesses**: Base interest rate + 9 percentage points per year

### BGB §289 - Compound Interest

[](#bgb-289---compound-interest)

**Compound interest (Zinseszinsen) is prohibited** by German law. This package only calculates simple interest on the principal amount.

Examples
--------

[](#examples)

See the `examples/` directory for complete working examples:

- **fetch-base-rates.php** - Fetching and caching base rates
- **calculate-interest.php** - Various calculation scenarios
- **detailed-calculation.php** - Detailed breakdown with all periods
- **partial-payments.php** - Calculate interest with partial payments
- **simple-partial-payment.php** - Simple example for manual verification
- **show-return-value.php** - Shows the complete return array structure

Run examples:

```
php examples/detailed-calculation.php
php examples/partial-payments.php
php examples/simple-partial-payment.php
```

Development
-----------

[](#development)

### Run Tests

[](#run-tests)

```
composer test              # Full test suite
composer test:types        # PHPStan static analysis
composer test:lint         # Code style check
composer test:unit         # Unit tests
```

### Code Style

[](#code-style)

```
composer lint              # Fix code style
```

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

---

Deutsche Dokumentation
======================

[](#deutsche-dokumentation)

Eine PHP-Bibliothek zur Berechnung von Verzugszinsen gemäß BGB §288.

Funktionen
----------

[](#funktionen)

✅ **Präzise BGB §288 Berechnungen**

- Verbraucherzins: Basiszins + 5 Prozentpunkte
- Unternehmerzins: Basiszins + 9 Prozentpunkte
- Periodenbasierte Berechnung mit automatischen Zinsänderungen
- Keine Zinseszinsen (§289 BGB konform)

✅ **Automatische Basiszins-Aktualisierung**

- Lädt historische Daten von der Bundesbank API
- Lokales Caching für Performance
- Speichert nur Zinsänderungen (optimierte Daten)

✅ **Flexible Konfiguration**

- Konfigurierbares Cache-Verzeichnis
- Optional: Aufteilung nach Kalenderjahren
- Anpassbare Aufschlagsätze
- Automatische Cache-Aktualisierung (monatliche Prüfung)

Voraussetzungen
---------------

[](#voraussetzungen)

- PHP 7.4 oder höher
- ext-simplexml
- ext-json

Installation
------------

[](#installation-1)

```
composer require ameax/bgb-interest
```

Schnellstart
------------

[](#schnellstart)

### 1. Basiszinssätze abrufen

[](#1-basiszinssätze-abrufen)

Zuerst die Basiszinssätze von der Bundesbank laden und cachen:

```
use Ameax\BgbInterest\BaseRateProvider;

$provider = new BaseRateProvider('./cache');
$provider->updateCache();
```

### 2. Verzugszinsen berechnen

[](#2-verzugszinsen-berechnen)

```
use Ameax\BgbInterest\BgbInterest;
use Ameax\BgbInterest\Config;

// Konfiguration
$config = new Config('./cache');
$calculator = new BgbInterest($config);

// Berechnung
$result = $calculator->calculate(
    10000.00,                      // Betrag in EUR
    new DateTime('2023-01-15'),    // Fälligkeitsdatum
    new DateTime('2025-10-02'),    // Zahlungsdatum
    false                          // false = Unternehmer, true = Verbraucher
);

echo "Verzugszinsen: {$result['total_interest']} EUR\n";
echo "Verzugstage: {$result['total_days']}\n";
```

### Ergebnis-Struktur

[](#ergebnis-struktur)

```
[
    'total_interest' => 3154.20,  // Gesamtzinsen
    'total_days' => 991,           // Verzugstage
    'amount' => 10000.00,          // Hauptforderung
    'is_consumer' => false,        // Verbraucher?
    'periods' => [                 // Perioden mit unterschiedlichen Zinssätzen
        [
            'from' => '2023-01-15',      // Von
            'to' => '2023-07-01',        // Bis
            'days' => 167,               // Tage
            'base_rate' => 1.62,         // Basiszins
            'interest_rate' => 10.62,    // Gesamtzins (Basiszins + 9%)
            'interest' => 485.90         // Zinsen dieser Periode
        ],
        // ... weitere Perioden
    ]
]
```

Erweiterte Nutzung
------------------

[](#erweiterte-nutzung)

### Aufteilung nach Kalenderjahren

[](#aufteilung-nach-kalenderjahren)

Berechnung nach Kalenderjahren für buchhalterische Zwecke:

```
$result = $calculator->calculate(
    5000.00,
    new DateTime('2023-06-15'),
    new DateTime('2024-03-15'),
    true,   // Verbraucher
    true    // Nach Jahren aufteilen
);
```

### Teilzahlungen

[](#teilzahlungen)

Berechnung mit Teilzahlungen, die den Hauptbetrag reduzieren:

```
$partialPayments = [
    [
        'date' => new DateTime('2023-06-01'),
        'amount' => 3000.00,
    ],
    [
        'date' => new DateTime('2023-10-15'),
        'amount' => 2000.00,
    ],
];

$result = $calculator->calculateWithPartialPayments(
    10000.00,                       // Ursprünglicher Betrag
    new DateTime('2023-01-15'),     // Fälligkeitsdatum
    new DateTime('2024-01-15'),     // Zahlungsdatum
    false,                          // Unternehmer
    $partialPayments                // Array mit Teilzahlungen
);

// Ergebnis enthält Teilzahlungen und reduzierten Hauptbetrag pro Periode
echo "Verzugszinsen: {$result['total_interest']} EUR\n";
echo "Teilzahlungen: " . count($result['partial_payments']) . "\n";

// Jede Periode zeigt den für die Berechnung verwendeten Hauptbetrag
foreach ($result['periods'] as $period) {
    echo "Hauptbetrag: {$period['principal']} EUR\n";
    if (isset($period['partial_payment'])) {
        echo "Zahlung: {$period['partial_payment']['amount']} EUR am {$period['partial_payment']['date']}\n";
    }
}
```

### Eigene Konfiguration

[](#eigene-konfiguration)

```
$config = new Config(
    '/eigener/cache/pfad',  // Cache-Verzeichnis
    5.0,                    // Verbraucher-Aufschlag (Standard: 5.0)
    9.0                     // Unternehmer-Aufschlag (Standard: 9.0)
);
```

### Automatische Cache-Aktualisierung

[](#automatische-cache-aktualisierung)

Der Calculator prüft automatisch das Cache-Alter bei der Initialisierung. Wenn der Cache älter als 1 Monat ist, wird versucht, die Daten von der Bundesbank API zu aktualisieren. Bei Fehlern wird automatisch auf den vorhandenen Cache zurückgegriffen.

```
// Cache wird automatisch aktualisiert, wenn älter als 1 Monat
$calculator = new BgbInterest($config);
```

### Manuelle Cache-Aktualisierung

[](#manuelle-cache-aktualisierung)

Sie können den Cache auch manuell aktualisieren:

```
$provider = new BaseRateProvider('./cache');
$rates = $provider->updateCache();

// Letzte Aktualisierung prüfen
$cacheFile = $provider->getCacheFilePath();
$data = json_decode(file_get_contents($cacheFile), true);
echo "Zuletzt aktualisiert: {$data['metadata']['last_updated']}\n";
```

**Hinweis:** Die Bundesbank aktualisiert die Basiszinssätze halbjährlich (Januar & Juli).

Rechtliche Informationen
------------------------

[](#rechtliche-informationen)

### BGB §288 - Verzugszinsen

[](#bgb-288---verzugszinsen)

Nach deutschem Recht:

- **Verbraucher**: Basiszinssatz + 5 Prozentpunkte pro Jahr
- **Unternehmer**: Basiszinssatz + 9 Prozentpunkte pro Jahr

### BGB §289 - Zinseszinsen

[](#bgb-289---zinseszinsen)

**Zinseszinsen sind verboten** nach deutschem Recht. Dieses Paket berechnet nur einfache Zinsen auf den Hauptbetrag.

Beispiele
---------

[](#beispiele)

Siehe `examples/` Verzeichnis für vollständige Beispiele:

- **fetch-base-rates.php** - Basiszinssätze abrufen und cachen
- **calculate-interest.php** - Verschiedene Berechnungsszenarien
- **detailed-calculation.php** - Detaillierte Aufschlüsselung mit allen Perioden
- **partial-payments.php** - Berechnung mit Teilzahlungen
- **simple-partial-payment.php** - Einfaches Beispiel zum Nachrechnen
- **show-return-value.php** - Zeigt die komplette Rückgabe-Array-Struktur

Beispiele ausführen:

```
php examples/detailed-calculation.php
php examples/partial-payments.php
php examples/simple-partial-payment.php
```

Berechnung erklärt
------------------

[](#berechnung-erklärt)

Die Verzugszinsen werden nach folgender Formel berechnet:

```
Zinsen = (Hauptbetrag × Zinssatz × Tage) / (100 × 365)

```

### Beispielrechnung

[](#beispielrechnung)

Forderung: 10.000 EUR Fällig seit: 15.01.2023 Bezahlt am: 02.10.2025 (991 Tage) Art: Unternehmer

**Periode 1** (15.01.2023 - 01.07.2023, 167 Tage):

- Basiszins: 1,62% + 9% = 10,62%
- Zinsen: (10.000 × 10,62 × 167) / 36.500 = 485,90 EUR

**Periode 2** (02.07.2023 - 01.01.2024, 183 Tage):

- Basiszins: 3,12% + 9% = 12,12%
- Zinsen: (10.000 × 12,12 × 183) / 36.500 = 607,66 EUR

*... weitere Perioden ...*

**Gesamt: 3.154,20 EUR** Verzugszinsen

Entwicklung
-----------

[](#entwicklung)

### Tests ausführen

[](#tests-ausführen)

```
composer test              # Vollständige Test-Suite
composer test:types        # PHPStan statische Analyse
composer test:lint         # Code-Style prüfen
composer test:unit         # Unit-Tests
```

### Code-Style

[](#code-style-1)

```
composer lint              # Code-Style korrigieren
```

###  Health Score

18

—

LowBetter than 8% of packages

Maintenance44

Moderate activity, may be stable

Popularity7

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity13

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% 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.

### Community

Maintainers

![](https://www.gravatar.com/avatar/f67be86f330b5a3e644c8594bbf322be6ab1a08da5434d9cef417097d5567287?d=identicon)[aranes](/maintainers/aranes)

---

Top Contributors

[![ms-aranes](https://avatars.githubusercontent.com/u/69188126?v=4)](https://github.com/ms-aranes "ms-aranes (5 commits)")

### Embed Badge

![Health badge](/badges/ameax-bgb-interest/health.svg)

```
[![Health](https://phpackages.com/badges/ameax-bgb-interest/health.svg)](https://phpackages.com/packages/ameax-bgb-interest)
```

###  Alternatives

[rs/laravel-version-control

Foundations for making your app version controlled. Provides migration, blueprint and base models. Will make your app GxP compliant if you exclusively use the VC models and table structure as set out in this package.

1227.5k](/packages/rs-laravel-version-control)[mad-web/laravel-seoable

Easy to map your eloquent fields to seo properties

407.6k](/packages/mad-web-laravel-seoable)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)