README

• 使用SQL语句定义表、表单和输入

• 搜索、列排序、分页，无需JavaScript

• 将文件和图像上传到文件系统或数据库字段（blob）

• 没有内置验证，相反，鼓励使用HTML的pattern属性和required属性

• 提供挂钩以添加验证、格式化数据或运行代码，在或之后：插入、更新和删除

• 使用Bootstrap css框架样式化

许可证

MIT

屏幕截图

要求

• PHP 7+，已启用mbstring和gd扩展
• SQLite 3、MariaDB/MySQL或PostgreSQL

状态

此项目目前处于测试版

使用SQLite3和PHP内置网络服务器快速演示

1. 将终端导航到'examples/'文件夹
2. sqlite3 example.db < example.sql
3. php -S localhost:8080
4. 在网页浏览器中打开https://:8080

从composer安装

composer require phpbootstraptableedit/phpbootstraptableedit

重要术语 - 索引、添加、编辑

• "索引"是显示所有记录的打开表，包括分页和搜索
• "添加"是插入新记录的表单
• "编辑"是更新现有记录的表单

$o->index_sql = "";       // sql to define the opening grid
$o->index_sql_param = []; // named params 
$o->index = [];           // field settings on index table

$o->add_sql = "";         // sql to define the fields when adding a record
$o->add_sql_param = [];   // named params 
$o->add = [];             // field settings on add form

$o->edit_sql = "";        // sql to define the fields when editing a record
$o->edit_sql_param = [];  // named params 
$o->edit = [];            // field settings on edit form

注意

停止SQL注入攻击，永远不要将用户输入放入SQL字符串中！相反，使用sql_param数组安全地传递输入。

技巧

使用nonce属性来防止跨站请求伪造（CSRF）攻击。

基本示例

$dbh = new PDO('sqlite:example.db');

$o = new PHPBootstrapTableEdit\PHPBootstrapTableEdit($dbh);

$o->table_name = 'markets';
$o->identity_name = 'id';

// define opening index table, to render the [edit] link, the last column must be the identity id
$o->index_sql = "
select m.title,
       c.title as country,
       m.create_date,
       case when m.is_active = 1 then 'Yes' else '-' end as is_active,
       m.id
from   markets m
left
join   countries c
on     m.country = c.code
where  ( coalesce(m.title, '') like :search or coalesce(c.title, '') like :search )
order by 2 desc
";

// named parameters for search
$o->index_sql_param[':search'] = '%' . trim($_REQUEST['_search'] ?? '') . '%';

// define fields on the edit form
$o->edit_sql = "select title, email, country, create_date, is_active from markets where id = :id";
$o->edit_sql_param[':id'] = intval($_POST['id'] ?? $_GET['id'] ?? 0);

// floating input style
$o->floating = true;

// define fields attributes
$o->edit['title']['required'] = true;
$o->edit['country']['type'] = 'select';
$o->edit['country']['sql'] = 'select code, title from countries'; // define how to populate the select dropdown
$o->edit['create_date']['type'] = 'date';
$o->edit['is_active']['type'] = 'checkbox';

// 12 column layout - colspan = 4 creates a three column layout
$o->edit['title']['colspan'] = '4';
$o->edit['email']['colspan'] = '4';
$o->edit['country']['colspan'] = '4';
$o->edit['is_active']['colspan'] = '4';
$o->edit['create_date']['colspan'] = '4';

// copy all 'edit' setting into 'add', the add form is the same
$o->add = $o->edit;
$o->add_sql = $o->edit_sql;
$o->add_sql_param = $o->edit_sql_param;

// call the controller
$o->run();

属性

charset（字符串），输出字符集，默认：'UTF-8'

table_name（字符串），数据库表

identity_name（字符串），表中自增id字段，通常是'id'}

index_sql（字符串），定义打开html表格列出所有记录的sql查询

index_sql_param（数组），index_sql的参数

示例

