README

此包包含了一系列在我们Laravel项目中使用的共享实用工具。

包含内容

认证守卫和用户提供者
HTTP请求日志
通过normani发送通知
通用中间件
通用宏定义
快速代码脚手架的生成器占位符
其他有趣的东西

安装

您可以通过composer安装此包

composer require liveintent/laravel-common

为您的API添加认证

LiveIntent API通常位于API网关后面。这意味着当请求到达您的Laravel API时，请求应该包含一个特殊、可信的JWT承载令牌，以识别发出请求的用户。

为了允许您的Laravel API识别来自此LI令牌的用户，您需要两样东西。首先，您需要一个验证令牌是否可信和有效的认证守卫。其次，您需要一个用户提供者，可以将LI令牌转换为API可用的可操作User对象。

幸运的是，这两个都是通过LaravelCommon包提供的。

添加Token守卫

在您可以将LI Token守卫切换之前，您需要将其注册到您的应用程序中。您可以通过在应用程序的AuthServiceProvider中添加以下行来完成此操作：

use LiveIntent\LaravelCommon\LaravelCommon;

/**
 * Register any authentication / authorization services.
 *
 * @return void
 */
public function boot()
{
    // ...

    LaravelCommon::registerAuthGuard();
}

现在，守卫已注册，您可以通过编辑config/auth.php文件并将默认API驱动程序切换到li_token驱动程序来指示应用程序使用它。

'api' => [
    'driver' => 'li_token',
    'provider' => 'users',
    'hash' => false,
],

但是，请注意，默认的'users'提供者将无法与'li_token'守卫一起使用，您需要选择以下两个用户提供者之一。

添加用户提供者

LaravelCommon包提供了两个用户提供者。当然，您可以自由定义自己的，但这两个应该涵盖大多数情况。

瞬态用户提供者

瞬态用户提供者适用于您需要在使用API中验证用户时，但不想在您的数据库中保存任何用户信息的情况。瞬态用户提供者将向您的应用程序提供可操作User对象，该对象将适用于Laravel的所有认证机制，但它不会将用户持久化到您的数据库中。

要使用此提供者，您需要首先在应用程序的AuthServiceProvider中注册它。您可以通过在应用程序中放置以下行来完成此操作：

use LiveIntent\LaravelCommon\LaravelCommon;

/**
 * Register any authentication / authorization services.
 *
 * @return void
 */
public function boot()
{
    // ...

    LaravelCommon::registerAuthGuard();
    LaravelCommon::registerTransientUserProvider();
}

注册提供者后，您还需要在config/auth.php文件中的'providers'部分为其定义一个新的提供者配置。在这里，您还可以定义应使用哪个模型作为用户模型。

