README

Laravel Markable

此包允许您轻松地将可标记功能添加到您的应用程序中，例如点赞、收藏、喜爱等。

安装

您可以通过 composer 安装此包

composer require maize-tech/laravel-markable

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

php artisan vendor:publish --tag="markable-migration-bookmark" # publishes bookmark migration
php artisan vendor:publish --tag="markable-migration-favorite" # publishes favorite migration
php artisan vendor:publish --tag="markable-migration-like"  # publishes like migration
php artisan vendor:publish --tag="markable-migration-reaction"  # publishes reaction migration

php artisan migrate

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

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

这是已发布配置文件的内容

<?php

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

    'user_model' => App\Models\User::class,

    /*
    |--------------------------------------------------------------------------
    | Table prefix
    |--------------------------------------------------------------------------
    |
    | Here you may specify the prefix for all mark tables.
    | If set, all migrations should be named with the given prefix and
    | the mark's class name.
    |
    */

    'table_prefix' => 'markable_',

    /*
    |--------------------------------------------------------------------------
    | Allowed values
    |--------------------------------------------------------------------------
    |
    | Here you may specify the list of allowed values for each mark type.
    | If a specific mark should not accept any values, you can avoid adding it
    | to the list.
    | The array key name should match the mark's class name in lower case.
    |
    */

    'allowed_values' => [
        'reaction' => [],
    ],
];

用法

基本用法

要使用此包，请将 Maize\Markable\Markable 特性添加到您希望添加标记的模型中。

完成后，您可以通过实现 $marks 数组来定义给定模型的可能标记列表，该数组包含标记类命名空间。

以下是一个包含 Markable 特性并实现 Like 标记的示例模型

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Maize\Markable\Markable;
use Maize\Markable\Models\Like;

class Course extends Model
{
    use Markable;

    protected $fillable = [
        'title',
        'description',
    ];

    protected static $marks = [
        Like::class,
    ];
}

现在您可以为模型分配点赞

use App\Models\Course;
use Maize\Markable\Models\Like;

$course = Course::firstOrFail();
$user = auth()->user();

Like::add($course, $user); // marks the course liked for the given user

Like::remove($course, $user); // unmarks the course liked for the given user

Like::toggle($course, $user); // toggles the course like for the given user

Like::has($course, $user); // returns whether the given user has marked as liked the course or not

Like::count($course); // returns the amount of like marks for the given course

自定义元数据

如果需要，您也可以在分配标记时添加自定义元数据

use App\Models\Course;
use Maize\Markable\Models\Like;

$course = Course::firstOrFail();
$user = auth()->user();

Like::add($course, $user, [
    'topic' => $course->topic,
]);

Like::toggle($course, $user, [
    'topic' => $course->topic,
]);

自定义标记模型

此包允许您定义自定义标记。

首先，您需要创建一个迁移，该迁移定义了新的标记模型。该包使用每个标记的单独表以提高执行相关查询时的性能。

迁移表名应包含在 config/markable.php 中定义的 table_prefix 属性下的前缀。默认前缀设置为 markable_。

以下是一个为书签创建的示例迁移

return new class extends Migration
{
    public function up()
    {
        Schema::create('markable_bookmarks', function (Blueprint $table) {
            $table->id();
            $table->foreignId('user_id')->constrained()->cascadeOnUpdate()->cascadeOnDelete();
            $table->morphs('markable');
            $table->string('value')->nullable();
            $table->json('metadata')->nullable();
            $table->timestamps();
        });
    }
}

完成后，您可以创建一个新的类，它扩展了抽象的 Mark 类，并实现 markableRelationName 方法，该方法用于检索使用标记实体作为中继的用户。

您还可以覆盖 markRelationName 方法，该方法用于检索给定模型实体的标记列表。默认情况下，关系名称是标记类名称的复数形式。

以下是一个书签标记的示例模型

<?php

namespace App\Models;

use Maize\Markable\Mark;

class Bookmark extends Mark
{
    public static function markableRelationName(): string
    {
        return 'bookmarkers';
    }
    
    /**
     * The override is useless in this case, as I am returning the default
     * relation name which is the plural name of the mark class name (bookmarks, indeed)
     */
    public static function markRelationName(): string
    {
        return 'bookmarks';
    }
}

这就完成了！现在您可以将自定义标记包含到所有您希望的模型中，并按前面的说明使用它。

处理标记值

您可能需要一个具有允许值子集的自定义标记。

在这种情况下，您可以像之前解释的那样定义您的自定义标记，并在 config/markable.php 下的 allowed_values 数组中添加允许值列表。

数组键名称应与标记的类名称小写匹配。

以下是在处理反应时的示例

'allowed_values' => [
    'reaction' => [
        'person_raising_hand',
        'heart',
        'kissing_heart',
    ],
],

然后您可以使用具有值的自定义标记

use App\Models\Post;
use Maize\Markable\Models\Reaction;

$post = Post::firstOrFail();
$user = auth()->user();

Reaction::add($post, $user, 'kissing_heart'); // adds the 'kissing_heart' reaction to the post for the given user

Reaction::remove($post, $user, 'kissing_heart'); // removes the 'kissing_heart' reaction to the post for the given user

Reaction::toggle($post, $user, 'heart'); // toggles the 'heart' reaction to the post for the given user

Reaction::has($post, $user, 'heart'); // returns whether the user has reacted with the 'heart' reaction to the given post or not

Reaction::count($post, 'person_raising_hand'); // returns the amount of 'person_raising_hand' reactions for the given post

您还可以使用通配符为特定标记允许任何值。

以下是在处理反应时的示例

'allowed_values' => [
    'reaction' => '*',
],

当设置时，您可以在给出反应时使用任何值

use App\Models\Post;
use Maize\Markable\Models\Reaction;

$post = Post::firstOrFail();
$user = auth()->user();

Reaction::add($post, $user, 'random_value'); // adds the 'random_value' reaction to the post for the given user

使用 eloquent 检索实体的标记列表

use App\Models\Course;
use App\Models\Post;

Course::firstOrFail()->likes; // returns the collection of like marks related to the course
Post::firstOrFail()->reactions; // returns the collection of reaction marks related to the post

使用 eloquent 检索标记实体的用户列表

use App\Models\Course;
use App\Models\Post;

Course::firstOrFail()->likers; // returns the collection of users who liked the course along with the mark value as pivot
Post::firstOrFail()->reacters; // returns the collection of users who reacted to the post along with the mark value as pivot

使用 eloquent 过滤标记模型

use App\Models\Course;
use App\Models\Post;

Course::whereHasLike(
    auth()->user()
)->get(); // returns all course models with a like from the given user

Post::whereHasReaction(
    auth()->user(),
    'heart'
)->get(); // returns all post models with a 'heart' reaction from the given user

测试

composer test

更新日志

有关最近更改的更多信息，请参阅更新日志。

贡献

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

安全漏洞

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

鸣谢

许可

麻省理工学院许可证（MIT）。有关更多信息，请参阅许可文件。

maize-tech / laravel-markable

维护者

详细信息