README

内部截图

Cloud Breeze：为何创建这个新项目

此包旨在扩展Laravel到一个可模块化的框架。通常情况下，对于Laravel，每次安装通常只创建一个应用程序。如果应用程序很大，它可能由几个功能组成，这些功能以某种方式相互关联。虽然这适用于愿意创建单个应用程序的人，但当需要创建一个包含许多不同功能的大型生态系统时，它变得更加困难，而这些功能可能根本不相关。

Cloud Breeze确保您拥有一个模块化系统，该系统具有（显然）模块，它们具有自己独立的实体：控制器、API & 网络路由、迁移、服务提供者、电子邮件、视图等。它提供了一些在Laravel已提供的基础上的一些额外功能，以尽可能简化开发。

• 专用认证页面（注册、登录、恢复）
• 专用仪表板
  • 用户管理
  • 选项管理
  • 媒体管理（图像等）
  • 模块管理（安装、启用、禁用）
  • 应用程序管理（让您为安全的API端点定义API密钥）。
• Oauth端点

这些在Laravel包扩展中提供。然而，我们已经将UI从后端分离，因此您可以调用（导入）一些前端元素，例如

• 字段，
• ValidationGenerator
• AuthService
• CoreService
• FieldsServices
• FormsServices
• Crud组件
• 对话框组件
• ...

这些确保您快速拥有一个与Cloud Breeze及其所有模块直接交互的UI。请注意，Cloud Breeze的UI是用Angular 8、Angular Material和其他一些依赖项构建的。您可以使用npm在您的环境中引入此包

npm i @cloud-breeze/core

安装

下载包

由于Cloud Breeze是一个包，因此可以使用composer命令进行安装

composer require tendoo/cms

然后，您需要运行以下命令来发布Cloud Breeze的资产

php artisan tendoo:publish

发布资产非常重要，因为系统需要将当前的Cloud Breeze版本保存到数据库中。这将有助于确切地知道何时执行更新。

创建存储磁盘

您需要更新位于config目录中的filesystems.php文件，进行以下更改

'disks' => [
  // ...

    'cb-root'       =>  [
        'driver'    =>  'local',
        'root'      =>  base_path()
    ],

  // ...
],

更新文件系统将允许Cloud Breeze正确保存模块并发布有用的资产。

注册EncryptCookies中间件

默认情况下，Cloud Breeze注册的cookie将被加密。因此，Cloud Breeze将无法从提供的登录UI中验证和记住已认证的用户。您需要在Kernel.php上注册中间件。如果您有任何特定的cookie从中间件 App\Http\Middleware\EncryptCookies 中释放，它将用于 Tendoo\Core\Http\Middleware\EncryptCookies。然后，您可以像这样注释（或删除）默认中间件 app\Http\Kernel.php

// something before...
protected $middlewareGroups = [
    'web' => [
        // \App\Http\Middleware\EncryptCookies::class, <= should be commended or deleted
        \Tendoo\Core\Http\Middleware\EncryptCookies::class, // <= here
        // other middleware ...
    ],

    // something else...
];
// something after...

更改用户模型

Cloud Breeze提供自己的身份验证表和模型。用户表名为_users，以表前缀命名。您需要调整您的身份验证配置文件，并确保使用的模型是Cloud Breeze提供的。通常，您需要这样修改：

'providers' => [
    'users' => [
        'driver' => 'eloquent',
        // 'model' => App\User::class,
        'model' => Tendoo\Core\Models\User::class, // <= the class here
    ],

    // 'users' => [
    //     'driver' => 'database',
    //     'table' => 'users',
    // ],
],

如果您在旧项目中使用Cloud Breeze，请确保检查.env文件是否有效。可能会发生Cloud Breeze将配置写入同一行的情况。这通常会导致应用程序崩溃，没有任何关于原因的提示。

安全

Cloud Breeze自带内置的安全系统。该系统主要是为了防止登录和注册页面的暴力攻击。基本上，它充当Laravel提供的节流中间件，但超越了通过黑名单随时间变得可疑的IP地址。显然，此行为可以禁用并配置。首先，您应该发布包以确保在您的Laravel项目的配置目录中可用的"tendoo.php"配置。

php artisan vendor:publish

一旦config/tendoo.php文件发布，它将包含一些配置，您可以设置以根据您的需求利用您的安全性。您会在该文件中找到2个安全系统：

