README

从jemdev\form\form对象开始，我们可以简单地调用对应于我们想要创建的字段类型的相应方法。例如，对于一个类型为 textarea 的字段

/* Création d'un champ de saisie */
$zone_texte = $oForm->textarea('id_zone_texte');

但是，我们可以为此字段添加属性，我们将在稍后讨论这一点。首先，让我们看看我们可以创建的字段列表。

所有DOCTYPES共有的字段

hidden
select
textarea
group
text
radio
checkbox
submit
reset
file
image
button

HTML5特有的字段

datalist
color
date
email
number
range
search
tel
time
url

注意，没有出现 input 字段：这是为了简化而故意为之。然而，我们可以看到存在与 input 字段可能的类型相对应的字段：hidden、text、radio 等...无论我们想要创建哪种字段，方法都与上面展示的 textarea 相同。

jemdev\form\form创建的对象的上的方法

当我们创建一个字段时，该方法返回一个包含方法的对象，这些方法可用于完善该字段的某些属性。

所有字段共有的方法

setLabel($label) : 允许指定与字段相关联的标签的文本。请注意，标签标签本身不会被创建，只有字段的属性会被存储并可用。
setAttribute($attr [, $value]) : 为了向特定字段添加一个属性，我们只需调用方法并指定属性名称和要分配的值。请注意，值是可选的。让我们再次回顾上面展示的例子

$zone_texte->setAttribute('cols', 50);
$zone_texte->setAttribute('rows', 10);

结果将对应以下HTML标签

<textarea id="id_zone_texte" name="id_zone_texte" cols="50" rows="10"></textarea>

此例中使用的例子允许强调一个特殊情况：此标签没有 value 属性，值显示在两个标签之间。但是，我们可以以与任何其他字段相同的方式指定此输入区的文本

$zone_texte->setAttribute('value', "Contenu de la zone de saisie");

结果是

<textarea id="id_zone_texte" name="id_zone_texte" cols="50" rows="10">Contenu de la zone de saisie</textarea>

而一个类型为 input 的 text 字段的结果将符合预期

/* Création d'un champ de saisie */
$zone_texte = $oForm->text('id_zone_texte');
$zone_texte->setAttribute('value', "Contenu de la zone de saisie");

结果

<input type="text" id="id_zone_texte" name="id_zone_texte" value="Contenu de la zone de saisie" />

setRule($rule, $msg[, $val]) : 我们可以指定验证规则。两个参数是必需的，即规则的名称和如果不满足规则要显示的消息。某些规则需要可选的第三个参数，这通常是一个控制值。稍后将会展示预定义的验证规则列表以及如何添加自定义规则。

每个对象特有的方法

select
- addOption
- addGroup
textarea
datalist
- addOption

验证规则

已经存在一些通用规则可用于验证表单数据

