解析器服务

• Introduction
• 降价解析器
• Twig 模板解析器
• 括号解析器
• YAML 配置解析器
• 初始化 (INI) 配置解析器
  • Winter风味的 INI
• 动态语法分析器
  • 查看模式
  • 编辑模式
  • 支持的标签
• 数据文件解析器：数组
  • 加载ArrayFile
  • 设定值
    • 多维数组
    • 默认值env() 帮手
    • 函数值
    • 常数值
  • 按键排序
  • 写ArrayFile
  • 渲染内容
• 数据文件解析器：.env
  • 设定值
    • 空行
  • 写EnvFile
  • 渲染内容
  • 获取变量

#Introduction

Winter 使用多种标准来处理标记、模板和配置。每一个都经过精心挑选，以发挥各自的作用，使您的开发过程和学习曲线尽可能简单。例如，在主题中找到的对象 使用Twig 和INI格式 在他们的模板结构中。下面更详细地描述了每个解析器。

#降价解析器

Markdown 允许您编写易于阅读和编写的纯文本格式，然后将其转换为 HTML。这Markdown facade 用于解析 Markdown 语法，基于GitHub 风格的降价.降价的一些简单示例：

This text is **bold**, this text is *italic*, this text is ~~crossed out~~.

# The largest heading (an <h1> tag)
## The second largest heading (an <h2> tag)
...
###### The 6th largest heading (an <h6> tag)

使用Markdown::parse 将 Markdown 呈现为 HTML 的方法：

$html = Markdown::parse($markdown);

您也可以使用|md 筛选在前端标记中解析 Markdown.

{{ '**Text** is bold.' | md }}

#Twig 模板解析器

Twig 是一个简单但功能强大的模板引擎，可以将 HTML 模板解析为优化的 PHP 代码，它是背后的驱动力前端标记,查看内容 和邮件内容.

这Twig facade 用于解析 Twig 语法，你可以使用Twig::parse 将 Twig 渲染为 HTML 的方法。

$html = Twig::parse($twig);

第二个参数可用于将变量传递给 Twig 标记。

$html = Twig::parse($twig, ['foo' => 'bar']);

可以扩展 Twig 解析器以通过以下方式注册自定义功能插件注册文件.

#括号解析器

Winter 还附带了一个简单的括号模板解析器作为 Twig 解析器的替代品，目前用于将变量传递给主题内容块.该引擎渲染 HTML 的速度更快，并且旨在更适合非技术用户。这个解析器没有门面，所以完全限定Winter\Storm\Parse\Bracket 类应该与parse 方法。

use Winter\Storm\Parse\Bracket;

$html = Bracket::parse($content, ['foo' => 'bar']);

语法使用单数大括号 渲染变量：

<p>Hello there, {foo}</p>

您还可以传递一个对象数组以作为变量进行解析。

$html = Template::parse($content, ['likes' => [
    ['name' => 'Dogs'],
    ['name' => 'Fishing'],
    ['name' => 'Golf']
]]);

可以使用以下语法迭代数组：

<ul>
    {likes}
        <li>{name}</li>
    {/likes}
</ul>

#YAML 配置解析器

YAML（“YAML Ain't Markup Language”）是一种配置格式，类似于 Markdown 它被设计为一种易于阅读和易于编写的格式，可转换为 PHP 数组。它几乎无处不在用于 Winter 的后端开发，例如表单字段 和列表栏 定义。一些 YAML 的示例：

receipt: Acme Purchase Invoice
date: 2015-10-02
user:
    name: Joe
    surname: Blogs

这Yaml facade 用于解析 YAML，您使用Yaml::parse 将 YAML 呈现为 PHP 数组的方法：

$array = Yaml::parse($yamlString);

使用parseFile 解析文件内容的方法：

$array = Yaml::parseFile($filePath);

解析器还支持反向操作，从 PHP 数组输出 YAML 格式。您可以使用render 方法：

