README

Wasp 是一个工具，可以将简单的 YAML 配置文件转换为可用的 WordPress 代码。使用各种“处理器”，wasp 解析您的配置文件并生成注册文章类型、分类法、菜单等功能所需的代码。Wasp 通过利用合理的默认值和接受用户定义的默认值，减少了这项工作的繁琐性质，提供了完全的灵活性。

Wasp 最好作为构建过程的一部分使用，这意味着只有 YAML 文件会存储在您的版本控制系统中。在构建过程中，wasp 会解析配置文件并生成一个 PHP 文件，该文件可以充当主题的 functions.php 文件、插件的主要文件、mu 插件的全部内容或由前述任何文件包含的文件。然而，wasp 也可以用来生成您可以用作项目起点的代码，允许您从那里保存和修改它。因此，如果您在某个时刻想要放弃使用 wasp，只需生成代码、保存它并从项目中删除 wasp 即可。Wasp 让您享受到主题或插件框架的好处，而无需提交！

安装

安装 wasp 的首选方法是使用 Composer

$ composer require balbuf/wasp --dev

现在，wasp 将可在 composer 的 "bin 目录" 中使用，默认情况下位于 vendor/bin。您应该能够通过以下方式运行 wasp：

$ vendor/bin/wasp

Wasp 默认不附带任何处理器，这样您就可以只利用所需的特性，而无需更多。为了开始，您需要安装一个或多个包含处理器的 wasp 插件。所有基本 WordPress 配置的必要处理器都可以在 balbuf/wasp-core 中找到。

$ composer require balbuf/wasp-core --dev

创建 Config YAML 文件

配置 YAML 文件可以命名为您喜欢的任何名称，并存储在任何位置。当您运行 generate 命令时，您将指定配置文件的位置。唯一的要求是文件包含有效的 YAML 以及为每个处理器正确格式化的数据。

您在 YAML 文件中设置的属性将取决于您打算使用的处理器。通常，一个顶级属性将被单个处理器使用，但有时多个处理器会针对同一属性执行不同的操作，或者处理器可能会引用它所处理的主要属性之外的其他属性以获取更多信息。

所有配置文件都应该包含一个 wasp 属性，它定义了文件本身的详细信息，例如：

wasp:
  # a unique prefix used to differentiate this project from others
  prefix: wasp_example

  # location of this file relative to the file root of the project
  dir: inc

  # how wasp should determine the public URL that corresponds to the file root of the project
  url_context: plugin

其他属性将取决于您希望使用的处理器，您应该查阅相应的 wasp 插件的文档。

生成代码

生成代码需要输入文件路径（到您的 YAML 配置文件）和输出文件路径（到生成的 PHP 代码），例如：

$ vendor/bin/wasp generate config.yml themes/my-theme/functions.php

输入文件路径和/或输出文件路径可以用 - 替换，分别从 STDIN 读取数据或将数据写入 STDOUT。

在您的项目中使用附加文件的一些处理器（例如，帮助包含文件、排队前端资源的处理器等）需要知道项目文件根路径。例如，文件根目录包含您的主题的 functions.php 文件或插件的主体插件文件。知道文件根在文件系统中的位置以及您的生成文件在文件根中的相对位置（通过配置文件中的 wasp.dir 属性指定），使处理器能够分析文件系统中的文件，并从生成的 PHP 文件中正确引用它们。

在大多数情况下，可以根据通过命令行提供的输出文件路径以及配置文件中指定的 wasp.dir 属性来识别文件根。然而，在写入 STDOUT 的情况下，可能需要显式指定项目的文件根。例如，上面的示例可以重写为

$ vendor/bin/wasp generate config.yml - --root=themes/my-theme > themes/my-theme/functions.php

如果没有指定或无法从输出路径中识别，文件根默认为当前工作目录。

添加处理器

通常通过使用 composer 安装额外的 wasp 插件来将处理器添加到您的项目中。当 wasp 运行时，它会分析您的项目的 composer.lock 文件以识别和执行所有 wasp 插件。

考虑到您的项目中安装的所有插件/处理器默认都是激活的，在生成代码时，您可能希望禁用某些插件和/或处理器。

要禁用插件，请使用 --disable-plugin= 选项以及插件的 composer 包名
要禁用处理器，请使用 --skip-handler= 选项以及处理器的机器名称

这两个选项都可以重复使用来禁用多个插件和/或处理器。

Wasp 配置属性

wasp 顶级属性包含有关项目的信息，并控制代码的生成方式。

高级配置

Wasp 使用 Twig 来处理其配置值，允许用户在配置中引用其他属性并使用 Twig 的过滤器、函数等执行一些基本值处理。为了在配置属性值中使用 Twig，必须在一些或全部值中包含 Twig 模板定界符：{{ }} 用于表达式，{% %} 用于更复杂的数据结构（循环、逻辑等）。（注意，当属性值以 Twig 模板开始时，值必须用引号括起来，否则 YAML 解析器会将其解释为内联对象，例如 property: '{{ template }}' 而不是无效的 property: {{ template }}。）

特殊变量

在配置属性模板中，存在一些特殊变量，允许访问周围的属性值、当前属性链等。

