README

Laravel NPS

轻松将自定义 NPS（净推荐值）集成到您的应用程序中。

安装

您可以通过 composer 安装此包

composer require maize-tech/laravel-nps

您可以使用以下命令发布和运行迁移

php artisan vendor:publish --tag="nps-migrations"
php artisan migrate

您可以使用以下命令发布配置文件

php artisan vendor:publish --tag="nps-config"

这是发布配置文件的内容

<?php

return [
    /*
    |--------------------------------------------------------------------------
    | Nps model
    |--------------------------------------------------------------------------
    |
    | Here you may specify the fully qualified class name of the nps model class.
    |
    */

    'nps_model' => Maize\Nps\Models\Nps::class,

    /*
    |--------------------------------------------------------------------------
    | Nps answer model
    |--------------------------------------------------------------------------
    |
    | Here you may specify the fully qualified class name of the nps answer
    | model class.
    |
    */

    'nps_answer_model' => Maize\Nps\Models\NpsAnswer::class,

    /*
    |--------------------------------------------------------------------------
    | Nps finder
    |--------------------------------------------------------------------------
    |
    | Here you may specify the fully qualified class name of the nps finder class.
    |
    */

    'nps_finder' => Maize\Nps\DefaultNpsFinder::class,

    /*
    |--------------------------------------------------------------------------
    | Nps visibility
    |--------------------------------------------------------------------------
    |
    | Here you may associate a custom visibility class to a name, which is then
    | used as a reference in the nps model.
    |
    */

    'visibility' => [
        'default' => Maize\Nps\DefaultNpsVisibility::class,
    ],

    /*
    |--------------------------------------------------------------------------
    | Nps range
    |--------------------------------------------------------------------------
    |
    | Here you may associate a custom range class to a name, which is then
    | used as a reference in the nps model.
    |
    */

    'range' => [
        'default' => Maize\Nps\DefaultNpsRange::class,
        'minimal' => Maize\Nps\MinimalNpsRange::class,
        'emoji' => Maize\Nps\EmojiNpsRange::class,
    ],

    /*
    |--------------------------------------------------------------------------
    | Route configurations
    |--------------------------------------------------------------------------
    |
    | Here you may specify whether routes should be enabled or not.
    | You can also customize the routes prefix and middlewares.
    |
    */

    'routes' => [
        'enabled' => true,
        'prefix' => '',
        'name' => 'nps',
        'middleware' => ['auth:api'],
        'endpoints' => [
            'show' => [
                'middleware' => [],
            ],
            'answer' => [
                'middleware' => [],
            ],
            'delay' => [
                'middleware' => [],
            ],
        ],
    ],

    /*
    |--------------------------------------------------------------------------
    | Cache
    |--------------------------------------------------------------------------
    |
    | Here you may specify the amount of time, in seconds, where each nps
    | is cached to avoid multiple database queries.
    |
    */

    'cache' => [
        'nps_ttl' => 3600,
        'nps_answer_ttl' => 3600,
    ],
];

用法

基本

要使用此包，请将 Maize\Nps\CanAnswerNps 特性添加到用户模型中。

以下是一个包含 CanAnswerNps 特性的示例模型

<?php

namespace App\Models;

use Maize\Nps\CanAnswerNps;

class User extends Model
{
    use CanAnswerNps;

    protected $fillable = [
        'fist_name',
        'last_name',
        'email',
    ];
}

然后您可以从数据库创建一个或多个 NPS，或者如果您愿意，也可以使用 CMS 来处理创建。

以下是应填写字段

问题：标识 NPS 的题目
starts_at：NPS 的开始日期
ends_at：NPS 的结束日期
range：接受的给定 NPS 的值范围。此值必须等于 config/nps.php 中定义的 range 列表中的某个键。默认为 default。
visibility：给定 NPS 的可见性。此值必须等于 config/nps.php 中定义的 visibility 列表中的某个键。默认为 default。

假设我们创建了一个从 2021-01-01 开始，一周后结束的 NPS：以下是我们将拥有的模型实体