$yamlString = Yaml::render($array);

#初始化 (INI) 配置解析器

INI 文件格式是定义简单配置文件的标准，通常由主题模板中的组件.它可以被认为是 YAML 格式的表亲，尽管与 YAML 不同，它非常简单，对拼写错误不太敏感并且不依赖于缩进。它支持带有部分的基本键值对，例如：

receipt = "Acme Purchase Invoice"
date = "2015-10-02"

[user]
name = "Joe"
surname = "Blogs"

这Ini facade 用于解析 INI，您使用Ini::parse 将 INI 呈现为 PHP 数组的方法：

$array = Ini::parse($iniString);

使用parseFile 解析文件内容的方法：

$array = Ini::parseFile($filePath);

解析器还支持反向操作，从 PHP 数组输出 INI 格式。您可以使用render 方法：

$iniString = Ini::render($array);

#Winter风味的 INI

传统上，PHP 函数使用的 INI 解析器parse_ini_string 仅限于 3 层深的数组。例如：

level1Value = "foo"
level1Array[] = "bar"

[level1Object]
level2Value = "hello"
level2Array[] = "world"
level2Object[level3Value] = "stop here"

Winter 扩展了这个功能Winter风味的 INI 允许无限深度的数组，灵感来自 HTML 表单的语法。继上面的示例之后，支持以下语法：

[level1Object]
level2Object[level3Array][] = "Yay!"
level2Object[level3Object][level4Value] = "Yay!"
level2Object[level3Object][level4Array][] = "Yay!"
level2Object[level3Object][level4Object][level5Value] = "Yay!"
; ... to infinity and beyond!

#动态语法分析器

Dynamic Syntax 是 Winter 独有的模板引擎，它从根本上支持两种渲染模式。解析一个模板会产生两个结果，一个view 或者editor 模式。以此模板文本为例，{text}...{/text} 标签代表的默认文本view 模式，而内部属性，name 和label, 被用作属性editor 模式。

<h1>{text name="websiteName" label="Website Name"}Our wonderful website{/text}</h1>

这个解析器没有门面，所以完全限定Winter\Storm\Parse\Syntax\Parser 类应该与parse 方法。的第一个参数parse 方法将模板内容作为字符串并返回一个Parser 目的。

use Winter\Storm\Parse\Syntax\Parser as SyntaxParser;

$syntax = SyntaxParser::parse($content);

#查看模式

假设我们使用上面的第一个示例作为模板内容，调用render 方法本身将使用默认文本呈现模板：

echo $syntax->render();
// <h1>Our wonderful website</h1>

就像任何模板引擎一样，将变量数组传递给render 将替换模板中的变量。这里的默认值为websiteName 被我们的新价值所取代：

echo $syntax->render(['websiteName' => 'Winter CMS']);
// <h1>Winter CMS</h1>

作为奖励功能，调用toTwig 方法将以准备状态输出模板，以供渲染树枝引擎.

echo $syntax->toTwig();
// <h1>{{ websiteName }}</h1>

#编辑模式

到目前为止，动态语法解析器与常规模板引擎没有太大区别，但是编辑器模式是动态语法的实用性变得更加明显的地方。编辑器模式开启了一个新的可能性领域，例如，在哪里布局将自定义表单字段注入页面 属于他们或为了电子邮件活动中使用的动态构建表单.

继续上面的例子，调用toEditor 上的方法Parser object 将返回一个 PHP 属性数组，这些属性定义变量应该如何被填充，例如通过表单构建器。

$array = $syntax->toEditor();
// 'websiteName' => [
//     'label' => 'Website name',
//     'default' => 'Our wonderful website',
//     'type' => 'text'
// ]

您可能会注意到这些属性与中找到的选项非常相似表单字段定义.这是有意为之的，因此这两个功能相互补充。我们现在可以轻松地将上面的数组转换为 YAML 并写入fields.yaml 文件：

$form = [
    'fields' => $syntax->toEditor()
];

