README

Laravel 应用中的弹出式共享

1) 简介

Sharedo 为您提供管理 Laravel 应用角色和权限的界面。您可以为用户分配读取或写入权限，并在需要时移除权限。它由 Inertia.js 和 Laravel Bouncer 支持。

2) 动机

我们意识到，将共享功能添加到 Laravel 项目中非常耗时，这可能会阻碍开发过程。
此包旨在通过使您能够轻松地将项目实体与其他用户共享来解决此问题。

3) 依赖项

如果您已预先安装了 Tailwind 和 Bouncer，您可以继续阅读安装部分。

Tailwind 安装

按照以下步骤安装 Tailwind

npm install -D tailwindcss@latest postcss@latest autoprefixer@latest

接下来，生成您的 tailwind.config.js 文件

npx tailwindcss init

在您的 tailwind.config.js 文件中，使用所有 Blade 模板和 JavaScript 组件的路径配置 purge 选项，以便 Tailwind 可以在生产构建中摇树振去未使用的样式

module.exports = {
    purge: [
        "./resources/**/*.blade.php",
        "./resources/**/*.js",
        "./resources/**/*.vue",
    ],
    darkMode: false, // or 'media' or 'class'
    theme: {
        extend: {},
    },
    variants: {
        extend: {},
    },
    plugins: [],
};

在您的 webpack.mix.js 中，将 tailwindcss 添加为 PostCSS 插件

mix.js("resources/js/app.js", "public/js").postCss(
    "resources/css/app.css",
    "public/css",
    [require("tailwindcss")]
);

打开 ./resources/css/app.css 文件，并添加以下代码，替换原始文件内容