因为 Twig 是一个旨在最终生成字符串的模板引擎，所以需要对特殊处理进行特殊处理以生成属性的非字符串值。提供了一个名为 output 的额外变量，该变量具有 setValue() 方法，可以覆盖属性模板解析后的属性值，例如 {% do output.setValue(["this", "produces", "an", "array"]) %}。类似地，特殊变量 this、top 和 vars 默认返回其他属性值的字符串。要访问其他类型的属性值，必须将属性名附加 .getValue()，例如 this.sibling_prop.getValue()；作为快捷方式，可以将属性名附加 () 来访问原始值，例如 this.sibling_prop()。

用户默认值

对于许多处理程序，其属性结构是关联数组的关联数组，wasp 提供了一种方便的方式来为这些二级关联数组提供默认值。为了说明这种属性结构

handler_property:

  thing1:
    name: Thing 1
    color: red

  thing2:
    name: Thing 2

注意处理程序的属性是一个关联数组，其中键（例如 thing1）表示项目的机器友好标识符，而项目的值是另一个关联数组，包含项目的属性和值（例如 name，color 等）。当项目数组具有许多可能的属性时，重复相同的值为每个项目并不是不常见。

为了减少重复，您可以添加一个具有填充属性的 default 项，这些属性将用于其他所有未显式设置的项，例如

handler_property:

  default:
    color: blue
    name: Untitled

  thing1:
    name: Thing 1
    color: red

  thing2:
    name: Thing 2

由于 thing2 未指定 color 属性，它从 default 项继承了 color 值（蓝色）。

自引用属性模板

默认项的另一个功能是在项目属性值解析时能够引用主项中的相同属性。除了提供默认值之外，默认项还可以修改每个主项中的属性值。为了制作自引用模板，可以使用 this 关键字。在以下示例中，我们使用默认的 post_type 属性为帖子类型别名添加前缀

post_types:

  default:
    post_type: wasp_{{ this }}

  event:
    post_type: event

  testimonial:
    post_type: testimonial

当此配置解析时，我们项目的 post_type 属性将分别为 wasp_event 和 wasp_testimonial。

配方

使用 Twig 的高级配置可能有点复杂，因此这里有一些示例“配方”来帮助说明潜在的可能性，并允许您以最少的努力从配置文件中获得最大收益。

条件前缀

上面的带前缀的帖子类型示例很棒，但在某些情况下，您可能需要使用 post_type wasp 处理程序来修改内置帖子类型或由插件提供的帖子类型。在这些情况下，向帖子类型值添加前缀是不正确的。我们可以使用 env 对象来关闭某些项目的前缀，例如

post_types:

  default:
    post_type: '{% if not env.noPrefix %}wasp_{{ this }}{% endif %}'

  event:
    post_type: event

  testimonial:
    post_type: testimonial

  post:
    post_type: post{% do env.set('noPrefix', true) %}

现在解析的 post_type 属性将分别是 wasp_event，wasp_testimonial 和 post。

这也可以通过向项添加自定义属性来实现

post_types:

  default:
    post_type: '{% if not this.no_prefix %}wasp_{{ this }}{% endif %}'

  event:
    post_type: event

  testimonial:
    post_type: testimonial

  post:
    post_type: post
    no_prefix: true

这可以使配置看起来更干净，但可能的缺点是 no_prefix 值将被传递给任何处理程序。在大多数情况下，处理程序将忽略它不期望的任何属性，但自定义属性可能会对某些处理程序产生意外的后果。

带有默认值的后缀

假设您想利用自引用模板，同时仍在主项之一中未设置属性的情况下提供默认值。这也同样可行！以这个想象的 images 处理程序为例，我们想要自动将 .jpeg 文件扩展名添加到 file 属性值中，同时仍然提供备用文件值

images:

  default:
    file: '{{ ( this ?: "placeholder" ) ~ ".jpeg" }}'

  pic1:
    file: kittens
    alt: Kittens playing!

  pic2:
    file: puppies
    alt: Puppies playing!

  pic3:
    alt: Image coming soon!

当配置解析时，文件属性的值将分别是 kittens.jpeg，puppies.jpeg 和 placeholder.jpeg。

默认数组值

在指定脚本依赖项时，许多或所有都要求 jquery。我们可以使用 default 对象和自定义属性来设置此脚本（以及其他脚本）作为默认基本依赖项。scripts 处理程序将查找 dependencies 属性，因此我们将利用 default 项和自定义属性（additional_dependencies）来合并我们的基本脚本依赖项与每个项的任何附加依赖项

scripts:

  default:
    dependencies: '{% set deps = ["jquery"] %}{% do output.setValue(this ?: (this.additional_dependencies() is iterable ? this.additional_dependencies() | merge(deps) : deps)) %}'

  main:
    additional_dependencies:
      - jquery-ui

  navigation:
    dependencies:
      - underscore

对于 main 项，它声明了额外的依赖项 jquery-ui，导致它使用默认的基本依赖项，产生 ['jquery', 'jquery-ui']。对于 navigation 项，我们不需要 jquery，所以我们直接使用 dependencies 属性；我们默认 dependencies 属性中的逻辑尊重这一点，并产生此项的 ['underscore']。

扩展

待办事项：创建插件、创建处理器、创建编译项、使用编译项、包含文件等。

balbuf / wasp

维护者

详细信息