• 反洪水请求
• 可疑请求

虽然反洪水请求可以防止来自同一客户端（基于其IP）发送过多的请求，但可疑请求允许您立即将任何尝试发送不可信请求的客户端（用户）列入黑名单。例如，执行GET请求/wp-admin/login.php，这显然表明该客户端正在寻找登录页面，而他不应该这么做。此解决方案让您可以处理此类请求，并在必要时阻止它们。

可疑请求配置如下：

'ip-banner' => [
    'enable'        =>  true,

    /**
     * describe what is forbidden
     * on each request processed
     */
    'forbidden'     =>  [
        '.php',
    ],

    /**
     * if a client makes the same mistake
     * "x" times, his ip will be banned
     */
    'mistakes-threshold'    =>  1,

    /**
     * the ip of the client
     * will be recorded
     * on the mentionned htaccess file
     */
    'htaccess-blocking'     =>  false,

    'htaccess-path'         =>  ''
],

对于反洪水请求，您只需指定客户端每分钟可以发送多少请求。如下所示：

'flood'             =>  [
    'prevent'       =>  false, // should be enabled
    'limit'         =>  30,
    'expiration'    =>  60
],

API

这描述了内部API的工作方式。

用户权限与角色

一个角色允许您将具有相同属性的用户分组。例如，您可以在系统中创建一个编辑角色，如果您计划创建一个需要此角色的博客。一旦创建角色，您就可以为其分配权限。权限是在系统中执行操作的能力。分配权限不是唯一步骤，您还需要验证用户是否通过其角色具有执行某些操作的能力。

创建角色

通过类Tendoo\Core\Models\Role可以创建角色。角色有一个名称和一个namespace，它更像是一个实体的计算机标识符。让我们看看以下示例：

<?php
use Tendoo\Core\Models\Role;

$role   = new Role;
$role->name   =   __( 'Super Man' );
$role->namespace  = 'superman';
$role->description  = ''; // whatever relevant to describe the role
$role->save();

到目前为止，您已创建了一个角色，这很简单。第二步是为角色分配权限，但在那之前，让我们创建一些权限。

创建权限

权限允许在系统中执行操作。您可以使用模型Tendoo\Core\Models\Permission来操作权限。让我们为超级人角色创建一些权限。

use Tendoo\Core\Models\Permission;

// ...
$permission   = new Permission;
$permission->name   =   __( 'Fly' );
$permission->namespace  =   'fly';
$permission->description  = ''; // once again whatever could be relevant.
$permission->save();

将权限分配给角色

现在我们已经创建了权限，让我们给超级人飞翔的能力。这应该使用模型类上的静态方法来实现，第一个参数是角色的namespace，第二个参数是权限的namespace。Role::addPermissions('[role namespace]', '[permission namespace]');。让我们看一个具体示例。

use Tendoo\Core\Models\Role;

// ... 
Role::addPermissions( 'superman', 'fly' );

您也可以通过将数组传递给第二个参数来添加多个权限。

use Tendoo\Core\Models\Role;

// ...
Role::addPermissions( 'superman', [ 'fly', 'eyelazer', 'frozen.breath' ]);

请注意，没有特定的方式来编写权限namespace，但是约定是不使用空格，并使用点"."或破折号"-"来分隔字符串。以下是一个示例："long.permission.namespace"。

从角色中删除权限

虽然您可以使用静态方法addPermissions来添加权限，但您应该使用RemovePermissions来删除特定角色的权限。以下是该方法的用例。

Role::namespace( 'superman' )
  ->removePermission([ 'fly' ]);

请注意，第二个参数始终应该是一个数组。

检查用户权限

如上所述，权限验证是通过用户模型在角色上进行的。然后你可以检查用户类。以下是操作步骤

use Tendoo\Core\Models\User;

if ( User::allowedTo( 'snap.infinite.gaunglet' ) ) {
  /// you're not strong enough
}

我们正在对此进行验证的用户是已连接的用户。如果没有用户当前连接，则此功能将无法工作。

表单与字段API

表单允许你从服务器检索表单或字段模式，你可以使用它来在前端渲染字段。请注意，这可以与来自npm包的“TendooFormsService”和“TendooFieldsService”一起使用。

如何注册表单端点

表单配置可以通过端点检索。以下是使其可用的方法

