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

Maintenance45

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

[slexx/laravel-webp

Detect webp support in laravel framework

104.6k](/packages/slexx-laravel-webp)

PHPackages © 2026

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