README

Laravel CacheBench is a comprehensive benchmarking and profiling tool designed to measure, compare, and analyze the performance of various Laravel cache drivers under identical, controlled workloads.

This package allows developers and DevOps engineers to make data-driven decisions when selecting a cache driver (Redis, Memcached, Database, File, Array) for their production environments.

Features

Multiple Scenarios: Organizes benchmarks into robust domains: CrudOperations (Writes, Reads, Deletes), ConcurrencyPressure (Multi-process race conditions, atomic increments, safe writes), HotKeyPressure (High traffic simulation on single keys), and RealWorld simulations.
Precise Metrics: Accurately calculates Throughput (Ops/sec), Memory Usage, Latency Percentiles (Avg, Median, Min, Max, P95, P99), and tracks Data Loss / Safety issues in high-concurrency environments.
Beautiful HTML Reports: Generates an interactive Chart.js HTML report to easily visualize throughput across all drivers.
Console Reporting: Provides a clean, hierarchical summary tree right in your terminal with actionable diagnostic notes.
Fully Containerized: Includes a Docker environment (Redis, Memcached, MySQL) for completely isolated and host-independent testing.
Multi-lingual Support: Native support for English (en) and Turkish (tr).

Requirements

PHP: 8.2+
Laravel: 11.0+
Docker & Docker Compose (for the isolated benchmarking environment)

Installation

You can install the package via composer (once published):

composer require Hktnv/laravel-cachebench

Publish the configuration and language files:

php artisan vendor:publish --tag=cachebench-config
php artisan vendor:publish --tag=cachebench-lang

Docker Environment Setup

To ensure consistent results, it is highly recommended to run the benchmarks inside the provided Docker environment. The environment ships with Redis, Memcached, and MySQL ready to go.

Using the included Makefile:

# Build the containers and install composer dependencies
make init

# Enter the isolated application container
make shell

Usage

Once inside the container (or your own environment), you can use the provided Artisan commands.

1. Run Benchmarks

To execute all benchmarking scenarios against all configured drivers from within the package directory, use Testbench:

vendor/bin/testbench cachebench:run

Important note for the database driver: If you intend to run benchmarks using the database cache driver, you must ensure that your database contains the cache and cache_locks tables. You can create them by running:
php artisan cache:table
php artisan migrate
(If you are using Testbench directly, use vendor/bin/testbench cache:table && vendor/bin/testbench migrate instead).

(Note: If you have installed this package in an actual Laravel app, use php artisan cachebench:run)

Options:

--driver=redis,memcached: Run benchmarks only for specific drivers.
--scenario=Concurrency: Run benchmarks only for specific scenarios (matches the class or namespace name like Crud, Concurrency, HotKey).
--iterations=100: Override the default number of iterations.

2. Generate HTML Report

While cachebench:run generates a detailed, live hierarchical tree in your console, you can also generate a persistent HTML visual report from the saved JSON results:

vendor/bin/testbench cachebench:report

This command will:

Output a structured summary Console Table.
Generate an interactive Chart.js HTML report at storage/cachebench/report.html to visualize and compare the throughput of all drivers.

3. Clean Results

To safely flush all previous benchmark JSON results and the HTML report:

vendor/bin/testbench cachebench:clean

Configuration

You can customize the package behavior by editing the config/cachebench.php file:

drivers: The array of cache drivers to include in the benchmark. Unavailable drivers will be skipped automatically.
storage_path: Directory where JSON results are saved.
report_path: Path where the final HTML report is written.

Testing

To run the internal unit tests (validating the mathematical accuracy of the benchmark metrics):

# Inside the docker container (make shell)
vendor/bin/phpunit

Or from the host machine:

make test

License

The MIT License (MIT). Please see License File for more information.

hktnv / laravel-cachebench

Maintainers

Package info

Statistics

Security