README

此库允许其他库配置自动生成代码的模板，使用composer插件快速启动项目。

一旦启用Pro Forma插件，从最终用户的角度来看，模板化过程是无缝的，因此安装配置了Pro Forma模板的库将自动生成这些文件（如果它们还不存在）。

项目安装

要在项目中使用Pro Forma，请将插件启用在composer.json文件中，并允许PuzzleDI使用包含代码模板的库

{
  "config": {
    "allow-plugins": {
      "lexide/pro-forma": true,
      "lexide/puzzle-di": true
    }
  },
  "extra": {
    "lexide/puzzle-di": {
      "whitelist": {
        "lexide/pro-forma": [
          "target/library"
        ]
      }
    }
  }
}

运行install或updateComposer命令将调用Pro Forma代码生成。如果尚未启用，Composer还可能询问是否应启用Pro Forma插件。

建议将自动生成的文件添加到版本控制中，但这不是必需的。

重要！只有白名单库的模板才会被生成。这包括任何白名单库添加到白名单信任链中的其他库。这是为了防止在向项目中添加新库时意外生成代码。如果Pro Forma没有生成预期的文件，建议检查库是否已正确白名单。

模板提供者

Pro Forma通过使用lexide/puzzle-di让库向其注册模板提供者，然后处理这些类提供的模板配置，将模板文件转换为生成代码。

Pro Forma使用lexide/puzzle-di收集一组TemplateProviderInterface类名。

Composer配置

每个库可以通过在库的composer.json文件中添加以下配置来注册一个模板提供者，该提供者实现Lexide\ProForm\Template\TemplateProviderInterface接口

{
  "extra": {
    "lexide/puzzle-di": {
      "files": {
        "lexide/pro-forma": {
          "class": "Fully\\Qualified\\Template\\Provider\\Class\\Name"
        }
      }
    }
  }
}

如果此库使用应使用Pro Forma自动生成代码的依赖项，则可以在库的composer.json文件中将这些依赖库添加到PuzzleDI的白名单链中，这与配置项目的方式非常相似

{
  "extra": {
    "lexide/puzzle-di": {
      "whitelist": {
        "lexide/pro-forma": [
          "dependent/library"
        ]
      }
    }
  }
}

模板

模板提供者的目的是返回一个包含Lexide\ProForm\Template\Template类实例的数组。这些实例需要包含所有必要的模板化生成代码的信息。

为了自定义返回哪些模板文件，提供者会传递两个配置对象；一个Lexide\ProForm\Template\ProviderConfig\ProjectConfig实例，它包含项目命名空间和已安装包列表，以及一个包含从项目的composer.json中获取的当前提供者配置的Lexide\ProForm\Template\ProviderConfig\LibraryConfig实例。这允许提供者做出诸如如果安装了包则添加特定模板或根据项目配置选项设置替换值等决策。

提供者的LibraryConfig实例中的值仅为其库定义，并按以下方式配置

{
  "extra": {
    "lexide/pro-forma": {
      "config": {
        "target/library": {
          "foo": "bar"
        }
      }
    }
  }
}

在此示例中，LibraryConfig实例将包含键foo下的值bar。

$value = $libraryConfig->getValue("foo");    // value is set to 'bar'

模板类

模板类Lexide\ProForma\Template\Template有四个属性

• name - 模板名称。
• templatePath - 要处理的模板文件的相对路径，相对于库根。
• outputPath - 要生成的文件的路径，相对于 项目根目录。
• replacements - 用于替换模板的键/值对数组。

这些属性可以通过手动创建的模板实例的设置器或通过工厂方法设置：Lexide\ProForma\Template\TemplateFactory::create()。

替换

模板文件可以包含占位符值，在生成输出文件时将被替换。替换数组由模板提供者确定，且每个模板都是定制的。Pro Forma事先不知道模板中存在哪些占位符值，它将根据提供者的键盲目尝试替换它们，因此如果使用了占位符，必须为模板实例中的每个占位符添加一个替换。

占位符键被双大括号包围，{{ key }}；大括号内的空格是可选的。在定义替换时，只使用键名，不需要大括号。

$template->setReplacements(["key" => "value"]);

重要提示！为了保持一致性，替换值必须始终是字符串；任何不是字符串的值都将被忽略，并输出一个描述该值无效的消息。这包括“可转换为字符串”的值或PHP自然转换为字符串的值。

重新生成文件

有时，如果库有更新且改变了模板的行为，可能需要重新生成文件。

为了执行此操作，临时将以下值添加到extra中的lexide/pro-forma部分

{
  "extra": {
    "lexide/pro-forma": {
      "overwrite": true
    }
  }
}

请注意，当此值设置为true时，Pro Forma将继续覆盖文件；此设置不是永久使用的，以避免在composer更新或安装后行为出现意外变化。

此外，此设置告诉Pro Forma覆盖所有文件，因此不在版本控制中的任何自定义修改将被删除。

最后，Pro Forma永远不会删除文件；如果卸载了库，其自动生成的代码需要手动删除。