README

VOCAB MAPPER

A Laravel package for both multi-tenant and single tenant architectures.

Vocab Mapper通过定义标准术语（默认词汇）与用户首选术语（自定义词汇）之间的映射，为您的租户或用户提供个性化体验，尤其是在两种术语都指代同一核心概念时。

安装

composer require monamoxie/vocab-mapper

供应商发布

Vocab Mapper包含一些默认配置，但建议您发布并自定义这些设置以满足您的需求。

发布配置

php artisan vendor:publish --tag=vocab-mapper-config

探索词汇配置

迁移子目录

migration_sub_dir => null

这是Vocab Mapper迁移文件将被发布的子目录。默认值为null，适用于大多数单租户应用程序。

对于需要为特定租户迁移使用不同子目录的多租户系统，您只需在此处设置子目录值。例如，stancl/tenancy多租户包要求租户迁移保存在database/migrations/tenant中。

如果是这种情况，则应将migration_sub_dir => '/tenant'的值设置为。

实体模型

您的应用程序中的一个实体是希望为某个核心概念使用自定义词汇（不同于标准术语）的唯一租户或用户。

单租户系统

在单租户系统中，这通常是代表您的用户的模型类。例如，\App\Models\User::class或管理并标识您的用户的任何模型命名空间。

多租户系统

在多租户系统中，这通常是代表租户的模型类。例如，\App\Models\Tenant::class或管理并标识您的租户的任何模型命名空间。

有关更多信息，请参阅术语分解部分。

实体具有UUID

如果实体模型使用UUID作为其主键，请启用此选项。

发布迁移

php artisan vendor:publish --tag=vocab-mapper-migration

此操作将根据在migration_sub_dir中提供的配置发布迁移文件。如果没有设置特定路径，则文件将发布到Laravel的默认迁移目录。

迁移

运行负责处理您的数据库迁移的artisan命令。

单租户系统

php artisan migrate

多租户系统

要执行的命令取决于您的设置或包配置。例如，使用stancl/tenancy包的项目将执行

php artisan tenants:migrate

使Eloquent模型可词汇化

词汇是在您的应用程序中默认使用的名称、标识或领域驱动术语。在一个教育项目中，它可能是用于存储学校教授的所有学科的单词SUBJECTS。在汽车项目中，它可能是用于标识系统中的所有车辆的单词VEHICLES。

要将任何模型VOCABLE（这是在多个租户或用户之间维护并使用不同术语表示的能力），应将HasVocab特质包含到模型中

<?php

namespace App\Models;

use Monamoxie\VocabMapper\Traits\HasVocab;
use Illuminate\Database\Eloquent\Model;

class MyModel extends Model
{
  use HasVocab;
}

就这些。

有了这个，这个模型，MyModel，现在应该准备好接受并维护每个租户或用户的不同身份。

创建默认词汇

从您的应用程序的任何部分，您可以调用

<?php

use App\Models\MyModel;

(new MyModel)->createVocab(name: 'Vocab Name');

参数 name 是可选的。如果没有提供，则默认词汇表（term, identity）将为此模型的表名。

将词汇映射到实体

从您的应用程序的任何部分，您可以调用

<?php

use App\Models\MyModel;

(new MyModel)->mapVocabTo($entity, $customName);

其中

$entity = An instance of your entity model, as defined in the config, entity_model

$customName = The custom terminology set or choosen by this $entity.

这个实体可以是当前登录的租户或当前登录的用户。这无关紧要。

您必须确保此实体的实例与配置中定义的 entity_model 匹配。

如果实体实例与配置中的 entity_model 设置不匹配，则会抛出类型为的异常

Monamoxie\VocabMapper\Exceptions\InvalidEntityModelException

mapVocabTo 的双重性

如果您尝试将词汇映射到实体，并且词汇映射器检测到该词汇不存在，它将静默地创建一个新的词汇并继续映射。

获取映射到实体的词汇

从您的应用程序的任何部分，您可以调用

<?php

use App\Models\MyModel;

(new MyModel)->getVocabFor($entity);

其中

$entity is an instance of your entity model, as defined in the config, entity_model

词汇收集器

或者，您还可以利用词汇收集器来获取映射到用户的词汇

<?php

use App\Models\MyModel;
use Monamoxie\VocabMapper\Facades\VocabCollector;

VocabCollector::getFor($entity, MyModel::class)

其中

$entity is an instance of your entity model.

This could be an instance of \App\Models\Tenant, or \App\Models\User or whatever. As long as it the namespace matches what you defined in the `user_model` config

getVocabFor 和 VocabCollector::getFor 的区别

(new MyModel)->getVocabFor($entity) 将返回一个 eloquent 模型，它是 Monamoxie\VocabMapper\VocabMapper 的实例

您可能想使用它来检查模型或进行任何 eloquent 操作。

或者，VocabCollector::getFor 返回一个 Monamoxie\VocabMapper\Data\VocabResponse 的实例，它非常适合在应用程序的客户端部分显示此数据。

VocabResponse 提供了实体定义的自定义词汇，包括其单数和复数形式。

例如，您可以在控制器中设置如下

<?php

use App\Models\MyModel;
use Monamoxie\VocabMapper\Facades\VocabCollector;

public function index()
{
    $entity = Tenant::where('id', auth()->user()->id)->first();

    return view('academy.foo.bar', [
        'vocab' => VocabCollector::getFor($entity, MyModel::class),
        'data' => 'some random data',
        'data2' => 'some other random data'
    ]);
}

如果是 API 驱动的设置，您也可以有如下设置。这无关紧要。

<?php

use Illuminate\Support\Facades\Response;
use App\Models\MyModel;
use Monamoxie\VocabMapper\Facades\VocabCollector;

public function get()
{
    $entity = Tenant::where('id', auth()->user()->id)->first();

    return Response::json([
      'message' => '',
      'data' => 'SOME DATA',
      'vocab' => VocabCollector::getFor($entity, MyModel::class),
    ], 200);
}

您也不限于仅与 Monamoxie\VocabMapper\Data\VocabResponse 的实例一起工作。

您可以通过在它上调用 toArray() 方法将其响应转换为数组。

VocabCollector::getFor($entity, MyModel::class)->toArray()

术语分解

测试

vendor/bin/phpunit

对于基于控制台的功能测试

vendor/bin/phpunit --coverage-text

或

对于基于 HTML 的功能测试

 vendor/bin/phpunit --coverage-html test-coverage

贡献

vendor/bin/testbench workbench:install

许可证

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