nelexa/crossplane

可靠的快速NGINX配置文件解析器和构建器。这是Nginx Python crossplane包的PHP端口。

维护者

详细信息

github.com/Ne-Lexa/php-crossplane

源代码

问题

安装数: 4,178

依赖项: 0

建议者: 0

安全: 0

星标: 19

关注者: 3

分支: 3

开放问题: 0

1.0.3 2022-10-03 12:55 UTC

Requires

Requires (Dev)

Suggests

Apache-2.0 2a8182d0b9c7e24cfbda39ffd5a5731688fa4795

  • Ne-Lexa <alexey.woop@nelexa.ru>

parsernginxcreossplane

This package is auto-updated.

Last update: 2024-08-30 01:12:00 UTC

README

crossplane

php-crossplane

可靠的快速NGINX配置文件解析器和构建器

ℹ️ 这是Nginx Python crossplane包的PHP端口，可以在这里找到。

Packagist Version Packagist PHP Version Support Build Status License

安装

在项目中安装

composer require nelexa/crossplane

全局安装

composer require --global nelexa/crossplane

在PHP中使用

$crossplane = new \Nelexa\NginxParser\Crossplane();

$lexer = $crossplane->lexer(); // gets \Nelexa\NginxParser\Lexer instance
$builder = $crossplane->builder(); // gets \Nelexa\NginxParser\Builder instance
$parser = $crossplane->parser(); // gets \Nelexa\NginxParser\Parser instance
$analyzer = $crossplane->analyzer(); // gets \Nelexa\NginxParser\Analyzer instance
$formatter = $crossplane->formatter(); // gets \Nelexa\NginxParser\Formatter instance

解析配置

$nginxConfigFile = '/etc/nginx/nginx.conf';
$crossplane = new \Nelexa\NginxParser\Crossplane();
$payload = $crossplane->parser()->parse($nginxConfigFile, $parseOptions = [
    \Nelexa\NginxParser\Parser::OPTION_COMMENTS => true,
    \Nelexa\NginxParser\Parser::OPTION_COMBINE => true,
    // etc...
]);

这将返回与crossplane parse部分中描述的相同负载。

从负载构建配置

$crossplane = new \Nelexa\NginxParser\Crossplane();
$config = $crossplane->builder()->build(
    [[
        'directive' => 'events',
        'args' => [],
        'block' => [[
            'directive' => 'worker_connections',
            'args' => ['1024'],
        ]],
    ]]
);

这将返回一个包含整个NGINX配置文件的整个字符串。

events {
    worker_connections 1024;
}

Lex配置

$crossplane = new \Nelexa\NginxParser\Crossplane();
$tokensIterator = $crossplane->lexer()->lex('/etc/nginx/nginx.conf');
$tokensArray = iterator_to_array($tokensIterator);

$crossplane->lexer()->lex()生成3元组。

[
    [
        'user', // token
        1,      // line
        false,  // quote
    ],
    [
        'www-data',
        1,
        false,
    ],
    [
        ';',
        1,
        false,
    ],
    [
        'worker_processes',
        2,
        false,
    ],
    [
        'auto',
        2,
        false,
    ],
    [
        ';',
        2,
        false,
    ],
    [
        'pid',
        3,
        false,
    ],
    [
        '/run/nginx.pid',
        3,
        false,
    ],
    [
        ';',
        3,
        false,
    ],
    // etc
]

注册自定义Lexer/Builder指令

$crossplane->registerExtension(new class() implements \Nelexa\NginxParser\Ext\CrossplaneExtension {
public function registerExtension(\Nelexa\NginxParser\Crossplane $crossplane): void
{
$crossplane->lexer()->registerExternalLexer(/* args */);
$crossplane->builder()->registerExternalBuilder(/* args */);
}

    public function lex(\Iterator $charIterator, string $directive): ?\Generator
    {
    }

    public function build(array $stmt, string $padding, int $indent = 4, bool $tabs = false): string
    {
    }
});

命令行界面

要在命令行界面中调用命令，如果您已在本项目中本地安装了包，请使用vendor/bin/crossplane，如果您已全局安装了包，请使用crossplane。

Usage:
  vendor/bin/crossplane command [options] [arguments]

Options:
  -h, --help            Display this help message
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi            Force ANSI output
      --no-ansi         Disable ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Available commands:
  build   builds an nginx config from a json payload
  format  formats an nginx config file
  help    Display help for a command
  lex     lexes tokens from an nginx config file
  minify  removes all whitespace from an nginx config
  parse   parses a json payload for an nginx config

crossplane parse

此命令将输入主NGINX配置文件的路径，然后将整个配置解析到下面定义的模式中，并将整个内容作为JSON负载输出。

Description:
  parses a json payload for an nginx config

