README

Bono Metronic是一个PHP框架，集成了高级Bootstrap模板Admin，即Metronic 7版本。由Xinix Technology开发，旨在加快基于Web的应用程序的开发和构建过程。

# 为什么选择Bono？

以下是一些您应该使用Bono的理由

动态显示和API使用功能支持。
使用标准模板以满足SCRUD（搜索、创建、读取、更新和删除）需求。
通过内置架构快速构建Web应用程序。

# 系统需求

以下是使用Bono Metronic达到最佳效果所需的条件，例如

PHP版本7.3
MySQL
Composer

# 安装

要安装Bono Metronic，请打开终端并运行以下命令：

$ git clone git@gitlab.com:sagara-xinix/projects/bono-metronic-v7.git bono-metronic
$ cd my-app
$ rm -rf .git
$ composer install

# 数据库初始配置

按照安装步骤进行后，必须进行以下配置

在phpMyAdmin中创建一个数据库
将位于文件夹docs/db中的文件bono.sql导入
打开位于config目录中的文件config.php
根据您的phpMyAdmin凭据调整以下部分

<?php
//some codes
'bono.providers' => array(
        'Norm\\Provider\\NormProvider' => array(
            'datasources' => array(
                'mysql' => array(
                    'driver'   => '\\Norm\\Connection\\PDOConnection',
                    'dialect'  => '\\Norm\\Dialect\\MySQLDialect',
                    'prefix'   => 'mysql',
                    'dbname'   => 'nama_database',
                    'host'     => 'localhost',
                    'username' => 'root',
                    'password' => 'password'
                )
            ),
// some codes
?>

# 运行Bono Metronic

要运行Bono Metronic应用程序，只需在浏览器中访问localhost/bono-metronic/www。如果成功，您将进入登录页面。Bono Metronic已经有一个注册用户，可以用于开发需求。登录凭据可以是：

username : admin
password : password

# Bono Metronic表创建规则

在数据库中创建表时，有一些字段是必须创建的，这些字段将由Bono Metronic自动填充。以下是在每个表中必须创建的字段

# 集合

集合代表数据库中的表（实体），而在集合中返回包含架构的数组。集合文件位于config/collections目录中。

# 创建集合

如前所述。集合是表的表示。例如，在数据库中，您有一个名为"product"的表，并且您想为此创建一个集合，方法如下：

打开config/collections目录
创建一个名为Product.php的新文件
按照以下内容填充文件

<?php

return array(
    'schema' => array(
        // input schema here
    ),
);

?>

# 在配置中注册集合

所有已创建的集合都必须首先在位于/config目录的config.php文件中注册，以便可以访问其URI地址。方法是在以下部分添加：

<?php
// some codes
'Bono\\Middleware\\ControllerMiddleware' => array(
            'default' => 'App\\Controller\\AppController',
            'mapping' => array(
                '/test' => null,
                '/user' => null,
                '/previleges' => null,
                '/role' => '\\App\Controller\\RoleController',
                '/sysparam' => null,
                '/collection' => null,    
            ),
        ),
//some codes
?>

默认情况下，集合将使用AppController作为其默认控制器。注册集合后，我们可以通过地址localhost/bono-metronic/www/index.php/collection访问它。

# 架构

架构与集合密切相关。架构代表数据库表中存在的字段/数据（不包括状态、_created_by、_updated_by、_created_time和_updated_time）。Bono Metronic V7已提供各种可用的架构，用于加速开发过程。架构为相关集合生成用于SCRUD（搜索、创建、读取、更新和删除）的HTML字段。架构组件文件位于src\App\Schema目录中。

Bono Metronic V7提供的架构如下：

# 缩略图

Schema Thumbnail 用作处理图像类型输入数据的。缩略图使用命名空间 App\Schema\Thumbnail

<?php

use App\Schema\Thumbnail;

return array(
    'schema' => array (
        'photo' => Thumbnail::create('photo','Gambar')->set('list-column', true)->set('bucket','storage'),
    )
)

?>

说明 : 'photo' 是数据库中字段的名称。而 'Gambar' 是用作显示给用户的标签别名。'list-column' 设置为 true，表示该字段将在表中显示。同时 'bucket' 和 'storage' 表示图像数据将保存在 www/storage 目录中。

# NormString

Schema NormString 用于处理字符串类型输入数据。NormString 使用命名空间 App\Schema\NormString

<?php

use App\Schema\NormString;

return array(
    'schema' => array (
        'name'   => NormString::create('name')->set('list-column', true),
    )
)

?>

说明 : 'name' 是数据库中字段的名称。'list-column' 设置为 true，表示该字段将在表中显示。

# InputMask

Schema InputMask 用于处理具有特定模式（如 NIK 或 NPWP 编号）的整数类型输入数据。InputMask 使用命名空间 App\Schema\InputMask

<?php

use App\Schema\InputMask;

return array(
    'schema' => array (
        'ktp' => InputMask::create('ktp')->set('list-column', true)->set_mask('99-9999-99_99.999'),
    )
)

?>

说明 : 'ktp' 是数据库中字段的名称。'list-column' 设置为 true，表示该字段将在表中显示。set_mask 和 '99-9999-99_99.999' 表示将输入整数设置为该模式。

# FileUpload

Schema FileUpload 用于处理文件类型（如 .pdf、.docx、.txt 等）的输入数据。FileUpload 使用命名空间 App\Schema\FileUpload

<?php

use App\Schema\FileUpload;

return array(
    'schema' => array (
        'file' => FileUpload::create('file')->set('list-column', true)->set('bucket','storage1'),
    )
)

?>

说明 : 'file' 是数据库中字段的名称。'list-column' 设置为 true，表示该字段将在表中显示。'bucket' 和 'storage1' 表示图像数据将保存在 www/storage1 目录中。

# Reference

Schema Reference 用于处理单选类型输入数据。Reference 使用命名空间 App\Schema\Reference

<?php

use App\Schema\Reference;

return array(
    'schema' => array (
        'dropdown' => Reference::create('dropdown')->to(array('a' => 'testing1', 'b' => 'test2')),
    )
)

?>

说明 : 'dropdown' 是数据库中字段的名称。to(array('a' => 'testing1','b' => 'test2')) 表示在点击下拉按钮时显示的选项。'a' 是键，'testing1' 是值。

# SelectTwoReference

Schema SelectTwoReference 用于处理单选类型输入数据。与 Reference 的区别在于 SelectTwoReference 具有内置搜索功能，使下拉数据的搜索更加容易。SelectTwoReference 使用命名空间 App\Schema\SelectTwoReference

<?php

use App\Schema\SelectTwoReference;

return array(
    'schema' => array (
        'select' => SelectTwoReference::create('select')->to(array('a' => 'testing1', 'b' => 'test2')),
    )
)

?>

说明 : 'select' 是数据库中字段的名称。to(array('a' => 'testing1','b' => 'test2')) 表示在点击下拉按钮时显示的选项。'a' 是键，'testing1' 是值。

# MultiReference

Schema MultiReference 用于处理多选类型输入数据。MultiReference 使用命名空间 App\Schema\MultiReference

<?php

use App\Schema\MultiReference;

return array(
    'schema' => array (
        'role' => MultiReference::create('role')->to('Role'),
    )
)

?>

说明 : 'role' 是数据库中字段的名称。to('Role') 表示选择的数据来自 'Role' 集合/表。

# SearchReference

Schema SearchReference 用于处理选择类型输入数据。SearchReference 的优点是能够显示更完整的数据并具有内置搜索功能。SearchReference 使用命名空间 App\Schema\SearchReference

<?php

use App\Schema\SearchReference;

return array(
    'schema' => array (
        'user' => SearchReference::create('user')->to('User','first_name')->set('field',array('email','first_name')),
    )
)

?>

说明 : 'user' 是数据库中字段的名称。to('User','first_name') 表示选择的数据来自 'User' 集合/表，且在输入字段中显示的是 'first_name' 数据。而 set('field',array('email','first_name')) 是在点击搜索按钮时显示的详细信息，即用户的 "email" 和 "first_name" 数据。

# DatePicker

Schema DatePicker 用于处理日期数据输入。DatePicker 使用命名空间 App\Schema\DatePicker。

<?php

use App\Schema\DatePicker;

return array(
    'schema' => array (
        'testdate' => DatePicker::create('testdate')->setformatdate('dd-mm-yyyy'),
    )
)

?>

说明： 'testdate' 是数据库中字段的名称。使用 setformatdate('dd-mm-yyyy') 可以创建将要保存的日期格式。对于日期数据的格式，可以使用 dd-mm-yyyy 或 dd/mm/yyyy 格式，具体取决于需要。

# SysparamReference

Schema SysparamReference 用于处理选择数据输入。SysparamReference 用于创建选项，这些选项只有少数几个，无需创建新模块，并具有分组功能。其中一个示例数据是性别数据。SysparamReference 使用命名空间 App\Schema\SysparamReference。要创建独立的 Sysparam 数据，可以访问 URL localhost/bono-metronic/www/index.php/sysparam

<?php

use App\Schema\DatePicker;

return array(
    'schema' => array (
        'sysparam' => SysparamReference::create('sysparam')->setGroups('gender'),
    )
)

?>

说明： 'sysparam' 是数据库中字段的名称。使用 setGroups('gender') 表示根据 sysParams 性别数据对 Sysparam 进行分组。

# 控制器

Bono Metronic V7 有一个默认控制器，即位于 src\App\Controller 目录中的 AppController.php。这些设置可以在 /config 目录中的 config.php 文件中查看。文件 AppController.php 包含各种函数，涵盖了涉及 SCRUD 操作（搜索、创建、读取、更新和删除）的各种需求。实际上，AppController.php 是从 vendor/xinix-technology 目录中的 NormController.php 继承而来，但 AppController.php 已根据需求进行了修改。

# 自定义控制器

Bono Metronic V7 允许用户创建自定义控制器。例如，如果想要为实体 Category 创建一个控制器，可以在 src/App/Controller 目录中创建 CategoryController.php 文件。该文件必须 extends 到 AppController。要使用 CategoryController 而不是默认控制器，可以在 config.php 文件的相应部分进行更改。

<?php
// some codes
'Bono\\Middleware\\ControllerMiddleware' => array(
    'default' => 'App\\Controller\\AppController',
    'mapping' => array(
        '/test' => null,
        '/user' => null,
        '/previleges' => null,
        '/role' => '\\App\Controller\\RoleController',
        '/sysparam' => null,
        '/category' => '\\App\Controller\\CategoryController',    
    ),
),
//some codes
?>

# NORM

Bono Metronic 使用 NORM，即一种将数据库表中的数据转换为对象机制。NORM 本身具有一些标准，例如 find 和 findOne，以下将进行详细说明。

# find()

find() 是 Norm Bono Metronic 中的一个标准，用于从表中获取所有数据。find() 的语法如下：

 $items = \Norm::factory('table_name')->find();

# find($id)

find($id) 是 Norm Bono Metronic 中的一个标准，用于根据传递的参数 ID 获取一个数据。find($id) 的语法如下：

 $items = \Norm::factory('table_name')->find(id);

# find(array('field' => criteria))

find(array('field' => criteria)) 是 Norm Bono Metronic 中的一个标准，用于根据传递的参数字段标准获取多个数据。find(array('field' => criteria)) 的语法如下：

 $items = \Norm::factory('table_name')->find(array('field' => criteria));

例如，如果我们想获取具有 company_id 等于 3 的 employee 表中的数据，其语法如下：

$employees = \Norm::factory('employee')->find(array('company_id' => 3));

# findOne(array('field' => criteria))

findOne(array('field' => criteria)) 是 Norm Bono Metronic 中的一个标准，用于根据传递的参数字段标准获取第一个找到的数据，并仅返回第一个找到的数据。findOne(array('field' => criteria)) 的语法如下：

 $items = \Norm::factory('table_name')->findOne(array('field' => criteria));

例如，如果我们想获取具有 company_id 等于 3 的 employee 表中的数据，其语法如下：

$employees = \Norm::factory('employee')->findOne(array('company_id' => 3));

# 标准运算符

在 NORM 操作中，有一些运算符可以增加搜索数据库数据的功能。以下是可以用于 NORM 字段的运算符：

# 提供者

Provider 是 Bono Metronic V7 的一个部分，用于将数据库中的数据（响应）以 JSON 格式返回，以便可以处理特定需求，例如 API。

Provider 位于 src\App\Observer 目录中，Bono Metronic V7 默认有 3 个（三个）内置提供者，如下所示：

AppProvider.php
LoginProvider.php
MetronicProvider.php

通常情况下，Provider 的内容如下

<?php 
namespace App\Provider;

class AppProvider extends \Bono\Provider\Provider
{
    public function initialize()
    {
        $app = $this->app;
    }
}
?>

说明

Provider 本身有一个命名空间，即 App\Provider

Provider 有一个必需的方法，即 initialize()，其内容是对应用进行初始化

initialize() 方法将包含用于返回 JSON 格式数据的路由

# 初始化方法填充

我们可以用返回 JSON 格式响应的路由来填充 initialize 方法。例如，如果我们想从 product 表中获取数据并以 JSON 格式显示，我们可以创建如下路由

<?php
    // inside initialize function
    $app->get('/product_api', function () use ($app) {
      $data = Norm::factory('product')->find();
      $app->response->data('product', $data);
  });
?>

说明

首先，我们定义 HTTP 方法，我们使用 GET，URI 是 /product_api

然后，对于第二个参数，我们创建一个匿名函数，该函数获取 product 表中的所有数据

然后返回响应

要访问已创建的路由的 URL，只需访问以下 URL 即可 localhost/bono-metronic/www/index.php/product_api.json

# 自定义 Provider

Bono Metronic V7 允许用户创建自定义 Provider。例如，如果我们想为产品创建特定的 Provider，我们可以在 src/App/Provider 目录下创建 ProductProvider.php，然后在 config.php 文件中将 ProductProvider.php "注册"。

<?php 
// some code
'Bono\\Provider\\LanguageProvider' => null,
'App\\Provider\\AppProvider'=> null,
'App\\Provider\\ProductProvider'=> null, // register new provider

?>

然后，我们将 ProductProvider.php 扩展为 AppProvider。以下是一个 ProductProvider.php 的示例

<?php

namespace App\Provider;

use Norm\Norm;

class ProductProvider extends AppProvider {
    public function initialize()
    {
        $app = $this->app;

        $app->get('/product_api', function () use ($app) {
            $data = Norm::factory('product')->find(); // mengambil seluruh data product
            $app->response->data('product', $data); // kembalikan response JSON dengan nama product dan kirimkan $data
        });
    }
}
?>

# 观察者

观察者是 Bono Metronic 中的一个功能，当数据将被添加到数据库或已添加到数据库时将运行。Observer 文件位于 src/App/Observer 目录中。观察者通常使用的一些方法包括

Saving = 在 Create 和 Update 操作之前将数据添加到数据库时运行
Saved = 当数据已成功添加到数据库时运行，无论是 Create 还是 Update
Searching = 在修改筛选器 ($criteria) 时运行
Searched = 在修改已获取的数据时运行

# 自定义观察者

要创建自定义观察者，只需在 src/App/Observer 目录中创建新的 observer 文件。例如，如果我们想为 Product 集合创建一个观察者，文件名为 ProductObserver.php，具有命名空间 App\Observer。要将其用于相关集合，可以声明如下

<?php
return array(
    'observers' => array(
        'App\\Observer\\ProductObserver' => null, // declare observer here
    ),
    'schema' => array(
        // some schema
    ),
);

# 中间件

中间件是 Bono Metronic 中的一个功能，具有用于过滤或监视各种活动或请求的机制。Bono Metronic 的中间件目录位于 src/App/Middleware。中间件将检查所有过程，从 $this->next->call() 之后的行从下到上。默认情况下，Bono Metronic 在该目录中包含两个内置中间件，即 AuditTrailMiddleware 和 MetronicNotification。以下是这两个中间件的简要说明

# AuditTrailMiddleware

<?php

namespace App\Middleware;

use \Norm\Norm;

class AuditTrailMiddleware extends \Slim\Middleware {

    public function call(){
        $request = $this->app->request;
        $user = array();
        if(!empty($_SESSION['user'])){
            $user = $_SESSION['user'];
        }
        
        
        $data = $this->app->request->getBody();

        $this->next->call();
        
        if (!empty($_REQUEST['password'])) {
            unset($data['password']);
        }

        $trail = array(
            'user' => !empty($user['$id']) ? $user['$id']:'',
            'uri' => $request->getPath(),
            'method' => $request->getMethod(),
            'data' => (!empty($data)) ? json_encode($data) : '',
            'ip_address' => $request->getIp(),
            'user_agent' => $request->getUserAgent(),
        );

        $model = Norm::factory('AuditTrail')->newInstance();
        $model->set($trail);
        $model->save();
        
    }
?>

说明：基本上，AuditTrailMiddleware 用于记录或审计用户在访问页面时发送请求的所有活动。这些数据从用户 ID、访问的页面 URI、使用的方法、数据、IP 地址甚至用户代理（浏览器）开始。然后，这些数据被添加到数据库中的 audit_trail 表中。此中间件扩展了 Slim 的中间件，我们必须重写函数 call

# MetronicNotification

class MetronicNotificationMiddleware extends NotificationMiddleware
{
    public function show($options = null)
    {

        unset($_SESSION['notification']);

        if (is_null($options)) {
            return $this->show(array('level' => 'error')) . "\n" . $this->show(array('level' => 'info'));
        }

        $messages = $this->query($options);

        if (!empty($messages)) {
            $result = '<div class="alert '.$options['level'].'" role="alert">';

            foreach ($messages as $message) {
                $result .= '<span>'.$message['message'].'</span> ';
            }

            $result .= '</div>';

            return $result;
        }

    }
  
}

说明：基本上，NotificationMiddleware 负责显示当用户输入数据时出现的通知，无论是成功还是失败。此中间件扩展了 NotificationMiddleware，并且 NotificationMiddleware 也扩展了 Slim。在这里，我们重写了 NotificationMiddleware 的 show 函数

# 自定义中间件

要创建自定义中间件，我们只需在 src/App/Middleware 目录中创建新文件，例如名为 TestMiddleware.php 的文件，具有命名空间 App\Middleware。然后，我们创建一个继承自 \Slim\Middleware 的类，并强制重写函数 call()。

<?php

namespace App\Middleware;

class TestMiddleware extends \Slim\Middleware {

    public function call() {
        // code here
    }

}

创建自定义中间件文件后，需要在该文件中注册到 config.php 文件中，如下所示：

'App\\Middleware\\MetronicNotificationMiddleware' => null,
'App\\Middleware\\AuditTrailMiddleware' => null,
'App\\Middleware\\TestMiddleware' => null, // register new middleware

## 过滤器

过滤器是 Bono Metronic 中的一个机制，用于过滤或验证进入的 HTTP 请求或更简单地说是将要输入数据库的数据。

## 过滤器的种类

Bono Metronic 中常用的过滤器包括以下几种：

## 使用过滤器的方式

过滤器与 Collections 密切相关，Collections 包含了将要输入数据库的数据结构的声明。使用过滤器的方式是通过“链式”调用，每个过滤器之间用字符“|”分隔，如下所示：

'username' => NormString::create('username')->filter('trim|required|unique:User,username')->set('list-column', true),

## 注册自定义过滤器

除了上述提到的过滤器外，Bono Metronic 还允许创建自定义过滤器。要创建并注册一个新的自定义过滤器，只需在 AppProvider.php 文件中的 initialize() 函数下进行注册。以下是一个注册自定义过滤器的简单示例：

<?php

namespace App\Provider;

use \Norm\Filter\Filter;
use Norm\Filter\FilterException;

class AppProvider extends \Bono\Provider\Provider
{
    public function initialize()
    {
        $app = $this->app;

        Filter::register('custom_filter', function ($key, $value, $model) {
            $search = array('name' => $model['name'], 'slug' => $model['slug']);

            $check = \Norm::factory($model->getClass())->findOne($search);

            if ($check) {
                throw new FilterException("data'" . $key . "'sudah ada");
            }
            return $value;
        });
    }

要使用我们刚刚创建的 custom_filter，可以在 collections 中像使用其他过滤器一样使用它，如下所示：

'username' => NormString::create('username')->filter('trim|required|custom_filter|unique:User,username')->set('list-column', true),

xinix-technology / bono-metronic-template

维护者

详细信息