File::put('fields.yaml', Yaml::render($form));

#支持的标签

有多种标签类型可以与动态语法解析器一起使用，这些标签类型旨在匹配常见的表单字段类型.

NOTE: 除了{variable} 标签将在查看模式下呈现其值。如果您只是想在视图模式下存储要在页面其他地方使用的值，那么建议使用{variable} 标签代替。

---

Variable

完全按照定义的形式呈现表单字段类型type 属性。此标记将简单地设置一个变量，并将在视图模式下呈现为空字符串。

{variable type="text" name="name" label="Name"}John{/variable}

---

选色器

用于颜色选择的颜色选择器小部件。此标签将包含选定的十六进制值。您可以选择提供一个availableColors 属性来定义可供选择的颜色。

{colorpicker name="bg_color" label="Background colour" allowEmpty="true" availableColors="#ffffff|#000000"}{/colorpicker}

---

Dropdown

呈现下拉表单字段。

{dropdown name="dropdown" label="Pick one" options="One|Two"}{/dropdown}

呈现具有独立值和标签的下拉表单字段。

{dropdown name="dropdown" label="Pick one" options="one:One|two:Two"}{/dropdown}

使用静态类方法返回的数组呈现下拉表单字段（该类必须是完全命名空间的类）。

{dropdown name="dropdown" label="Pick one" options="\Path\To\Class::method"}{/dropdown}

---

上传文件

文件的文件上传器输入。此标记值将包含文件的完整路径。

{fileupload name="logo" label="Logo"}defaultlogo.png{/fileupload}

---

Markdown

Markdown 内容的文本输入。

{markdown name="content" label="Markdown content"}Default text{/markdown}

在 Twig 中呈现为

{{ content | md }}

---

媒体查找器

媒体库项目的文件选择器。此标记值将包含文件的相对路径。

{mediafinder name="logo" label="Logo"}defaultlogo.png{/mediafinder}

在 Twig 中呈现为

{{ logo | media }}

---

Radio

呈现单选表单字段。

{radio name="radio" label="Thoughts?" options="y:Yes|n:No|m:Maybe"}{/radio}

---

Repeater

呈现内部包含其他字段的重复部分。

{repeater name="content_sections" prompt="Add another content section"}
    <h2>{text name="title" label="Title"}Title{/text}</h2>
    <p>{textarea name="content" label="Content"}Content{/textarea}</p>
{/repeater}

在 Twig 中呈现为

{% for fields in repeater %}
    <h2>{{ fields.title }}</h2>
    <p>{{ fields.content | raw }}</p>
{% endfor %}

呼唤$syntax->toEditor 将为转发器字段返回不同的数组：

'repeater' => [
    'label' => 'Website name',
    'type' => 'repeater',
    'fields' => [

        'title' => [
            'label' => 'Title',
            'default' => 'Title',
            'type' => 'text'
        ],
        'content' => [
            'label' => 'Content',
            'default' => 'Content',
            'type' => 'textarea'
        ]

    ]
]

转发器字段还支持组模式，与动态语法分析器一起使用，如下所示：

{variable name="sections" type="repeater" prompt="Add another section" tab="Sections"
    groups="$/author/plugin/repeater_fields.yaml"}{/variable}

这是 repeater_fields.yaml 组配置文件的示例：

quote:
    name: Quote
    description: Quote item
    icon: icon-quote-right
    fields:
        quote_position:
            span: auto
            label: Quote Position
            type: radio
            options:
                left: Left
                center: Center
                right: Right
        quote_content:
            span: auto
            label: Details
            type: textarea

有关中继器组模式的更多信息，请参阅中继器小部件.

---

丰富的编辑器

丰富内容的文本输入 (WYSIWYG)。

{richeditor name="content" label="Main content"}Default text{/richeditor}

在 Twig 中呈现为

{{ content | raw }}

---

Text

较小文本块的单行输入。