Usage:
  vendor/bin/crossplane parse [options] [--] <filename>

Arguments:
  filename                the nginx config file

Options:
  -o, --out[=OUT]         write output to a file
  -i, --indent[=INDENT]   number of spaces to indent output [default: 0]
      --ignore[=IGNORE]   ignore directives (comma-separated) (multiple values allowed)
      --no-catch          only collect first error in file
      --tb-onerror        include tracebacks in config errors
      --combine           use includes to create one single file
      --single-file       do not include other config files
      --include-comments  include comments in json
      --strict            raise errors for unknown directives
  -h, --help              Display this help message
  -q, --quiet             Do not output any message
  -V, --version           Display this application version
      --ansi              Force ANSI output
      --no-ansi           Disable ANSI output
  -n, --no-interaction    Do not ask any interactive question
  -v|vv|vvv, --verbose    Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

隐私和安全

由于crossplane通常用于创建发送到不同服务器的负载，因此需要考虑安全性。因此，添加了--ignore选项。它可以用来确保某些敏感指令完全不在负载输出中。

例如，我们总是使用类似这个标志的NGINX Amplify Agent，以尊重用户的隐私。

--ignore=auth_basic_user_file,secure_link_secret,ssl_certificate_key,ssl_client_certificate,ssl_password_file,ssl_stapling_file,ssl_trusted_certificate

模式

响应对象

{
    "status": String, // "ok" or "failed" if "errors" is not empty
    "errors": Array,  // aggregation of "errors" from Config objects
    "config": Array   // Array of Config objects
}

配置对象

{
    "file": String,   // the full path of the config file
    "status": String, // "ok" or "failed" if errors is not empty array
    "errors": Array,  // Array of Error objects
    "parsed": Array   // Array of Directive objects
}

指令对象

{
    "directive": String, // the name of the directive
    "line": Number,      // integer line number the directive started on
    "args": Array,       // Array of String arguments
    "includes": Array,   // Array of integers (included iff this is an include directive)
    "block": Array       // Array of Directive Objects (included iff this is a block)
}

注意

如果这是一个include指令并且未使用--single-file标志，则将使用一个包含由此指令包含的配置索引数组的"includes"值。

如果这是一个块指令，则将使用一个包含定义块上下文的更多指令对象的"block"值。

错误对象

{
    "file": String,     // the full path of the config file
    "line": Number,     // integer line number the directive that caused the error
    "error": String,    // the error message
    "callback": Object  // only included iff an "onerror" function was passed to parse()
}

注意

如果使用crossplane parse的--tb-onerror标志，则"callback"将包含一个字符串，表示错误引起的跟踪信息。

示例

主要的NGINX配置文件位于/etc/nginx/nginx.conf。

events {
    worker_connections 1024;
}