$nps = [
    "id" => 1,
    "question" => "How would you rate our platform?",
    "starts_at" => "2021-01-01",
    "ends_at" => "2021-01-31",
    "range" => "default", // default range is 1-5
    "visibility" => "default", // by default a NPS is always visible
    "updated_at" => "2021-01-01",
    "created_at" => "2021-01-01",
];

现在您可以调用自定义 API 来检索、回复或延迟当前 NPS，这可以在 config/nps.php 中自定义

GET - /nps

此端点使用给定的标准检索当前 NPS

starts_at 日期必须早于 now()
ends_at 日期必须早于 now()
NPS 必须是可见的（默认为 true）

然后根据它们的 ends_at 日期对 NPS 条目进行筛选，以选择第一个到期的 NPS。

响应包含 NPS id（用于 POST 路由）、题目和接受的值。以下是一个示例响应正文

{
    "data": {
        "id": 1,
        "values": [
            1,
            2,
            3,
            4,
            5
        ],
        "question": "How would you rate our platform?"
    }
}

POST - /nps/{id}

此端点存储给定 NPS 的当前认证用户的答案。请求需要以下属性

value：用户选择的值
answer：用户（可选）编写的答案

请求应用了一些基本的验证规则

value 属性必须是整数
value 属性应在给定 NPS 模型定义的范围内
如果 value 为 null，则用户无法提交答案
用户可以拒绝提交 NPS。在这种情况下，value 和 answer 属性都应为 null

POST - /nps/{id}/delay

此端点将当前认证用户的 NPS 答案标记为缓存中的已回答，但仅限有限时间。

这样，即使答案未存储在数据库中，hasAnsweredCurrentNps 和 hasAnsweredNps 方法也将返回 true。

用户只能在经过指定时间后才能再次看到 NPS。

时间（以秒为单位）可以在 config/nps.php 中的 nps_answer_ttl 属性中配置。

自定义范围类

如果您想为NPS定义一个自定义的值范围，您可以定义一个新的类，该类继承自NpsRange抽象类，并包含一个$values数组。

class MyCustomNpsRange extends NpsRange
{
    protected static array $values = [2, 4, 6, 8, 10];
}

然后，您可以将该类与用于NPS模型range属性的名称关联起来。这可以通过在config/nps.php中添加range列表中的键值对轻松完成。

'range' => [
    'default' => Maize\Nps\DefaultNpsRange::class,
    'minimal' => Maize\Nps\MinimalNpsRange::class,
    'emoji' => Maize\Nps\EmojiNpsRange::class,
    'custom' => Path\To\MyCustomNpsRange::class,
]

如果您想将值定义为字符串数组，也可以定义一个关联数组。在这种情况下，键应包含字符串，而值是从POST端点发送的关联整数。

class EmojiNpsRange extends NpsRange
{
    protected static array $values = [
        '😡' => 1,
        '🙁' => 2,
        '😐' => 3,
        '😉' => 4,
        '😍' => 5,
    ];
}

自定义可见性类

如果您想为NPS定义一个自定义的可见性，您可以定义一个新的类，该类继承自NpsVisibility抽象类并实现__invoke抽象方法。

例如，假设我们想使NPS对于用户在至少登录5次后可见。这是我们应有的自定义可见性类

class MinLoginsVisibility extends NpsVisibility
{
    public function __invoke(Nps $nps): bool
    {
        return auth()->user()->accessLogs()->count() >= 5;
    }
}

然后，您可以将其与用于NPS模型visibility属性的名称关联起来。这可以通过在config/nps.php中的visibility列表中添加键值对轻松完成。

'visibility' => [
    'default' => Maize\Nps\DefaultNpsVisibility::class,
    'min_logins' => Path\To\MinLoginsVisibility::class,
]

测试

composer test

变更日志

请参阅变更日志以获取有关最近更改的更多信息。

贡献

请参阅贡献指南以获取详细信息。

安全漏洞

请查阅我们的安全策略了解如何报告安全漏洞。

鸣谢

许可

MIT许可证（MIT）。请参阅许可文件以获取更多信息。

maize-tech / laravel-nps

维护者

详细信息