{text name="websiteName" label="Website Name"}Our wonderful website{/text}

---

Textarea

较大文本块的多行输入。

{textarea name="websiteDescription" label="Website Description"}
    This is our vision for things to come
{/textarea}

#数据文件解析器：数组

Winter CMS 使用 PHP 数组文件（除了返回单个数组外什么都不做的 PHP 文件）用于管理configuration 和翻译数据文件.为了以编程方式简化对这些文件的处理，Winter 提供了Winter\Storm\Parse\PHP\ArrayFile 解析器在核心。

#加载ArrayFile

这ArrayFile 类可用于修改 PHP 数组文件。这ArrayFile::open() 方法将初始化ArrayFile 具有所提供路径内容的解析器（如果路径不存在，它将在调用时创建$arrayFile->write()).

use Winter\Storm\Parse\PHP\ArrayFile;

$arrayFile = ArrayFile::open('/path/to/file.php');
$arrayFile->set('foo', 'bar');
$arrayFile->write();

这ArrayFile::open() 方法接受第二个参数$throwIfMissing 默认为false.如果true， A\InvalidArgumentException 如果提供，将被抛出$filePath 不指向现有文件。

#设定值

可以链接设置值，也可以通过传递数组来设置多个值

ArrayFile::open('/path/to/file.php')
    ->set('foo', 'bar')
    ->set('bar', 'foo')
    ->write();

// or

ArrayFile::open('/path/to/file.php')->set([
    'foo' => 'bar',
    'bar' => 'foo'
])->write();

多维数组

可以通过点符号或传递数组来设置多维数组。

ArrayFile::open('/path/to/file.php')->set([
    'foo.bar.a' => 'bar',
    'foo.bar.b' => 'foo'
])->write();

// or

ArrayFile::open('/path/to/file.php')->set([
    'foo' => [
        'bar' => [
            'a' => 'bar',
            'b' => 'foo'
        ]
    ]
])->write();

将输出：

<?php

return [
    'foo' => [
        'bar' => [
            'a' => 'bar',
            'b' => 'foo',
        ]
    ]
];

默认值env() 帮手

如果数组文件有env() 给定键的函数调用，设置该键的值将为调用设置默认参数env() 而不是更换env() 统统打电话

例如，如果数组文件如下所示：

<?php

return [
    'foo' => [
        'bar' => env('EXAMPLE_KEY'),
    ]
];

然后下面的代码用于设置foo.bar 财产：

ArrayFile::open('/path/to/file.php')->set([
    'foo.bar' => 'Winter CMS',
])->write();

将导致：

<?php

return [
    'foo' => [
        'bar' => env('EXAMPLE_KEY', 'Winter CMS'),
    ]
];

函数值

可以通过以下方式将函数调用添加到您的配置中PHPFunction 类或使用function() 辅助方法 在ArrayFile 目的。

use Winter\Storm\Parse\PHP\ArrayFile;
use Winter\Storm\Parse\PHP\PHPFunction;

ArrayFile::open('/path/to/file.php')->set([
    'foo.bar' => new PHPFunction('env', ['argument1', 'argument1']),
])->write();

// or

$arrayFile = ArrayFile::open('/path/to/file.php');
$arrayFile->set([
    'foo.bar' => $arrayFile->function('env', ['argument1', 'argument1']),
]);
$arrayFile->write();

常数值

可以通过以下方式将常量添加到您的配置中PHPConstant 类或使用constant() 辅助方法 在ArrayFile 目的。

use Winter\Storm\Parse\PHP\ArrayFile;
use Winter\Storm\Parse\PHP\PHPConstant;

ArrayFile::open('/path/to/file.php')->set([
    'foo.bar' => new PHPConstant('PHP_OS'),
])->write();

// or

$arrayFile = ArrayFile::open('/path/to/file.php');
$arrayFile->set([
    'foo.bar' => $arrayFile->constant('\Path\To\Class::VALUE'),
]);
$arrayFile->write();