http {
    include conf.d/*.conf;
}

此配置文件位于/etc/nginx/conf.d/servers.conf。

server {
    listen 8080;
    location / {
        try_files 'foo bar' baz;
    }
}

server {
    listen 8081;
    location / {
        return 200 'success!';
    }
}

因此，如果您运行此命令

vendor/bin/crossplane parse --indent=4 /etc/nginx/nginx.conf

格式化后的JSON输出将如下所示

{
    "status": "ok",
    "errors": [],
    "config": [
        {
            "file": "/etc/nginx/nginx.conf",
            "status": "ok",
            "errors": [],
            "parsed": [
                {
                    "directive": "events",
                    "line": 1,
                    "args": [],
                    "block": [
                        {
                            "directive": "worker_connections",
                            "line": 2,
                            "args": [
                                "1024"
                            ]
                        }
                    ]
                },
                {
                    "directive": "http",
                    "line": 5,
                    "args": [],
                    "block": [
                        {
                            "directive": "include",
                            "line": 6,
                            "args": [
                                "conf.d/*.conf"
                            ],
                            "includes": [
                                1
                            ]
                        }
                    ]
                }
            ]
        },
        {
            "file": "/etc/nginx/conf.d/servers.conf",
            "status": "ok",
            "errors": [],
            "parsed": [
                {
                    "directive": "server",
                    "line": 1,
                    "args": [],
                    "block": [
                        {
                            "directive": "listen",
                            "line": 2,
                            "args": [
                                "8080"
                            ]
                        },
                        {
                            "directive": "location",
                            "line": 3,
                            "args": [
                                "/"
                            ],
                            "block": [
                                {
                                    "directive": "try_files",
                                    "line": 4,
                                    "args": [
                                        "foo bar",
                                        "baz"
                                    ]
                                }
                            ]
                        }
                    ]
                },
                {
                    "directive": "server",
                    "line": 8,
                    "args": [],
                    "block": [
                        {
                            "directive": "listen",
                            "line": 9,
                            "args": [
                                "8081"
                            ]
                        },
                        {
                            "directive": "location",
                            "line": 10,
                            "args": [
                                "/"
                            ],
                            "block": [
                                {
                                    "directive": "return",
                                    "line": 11,
                                    "args": [
                                        "200",
                                        "success!"
                                    ]
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

crossplane parse（高级）

此工具使用两个标志，可以更改crossplane处理错误的方式。

第一个，--no-catch，可以在您希望crossplane在找到第一个错误后退出解析时使用。

第二个，--tb-onerror，将在JSON输出的所有错误对象中添加一个"callback"键，每个都包含一个字符串表示的跟踪信息，该信息表示如果未捕获异常，解析器将引发。这可以用于日志记录目的。

crossplane build

此命令将输入文件的路径。该文件应包含上述定义结构的NGINX配置的JSON表示。将crossplane parse的输出保存和使用以重新构建配置文件不应导致内容有任何差异，除了格式外。

Description:
  builds an nginx config from a json payload

Usage:
  vendor/bin/crossplane build [options] [--] <filename>

Arguments:
  filename               the file with the config payload

Options:
  -d, --dir[=DIR]        the base directory to build in [default: $PWD]
  -f, --force            overwrite existing files
  -i, --indent[=INDENT]  number of spaces to indent output [default: 4]
  -t, --tabs             indent with tabs instead of spaces
      --no-headers       do not write header to configs
      --stdout           write configs to stdout instead
  -h, --help             Display this help message
  -q, --quiet            Do not output any message
  -V, --version          Display this application version
      --ansi             Force ANSI output
      --no-ansi          Disable ANSI output
  -n, --no-interaction   Do not ask any interactive question
  -v|vv|vvv, --verbose   Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

crossplane lex

该命令接收一个NGINX配置文件，通过删除空白和注释将其拆分为标记，并将标记列表以JSON数组的形式输出。

Description:
  lexes tokens from an nginx config file

Usage:
  vendor/bin/crossplane lex [options] [--] <filename>

Arguments:
  filename               the nginx config file

Options:
  -o, --out[=OUT]        write output to a file
  -i, --indent[=INDENT]  number of spaces to indent output [default: 0]
  -l, --line-numbers     include line numbers in json payload
  -h, --help             Display this help message
  -q, --quiet            Do not output any message
  -V, --version          Display this application version
      --ansi             Force ANSI output
      --no-ansi          Disable ANSI output
  -n, --no-interaction   Do not ask any interactive question
  -v|vv|vvv, --verbose   Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

示例

将此NGINX配置文件传递到 /etc/nginx/nginx.conf

events {
    worker_connections 1024;
}

http {
    include conf.d/*.conf;
}

通过运行

vendor/bin/crossplane lex /etc/nginx/nginx.conf

将生成以下JSON输出

["events","{","worker_connections","1024",";","}","http","{","include","conf.d/*.conf",";","}"]

然而，如果您选择使用--line-numbers标志，则输出将类似于

[["events",1],["{",1],["worker_connections",2],["1024",2],[";",2],["}",3],["http",5],["{",5],["include",6],["conf.d/*.conf",6],[";",6],["}",7]]

crossplane format

这是一个快速且实用的工具，它内部使用crossplane parse来格式化NGINX配置文件。它的目的是展示您可以使用crossplane的解析能力做什么。它并不是一个功能齐全、特性丰富的格式化工具。如果您正在寻找这样的工具，那么您可能需要考虑使用crossplane的PHP API自己编写。

Description:
  formats an nginx config file

Usage:
  vendor/bin/crossplane format [options] [--] <filename>

Arguments:
  filename               the nginx config file

Options:
  -o, --out[=OUT]        write output to a file
  -i, --indent[=INDENT]  number of spaces to indent output [default: 4]
  -t, --tabs             indent with tabs instead of spaces
  -h, --help             Display this help message
  -q, --quiet            Do not output any message
  -V, --version          Display this application version
      --ansi             Force ANSI output
      --no-ansi          Disable ANSI output
  -n, --no-interaction   Do not ask any interactive question
  -v|vv|vvv, --verbose   Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

crossplane minify

这是一个简单有趣的小工具，它内部使用crossplane lex尽可能多地删除NGINX配置文件中的空白，而不影响其功能。它无法想象这个工具对大多数人有多大用途，但它展示了您可以使用crossplane的词法分析能力做些什么。

Description:
  removes all whitespace from an nginx config

Usage:
  vendor/bin/crossplane minify [options] [--] <filename>

Arguments:
  filename              the nginx config file

Options:
  -o, --out[=OUT]       write output to a file
  -h, --help            Display this help message
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi            Force ANSI output
      --no-ansi         Disable ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug