README

重要通知

该项目是从以下地址分叉而来： https://github.com/darrenmothersele/php-forms-api

此代码的主要仓库是github。如果您从其他位置收到了文件，请检查此URL以获取最新版本

https://github.com/degami/php-forms-api

对于错误报告、功能请求或支持请求，请在GitHub案例跟踪器中启动案例

https://github.com/degami/php-forms-api/issues

此库使用开源许可证GPL。有关更多信息，请参阅LICENSE.txt

要求

PHP 7.2
jQuery UI
jQuery-mask-plugin ~~( https://github.com/igorescobar/jQuery-Mask-Plugin 由于packagist.org的包信息损坏，该组件未作为依赖项包含在composer.json中，您需要自行下载文件 )~~
为了使用recaptcha字段，需要Google的reCaptcha库（ https://code.google.com/p/recaptcha/downloads/list?q=label:phplib-Latest ）
为了使用nestable字段，需要jQuery nestable插件（ https://github.com/dbushell/Nestable 组件，您需要自行下载文件）

路线图

完成文档！ 您也可以使用phpdoc生成漂亮的文档（phpdoc -d src -t docs --template=clean）
~~完成对例如disabled、attributes等选项的实现~~
~~提供更广泛的示例~~
~~完成可折叠字段集和密码强度计的javascript功能。~~
完成单元测试。
~~支持AJAX表单提交和文件上传。~~
提供更好的默认主题和定义主题的方法。
~~实现新的字段类型，如按钮、日期~~
~~添加对带掩码字段的支持，可能使用jQuery插件。~~
~~多步表单~~
~~表单构建类（类似于drupal_get_form），以便在表单定义期间注入表单状态~~
~~支持AJAX表单更新（例如“添加另一个”按钮，依赖字段，事件驱动的表单元素修改）~~
~~自命名空间~~

介绍

这个PHP表单API简化了在PHP应用程序中构建、验证和处理HTML表单的繁琐工作。表单API处理所有常见的表单元素和验证规则，并且其面向对象的设计可以轻松扩展，添加新的字段和验证规则。

基本表单工作流程

此表单API的基本工作流程如下

创建新的表单对象
向表单中添加字段
处理表单
显示表单

一开始可能不明显为什么在显示表单之前处理表单。这样做是因为，在使用此库时，通常同一页（或MVC中的控制器）将处理表单提交以及显示表单。这很有用，因为如果表单验证失败，您就可以在正确的位置再次显示表单，带有错误信息和提示，以便纠正错误并重新提交表单。

让我们更详细地看看表单工作流程的步骤

创建新的表单对象

表单对象是使用此表单API的主要起点。当您创建表单时，您可以在一个数组中提供一些选项来覆盖默认选项。默认情况下，表单提交回自身，这是最有用的配置，因为您可以使用相同的对象来验证和处理提交的表单。

注意：如果您只有一个表单，可以使用默认表单ID cs_form，但如果您有多个表单，则必须覆盖此值。表单ID用于生成HTML ID标签，因此对于有效的HTML必须是唯一的。它还用于生成在表单提交时使用的默认php函数名称。

向您的表单添加字段

您可以向表单添加任意数量的字段，但唯一必需的字段是提交按钮，以便用户可以提交表单。

如果您想拆分较长的表单或隐藏不常用的高级选项，可以在fieldsets内部嵌套字段。JavaScript（jQuery）提供支持可折叠的fieldsets。

处理表单

以下是提交表单进行处理的步骤

检查传入的请求以查看表单是否已提交。如果此页面请求是提交的结果，则将请求中的值复制到表单中。
调用此form_id的任何更改函数。
运行在验证（预处理）之前定义的任何字段处理器。
验证表单。如果表单未提交，则不检查任何内容直接失败验证，以便表单首次显示。如果此请求是提交此表单的结果，则运行所有字段验证器。如果任何验证器失败，则在表单中设置错误条件。然后如果找到，调用表单级别的验证处理程序。
如果表单已提交并通过验证，则运行在验证（后处理）之后定义的任何字段处理器。然后检查是否存在作为PHP函数的提交处理程序。
如果找到提交处理程序，则将其调用，传入最终的表单对象（可以用于提取值）。

显示表单

显示表单实际上是最后一步。如果请求中没有找到表单提交，则这是第一次显示，并已填充默认值。或者，表单可能是由于请求失败验证而显示的。在这种情况下，将显示有关错误条件的额外信息。

联系表单示例的演示

您可以在该文件中找到此示例的源代码：example/contact.php

表单API参考

包含：自动加载将完成魔法：）

使用方法：编写定义和提交函数，然后使用form_builder::get_form()获取表单对象并渲染它。

表单对象

此示例数组显示了表单对象的全部有效选项及其默认值

$options = array(
  'form_id' => 'cs_form',
  'action' => '',
  'attributes' => array(),
  'method' => 'post',
  'container_tag' => FORMS_DEFAULT_FORM_CONTAINER_TAG, //set in configuration
  'container_class' => FORMS_DEFAULT_FORM_CONTAINER_CLASS, //set in configuration
  'prefix' => '',
  'suffix' => '',
  'submit' => array(FORM_ID .'_submit'),
  'validate' => array(FORM_ID .'_validate'),
  'inline_errors' => FALSE,
  'ajax_submit_url' => '',
);

字段在渲染时获得表单引用，因此可以修改表单对象状态（例如，添加enctype属性或js脚本）

字段对象

以下是可用的字段及其选项

常见

$options = array(
  'title' => '',
  'description' => '',
  'name' => '',
  'id' => '',
  'attributes' => array(),
  'default_value' => '',
  'disabled' => FALSE,
  'stop_on_first_error' => FALSE,
  'tooltip' => FALSE,
  'container_tag' => FORMS_DEFAULT_FIELD_CONTAINER_TAG, //set in configuration
  'container_class' => FORMS_DEFAULT_FIELD_CONTAINER_CLASS, //set in configuration
  'label_class' => FORMS_DEFAULT_FIELD_LABEL_CLASS, //set in configuration
  'container_inherits_classes' => FALSE,
  'required_position' => 'after',
  'prefix' => '',
  'suffix' => '',
  'size' => 60,
  'weight' => 0,
  'validate' => array(),
  'preprocess' => array(),
  'postprocess' => array(),
);

文本字段

$options += array(
  'type' => 'textfield',
);

自动完成

$options += array(
  'type' => 'autocomplete',
  'autocomplete_path' => '',
  'options' => array(),
  'min_length' => 3,
);

如果定义了选项数组，则用作自动完成小部件的源，否则使用autocomplete_path

旋转器

$options += array(
  'type' => 'spinner',
  'min'  => NULL,
  'max'  => NULL,
  'step' => 1,
);

掩码字段

$options += array(
  'type' => 'maskedfield',
  'mask' => '',
);

密码字段

$options += array(
  'type' => 'password',
  'with_confirm' => FALSE,
  'with_strength_check' => FALSE,
  'confirm_string' => 'Confirm password',
);

文本区域

$options += array(
  'type' => 'textarea',
  'rows' => 5,
  'resizable' => FALSE,
);

$options += array(
  'type' => 'tinymce',
  'tinymce_options' => array(),
);

提交按钮

$options += array(
  'type' => 'submit',
  'js_button' => FALSE,
);

它们始终有效。

重置按钮

$options += array(
  'type' => 'reset',
);

它们始终有效。

按钮

$options += array(
  'type' => 'button',
  'label' => '',
  'js_button' => FALSE,
);

图像按钮

$options += array(
  'type' => 'image_button',
  'src' => '',
  'alt' => '',
  'js_button' => FALSE,
);

它们始终有效。提交后的值是一个包含字段x,y的数组

选择列表

$options += array(
  'type' => 'select',
  'options' => array(),
  'multiple' => FALSE,
);

选择菜单

$options += array(
  'type' => 'selectmenu',
);

多选

$options += array(
  'type' => 'multiselect',
);

滑块

$options += array(
  'type' => 'slider',
  'options' => array(),
);

颜色选择器

$options += array(
  'type' => 'colorpicker',
);

单选按钮

$options += array(
  'type' => 'radios',
  'options' => array(),
);

复选框

$options += array(
  'type' => 'checkboxes',
  'options' => array(),
);

复选框

$options += array(
  'type' => 'checkbox',
);

开关盒

$options += array(
  'type' => 'switchbox',
  'yes_value' => 1,
  'yes_label' => 'Yes',
  'no_value' => 0,
  'no_label' => 'No',
);

隐藏值

$options += array(
  'type' => 'hidden',
);

标记

$options += array(
  'type' => 'markup',
);

标记值不会传递给values()函数

进度条

$options += array(
  'type' => 'progressbar',
  'show_label' => FALSE,
  'indeterminate' => FALSE,
);

值

$options += array(
  'type' => 'value',
);

值在提交表单时传递，但在渲染期间不显示。它们始终有效。

文件

$options += array(
  'type' => 'file',
  'destination' => '',
);

日期

$options += array(
  'type' => 'date',
  'start_year' => '',
  'end_year' => '',
  'granularity' => 'day', // one of: year, month or day
  'js_selects' => FALSE,
);
$options['default_value'] = array(
  'year'=>'',
  'month'=>'',
  'day'=>'',
);

日期选择器

$options += array(
  'type' => 'datepicker',
  'date_format' => 'yy-mm-dd',
  'change_month' => FALSE,
  'change_year' => FALSE,
  'mindate' => '-10Y',
  'maxdate' => '+10Y',
  'yearrange' => '-10:+10',
  'disabled_dates' => array(),
);

时间

$options += array(
  'type' => 'time',
  'granularity' => 'seconds', // one of: hours, minutes or seconds
  'js_selects' => FALSE,
);
$options['default_value'] = array(
  'hours'=>'',
  'minutes'=>'',
  'seconds'=>'',
);

日期时间

$options += array(
  'type' => 'datetime',
  'start_year' => '',
  'end_year' => '',
  'granularity' => 'day - seconds', // one of: year, month, day, hours, minutes or seconds
  'js_selects' => FALSE,
);
$options['default_value'] = array(
  'year'=>'',
  'month'=>'',
  'day'=>'',
  'hours'=>'',
  'minutes'=>'',
  'seconds'=>'',
);

数学验证码

$options += array(
  'type' => 'math_captcha',
  'pre_filled' => FALSE,
);

图片验证码

$options += array(
  'type' => 'image_captcha',
   'out_type' => 'png',
   'characters' => 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789',
   'min_length' => 5,
   'max_length' => 8,
   'image_width' => 100,
   'image_height' => 50,
   'font_size' => 14,
   'pre_filled' => FALSE,
);

Recaptcha

$options += array(
  'type' => 'recapcha',
  'publickey' => '',
  'privatekey' => '',
);

确保您已加载recaptchalib.php（https://code.google.com/p/recaptcha/downloads/list?q=label:phplib-Latest）

标签容器

$options += array(
  'type' => 'tag_container',
  'tag' => 'div',
);

表格容器

$options += array(
  'type' => 'table_container',
  'table_header' => array(),        // an array of column headers
  'col_row_attributes' => array(),  // a matrix of cells attributes ( each one can be a string or an array )
);

字段集

$options += array(
  'type' => 'fieldset',
);

标签页

$options += array(
  'type' => 'tabs',
);

手风琴

$options += array(
  'type' => 'accordion',
);

可排序的

$options += array(
  'type' => 'sortable',
  'handle_position' => 'left',
);

$options += array(
  'type' => 'sortable_table',
  'handle_position' => 'left',
  'table_header' => array(),
);

嵌套的

$options += array(
  'type' => 'nestable',
);

可重复的

$options += array(
  'type' => 'repeatable',
  'num_reps' => 1,
);

地理位置（纬度，经度）

$options += array(
  'type' => 'geolocation',
);
$options['default_value'] = array(
  'latitude' => NULL,
  'longitude' => NULL,
);

$options += array(
  'type' => 'gmaplocation',
  'zoom' => 8,
  'scrollwheel' => FALSE,
  'mapwidth' => '100%',
  'mapheight' => '500px',
  'markertitle' => NULL,
  'maptype' => 'google.maps.MapTypeId.ROADMAP',
  'with_geocode' => FALSE,
  'lat_lon_type' => 'hidden',
  'geocode_box' => NULL,
  'with_map' => TRUE,
);
$options['default_value'] = array(
  'latitude' => NULL,
  'longitude' => NULL,
  'geocodebox' => NULL,
);

验证器参考

必填、最大长度、最小长度、精确长度、正则表达式、字母、字母数字、带短划线的字母数字、数字、整数、字段匹配、电子邮件、文件扩展名、文件不存在、文件最大大小、文件类型。

处理器参考

出于安全原因，所有用户提交的数据在使用前都应进行过滤。此表单API库通过提供一些有用的过滤工具来帮助您处理提交的输入。您可以在需要时在提交函数中使用它们，或者让它们在表单处理期间自动运行。您可以在字段验证之前或之后指定要运行的处理器。

纯文本、修剪、左修剪、右修剪、XSS、XSS弱、添加反斜杠

Form_builder

将是一种获取表单对象的新方法。类似于drupal_get_form，它将向表单定义函数传递一个form_state参数。

degami / php-forms-api

维护者

详细信息