$o->index_sql_param = [':_search' => '%' . trim($_GET['search'] ?? '')  . '%'];

add_sql（字符串），定义在添加页面上显示的字段以及插入中使用的字段

示例

// no record is returned from this query, just meta data; the field names 
$o>->add_sql = "select field1, field2, id from table where id = 0";

add_sql_param（数组），add_sql的命名参数，通常不需要，因为没有检索记录

edit_sql（字符串），定义在编辑页面上显示的字段以及更新中使用的字段

示例

$o>->edit_sql = "select field1, field2, id from table where id = :id";

edit_sql_param（数组），edit_sql的命名参数

示例

$o->add_sql_param[':id'] = $_GET['id'] ?? $_POST['id'];

add（数组），定义在添加表单上渲染add_sql中的字段的方式

示例

$o->add['country']['type']     = 'select';  
$o->add['country']['required'] = true; // normal html prop/attr
$o->add['country']['sql']      = 'select code, title from countries'; // custom html attribute to define options 
$o->add['country']['colspan']  = '3'; // layout

edit（数组），定义在编辑表单上渲染edit_sql中的字段的方式

示例

$o->edit['country']['type']     = 'select';  
$o->edit['country']['required'] = true; // normal html prop/attr
$o->edit['country']['sql']      = 'select code, title from countries'; // custom html attribute to define options 
$o->edit['country']['colspan']  = '3'; // layout

// or we could have copied setting from add to edit, or vice versa
// $o->edit['country'] = $o->add['country'];

index（数组），定义在打开表上渲染字段的挂钩，函数名或闭包

示例

$o->index['create_date']['function'] = function($data) { return date('d/m/Y', strtotime($data['value'])); };

floating（布尔值），在添加和编辑表单上启用Bootstrap的浮动标签。https://bootstrap.ac.cn/docs/5.3/forms/floating-labels/

nonce_name（字符串），csrf字段名称，默认'nonce'}

nonce_value（字符串），csrf字段值

limit（整数），分页限制每页记录数，0 = 关闭，默认 = 100

ellipse_at（整数），在索引表中截断文本，0 = 关闭，默认 = 0

query_string_carry（数组）此数组中的条目添加到所有查询字符串中，用于在页面间携带数据

示例

// carry parent_id in the querystring
// now try appending '&parent_id=5' on to the location bar; value will remain after editing, searching, or paging
$o->query_string_carry[] = 'parent_id';

i18n（数组），包含所有本地化设置的关联数组

默认值

$o->i18n['no_records' => 'No Records', 'not_found' => 'Not Found', 'search' => 'Search', 'edit' => 'Edit', 'add' => 'Add', 'add_2' => 'Add', 'back' => 'Back', 'delete' => 'Delete', 'update' => 'Update', 'delete_file' => 'mark for removal', 'update_success' => 'Updated', 'insert_success' => 'Added', 'delete_success' => 'Deleted'];

css（数组），CSS类设置

默认值

$o->css['index_table' => 'table-striped table-hover', 'index_active' => 'table-primary', 'pagination' => ''];

redirect（布尔值）在调试时很有用，设置为false后，在插入/更新/删除后页面不会重定向

'on'事件挂钩

在 SQL 插入/更新/删除之前会调用 'on' 事件钩子函数。'on' 函数可以用于转换 POST 数据或添加验证。从 'on_' 函数返回字符串会在添加/编辑表单上显示警告并跳过插入/更新/删除操作。

• on_insert （闭包或函数名）
• on_update （闭包或函数名）
• on_delete （闭包或函数名）

纯文本警告

$o->on_insert = function()
{
   if(strlen($_POST['email'] ?? '') == 0) {
       return "Email Required";
   } 
}

HTML 和文本警告

$o->on_update = function()
{
    return ['html' => '<b>unescaped html, or maybe just passing some json</b>',
            'text' => 'optional, I appear in an alert div on the edit form'];

}

