abduns/laravel-fit-reader

A focused Laravel 12 package to read Garmin .fit activity files.

v1.2.3 2026-05-17 12:47 UTC

Requires

• php: ^8.2
• illuminate/http: ^12.0
• illuminate/support: ^12.0

Requires (Dev)

• orchestra/testbench: ^10.0
• pestphp/pest: ^3.0
• pestphp/pest-plugin-laravel: ^3.0

MIT

• Dunn

• parser
• laravel
• activity
• training
• garmin
• Fit
• fitness
• workout
• fit-reader

README

A focused, developer-friendly Laravel package to read and parse Garmin .fit activity files.

Features

• Modern PHP support
• Lightweight and fast
• Typed API
• DTO Support
• Laravel Integration
• Extensible architecture

Installation

composer require abduns/laravel-fit-reader
php artisan vendor:publish --tag="fit-reader-config"

Quick Start

use Dunn\FitReader\Facades\FitReader;

// Read from a local path
$activity = FitReader::fromPath(storage_path('app/activities/run.fit'));

echo "Total Distance: " . $activity->totalDistanceMeters . " meters";

Example output:

Total Distance: 5000.5 meters

Why This Package?

• Existing solutions are outdated or rely on external binaries
• Missing modern PHP features
• Poor developer experience
• No standards compliance
• Not built specifically for Laravel 12+

This package provides a native PHP implementation for parsing FIT files, converting raw data into easy-to-use Data Transfer Objects (DTOs).

Usage

Basic Usage

use Dunn\FitReader\Facades\FitReader;

$activity = FitReader::fromPath(storage_path('app/activities/run.fit'));

// Activity Summary
echo "Start Time: " . $activity->startTime->format('Y-m-d H:i:s');
echo "Sport: " . $activity->getSportName(); // e.g., "running", "cycling", "swimming"

Advanced Usage

use Illuminate\Http\Request;
use Dunn\FitReader\Facades\FitReader;

class ActivityController extends Controller
{
    public function store(Request $request)
    {
        $file = $request->file('activity_file');
        
        // Parse the uploaded file directly
        $activity = FitReader::fromUploadedFile($file);
        
        // Export entire activity as array
        $array = $activity->toArray();
        $json = $activity->toJson();
        
        return response()->json([
            'distance' => $activity->totalDistanceMeters,
            'duration' => $activity->totalDurationSeconds,
            'records_count' => $activity->records->count(),
        ]);
    }
}

Configuration

return [
    'units' => [
        'raw_values' => false, // Set to true if you want raw values instead of converted units
    ],
];

Standards / Specifications

References:

• Flexible and Interoperable Data Transfer (FIT) Protocol

Supported Features

Feature	Support
Activity Parsing	✅
Records (Time Series Data)	✅
Laps Data	✅
Exporting Data	✅
Detecting Activity Type	✅

Compatibility

Platform	Supported
PHP 8.2+	✅
Laravel 12.x	✅

Design Goals

• Developer experience first
• Predictable APIs
• Minimal dependencies
• Strong typing
• Extensibility
• Native PHP Implementation

Architecture

• Decoded streams into typed DTOs (FitActivity, FitRecord, FitLap)
• Facade for ease of use
• Native file parsing without binary dependencies

Performance

Operation	Time
Parse typical FIT file	< 50ms

Testing

composer test

Roadmap

• Support writing/editing FIT files

Contributing

Contributions, issues, and discussions are welcome.

Security

If you discover security issues, please report them responsibly.

License

MIT