/* ./resources/css/app.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

接下来，在您的主 Blade 布局（通常是 resources/views/layouts/app.blade.php 或类似）中导入样式表，并在未存在的情况下添加响应式视口元标签

 <!doctype html>
  <head>
    <!-- ... --->
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <link href="{{ asset('css/app.css') }}" rel="stylesheet">
  </head>
  <!-- ... --->

Bouncer 安装

使用 composer 安装 Bouncer

composer require silber/bouncer v1.0.0-rc.10

将 Bouncer 的特质添加到您的用户模型中

use Silber\Bouncer\Database\HasRolesAndAbilities;

class User extends Model
{
    use HasRolesAndAbilities;
}

通过运行以下命令将 Bouncer 迁移发布到您的应用程序迁移目录

php artisan vendor:publish --tag="bouncer.migrations"

4) 安装

使用以下命令使用 composer 安装 Sharedo 包
```
composer require  geekyants/sharedo
```
安装后，将包的配置文件移动到您的项目配置文件夹
```
php artisan vendor:publish  --tag="config"
```
从现在开始，按照以下方式构建 sharedo 包中现有的视图组件
```
php artisan ui sharedo
```
将在您的资源目录中创建一个包含 Vue.js 组件的 Sharedo 文件夹。现在，您可以轻松自定义 Sharedo 的 Vuejs 组件 🚀
现在，运行迁移。执行此命令后，Bouncer 迁移和 new_users_sharedo 表将被迁移
```
php artisan migrate
```

要将共享o生成的 CSS 和 JavaScript 文件编译和压缩，请将以下内容添加到您的 webpack.mix.js 文件中
```
.js("resources/js/sharedo.js", "public/js")
.vue()
```
注意：如果您的 CSS 未在 app.css 文件中编译，您可以在 sharedo.blade.php 文件中更改它。
安装依赖项
```
composer install
npm install
```
最后，按照以下步骤构建您的资产
```
npm run dev
```

5) 使用方法

您必须在要共享的实体模型上定义一个 user 关系。该关系应返回该实体的用户。

要与其他用户共享您的实体，请访问

{APP_URL}/sharedo/{entity_name}/{entity_id}

例如，如果您想为 ID 为 123 的项目模型打开 Sharedo，请访问

{APP_URL}/sharedo/projects/123

注意：entity_name 应与您要共享的模型对应的数据库迁移的名称相同。

注意：Sharedo 会将错误信息发送回您的应用程序的错误 props。

如果您邀请的用户不在您的数据库中，Sharedo会自动在您的用户表中创建它。此外，一个新条目将被插入到new_users_sharedo表中，将用户的id作为外键引用，并将has_ever_logged_in属性设置为false。
这可以帮助您区分由Sharedo创建的用户和通过常规注册流程创建的用户。

为了限制其他用户访问您的实体，您必须显式使用Bouncer方法这里。

注意：**获得实体写入访问权限的用户也可以与其他用户共享该实体**。

6) 定制化

您可以通过修改位于配置文件夹中的sharedo.php文件来轻松定制Sharedo的功能。

您可以通过修改位于配置文件夹中的sharedo.php文件来轻松定制Sharedo的功能。

如果您的文件不在App\Models\中，则将modelPath更改为该位置而不是App\Models\。
```
"modelPath" => "App\Models\\"
```
要向Sharedo添加自己的自定义中间件，请将其附加到中间件数组。
例如，如果您想添加"admin"中间件，则您的中间件数组将如下所示
```
"middleware" => ['web', 'auth','admin']
```
如果您只想让某些实体可共享，可以将它们添加到restrict-entities数组中。
例如，如果您只想让files实体可共享，则您的数组将如下所示
```
'restrict-entities' => ['files'],
```
当用户获得访问权限时，您还可以向他们发送电子邮件通知。
当用户的访问权限发生变化时，Sharedo会触发一个**UserAbilityChanged**事件，并将其与**SendUserAbilityChangedNotification**监听器关联。如果您想发送电子邮件通知，请在EventServiceProvider中进行以下更改
```
use Geekyants\Sharedo\Events\UserAbilityChanged;
use Geekyants\Sharedo\Listeners\SendUserAbilityChangedNotification;
protected $listen = [
 ...
      UserAbilityChanged::class => [
        SendUserAbilityChangedNotification::class,
    ]

];
```
您还可以通过发布Sharedo邮件资源来修改电子邮件模板
```
php artisan vendor:publish  --tag="mail"
```
运行此命令后，邮件通知模板将位于resources/vendor/sharedo/mail目录

您可以将自己的监听器附加到事件。例如，如果您想将**SendSlackNotification**监听器附加到**UserAbilityChanged**事件，请执行以下操作
```
use Geekyants\Sharedo\Events\UserAbilityChanged;

...

protected $listen = [
        UserAbilityChanged::class => [
            SendSlackNotification::class,
        ]
    ];
```
要提供一个允许搜索用户的选项，您可以创建一个实现包中的**UserContactsInterface.php**的类并定义**getUserContacts**函数。

**getUserContacts**函数的返回类型应该是包含对象数组的JSON表示的字符串。每个表示用户的对象必须有一个如以下所示的**"email"**属性
```
"[
  { email: '', ... },
  { email: '', ... },
  { email: '', ... }
]"
```
例如，您可以创建一个名为**SendUserContacts**的类，该类实现**UserContactsInterface**并在**getUserContacts**函数中执行操作
```
<?php

namespace App\Repository;

use App\Models\User;
use Geekyants\Sharedo\Interfaces\UserContactsInerface;

class SendUserContacts implements UserContactsInerface
{

    public function getUserContacts($query)
    {
        $users = Some operation to get users
        $users = json_encode($users); //convert users array to json string
        return $users;
    }
}
```
在sharedo.config文件中，将"typehead"键设置为**SendUserContacts**类路径
```
"typehead" => "App\Repository\SendUserContacts"
```

7) 技术栈

Laravel，Tailwind，Bouncer，Vue.js，Inertia.js

8) 贡献者

Cyrus Passi (@Cyrus2505)
Ila Sahu (@ilasahu94)
Sanket Sahu (@sanketsahu)
Gaurav Guha (@greedy_reader)
Aditya Jamuar (@GeekJamuar)
Madhav Bansal (@madhavb23)

9) 如何贡献

感谢您对Sharedo的贡献兴趣！我们很幸运能有您🙂 前往贡献指南，了解如何成为这个美好、不断发展的社区的一部分。

对于主要更改，请先打开一个问题来讨论更改，并根据需要更新测试。

10) 许可证

根据MIT许可证授权。请参阅许可证文件获取更多信息。

geekyants / sharedo

维护者

详情