README

Laravel Notes

任何和所有模型实体的集中式备注存储。终于不再需要在每个表中存储备注字段了！非常适合系统级通用评论系统。

安装最新版本 · 报告错误 · 请求功能

📔 目录

关于项目
- 技术栈
- 特性
安装
- 版本矩阵
用法
- 配置
- 模型
贡献
- 项目工具快速参考
变更日志
许可证
致谢

🌟 关于项目

在最近的一个个人项目中，我发现我几乎在所有表中都使用了notes字段，并且功能也是共享的。这个想法是用户可以快速对系统中的任何实体留下备注，这样集中化可以节省每个表中大量的开销和重复代码。我还使用了一个共享的Livewire表格，它会在查看特定实体时自动加载Audit（该包的优秀设计启发了本项目）。该表格会自动注入到由URL别名自动确定的渲染视图中，这是一个完美的用例，可以复制用于备注系统，因此这个库应运而生。

👾 技术栈

语言: PHP
依赖管理器: Composer
框架: Laravel
包: illuminate/support
包: orchestra/testbench
包: pestphp/pest
包: phpunit/phpunit
包: friendsofphp/php-cs-fixer

🎯 特性

针对任何模型实体的集中式备注存储
节省在多个表中复制重复字段和功能
通过接口和特性组合快速应用于任何模型
易于覆盖的用户解析器，用于自定义认证场景
高度可定制和可覆盖
几分钟即可启动运行

未来可以尝试添加的功能

某种形式的自动化（可定制）可注入组件，用于Blade和/或Livewire，具有后端CRUD功能。
轻松扩展到所有表中任何重复字段集的快速捕获，可能是一个有趣的项目增强功能

💾 安装

可以通过Composer进行安装

composer require othyn/laravel-notes

然后通过以下方式将配置文件和迁移文件发布到您的应用范围中

# Config
php artisan vendor:publish \
    --provider="Othyn\\LaravelNotes\\LaravelNotesServiceProvider" \
    --tag="config"

# Migrations
php artisan vendor:publish \
    --provider="Othyn\\LaravelNotes\\LaravelNotesServiceProvider" \
    --tag="migrations"

请记住检查默认配置是否符合您的需求（如有必要则进行修改），并运行迁移以生成新的notes表！

接下来，您需要前往配置部分，让我们开始了解使用方法！在那里见。

版本矩阵

以下是当前项目中使用的框架和库的支持版本矩阵。

如果您需要支持旧版本的Laravel，请提交一个问题，因为我们可能能够降低版本要求，我认为不需要这么新。或者，您可以自由地提交一个PR！

🛠️ 使用方法

Laravel Notes在实现上很简单，要开始使用，您只需要将相关的接口和特质组合添加到您希望存储笔记的模型中。

🐘 模型

所以，您想使用Laravel Notes？我喜欢您，让我们动手做吧。您需要做的只是添加相关的接口和特质组合到您希望存储笔记的模型中

<?php

declare(strict_types=1);

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

/**
 * What better place to store notes. 
 */
class Fridge extends Model implements \Othyn\LaravelNotes\Contracts\Notable
{
    use \Othyn\LaravelNotes\Traits\Notable;
}

就是这样！

以下方法和属性将暴露给模型

<?php

declare(strict_types=1);

$fridge = Fridge::first();

// Gets an Eloquent Collection of all Notes currently attached to the Fridge, this is a magic implementation that 
//  Laravel automagically generates based on the `notes()` relationship
$notes = $fridge->notes;

// Gets the latest Note that was attached to the Fridge
$latestNote = $fridge->latestNote();

// Gets the oldest Note that was attached to the Fridge
$oldestNote = $fridge->oldestNote();

// Create a new Note on the Fridge, with the authentication relation being automatically captured at creation if
//  applicable, returns the created Note
$note = $fridge->note(contents: 'Remember to buy some chocolate');

// From the Note instance, you can also get the attached Notable instance, in this case the Fridge, this is a magic
//  implementation that Laravel automagically generates based on the `notable()` relationship
$notable = $note->notable;

// From the Note instance, you can also get the attached User instance, in this case the default User implementation,
//  this is a magic implementation that Laravel automagically generates based on the `user()` relationship
$user = $note->user;

因为我们处理的是原生Laravel关系，所以所有常规的Eloquent内容也适用于所使用的关系方法

<?php

declare(strict_types=1);

$fridge = Fridge::first();

