chernegasergiy/battery-info

Cross-platform PHP extension for retrieving battery level and charging status (Linux, macOS, Windows, Android).

v0.2.0 2026-07-25 21:17 UTC

Requires

• php: >=8.0

LicenseRef-CSSM-Unlimited-2.0

• Serhii Cherneha

• extension
• android
• status
• info
• battery
• sysfs
• jni

Published on Packagist.org on 2026-07-26 09:55 UTC

Extension name: ext-battery-info

Supports Zend Thread Safety (ZTS): ✅

Supports non-Thread Safe mode (NTS): ✅

Supported operating systems: no restrictions

README

This extension exposes a single function: battery_info() which returns an array with keys:

• batteries (array) — array of all detected batteries, each containing:
  • name (string) — battery identifier (e.g., "BAT0", "BAT1")
  • level (int|null) — 0..100 or null if unknown
  • charging (bool|null) — true/false or null
  • status (string|null) — "charging"/"discharging"/"full"/"not charging"/null
• level (int|null) — primary battery level (0..100 or null)
• charging (bool|null) — primary battery charging state
• status (string|null) — primary battery status
• platform (string) — platform name ("linux", "macos", "windows", "android")

Installation

Install with PIE (Recommended)

The easiest way to install the extension is using PIE (PHP Installer for Extensions).

If you don't have PIE installed yet, you can download the standalone PHAR:

curl -sSLO https://github.com/php/pie/releases/latest/download/pie.phar
chmod +x pie.phar
sudo mv pie.phar /usr/local/bin/pie

Then install the extension:

pie install chernegasergiy/battery-info

Manual Installation

1. Build or Download the extension binary for your OS.
2. Locate your extensions directory: php -i | grep extension_dir.
3. Copy the file:
   • Linux/macOS/Android: battery_info.so
   • Windows: php_battery_info.dll
4. Enable in php.ini:
   • Add extension=battery_info (or extension=php_battery_info.dll on Windows).

Build (typical Unix/macOS)

phpize
./configure --enable-battery_info
make
sudo make install

Usage Example

<?php
if (!function_exists('battery_info')) {
    die("Extension not loaded");
}

$info = battery_info();

echo "Platform: " . $info['platform'] . "\n";

// Check all batteries
if (!empty($info['batteries'])) {
    foreach ($info['batteries'] as $battery) {
        echo "Battery: " . $battery['name'] . "\n";
        echo "  Level: " . ($battery['level'] ?? 'unknown') . "%\n";
        echo "  Status: " . ($battery['status'] ?? 'unknown') . "\n";
    }
} else {
    echo "No batteries detected.\n";
}

// Or use primary battery info directly
if ($info['level'] !== null) {
    echo "\nPrimary battery: " . $info['level'] . "% (" . $info['status'] . ")\n";
}

Notes

• Android requires the android-battery-bridge app running a TCP server on 127.0.0.1:8765 — see android_battery.c for details.
• On Linux the extension reads /sys/class/power_supply/*/capacity and status.
• On macOS the extension uses IOKit (build with Xcode tools available).
• On Windows the extension uses GetSystemPowerStatus.

Contributing

Contributions are welcome and appreciated! Here's how you can contribute:

1. Fork the project
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Please make sure to update tests as appropriate and adhere to the existing coding style.

License

This library is licensed under the CSSM Unlimited License v2.0 (CSSM-ULv2). See the LICENSE file for details.