icordeiro/kpi-calculator

A lightweight PHP library for calculating KPIs like Average Ticket, Gross Margin, etc.

v1.0.4 2025-05-05 12:34 UTC

Requires

• php: ^8.3

Requires (Dev)

• phpunit/phpunit: ^9.5

MIT

• icordeiro

README

A lightweight and reusable PHP library for calculating key business performance indicators (KPIs). Useful for dashboards, BI systems, or any reporting automation.

📦 Installation

You can install this package via Composer:

composer require icordeiro/kpi-calculator

🚀 Features

• Calculate Average Ticket
• Calculate Gross Margin Percentage
• Calculate Value and Percentage Variations
• Calculate Average Price per Unit
• Calculate Quantity per Customer
• Error handling: Methods now validate inputs and throw exceptions if required, such as checking for division by zero.

🔧 Usage

<?php

require 'vendor/autoload.php';

use icordeiro\KpiCalculator;

try {
    $totalSales = 10000;
    $totalReceipts = 250;
    $cmv = 7000;
    $previousValue = 8500;
    $currentValue = 10000;
    $totalQuantity = 500;
    $customers = 200;

    // Average Ticket
    $averageTicket = KpiCalculator::calculateAverageTicket($totalSales, $totalReceipts);
    // Result: 40.0

    // Gross Margin Percentage
    $margin = KpiCalculator::calculateMarginOnSales($totalSales, $cmv);
    // Result: 30.0

    // Value Variation (%)
    $valueVariation = KpiCalculator::calculateValueVariation($currentValue, $previousValue);
    // Result: 17.65...

    // Percentage Variation
    $percentageVariation = KpiCalculator::calculatePercentageVariation(70.0, 65.0);
    // Result: 5.0

    // Average Price per Unit
    $avgPrice = KpiCalculator::calculateAveragePrice($totalSales, $totalQuantity);
    // Result: 20.0

    // Quantity per Customer
    $qtyPerCustomer = KpiCalculator::calculateQuantityPerCustomer($totalQuantity, $customers);
    // Result: 2.5
} catch (\InvalidArgumentException $e) {
    echo "Error: " . $e->getMessage();
}

🧪 Available Methods (updated to reflect exceptions)

Method	Description
calculateAverageTicket	Total sales divided by the number of receipts. Throws InvalidArgumentException if receipts are zero.
calculateMarginOnSales	(sales - cost) / sales * 100. Throws InvalidArgumentException for invalid values like division by zero.
calculateValueVariation	(current / previous - 1) * 100. Throws InvalidArgumentException if previous value is zero.
calculatePercentageVariation	currentPercentage - previousPercentage.
calculateAveragePrice	Total sales divided by quantity sold. Throws InvalidArgumentException for zero quantity sold.
calculateQuantityPerCustomer	Quantity sold divided by the number of customers. Throws InvalidArgumentException for zero customers.

🧱 Requirements

• PHP 8.1 or higher

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

🙌 Contributing

Pull requests are welcome. If you have ideas for new KPI methods or improvements, feel free to open an issue or PR.

Made with ❤️ by icordeiro