'after' 事件钩子

after 函数在 SQL 插入/更新/删除之后被调用。after_insert 是一个独特的钩子，它接收一个参数；插入的 ID。

• after_insert （闭包或函数名）
• after_update （闭包或函数名）
• after_delete （闭包或函数名）

示例

$o->after_insert = function($id)
{
    // i'm unique, i have the inserted id as an argument
}

$o->after_update = function()
{
    // all other hooks have to get their own identity key
    $id = $_POST['id'];
} 

常规 HTML 属性

标准 HTML 属性可以设置在 add 和 edit 数组中。它们会按照预期传递。

$o->edit["title"]["type"]      = "text"; // text is already a default, no need to specify text
$o->edit["title"]["maxlength"] = "25";
$o->edit["title"]["foo"]       = "bar"; 
$o->edit["title"]["required"]  = true; // use true/false for properties

// outputs:
// <input name='title' type='text' maxlength='25' foo='bar' required>

自定义 HTML 属性

自定义属性指导此库如何渲染输入。与如 maxlength 等常规 HTML 属性不同，自定义属性不会出现在输入中。

• colspan （字符串）Bootstrap 表单有一个 12 列布局，因此所有字段都使用 '4' 会创建一个 3 列布局；12/4 = 3

示例

$o->edit[field]['colspan'] = "4";

• div_class （字符串）为包含输入的 div 添加一个类

示例

// in this example 'form-switch' is added to make a checkbox render as a switch
$o->edit[field]['div_class'] = "form-switch";

• label （字符串），更改与字段一起出现的标题

示例

$o->add[field]['label']   = "Country";
$o->edit[field]['label']  = "Country";
$o->index[field]['label'] = "Country";

• sql （字符串）用于填充选择、单选按钮或复选框输入的 SQL 语句示例

// the first column is the value, the second column is the displayed title
$o->edit[field]['sql'] = "select code, title from countries";

• sql_param （数组），关联数组用于存储 SQL 的命名参数

示例

$o->edit[field]['sql_param'] = array(":code" = $_GET['code']);

文件上传的自定义 HTML 属性

• file_extension （字符串）定义要接受的文件类型。对于图像，有效的格式是 png、gif、jpg、format 和 meta 在上传时验证。对于非图像，例如 doc 或 pdf，格式和 meta 在上传时不验证。

示例

$o->edit[field]['file_extension'] = 'png'; // this still allows gif or jpg to be uploaded, but saved binary will be png

• file_path （字符串）可选，上传文件到文件系统的位置；数据库字段中存储一个文件名。如果没有指定 file_path，二进制内容将直接存储到数据库字段中，且不保存文件名。

示例

// store files here:
$o->edit[field]['file_path'] = '/by/listing/a/path/file/is/saved/to/the/filesystem';

// no path means save binaries in the database field; field must be a blob, no filename is saved 
$o->edit[field]['file_path'] = null;

• file_image_width （整数）可选，当 file_extension 是 png、gif 或 jpg 时，指定所需的宽度。

示例

$o->edit[field]['file_image_width'] = 100;

• file_image_height （整数）可选，当 file_extension 是 png、gif 或 jpg 时，指定所需的宽度。

示例

$o->edit[field]['file_image_height'] = 100;

• file_image_crop_or_resize （字符串，'crop' 或 'resize'）可选，指定在 file_extension 时如何调整图像大小，仅适用于 png、gif 或 jpg。'crop' 根据宽度和高度设置创建图像。'resize' 在保持原始图像宽高比的同时，将大小限制为宽度和高度设置。示例

$o->edit[field]['file_image_crop_or_resize'] = 'crop'; // valid options: 'crop' or 'resize'

标签 - 重命名字段

重命名与字段一起出现的标题示例

// make country_code appear as Country
$o->add['country_code']['label']   = "Country";
$o->edit['country_code']['label']  = "Country";
$o->index['country_code']['label'] = "Country";