README

构建与 nginx 配置语法相似的文件。针对 nginx 的特定指令在单独的包中实现。

结构

• 顶层有一个 "上下文"
• 上下文包含项目列表
• 项目可以是 "指令" 或 "注释"
• 有两种类型的指令：单行和块
• 任何类型的指令都有 "名称" 和参数列表（可以为空，参数是字符串）
• 块指令有嵌套上下文
• 嵌套上下文包含项目列表等。层数不限

语法

# The main context
# Comment line starts with "#"
# Indents doesn't matter
# Empty strings doesn't matter

single_directive;
single_directive_with_parameters one two three;

block_directive param1 param2 {
    # Nested context
    nested_single_directive;
    nested_block_directive {
        nested_nested_single_directive param;
    }
}

示例

use axy\nginx\config\syntax\Context;

$main = new Context();
$main->comment->set([
    'The main context',
    'Comment line starts with "#"', 'Indents doesn\'t matter',
    'Empty strings doesn\'t matter',
]);

$main->append('');
$main->single('single_directive');
$directive = $main->single('single_directive_with_parameters', ['one', 'two']);
$directive->params[] = 'three';
$main->append('');

$block = $main->block('block_directive', ['param1', 'param2']);
$block->context->single('nested_single_directive');
$nested = $block->context->block('nested_block_directive');
$nested->context->single('nested_nested_single_directive', 'param');
$block->context->comment->set('Nested context');

echo $main->render();

结果是 "语法" 部分的文本。

类层次结构

• BaseItem
  • BaseContext
    • Context
      • DirectiveContext
  • BaseDirective
    • SingleDirective
      • CustomSingleDirective
    • BlockDirective
      • CustomBlockDirective
• 注释

Context

context 有一个公共数组 $items。当上下文渲染时，它会按顺序渲染所有项目。

项目可以是任何可以转换为字符串的值（对象或标量）。

$context->append(new CustomeSingleDirective('name')); // append BaseItem
$context->append('other_directive;'); // or just a string

项目将在单独的行（或几行）上渲染，缩进为当前上下文。如果标量项目转换为空行，则输出中将占用一行空行。如果对象项目转换为空行，则不占用任何行。

方法和属性

• 可以直接操作 $items 数组
• append($item): void - 将项目追加到数组中
• single($name [, $params]): CustomSingleDirective - 创建单行指令的辅助函数（见下文）。创建、追加并返回。
• block($name [, $params]): CustomBlockDirective - 块指令创建的辅助函数

指令

CustomSingleDirective 和 CustomBlockDirective 用于简化指令的创建。它们作为构造函数的参数

• $name（字符串）- 指令名称
• $params - 参数列表
  • 作为公共属性可用，之后可以更改
  • NULL - 无参数
  • 字符串 - 原样显示（无需转义）
  • 字符串[] - 参数列表，转义并连接
    • 转义空格和引号
    • 不确定是否正确

$directive = new CustomSingleDirective('my_directive', 'param');
echo $directive; // my_directive param;

基类 SingleDirective 和 BlockDirective 用作特定指令类的父类。

块指令上下文

BlockDirective 有一个公共属性 $context。

$block = new CustomBlockDirective('block');
$block->context->append('one');
$block->append('two'); // alias for $block->context->append()

结果

block {
    one
    two
}

还有 $topContext 和 $mainContext（受保护）。它们会自动追加到 $context 中。通常只需要使用 $context 即可。

但是，特定的指令类应该将其内容写入 $mainContext。如果用户想添加自定义指令，他们可以使用 $context->appned()（追加到末尾）或 $topContext->append()。

禁用指令

默认情况下，所有指令对象都是启用的。但可以禁用并且不会显示。

• isEnabled(): bool
• enable(): void
• disable(): void

注释

所有指令和上下文对象都有一个公共属性 comment。

$directive = new CustomSingleDirective('name');
$directive->comment->set('It is directive');

结果

# It is directive
name;

set() 可以接受

• 字符串 - 注释内容，可以是多行的
• 字符串[] - 将连接
• NULL - 无注释（默认）
• delete() 是 set(null) 的别名

可以为块指令及其上下文设置注释

$block = new CustomBlockDirective('block');
$block->context->single('single');
$block->comment->set('It is directive');
$block->context->comment->set('It is context');

结果

# It is directive
block {
    # It is context
    single;
}

渲染

所有 BaseItem 实现 __toString()，但有一些细微差别

• 可能会有尾随空格
• 使用制表符进行缩进（每嵌套一层一个制表符）
• "\n" 用于换行

在顶层格式化可以使用 render() 方法。参数：

• $indent（字符串，默认为4个空格） - 替换制表符
• $clear（布尔值，默认为FALSE） - 删除注释行和空行
• $rtrim（布尔值，默认为TRUE） - 删除尾部空格、文件末尾的空行并以一个空行结束文件
• $nl（字符串，默认为"\n"） - 换行符号