README

PHP: Garmin Connect

A comprehensive PHP API wrapper for Garmin Connect, providing access to health, fitness, and device data. Works standalone or with Laravel.

About

This library enables developers to programmatically access Garmin Connect data including:

• Health Metrics: Heart rate, sleep, stress, body battery, SpO2, HRV, respiration
• Activity Data: Workouts, exercises, training status, performance metrics
• Device Information: Connected devices, settings, alarms, solar data
• Goals & Achievements: Personal records, badges, challenges
• Body Composition: Weight tracking, blood pressure, hydration
• Historical Data: Trends, progress tracking, date range queries

Based on the Python garminconnect library with OAuth authentication ported from garth.

Requirements

• PHP 8.4+
• ext-json
• Guzzle ^7.5 (installed automatically)

Installation

composer require alexoid/laravel-garmin

Quick Start (Standalone)

use Alexoid\GarminConnect\GarminConnect;

// Login with credentials
$garmin = new GarminConnect(
    email: 'your@email.com',
    password: 'yourpassword',
);
$garmin->login('~/.garminconnect');

// Subsequent runs — tokens are reused automatically
$garmin = new GarminConnect();
$garmin->login('~/.garminconnect');

// Get data
$summary = $garmin->getUserSummary('2026-03-02');
echo "Steps: " . $summary['totalSteps'];

$hr = $garmin->getHeartRates('2026-03-02');
echo "Resting HR: " . $hr['restingHeartRate'];

$activities = $garmin->getActivities(0, 10);

MFA (Two-Factor Authentication)

If your account has MFA enabled, use the non-blocking mode:

$garmin = new GarminConnect(
    email: 'your@email.com',
    password: 'yourpassword',
    returnOnMfa: true,
);

[$status, $clientState] = $garmin->login();

if ($status === 'needs_mfa') {
    $mfaCode = readline('MFA code: '); // or get from your UI
    $garmin->resumeLogin($clientState, $mfaCode, '~/.garminconnect');
}

// Now authenticated
$summary = $garmin->getUserSummary(date('Y-m-d'));

Or use the blocking MfaHandler interface for CLI apps:

use Alexoid\GarminConnect\Auth\MfaHandler;

class CliMfaHandler implements MfaHandler
{
    public function promptMfaCode(): string
    {
        echo "Enter MFA code: ";
        return trim(fgets(STDIN));
    }
}

$garmin = new GarminConnect(
    email: 'your@email.com',
    password: 'yourpassword',
    mfaHandler: new CliMfaHandler(),
);
$garmin->login('~/.garminconnect');

Quick Start (Laravel)

Publish the config:

php artisan vendor:publish --tag=garminconnect-config

Set environment variables:

GARMIN_EMAIL=your@email.com
GARMIN_PASSWORD=yourpassword
GARMIN_DOMAIN=garmin.com
GARMIN_TOKEN_STORE=file
GARMIN_TOKEN_PATH=/path/to/tokens

Log in (handles MFA interactively):

php artisan garmin:login

Use the Facade:

use Alexoid\GarminConnect\Laravel\GarminConnect;

GarminConnect::login();

$stats = GarminConnect::getUserSummary(now()->format('Y-m-d'));
$hr = GarminConnect::getHeartRates(now()->format('Y-m-d'));

Token Storage

Tokens are persisted so you don't need to re-authenticate on every request.

Examples

The examples/ directory contains working code you can run or copy into your project:

Available Methods (105)

Profile (6 methods)

User Stats (10 methods)

Heart Rate (3 methods)

Wellness (10 methods)

Activities (10 methods)

Activity Details (9 methods)

Downloads (2 methods)

Devices (6 methods)

Health (13 methods)

Metrics (7 methods)

Training (6 methods)

Badges & Challenges (8 methods)

Gear (8 methods)

Goals (1 method)

Uploads (6 methods)

Testing

vendor/bin/phpunit
vendor/bin/phpunit --testdox  # verbose output

Development

# Install dependencies
composer install

# Run tests
vendor/bin/phpunit

# Static analysis
vendor/bin/phpstan analyse

# Code formatting
vendor/bin/php-cs-fixer fix

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/new-endpoint)
3. Make your changes
4. Run tests (vendor/bin/phpunit)
5. Submit a pull request

License

MIT License. See LICENSE for details.