'providers' => [
    //...

    'li_token' => [
        'driver' => 'li_token_transient',
        'model' => App\Models\User::class,
    ]

最后，我们可以回到先前定义的认证守卫，并指示它使用此新的li_token用户提供者。修改守卫配置中的'provider'如下所示

'api' => [
    'driver' => 'li_token',
    'provider' => 'li_token,
    'hash' => false,
],

这就完成了！现在您应该能够向应用程序发出认证请求。

持久化用户提供者

当您的应用程序不仅需要验证用户，还需要与用户存储一些信息时，持久化用户提供者是一个更好的选择。在这种情况下，持久化用户提供者可以从您的数据库中检索相关的User对象，或者如果没有找到，则创建一个新的对象。

要使用此提供者，您需要首先在应用程序的AuthServiceProvider中注册它。您可以通过在应用程序中放置以下行来完成此操作：

use LiveIntent\LaravelCommon\LaravelCommon;

/**
 * Register any authentication / authorization services.
 *
 * @return void
 */
public function boot()
{
    // ...

    LaravelCommon::registerAuthGuard();
    LaravelCommon::registerPersistentUserProvider();
}

注册提供者后，您还需要在config/auth.php文件中的'providers'部分为其定义一个新的提供者配置。在这里，您还可以定义应使用哪个模型作为用户模型。

'providers' => [
    //...

    'li_token' => [
        'driver' => 'li_token_persistent,
        'model' => App\Models\User::class,
    ]

最后，我们可以回到先前定义的认证守卫，并指示它使用此新的li_token用户提供者。修改守卫配置中的'provider'如下所示

'api' => [
    'driver' => 'li_token',
    'provider' => 'li_token,
    'hash' => false,
],

这就完成了！现在您应该能够向应用程序发出认证请求。

自定义持久化方法

如果您需要更细粒度的控制用户在应用程序中的持久化方式，您可以在User模型上定义一个persistFromTransient方法，该方法将替换默认方式将用户持久化到数据库。

/**
 * Persist a copy of the transient user in the database.
 */
public function persistFromTransient()
{
    static::upsert(
        [['id' => $this->id]],
        ['id'],
        [],
    );
}

上述示例使用了Laravel的upsert功能，但您可以根据自己的理解定义该方法。

记录HTTP请求

从之前的实现升级

现在，AssignRequestId中间件已经被弃用，应从您的项目中删除。请参阅下述说明了解如何升级。

带有上下文的记录HTTP请求

在您的app/Http/Kernel.php中，更新您的$middleware以包括LogWithRequestContext。

注意：此中间件必须是数组中的第一个

protected $middleware = [
    \LiveIntent\LaravelCommon\Http\Middleware\LogWithRequestContext::class,
    // ... All other middleware

您还必须确保在config/logging.php中添加tap键和值到stderr。

'stderr' => [
    // ... Other configs
    'tap' => [
        \LiveIntent\LaravelCommon\Log\HttpLogger::class,
    ],
],

注意：如果您使用任何其他类型的日志记录机制，也要在该机制中添加相同的tap键/值。

记录HTTP请求摘要

如果您希望添加请求摘要日志条目，请在您的应用程序服务提供者中注册http日志记录器。

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use LiveIntent\LaravelCommon\LaravelCommon;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Register any application services.
     *
     * @return void
     */
    public function register()
    {
        LaravelCommon::logHttpRequests();
    }
}

健康检查

在您的应用程序服务提供者中注册健康检查。

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use LiveIntent\LaravelCommon\LaravelCommon;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Bootstrap any application services.
     *
     * @return void
     */
    public function boot()
    {
        LaravelCommon::healthChecks();
    }
}

这将注册一个位于'/health'的HTTP健康检查以及任何队列工作者的健康检查。健康检查的额外配置可用，请参阅实现。

注意，健康检查是在服务提供者的boot方法中注册的，而不是在register方法中。

测试

身份验证

LaravelCommon包提供了一些在HTTP测试期间与身份验证交互的辅助函数，这些辅助函数是Laravel已经提供的辅助函数的补充。

您可以使用ActsAsUsers特质提供的方法之一，指示您的测试“以用户身份登录”。

在下面的示例中，我们正在测试的端点要求用户必须是管理员。

<?php

namespace Tests\Feature\Api\Notification;

use Tests\Feature\Api\ApiTestCase;
use App\Models\PendingNotification;
use LiveIntent\LaravelCommon\Testing\ActsAsUsers;

class DeleteNotificationTest extends ApiTestCase
{
    use ActsAsUsers;

    /** @test */
    public function an_admin_user_can_delete_an_existing_notification()
    {
        $notification = PendingNotification::factory()->create();

        $this->actingAsAdmin()
            ->deleteJson("/api/notifications/{$notification->id}")
            ->assertOk();
    }
}

这些方法不会在数据库中持久化用户。如果您需要扮演数据库中持久化的用户，您可以使用Laravel框架本身提供的actingAs方法。

这里所有可用的模拟方法

开发

要开发此包，请克隆此存储库并通过以下方式安装依赖项：

composer install

在开发laravel包时，能够同时开发您的包和laravel应用程序通常很有用。

使用composer，您可以通过更新您的项目composer.json文件，将您正在开发的包符号链接到您所需项目的依赖项中。

{
  "repositories": [
    {
        "type": "path",
        "url": "../../packages/my-package"
    }
  ],
  "require": {
    "my/package": "*"
  }
}

测试

您可以通过以下方式运行测试：

composer test

# or directly via
vendor/bin/phpunit

代码检查

安装的代码检查器将自动格式化您的代码，使其符合我们商定的php编码标准。

您可以通过以下方式运行它：

composer lint

liveintent / laravel-common

维护者

详情