#按键排序

这ArrayFile 对象支持在渲染前对文件中使用的键进行排序。

$arrayFile = ArrayFile::open('/path/to/file.php');
$arrayFile->set([
    'b' => 'is awesome'
    'a.b' => 'CMS',
    'a.a' => 'Winter',
]);
$arrayFile->sort(ArrayFile::SORT_ASC);
$arrayFile->write();

会写出来：

<?php

return [
    'a' => [
        'a' => 'Winter',
        'b' => 'CMS',
    ],
    'b' => 'is awesome',
];

排序方法支持以下选项：

• ArrayFile::SORT_ASC
• ArrayFile::SORT_DESC
• 可调用函数

默认情况下，sort() 将使用ArrayFile::SORT_ASC.

#写ArrayFile

默认情况下，调用$arrayFile->write() 将写入当前状态ArrayFile 到初始化时提供的路径ArrayFile::open($path).

如果需要，您可以指定一个不同的写入路径作为提供给write($path) 方法：

ArrayFile::open('/path/to/file.php')->set([
    'foo.bar' => 'Winter CMS',
])->write('/path/to/another.file.php');

#渲染内容

如果你需要 PHPArrayFile 内容作为字符串而不是直接写入文件write()， 这render() 可以使用方法。

$phpConfigString = ArrayFile::open('/path/to/file.php')->set([
    'foo.bar' => 'Winter CMS',
])->render();

#数据文件解析器：.env

Winter支持使用DotEnv 文件 (.env) 来管理环境特定变量。

获取这些值就像使用env() 辅助功能. Winter 还提供了一种以编程方式设置值的方法.env 通过使用文件Winter\Storm\Parse\EnvFile 解析器在核心。

#加载EnvFile

这EnvFile 类可用于修改 PHP 数组文件。这EnvFile::open() 方法将初始化EnvFile 具有所提供路径内容的解析器（如果路径不存在，它将在调用时创建$envFile->write()).

默认情况下，.env 与之交互的文件将是base_path('.env')，如果需要，可以通过将路径传递给open() 方法。

#设定值

可以一次设置一个值，也可以通过传递一组值来设置值。

$env = EnvFile::open();
$env->set('FOO', 'bar');
$env->set('BAR', 'foo');
$env->write();

// or

EnvFile::open()->set([
    'FOO' => 'bar'
    'BAR' => 'foo'
])->write();

注意：不支持数组点符号和嵌套数组EnvFile

use Winter\Storm\Config\EnvFile;

$env = EnvFile::open();
$env->set('FOO', 'bar');
$env->write();

注意：值是按照提供的顺序设置的，目前不支持自动排序，因为注释和空行会使排序变得更加复杂。

空行

也可以在 env 文件中添加空行，通常用于组织目的：

$env = EnvFile::open();
$env->set('FOO', 'bar');
$env->addEmptyLine();
$env->set('BAR', 'foo');
$env->write();

将输出：

FOO="bar"

BAR="foo"

#写EnvFile

默认情况下，调用$envFile->write() 将写入当前状态EnvFile 到初始化时提供的路径EnvFile::open($path). （默认为base_path('.env') 当没有$path 提供）。

如果需要，您可以指定一个不同的写入路径作为提供给write($path) 方法：

EnvFile::open()->set([
    'FOO' => 'bar',
])->write('/path/to/.env.alternative');

#渲染内容

如果您需要EnvFile 内容为字符串；而不是直接写入文件write()， 这render() 可以使用方法。

$envFileString = EnvFile::open()->set([
    'APP_NAME' => 'Winter CMS',
])->render();

#获取变量

这EnvFile 解析器提供了一个getVariables() 方法可用于获取当前变量的关联数组，不包括任何注释或空行。

$envVariables = EnvFile::open()->set([
    'APP_NAME' => 'Winter CMS',
])->getVariables();

echo $envVariables['APP_NAME']; // echos "Winter CMS"