README

主分支:

扩展 Zend Framework 1 功能的库。

要求

MolComponents 需要 Zend Framework 1 (>=1.11.0 推荐，较旧版本也应正常工作) 和至少 PHP 5.3。

安装

MolComponents 可通过 Composer 安装。

只需在您的 composer 配置中要求 matthimatiker/molcomponents

{
    "require": {
        "matthimatiker/molcomponents": ">=1.4.2"
    }
}

通过以下方式安装 MolComponents

php composer.phar install

特性

以下是该库提供的一些功能示例。组件遵循使用即用的设计：所有功能都是完全可选的。

请参阅类的文档以获取更多详细信息。

控制器操作中的参数支持

通过扩展 Mol_Controller_ActionParameter，您可以声明必需的参数作为操作方法的参数

/**
 * Example action.
 *
 * @param integer $page
 */
public function myAction($page = 1) 
{
   // my code
}

组件使用参数文档来确定预期的数据类型。验证会自动执行。成功后，值将被转换为预期类型，并作为参数传递给操作。

资源的懒加载

通常，Zend Framework 1 会为每个请求初始化所有配置的资源。Mol_Components 提供了一种机制，可以延迟资源的初始化，直到实际请求资源时。

要使用懒加载，应用程序引导程序必须继承自 Mol_Application_Bootstrap

class My_Bootstrap extends Mol_Application_Bootstrap
{
}

引导程序的工作方式与之前完全相同，但现在可以激活 application.ini 中任何资源的懒加载。

resources.log.stream.writerName          = "Stream"
resources.log.stream.writerParams.stream = APPLICATION_PATH "/logs/application.log"
resources.log.stream.writerParams.mode   = "a"
resources.log.lazyLoad                   = On

在此示例中，不再为每个请求引导日志资源。相反，它仅在引导程序显式请求时初始化，例如在控制器操作中

public function myAction() 
{
    $bootstrap = $this->getInvokeArg('bootstrap');
    $logger = $bootstrap->getResource('log');
}

请注意，某些资源必须尽早执行，因为它们会修改应用程序的全局状态，并且不会通过 getResource() 明确检索。

可配置的邮件模板

MolComponents 提供了一个灵活的邮件配置系统。无需手动创建 Zend_Mail 对象，就可以预配置邮件属性（默认收件人、模板等）并通过别名检索邮件对象。

要使用此系统，必须激活并配置 mailer 资源，并通过 application.ini 进行配置。应定义邮件配置文件的路径以及邮件模板的视图脚本路径

resources.mailer.templates[] = APPLICATION_PATH "/mails/mail-templates.ini"
resources.mailer.scripts[]   = APPLICATION_PATH "/mails/views"

可以添加任意数量的模板配置和脚本路径。如果发生冲突，则后来定义的模板配置将覆盖其前辈的设置。

mail-templates.ini 包含每个邮件模板的一个部分。每个模板定义了多个邮件属性

[registration]
charset     = "UTF-8"
subject     = "Registration successful"
bcc[]       = "registration-log@my-domain.com"
replyTo     = "registration-support@my-domain.com"
from        = "no-reply@my-domain.com"
script.text = "registration.txt.phtml"
script.html = "registration.html.phtml"

视图的翻译器用于自动翻译主题。命名的视图模板用于生成邮件的文本和 HTML 部分。

提示：可以使用继承来轻松定义默认邮件属性。

现在可以使用启动的邮件工厂的create()方法从模板创建Zend_Mail对象。

public function myAction()
{
    $factory    = $this->getInvokeArg('bootstrap')->getResource('mailer');
    $parameters = array('userName', $name);
    $mail       = $factory->create('registration', $parameters);
}

create()方法接收一个模板名称和（可选）一个参数列表，该参数列表传递给配置的内容视图脚本。

创建后，可以像平常一样修改和发送邮件。

$mail->addTo('recipient@user.com');
$mail->send();

高级表单创建

许多表单具有相同的功能。例如，出于安全原因，CSRF令牌通常被要求。虽然有必要，但这些附加元素使得测试变得困难，因为它们通常依赖于全局状态，因此在单元测试中需要特殊处理。

为了克服这些问题，MolComponents提供了一种可配置的表单工厂，结合了一个简单的插件系统。工厂负责创建Zend_Form实例，插件用于处理横切关注点。

一个简单的用例是创建表单类的别名。

resources.form.aliases.login        = "My_Login_Form"
resources.form.aliases.registration = "My_Registration_Form"

现在可以通过别名检索表单实例。

public function myAction()
{
    $factory = $this->getInvokeArg('bootstrap')->getResource('form');
    // Creates an instance of My_Login_Form
    $loginForm = $factory->create('login');
}

从现在起，更改表单的类型只需配置即可。但表单工厂真正的好处是能够使用插件。插件接收每个创建的表单，并且有增强这些表单实例的能力。

插件可以通过配置简单添加。

resources.form.plugins.autoComplete.class = "Mol_Form_Factory_Plugin_AutoCompleteOff"

自动完成关闭插件会给每个表单添加autocomplete="off"属性，并阻止浏览器缓存输入数据。

更复杂的插件需要额外的选项。以下插件会给所有表单添加CSRF令牌。

resources.form.plugins.csrf.class = "Mol_Form_Factory_Plugin_Csrf"
resources.form.plugins.csrf.options.element.name    = "my_csrf_token"
resources.form.plugins.csrf.options.element.salt    = "secret-salt"
resources.form.plugins.csrf.options.element.timeout = 1800

提示：如果表单实例的创建过于复杂，无法由工厂处理，那么仍然可以受益于插件系统。工厂的create()方法也接受Zend_Form对象，并将所有插件应用于这些实例。

$form = new Zend_Form();
$enhancedForm = $factory->create($form);

表单元素依赖关系验证

经常需要验证不同表单值之间的关系：密码验证值必须等于原始密码，结束日期必须大于开始日期，等等。

MolComponents提供了一种简化关系验证的机制。此外，它还提供了一些常用关系验证器。

要验证关系，必须将Mol_Validate_Form_ElementRelation添加到表单元素中。

$from = new Zend_Form_Element_Text('from);
$to = new Zend_Form_Element_Text('to');
// Ensure that the provided "to" date is only valid if it is
// beyond the "from" date:
$relation = new Mol_Validate_Form_Relation_GreaterThan();
$to->addValidator(new Mol_Validate_Form_ElementRelation($relation, $from));

上述关系读作：$to必须大于$from。

ElementRelation期望一个类型为Zend_Validate_Interface的内部验证器，该验证器能够检查两个相关值的有效性。

public function isValid($value, $other = null)
{
}

任何提供该接口的验证器都可以用于验证关系。因此，扩展关系验证以包含自定义逻辑非常容易。

为了使创建关系验证器更易于阅读，可以通过字符串标识符访问内置验证器。

$to->addValidator(new Mol_Validate_Form_ElementRelation('>', $from));

这创建了一个与第一个示例相同的验证器。

目前，库提供了以下关系验证器（对应的标识符在括号中显示）：

• 等于（==）
• 不等于（!=）
• 小于（<）
• 大于（>）
• 小于或等于（<=）
• 大于或等于（>=）
• 包含
• 不包含

简化的URL生成

视图助手Mol_View_Helper_To可以用作Zend_View_Helper_Url的替代方案，在视图脚本中生成URL。

<?= $this->to('my-action', 'my-controller', 'my-module')->withParam('confirm', 1); ?>

它避免了以数组形式传递必要信息，并提供了一个流畅的接口，使URL生成更易于阅读。

默认情况下，必须明确提供所有URL参数，请求的参数不会自动包括在内。