// Gets a Note by its ID on a Fridge
$note = $fridge->notes()->find(7);

// Get all Notes on the Fridge with who wrote them
$notes = $fridge->notes()->with('user')->get();

这是默认的Note实体的样子，方便属性引用

<?php

declare(strict_types=1);

namespace Othyn\LaravelNotes\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\SoftDeletes;

/**
 * Othyn\LaravelNotes\Models\Note.
 *
 * @property int                             $id
 * @property int                             $user_id
 * @property int                             $user_type
 * @property int                             $notable_id
 * @property int                             $notable_type
 * @property string                          $contents
 * @property \Illuminate\Support\Carbon|null $created_at
 * @property \Illuminate\Support\Carbon|null $updated_at
 * @property \Illuminate\Support\Carbon|null $deleted_at
 *
 * @mixin \Eloquent
 */
class Note extends Model implements \Othyn\LaravelNotes\Contracts\Note
{
    use SoftDeletes;
    use \Othyn\LaravelNotes\Traits\Note;

    /**
     * {@inheritdoc}
     */
    protected $guarded = [
        'id',
        'created_at',
        'updated_at',
        'deleted_at',
    ];
}

如您所见，IDE类型提示已嵌入到合约和默认模型中，以协助发现上述所有方法和属性。

如果您想更进一步，让事情变得更精彩，让我们看看配置能为您做什么。

🔧 配置

由于我们将配置作为安装的一部分发布，您现在应该在项目中有一个可编辑的 config/laravel-notes.php 文件。以下是每个配置选项的含义以及它能为您做什么的详细说明。

note
- 类型: \Othyn\LaravelNotes\Contracts\Note
- 默认: \Othyn\LaravelNotes\Models\Note::class
- 描述
  - 用于引用Note的模型实例，该实例实现\Othyn\LaravelNotes\Contracts\Note。
  - 您可以在任何自定义实现中使用\Othyn\LaravelNotes\Traits\Note特质来实现基本功能。
auth.guards
- 类型: array<string>
- 默认: ['web', 'api']
- 描述
  - 应该轮询的Laravel Auth守卫，以确定绑定到Note的登录User。
auth.user.field_prefix
- 类型: string
- 默认: user
- 描述
  - 多态关系字段前缀，将用于notes表中的{field_prefix}_id和{field_prefix}_type。
auth.user.resolver
- 类型: \Othyn\LaravelNotes\Contracts\UserResolver
- 默认: \Othyn\LaravelNotes\Resolvers\UserResolver::class
- 描述
  - 应该解析绑定到Note的认证Entity的对象，实体的id是唯一重要的。
  - 您可以使用\Othyn\LaravelNotes\Contracts\UserResolver合约轻松实现自己的解析器。
  - 必须返回一个\Illuminate\Contracts\Auth\Authenticatable实例或返回用户值的null。
database.connection
- 类型: string
- 默认: config('database.default')
- 描述
  - 用于所有笔记相关活动的数据库连接。
  - 在确定默认值时，它将首先从环境变量LARAVEL_NOTES_CONNECTION中读取，然后读取Laravel默认的database.default配置值。
database.table
- 类型: string
- 默认: notes
- 描述
  - 用于存储笔记的数据库表。
  - 在确定默认值时，它将首先从环境变量LARAVEL_NOTES_TABLE中读取，然后将其设置为上述预定义的默认值。

就这样！想贡献？继续阅读。

🍞 贡献

请参阅贡献指南了解如何开始。感谢您的贡献！

🧰 项目工具快速参考

项目命令只有几个，都是一些常规内容。

# Lets make sure things are formatted correctly.
$ composer php-cs-fixer

# Lets make sure things are still functioning as intended.
$ composer test

# Lets make sure things are still functioning as intended, this time with code coverage reporting.
$ composer test-coverage

就这些了，去创造一些酷炫的东西并提交一个PR吧！

⚠️ 许可证

在MIT许可证下分发。有关更多信息，请参阅LICENSE。

💎 致谢

在制作此项目过程中使用到的有用资源和库。

README：Louis3797/awesome-readme-template
README：ikatyang/emoji-cheat-sheet
README：shields.io
Logo：Tag SVG Vector 242
- 来自Cube Icon Collection
- 许可协议CC Attribution License
起始模板：Laravel Package Boilerplate
灵感来源：owen-it/laravel-auditing

othyn / laravel-notes

维护者

详细信息