// let's register the event first
use Tendoo\Core\Facades\Hook;

//...
Hook::addFilter( 'public.forms', useThis( Event::class )->method( 'forms' ) );
// useThis() .. is a shorthand to write 'Modules\Events\Event@form'

通常，使用来自angular库的TendooFormsService服务，将使用以下请求对API服务器进行请求

http://yourapi.com/api/tendoo/public/forms/{namespace}/{index?}

其中namespace表示你的公共表单的命名空间，而index是可选的资源标识符（例如，用于填充表单的用户的ID），发送到服务器（通常在检索特定实体的表单时进行修改）。

现在，如果你提供的命名空间与你的表单命名空间匹配，只需返回表单即可。

namespace Modules\YourModule\Events;

class Event
{
  public function forms( $forms, $namespace ) 
  {
    if ( $namespace === 'your-namespace' ) {
      return [
        'title' =>  __( 'Your Form Titlte' ),
        'description' => '', // a description here
        'sections'  =>  [
          {
            'title' =>  '', // section title
            'description' =>  '',
            'fields'  =>  [ // here to register as many field as the section has.
              {
                'label' =>  'Field Name',
                'name'  =>  'field-name',
                'validation'  =>  'required',
                'description' =>  'field description',
                'appearance' => 'outline', // or any angular material valid field appearance
              }
            ]
          }
        ]
      ];
    }

    return $forms;
  }
}

如何注册字段端点

注册字段端点几乎与注册表单相似。它是通过Hook public.fields进行的。

请注意，如果你不需要具有复杂表单架构，包括部分，但只想有字段，你应该使用这个。

这可以用于创建登录和注册页面，这些页面通常不包含部分，而只有字段。

use Tendoo\Core\Facades\Hook;

// ...
Hook::addFilter( 'public.fields', useThis( Event::class )->method( 'fields' ) );

现在在回调中，如果你提供的命名空间与你的字段命名空间匹配，只需返回字段即可。

namespace Modules\YourModule\Events;

class Event
{
  public function fields( $fields, $namespace )
  {
    if ( $namespace === 'your-fields-namespace' ) {
      return [
        [
          'label' =>  __( 'Username' ),
          'name'  =>  'username',
          'validation'  =>  'required',
          'description' =>  __( 'Your username' ),
          'appearance'  =>  'outline',
          'type'      =>  'text'
        ], [
          'label' =>  __( 'Password' ),
          'name'  =>  'password',
          'validation'  =>  'required',
          'description' =>  __( 'Your username' ),
          'appearance'  =>  'outline',
          'type'      =>  'password' // to turn the text field into a password field
        ]
      ]
    }
    return $fields;
  }
}

CRUD API

CRUD API帮助你在特定表上快速创建/读取/更新/删除功能。目的是创建一个包含大多数有用功能的UI。本节将描述如何使用此API。

注册API命名空间

第一步是注册命名空间。在这里，命名空间表示一个唯一标识符。你可以按自己的意愿定义它，但需要使用模块命名空间。然后你可以使用类似的命名空间：yourmodule.orders，其中“yourmodule”是你的模块命名空间，“orders”是CRUD的对象。

以下是定义CRUD资源的方法

use Tendoo\Core\Facades\Hook;

Hook::addFilter( 'register.crud', useThis( CrudEvent::class )->method( 'orderCRUD' ) );

现在从事件类中，你只需返回用于CRUD组件的类。请注意，你可以使用php artisan module:crud命令自动生成CRUD。在过程结束时，你将得到一个用于CRUD实体的参考类。

namespace Modules\YourModule\Events;

use Modules\YourModules\Crud\OrdersCRUD;

class CrudEvent
{
  public function orderCRUD( $namespace )
  {
    if ( $namespace === 'yourmodule.orders' ) {
      return OrdersCRUD::class;
    }

    return $namespace;
  }
}

请注意，标识符yourmodule.orders是在使用Angular库中的TendooCrudService时提到的。通常，以下是使用该库进行请求的方法。

import { TendooCrudService } from '@cloud-breeze/core';

class OrdersComponent implements OnInit {
  constructor(
    private tendooCrud: TendooCrudService
  ){}

  ngOnInit() {
    this.tendooCrud.getConfig( 'yourmodule.orders' ).subscribe( config => {
      // render the crud
    })
  }
}

请参阅Angular库以获取更好的示例。