README

本包为在upcoach平台上开发应用程序提供了一个起点。它包含一些有用的组件，如API客户端、请求验证和webhook控制器，以帮助您顺利开始。

功能

安装和Webhook管理

要使用本包与upcoach配合，您需要在upcoach开发者门户中提供安装URL和Webhook URL。本包在routes/api.php文件中提供了两个端点来自动处理这些URL。

POST /api/upcoach-install
POST /api/upcoach-webhooks

要设置您的应用程序，请使用以下URL：

https://your-application-address.com/api/upcoach-install 作为安装URL。
https://your-application-address.com/api/upcoach-webhooks 作为Webhook URL。

upcoach请求中间件

要验证来自upcoach的传入请求，您可以使用 Upcoach\UpstartForLaravel\Http\Middleware\EnsureUpcoachRequestIsValid 中间件。此中间件将验证请求的签名，如果有效，则将安装添加到请求对象中。

API客户端

应用程序安装后，将发起一个包含API令牌的安装请求。此令牌通过安装模型保存在数据库中，包括其他相关信息。您可以使用此令牌在查询upcoach API时访问所需的API端点（限制于已安装的组织）。

以下是使用提供的upcoach API客户端的示例

$installation = Upcoach\UpstartForLaravel\Models\Installation::query()
    ->forOrganization($organizationId)
    ->firstOrFail();

或者如果您正在使用Upcoach\UpstartForLaravel\Http\Middleware\EnsureUpcoachRequestIsValid中间件，您可以通过请求对象访问安装

$installation = $request->installation;

然后您可以使用upcoach API客户端查询API

$client =  app(Upcoach\UpstartForLaravel\Api\Client::class, [$installation]);
$programInfo = $client->getProgramInfo($programId);

入门

要开始使用本包，您需要按照以下步骤操作

在upcoach开发者门户上注册upcoach开发者计划。
在开发者门户上创建一个新的应用程序。
使用以下命令安装包

composer require upcoach/upstart-for-laravel

通过运行以下命令发布配置和迁移文件

php artisan upstart-for-laravel:install

通过将以下详细信息添加到您的.env文件中配置您的Laravel应用程序

UPCOACH_APP_ID=
UPCOACH_APP_SIGNING_SECRET=

您可以在开发者门户上应用程序的开发者信息部分找到这些详细信息。

用法

完成上述入门步骤。
在开发者门户上创建一个新的块。
在您的应用程序中创建一个新的路由来处理该块。
将Upcoach\UpstartForLaravel\Http\Middleware\EnsureUpcoachRequestIsValid中间件添加到路由中。

Route::group(['middleware' => [EnsureUpcoachRequestIsValid::class]], function () {
    Route::get('/your-block-connector-path', YourBlockController::class);
});

为该路由创建一个新的控制器。

class YourBlockController extends Controller
{
    public function __invoke(Request $request)
    {
        /**
         * Parameters coming from the upcoach
         * app_id
         * organization_id
         * program_id
         * block_id
         * program_block_id
         * user_id
         * user_role
         */

        // You can access the installation via the request object.
        $installation = $request->installation;

        // You can use the installation to query the upcoach API if needed.
        $client = app(Upcoach\UpstartForLaravel\Api\Client::class, [$installation]);
        $programInfo = $client->getProgramInfo($request->program_id);

        // Your code here.
    }
}

开发者模式 & 测试

本包提供了一些功能，可以帮助您在没有在upcoach应用程序上安装的情况下测试您的应用程序。

启用开发者模式

要启用开发者模式，您可以设置UPCOACH_DEVELOPER_MODE环境变量。当开发者模式启用时，Client类会被FakeClient替换，API调用将被模拟。有关更多信息，请参阅Upcoach\UpstartForLaravel\Mocks\FakeClient类。

UPCOACH_DEVELOPER_MODE=true

模拟upcoach请求

您可以使用upstart:simulate artisan命令来模拟upcoach请求。此命令支持交互模式，您可以直接在控制台中回答问题。运行以下命令以启动交互模式

php artisan upstart:simulate

或者，您可以直接通过提供所需选项来模拟请求。以下是一个示例

php artisan upstart:simulate --type=block --url=your-block-connector-path

您还可以提供有效载荷以覆盖默认的有效载荷参数

php artisan upstart:simulate --type=block --url=your-block-connector-path --payload='{"o": "custom-organization-id"}'

此命令对于测试设置页面也很有用

php artisan upstart:simulate --type=settings --url=your-settings-page

运行 upstart:simulate 命令后，它将显示您可以在浏览器中打开以模拟请求的 URL。此外，它还将输出完整的命令，包括所有有效载荷参数，您可以直接在控制台中用于后续请求，而无需回答问题并获得相同的 URL。

故障排除

CSRF Token Mismatch

如果您在上教练应用程序中遇到 CSRF Token Mismatch 错误，您可以通过将以下代码添加到 app/Http/Middleware/VerifyCsrfToken.php 文件来修复它

/**
     * Create a new "XSRF-TOKEN" cookie that contains the CSRF token.
     *
     * @param  \Illuminate\Http\Request  $request
     * @param  array  $config
     * @return \Symfony\Component\HttpFoundation\Cookie
     */
    protected function newCookie($request, $config)
    {
        return new Cookie(
            name: 'XSRF-TOKEN',
            value: $request->session()->token(),
            expire: $this->availableAt(60 * $config['lifetime']),
            path: $config['path'],
            domain: $config['domain'],
            secure: true,
            httpOnly: false,
            raw: false,
            sameSite: Cookie::SAMESITE_NONE
        );
    }

这将设置 CSRF 甜点的 SameSite 属性为 None 并将 Secure 属性设置为 true。这将允许上教练应用程序将 CSRF 甜点发送到您的应用程序。否则，由于默认将 SameSite 属性设置为 Lax，上教练应用程序将无法在 iframe 中将 CSRF 甜点发送到您的应用程序。

测试

composer test

贡献

有关详细信息，请参阅贡献指南

安全漏洞

请审查我们关于如何报告安全漏洞的安全策略

致谢

许可证

MIT 许可证 (MIT)。有关更多信息，请参阅许可证文件

upcoach / upstart-for-laravel

维护者

详情