README

Wasp是一个将简单的YAML配置文件转换为工作WordPress代码的工具。通过使用各种"处理器"，Wasp解析您的配置文件并生成必要的代码以注册文章类型、分类法、菜单等等！Wasp通过利用合理的默认值和接受用户定义的默认值来实现完全的灵活性，从而减少了这项工作的繁琐性。

Wasp最好作为构建过程的一部分使用，这意味着只有YAML文件会被存储在您的版本控制系统中。在构建过程中，Wasp将解析配置文件并生成一个PHP文件，该文件可以作为主题的functions.php文件、插件的主要文件、mu-plugin的全部内容或任何前者的包含文件。但是，Wasp也可以用来生成代码，您可以将这些代码作为项目的起点，并从那里保存和修改它。因此，如果您在任何时候想要放弃Wasp，只需生成代码、保存并从项目中移除Wasp即可。Wasp为您提供了主题或插件框架的好处，而无需进行任何提交！

安装

安装Wasp的首选方式是通过Composer

$ composer require balbuf/wasp --dev

现在，Wasp将可用在Composer的"bin dir"中，默认情况下位于vendor/bin。您应该能够通过以下方式运行Wasp

$ vendor/bin/wasp

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

$ composer require balbuf/wasp-core --dev

创建配置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']。

扩展

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