README

Laravel Strava 包

一个用于访问Strava API数据的Laravel包。兼容Laravel 5.0及以上版本。

目录

• Strava访问凭证
• 安装
• 发布Strava配置文件
• 自动发现
  • 提供者
  • 外观
• 使用
  • 初始化外观
  • 验证用户
  • 获取访问令牌
  • 访问令牌过期
  • 注销用户
• 可用方法
  • 运动员数据
  • 用户活动数据
  • 用户单个活动
  • 用户单个活动流
  • 活动评论
  • 活动赞
  • 活动圈
  • 活动区域
  • 更新活动
  • 运动员区域
  • 运动员统计
  • 俱乐部
  • 俱乐部成员
  • 俱乐部活动
  • 俱乐部管理员
  • 运动员俱乐部
  • 装备
  • 路线
  • 运动员路线
  • 分段
  • 分段努力
  • 收藏分段
• 参数类型
• 缓存
• 有用链接

Strava访问凭证

为了使用此包，您需要在您的Strava账户中创建一个应用。创建Strava应用以访问您的API凭证。请点击此处获取有关Strava API的更多信息。创建Strava应用

安装

在您的Laravel项目中安装包，请使用以下Composer命令

composer require codetoad/strava

发布Strava配置文件

vendor:publish命令将在您的Laravel项目配置文件夹config/ct_strava.php中发布一个名为ct_strava.php的文件。使用从您创建的Strava应用中生成的Strava API凭证编辑此文件。

php artisan vendor:publish --provider="CodeToad\Strava\StravaServiceProvider"

已发布配置文件内容

'client_id' => env('CT_STRAVA_CLIENT_ID', '')
'client_secret' => env('CT_STRAVA_SECRET_ID', '')
'redirect_uri' => env('CT_STRAVA_REDIRECT_URI', '')

或者，您可以选择忽略上述发布命令，并将以下变量添加到您的.env文件中。确保添加您的Strava应用凭证

CT_STRAVA_CLIENT_ID=ADD-STRAVA-CLIENT-ID-HERE
CT_STRAVA_SECRET_ID=ADD-STRAVA-SECRET-HERE
CT_STRAVA_REDIRECT_URI=ADD-STRAVA-REDIRECT-URI-HERE

自动发现

如果您正在使用Laravel 5.5+，则不需要手动添加服务提供者或外观。这将是自动发现的。对于Laravel 5.5以下的版本，您必须在您的Laravel项目config/app.php中的适当数组中手动添加ServiceProvider和Facade。

提供者

CodeToad\Strava\StravaServiceProvider::class,

别名 / 外观

'Strava' => CodeToad\Strava\StravaFacade::class,

使用

使用Strava外观

将Strava外观添加到您的控制器顶部，以便您可以使用Strava类方法。

use Strava;

class MyController extends Controller
{
  // Controller functions here...
}

验证用户

调用Strava::authenticate()方法，将您重定向到Strava。如果身份验证成功，用户将被重定向到您在config文件或.env文件中添加的redirect_uri。现在您还可以在身份验证时将$scope作为参数传递。您可以按需添加或删除作用域。一些是必需的，一些是可选的。有关可用作用域的详细信息，请参阅此处Strava身份验证作用域

public function stravaAuth()
{
  return Strava::authenticate($scope='read_all,profile:read_all,activity:read_all');
}

获取用户访问令牌

当返回到重定向的URI时，调用Strava::token($code)方法以生成用户的Strava访问令牌和刷新令牌。令牌使用重定向URI中的code参数值生成。务必将用户的access_token和refresh_token存储在您的数据库中。

public function getToken(Request $request)
{
  $token = Strava::token($request->code);

  // Store $token->access_token & $token->refresh_token in database
}

示例响应

"token_type": "Bearer"
"expires_at": 1555165838
"expires_in": 21600 // 6 Hours
"refresh_token": "671129e56b1ce64d7e0c7e594cb6522b239464e1"
"access_token": "e105062b153da39f81a439b90b23357c741a40a0"
"athlete": ...

目前您可以访问 Athlete 对象，并使用它登录到您的网站。当然，您需要编写登录系统的逻辑，但运动员姓名、电子邮件等信息都包含在对象中，供您与自己的数据库数据进行验证。

访问令牌过期

根据Strava实施的新流程，访问令牌现在将在6小时后过期，需要使用刷新令牌进行更新。在上面的示例中，您可以看到响应中有一个 refresh_token 和一个 expires_at 字段。在存储用户访问令牌时，您可能还想存储 expires_at 字段。这将允许您检查当前访问令牌何时过期。

在调用以下任何Strava方法时，您可能需要将当前时间与 expires_at 字段进行比较，以验证令牌。如果令牌已过期，您需要调用 Strava::refreshToken($refreshToken) 方法来生成新的令牌。您需要做的就是传递用户当前存储的 refresh_token，该方法将返回一组新的令牌（访问和刷新），并使用响应中的新令牌更新当前用户的令牌。以下是一个示例，使用 Strava::athlete($token) 方法。

use Carbon\Carbon;

public function myControllerFunction(Request $request)
{
  // Get the user
  $user = User::find($request->id);

  // Check if current token has expired
  if(strtotime(Carbon::now()) > $user->expires_at)
  {
    // Token has expired, generate new tokens using the currently stored user refresh token
    $refresh = Strava::refreshToken($user->refresh_token);

    // Update the users tokens
    User::where('id', $request->id)->update([
      'access_token' => $refresh->access_token,
      'refresh_token' => $refresh->refresh_token
    ]);

    // Call Strava Athlete Method with newly updated access token.
    $athlete = Strava::athlete($user->access_token);

    // Return $athlete array to view
    return view('strava.athlete')->with(compact('athlete'));

  }else{

    // Token has not yet expired, Call Strava Athlete Method
    $athlete = Strava::athlete($user->access_token);

    // Return $athlete array to view
    return view('strava.athlete')->with(compact('athlete'));

  }

}