required :
- 检查必需的值是否为空。
- 用法：$objet->setRule('required', "message");
email :
- 检查电子邮件地址的有效性。
- 用法：$objet->setRule('email', "message");
url :
- 检查URL的语法。
- 用法：$objet->setRule('url', "message");
alpha :
- 检查字符串的语法是否有效。只接受可加重的字母字符。
- 用法：$objet->setRule('alpha', "message");
单词 :
- 验证一个或多个单词的语法有效性。接受字母字符、引号、撇号、破折号和空格。
- 用法：$objet->setRule('word', "message");
alnum :
- 验证一个字母数字字符串的语法有效性，接受单词、数字以及标点符号。
- 用法：$objet->setRule('alnum', "message");
num :
- 验证一个数字字符串的语法有效性，只接受数字。
- 用法：$objet->setRule('num', "message");
float :
- 验证一个浮点数的语法有效性。接受带或不带小数的数字，以及点或逗号作为分隔符。
- 用法：$objet->setRule('float', "message");
minlength :
- 验证字符串至少包含一定数量的字符。必须在第三个参数中指定一个整数，表示所需的最小字符数。
- 用法：$objet->setRule('minlength', "message", 10);
maxlength :
- 验证字符串最多包含一定数量的字符。必须在第三个参数中指定一个整数，表示所需的最大字符数。
- 用法：$objet->setRule('maxlength', "message", 50);
rangelength :
- 验证字符串的字符数在指定的最小值和最大值之间。必须在第三个参数中指定一个包含两个整数的数组，分别对应所需的最小和最大字符数。
- 用法：$objet->setRule('rangelength', "message", array(10, 50));
minval :
- 验证值是否大于或等于最小值。必须在第三个参数中指定一个整数或浮点数，表示所需的最小值：此规则可以与规则 num 或 float 一起使用。
- 用法：$objet->setRule('minval', "message", 1);
maxval :
- 验证值是否小于或等于最大值。必须在第三个参数中指定一个整数或浮点数，表示所需的最大值：此规则可以与规则 num 或 float 一起使用。
- 用法：$objet->setRule('maxval', "message", 12);
rangeval :
- 验证值是否介于最小值和最大值之间。必须在第三个参数中指定一个包含两个整数或浮点数的数组，分别对应所需的最小和最大值：此规则可以与规则 num 或 float 一起使用。
- 用法：$objet->setRule('rangeval', "message", array(1, 12));
inferieur :
- 验证值是否严格小于最大值。必须在第三个参数中指定一个值，表示输入的数字必须严格小于该值。此规则可以与规则 num 或 float 一起使用。
- 用法：$objet->setRule('inferieur', "message", 100);
superieur :
- 验证值是否严格大于最小值。必须在第三个参数中指定一个值，表示输入的数字必须严格大于该值。此规则可以与规则 num 或 float 一起使用。
- 用法：$objet->setRule('superieur', "message", 1);
regex :
- 验证输入是否与定义的正则表达式匹配。这是一个非常实用的规则，通常可以替代编写其他特定规则。如果输入必须匹配特定的PCRE掩码，请在第三个参数中指定此掩码。
- 用法：$objet->setRule('regex', "message", "#^[A-Z]{1}[0-9]{4}$#");
formatdateheure :
- 验证日期格式的有效性。将使用与PHP原生函数 date() 相同的日期格式规则，请参阅相关文档。
- 用法：$objet->setRule('formatdateheure', "message", 'd/m/Y');
validedate :
- 根据给定格式验证日期。日期格式将根据第三个参数进行验证，但会检查日期本身的存在，例如禁止输入2月30日。
- 使用方法：$objet->setRule('validedate', "message", 'd/m/Y');
比较 :
- 比较两个值，如果两个字符串相同则返回真。在创建带有确认字段的密码时很有用。
- 使用方法：$objet->setRule('comparer', "message", $valeur_de_controle);
不同 :
- 检查输入的值是否与参数不同。例如，对于一个下拉列表，第一个选项显示“选择一个值”，其value属性值为“-1”，则指定这个值不能被选中。这相当于在列表中强制选择。
- 使用方法：$objet->setRule('differentDe', "message", '-1');

注意，如果一个字段没有定义为必填，但您为内容定义了验证规则，则只有在输入了内容时才会返回错误信息。例如，一个需要输入日期的字段，只有在输入了错误的日期时才会返回错误，但如果字段保持为空且没有定义required规则，则规则将被忽略。

总之

原则很简单，该方法期待以下参数

规则的名称；
规则未遵守时显示的消息；
对于某些规则，一个控制值（minlength、maxlength、minval、maxval、rangeval、inferieur、superieur、regex、validedate、comparer、differentDe）；
对于某些其他规则，第二个控制值（rangelength、rangeval）：在这种情况下，第三个参数将是一个包含两个要使用为控制元素的值的索引数组。

方法链

一旦为表单字段创建了一个对象，就可以链式调用方法，从而避免在每个新方法调用时重新写入变量。

示例

$nom = $oForm->text('nom', 'nom')
             ->setLabel('Nom du client')
             ->setAttribute('class', 'classe_css_quelconque')
             ->setAttribute('value', $infosClient['nom'])
             ->setRule('required', "Le nom du client est requis");

定义自定义验证规则。

在无法为特定字段定义正则表达式进行验证的情况下，仍然可以将额外的验证方法添加到表单管理系统中。通常，当需要从数据库或其他外部源收集控制信息，或者当数据必须符合需要计算控制的模式时，例如验证社会保险号的校验码时，这是必不可少的。为此，我们将定义一个扩展jemdev\form\process\validation的类。为了简化，以下是一个可以作为基础的示例

class helpers_validationsupplementaire extends jemdev\form\process\validation
{
    public static $aMethodesSupplementaires = array(
        'autreMethodeValidation'
    );
    /**
     * Constructeur.
     *
     * Crée l'instance parente et valide les données du formulaire.
     *
     */
    public function __construct($aDatas, $oRules, $aExceptionErreurs)
    {
        parent::__construct($aDatas, $oRules, $aExceptionErreurs);
        foreach(self::$aMethodesSupplementaires as $methode)
        {
            self::$methodesValidation[] = $methode;
        }
    }
    public function __get($cle)
    {
        $authorise = array('aMethodesSupplementaires');
        if(in_array($cle, $authorise))
        {
            return $this->${$cle};
        }
    }

    /**
     * Vérifie la validité d'une donnée saisie.
     *
     * @param   mixed     $valeur
     * @return  bool    Retourne TRUE si la valeur est falide, FALSE dans le cas contraire
     */
    public function _autreMethodeValidation($valeur)
    {
        /* Code validant la valeur saisie dans le formulaire et retournant un booléen */
        //... $bValide = false; // <== Votre propre code définissant la valeur du retour
        /* On retourne le résultat */
        return $bValide;
    }
}

