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 或类似）中导入您的样式表，并添加响应式视口 meta 标签（如果尚未添加）

 <!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 的 Vue.js 组件 🚀
现在，运行迁移。执行此命令后，将迁移 Bouncer 迁移和 new_users_sharedo 表
```
php artisan migrate
```

为了编译和最小化 sharedo 生成的 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数组中。
例如，如果您只想文件实体可共享，则您的数组将如下所示
```
'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 / share-dialog

维护者

详细信息