注销用户

您可以让用户在您的Strava应用中注销他们的Strava账户。只需允许用户调用以下方法，传递存储在他们账户中的访问令牌。

Strava::unauthenticate($token);

可用方法

所有方法都需要访问令牌，一些方法接受以下列出的可选参数。

• 可选参数
  • $page (Int - 默认 1)
  • $perpage (Int - 默认 10)
  • $before (Int/Timestamp - 默认 = 最新的)
  • $after (Int/Timestamp - 默认 = 最新的)

运动员数据

返回当前认证的运动员。

Strava::athlete($token);

用户活动数据

返回运动员的活动。

Strava::activities($token, $page, $perPage, $before, $after);

用户单个活动

返回由认证的运动员拥有的指定活动。

Strava::activity($token, $activityID);

用户单个活动流

返回指定活动的流。

// $keys is a string array containing required streams
// e.g. ['latlng', 'time']
Strava::activityStream($token, $activityID, $keys = '', $keyByType = true);

活动评论

返回指定活动的评论。

Strava::activityComments($token, $activityID, $page, $perPage);

活动赞

返回对活动表示赞成的运动员。

Strava::activityKudos($token, $activityID, $page, $perPage);

活动圈

返回活动的圈数据。

Strava::activityLaps($token, $activityID);

活动区域

需要Summit功能。返回指定活动的区域。

Strava::activityZones($token, $activityID);

更新活动

更新由认证的运动员拥有的指定活动。需要 activity:write，因此要更新活动，您需要按照以下方式进行认证：Strava::authenticate('read_all,profile:read_all,activity:read_all,activity:write');。

Strava::updateActivityById($token, $activityID, array $updateableActivity);

您可以从以下内容更新一个或多个单个参数

// Example $updateableActivity
$updateableActivity = [
    'commute' => false,
    'trainer' => false,
    'description' => 'Easier ride than usual',
    'name' => 'Fun ride',
    'type' => 'Ride', // string, instance of ActivityType
    'gear_id' => 'b12345678987654321',
];

在官方Strava文档中查找更多信息

• 可更新活动
• 活动类型

运动员区域

返回认证运动员的心率区和功率区。

Strava::athleteZones($token);

运动员统计

返回运动员的活动统计信息。

Strava::athleteStats($token, $athleteID, $page, $perPage);

俱乐部

返回使用其标识符的给定俱乐部。

Strava::club($token, $clubID);

俱乐部成员

返回属于给定俱乐部的运动员列表。

Strava::clubMembers($token, $clubID, $page, $perPage);

俱乐部活动

从特定俱乐部的成员中检索最近的活动。认证的运动员必须属于请求的俱乐部才能调用此端点。支持分页。尊重所有活动的运动员个人资料可见性。

Strava::clubActivities($token, $clubID, $page, $perPage);

俱乐部管理员

返回给定俱乐部的管理员列表。

Strava::clubAdmins($token, $clubID, $page, $perPage);

运动员俱乐部

返回包括认证运动员的俱乐部的列表。

Strava::athleteClubs($token, $page, $perPage);

装备

使用装备ID检索设备数据。

Strava::gear($token, $gearID);

路线

返回使用其路线ID的路线。

Strava::route($token, $routeID);

运动员路线

返回使用运动员ID创建的路线列表。

Strava::athleteRoutes($token, $athleteID, $page, $perPage);

分段

返回指定的段。

Strava::segment($token, $segmentID);

分段努力

返回由认证的运动员拥有的活动中的段努力。

Strava::segmentEffort($token, $segmentID);

收藏分段

认证运动员的收藏段列表。

Strava::starredSegments($token, $page, $perPage);

获取API限制

Strava在响应头中返回有关API调用配额和使用情况的信息。

以下列出的方法在调用使用API限制（如获取活动）时会返回此信息。一些调用，如刷新访问令牌，似乎不会消耗API调用限制，因此结果数组中将出现null。

同样，当你尝试在调用消耗限制之前获取限制时，你将收到null。默认的允许限制不是硬编码的，因为不同的账户可能有不同的限制。

所有API限制

以多维数组的形式返回所有限制，例如。

[  
	['allowance']['15minutes'] => "100",  
	['allowance']['daily'] => "1000",  
	['usage']['15minutes'] => "7",  
	['usage']['daily'] => "352",  
]

Strava::getApiLimits();

分配的API限制

返回Strava账户可用的每日和15分钟请求限制，例如。

[  
	['15minutes'] => '100',  
	['daily'] => '1000',  
]

Strava::getApiAllowanceLimits();

使用的API调用

返回在Strava账户中使用的每日和15分钟调用的数量，例如。

[  
	['15minutes'] => '7',  
	['daily'] => '352',  
]

Strava::getApiUsageLimits();

参数类型

$token        = string
$activityID   = integer
$athleteID    = integer
$clubID       = integer
$gearID       = integer
$routeID      = integer
$segmentID    = integer
$page         = integer
$perPage      = integer
$before       = integer (timestamp)
$after        = integer (timestamp)

缓存

强烈建议您缓存对Strava的请求，原因如下。

(1) 速率限制

Strava的API速率限制为每15分钟100个请求和每天10,000个请求。如果你的网站流量很大，你可能需要考虑缓存Strava响应数据，以免超过这些限制。

(2) 网站加载速度

缓存您的Strava数据将大大提高网站加载时间。

有用链接

• Laravel缓存文档
• Strava开发者
• 创建Strava应用