该类的名称以及它在您的应用程序中的加载方式取决于您自己以及您的应用程序架构。

我们主要关注的是类属性“$aMethodesSupplementaires”，其中您将指定与方法名称对应的规则名称。然后是验证方法：它至少接受一个参数，即输入值。该代码的内容取决于您的需求，并且必须强制返回一个布尔值。如果您需要指定其他参数，例如一个控制值，您必须在方法定义中添加它，并在您为相关字段定义验证规则时调用该方法。

实现额外的验证方法

为了让您自定义的验证规则被考虑，首先需要在创建表单实例之前定义它们。然后，在创建该实例时，您必须指定要查找这些额外规则类的列表。

/* Le formulaire nécessitera des méthodes spécifiques de validation : on le chemin vers la classe appropriée */
$aClassValidExterne = array(
    "chemin/vers/fichier/classe/specifique.php",
    'nom_de_la_classe'
);

/**
 * Création de l'instance de formulaire
 */
$oForm = new jemdev\form\form('test', 'post', null, $aClassValidExterne);

请注意，在创建表单实例时，附加类在第四个参数中指定。在添加类型为FILE的input字段时，可以将第三个参数设置为NULL，因为将自动使用默认值，并在必要时进行修改。现在，您可以将自定义规则应用于相应的字段，如上所述。

注意：在未来不久，验证部分的代码可能会简化，以便创建附加验证类更加简单，尽管在目前实践中这只有很少的困难。

将表单集成到模板（template）中

接下来，我们需要显示表单，为此，我们将准备一个模板。

准备模板（template）

为了最大程度地简化您的工作，请准备一个模板，您可以在其中调整HTML格式。以下是一个基本表单的示例，它将最终显示如下：

<form id="template_form" action="#" method="post">
  <fieldset>
    <legend>Les champs de mon formulaire</legend>
    <p>
      <label for="nom">Votre nom</label>
      <input type="text" name="nom" id="nom" value="" />
    </p>
    <input type="submit" id="envoi" name="envoi" value="Envoyer les données" />
  </fieldset>
</form>

在此阶段，我们只需要fieldset部分，请勿使用<form>标签，因为它将被自动集成。我们将把内容直接放在PHP变量中，这里使用HEREDOC语法。

<?php
$sForm = <<<CODE_HTML
      <fieldset>
        <legend>Les champs de mon formulaire</legend>
        <p>
          <label for="nom">Votre nom</label>
          <input type="text" name="nom" id="nom" value="" />
        </p>
        <input type="submit" id="envoi" name="envoi" value="Envoyer les données" />
      </fieldset>

CODE_HTML;

集成动态字段

现在，我们将用PHP变量替换某些部分。最终代码将类似于以下内容

<?php
$sForm = <<<CODE_HTML
      <fieldset>
        <legend>Les champs de mon formulaire</legend>
        <p>
          <label for="{$nom->id}">{$nom->label}</label>
          {$nom}
        </p>
        {$envoi}
      </fieldset>

CODE_HTML;

注意包含字段的行：您可以看到我们在花括号“{”和“}”之间指定了变量，并且可以调用两个属性。这些变量实际上是对象，因此包含属性：id和label，这些属性是在创建字段时定义的。单独放在花括号中的变量将调用实例的__toString方法，该方法将返回标签的HTML代码。

这种方式让您有充分的自由以最适合您的方式来结构化表单，这一级别没有任何限制，jemdev\form包根本不处理显示。

添加内容并获取完整表单的代码。

一旦您定义了模板并设置了变量，并且所有字段都已创建，剩下的就是在您的页面上获取准备好的待显示内容。

/* On définit le chemin vers le gabarit */
$form_tpl       = "chemin/vers/le/fichier/form.phtml";

请注意，这里的文件扩展名是“．phtml”，这是一种相对常见的扩展名，但您完全可以使用其他扩展名，例如“．tpl.php”等。尽管如此，我推荐使用“．phtml”。

/* On crée tous les champs de notre formulaire */
/* ... ... ... ... */
/* On inclut le fichier gabarit */
include($form_tpl);
/**
 * On indique à l'instance de formulaire que son contenu est la
 * variable définie dans le gabarit, ici $sForm
 */
$oForm->contenu = $sForm;
/* On récupère le code complet du formulaire */
$sFormulaire = sprintf('%s', $oForm);

重要：您没有看到隐藏字段的集成：这是正常的，因为它是自动添加的最后一次操作。

结论

我在2007年或2008年左右创建了此包，并且每天都在使用它。这个版本是一个重构版本，集成了命名空间和composer，以简化其使用。如有需要，请告诉我您的观察和/或问题，我将尽力找到时间来解决。

jemdev / form

维护者

详细信息