Laravel Strava Client

Overview

The Laravel Strava Client is a comprehensive package designed to seamlessly integrate Strava API functionality into Laravel applications. Created by Jordan Partridge, a specialist in building Laravel integration packages, this package provides developers with tools to authenticate, retrieve, and manipulate Strava activity data through an elegant and Laravel-friendly interface.

🚀 Quick Start Guide

composer require jordanpartridge/strava-client

STRAVA_CLIENT_ID=your-client-id-from-strava
STRAVA_CLIENT_SECRET=your-client-secret-from-strava
STRAVA_REDIRECT_URI=https://yourdomain.com/strava/callback

# Optional: Configure where to redirect after successful connection
STRAVA_REDIRECT_AFTER_CONNECT=/dashboard

php artisan vendor:publish --tag=strava-client-config
php artisan vendor:publish --tag=strava-client-migrations
php artisan migrate

use JordanPartridge\StravaClient\Concerns\HasStravaTokens;
use JordanPartridge\StravaClient\Contracts\HasStravaToken;

class User extends Authenticatable implements HasStravaToken
{
    use HasStravaTokens;

    // Your existing code...
}

// In your Blade template - connect Strava button
<a href="/strava/redirect" class="btn btn-primary">
    Connect Strava Account
</a>

// In your controller - fetch activities (auto-refreshes tokens!)
use JordanPartridge\StravaClient\Facades\StravaClient;

$activities = StravaClient::activityForAthlete(1, 30);
$athlete = StravaClient::getAthlete();
$activity = StravaClient::getActivity(12345678);

Basic Usage

Zero-Configuration Authentication

The package automatically handles the entire OAuth 2.0 flow! No routes, controllers, or callback handling needed.

Step 1: Add the HasStravaTokens trait to your User model

use JordanPartridge\StravaClient\Concerns\HasStravaTokens;
use JordanPartridge\StravaClient\Contracts\HasStravaToken;

class User extends Authenticatable implements HasStravaToken
{
    use HasStravaTokens;
    // ...
}

Step 2: Direct users to start authentication

The package provides ready-to-use routes automatically:

// In your blade template or controller
<a href="/strava/redirect" class="btn btn-primary">
    Connect Strava Account
</a>

// Or programmatically
return redirect('/strava/redirect');

Step 3: That's it! 🎉

The package automatically:

• Handles OAuth redirect to Strava
• Processes the callback at /strava/callback
• Exchanges authorization code for tokens
• Stores encrypted tokens in the database
• Redirects users back to your configured success page

Configure where to redirect after successful connection:

// In config/strava-client.php
'redirect_after_connect' => '/dashboard', // or wherever you want

Automatic Token Refresh - Set and Forget!

The package automatically refreshes expired tokens on every API call. You never need to worry about token expiration again!

How Auto-Refresh Works:

1. You make any API call (activities, athlete data, etc.)
2. Package checks if token is expired or will expire soon
3. If expired, automatically refreshes token using refresh_token
4. Updates database with new access_token and expires_at
5. Retries the original API call with fresh token
6. Returns your data as if nothing happened!

Fetching Activities

Once authenticated, simply make API calls. Token refresh happens automatically behind the scenes:

use JordanPartridge\StravaClient\Facades\StravaClient;

// Set tokens from your stored user tokens
$token = auth()->user()->stravaToken;
StravaClient::setToken($token->access_token, $token->refresh_token);

// Get recent activities (page 1, 30 per page)
$activities = StravaClient::activityForAthlete(1, 30);

// Get more activities (page 2, 50 per page)
$moreActivities = StravaClient::activityForAthlete(2, 50);

// Get a specific activity by ID
$activity = StravaClient::getActivity(12345678);

Syncing Activities to Your Database

The package provides a convenient way to sync Strava activities to your application's database:

use JordanPartridge\StravaClient\Facades\Strava;
use App\Models\Ride;

public function syncActivities()
{
    $activities = Strava::activities()->get();

    foreach ($activities as $activity) {
        Ride::updateOrCreate(
            ['external_id' => $activity['id']],
            [
                'name' => $activity['name'],
                'distance' => $activity['distance'],
                'moving_time' => $activity['moving_time'],
                'elapsed_time' => $activity['elapsed_time'],
                'elevation' => $activity['total_elevation_gain'],
                'date' => Carbon::parse($activity['start_date']),
                'average_speed' => $activity['average_speed'],
                'max_speed' => $activity['max_speed'],
                'calories' => $activity['calories'] ?? 0,
                'polyline' => $activity['map']['summary_polyline'] ?? null,
            ]
        );
    }
}

Advanced Usage

Automatic Token Refresh

The package automatically handles token refreshing when tokens expire. Here's how it works:

// You don't need to check token expiry - the package handles it!
$token = auth()->user()->stravaToken;
StravaClient::setToken($token->access_token, $token->refresh_token);

// This call will auto-refresh tokens if needed
$activities = StravaClient::activityForAthlete(1, 30);

// Built-in retry protection (max 3 attempts)
// Throws MaxAttemptsException if refresh fails repeatedly

Error Handling

The package provides comprehensive error handling for various API scenarios:

use JordanPartridge\StravaClient\Facades\StravaClient;
use JordanPartridge\StravaClient\Exceptions\Request\RateLimitExceededException;
use JordanPartridge\StravaClient\Exceptions\Request\ResourceNotFoundException;
use JordanPartridge\StravaClient\Exceptions\Authentication\MaxAttemptsException;

try {
    $activities = StravaClient::activityForAthlete(1, 30);
} catch (RateLimitExceededException $e) {
    // Handle rate limiting (429 status)
    logger('Rate limited by Strava API');
} catch (ResourceNotFoundException $e) {
    // Handle 404 errors
    logger('Resource not found');
} catch (MaxAttemptsException $e) {
    // Handle when token refresh fails repeatedly
    logger('Token refresh failed after max attempts');
}

Example Implementation

The "Fat Bike Corps" page on jordanpartridge.us demonstrates a complete implementation of the Strava Client package.

use JordanPartridge\StravaClient\Facades\Strava;

public function handle()
{
    $activities = Strava::activities()
        ->after(now()->subDays(30))
        ->perPage(50)
        ->get();

    foreach ($activities as $activity) {
        Ride::updateOrCreate(
            ['external_id' => $activity['id']],
            [
                'name' => $activity['name'],
                'distance' => $activity['distance'],
                'moving_time' => $activity['moving_time'],
                'elevation' => $activity['total_elevation_gain'],
                'date' => Carbon::parse($activity['start_date']),
                'average_speed' => $activity['average_speed'],
                'max_speed' => $activity['max_speed'],
                'polyline' => $activity['map']['summary_polyline'] ?? null,
            ]
        );
    }

    // Clear cached metrics to ensure fresh data
    app(RideMetricService::class)->clearCache();
}

Frequently Asked Questions