README

本模块提供了一种从 YAML 固定值和自定义类填充数据库的方法。例如，在构建 Web 应用程序时，可以通过 YAML 定义页面和默认对象，并在开发人员之间共享。这扩展了 SilverStripe 数据模型中的 requireDefaultRecords 概念。

需求
安装说明
设置
配置选项
YAML 格式
扩展
- PopulateMySQLExport
发布配置
允许 Populate 在 "实时" 环境中运行

需求

PHP 8.1
SilverStripe 框架 ^5
SilverStripe Versioned ^2

安装说明

此模块只能用于开发环境，绝不应该在生产环境中使用。虽然存在防止在生产环境中运行的代码，但这并不是万无一失的，因此您 绝不应该在生产环境中运行此模块。在 composer 中将其作为开发依赖项安装，如下所示

composer require --dev dnadesign/silverstripe-populate

设置

首先在您的配置目录中创建一个新的 yml 配置文件 app/_config/populate.yml（或者如果您更喜欢，可以将其添加到现有的 config.yml 文件中）。

DNADesign\Populate\Populate:
  include_yaml_fixtures:
    - 'app/fixtures/populate.yml'

如果您正在与 populate 共享测试设置，可以指定任意数量的路径来加载固定值。

一个示例 app/fixtures/populate.yml 可能如下所示

Page:
  home:
    Title: "Home"
    Content: "My Home Page"
    ParentID: 0
SilverStripe\Security\Member:
  admin:
    ID: 1
    Email: "admin@example.com"
    PopulateMergeMatch:
      - 'ID'
      - 'Email'

默认情况下，当您通过 /dev/tasks/PopulateTask/ 运行 PopulateTask 时将创建记录。为了在应用程序构建过程中让开发人员完全透明，您还可以将其包含在 dev/build 中的 requireDefaultRecords 钩子中，如下所示在您的应用程序模型之一中的 requireDefaultRecords 方法中包含以下内容

use DNADesign\Populate\Populate;

class Page extends SiteTree
{
    public function requireDefaultRecords()
    {
        parent::requireDefaultRecords();
        Populate::requireRecords();
    }
}

配置选项

include_yaml_fixtures

要解析的 YAML 文件的数组。

mysite/_config/app.yml

DNADesign\Populate\Populate:
  include_yaml_fixtures:
    - 'app/fixtures/populate.yml'

truncate_objects

要从中删除其实例的 ClassName 数组。在导入之前从数据库中删除这些实例很有用，可以防止导入多个填充内容的副本。建议删除您创建的任何对象，以确保您可以在开发过程中多次运行 PopulateTask 并获得一致的数据库状态。这支持版本化对象（如 SiteTree）和 Fluent（如果已安装模块）。

DNADesign\Populate\Populate:
  truncate_objects:
    - Page
    - SilverStripe\Assets\Image

truncate_tables

要截断的表数组。当您的填充类与您想要截断的表没有关系时很有用

DNADesign\Populate\Populate:
  truncate_tables:
    - Image_Special_Table

如果您想合并新旧记录而不是清除所有记录，请参阅 更新记录。

YAML 格式

Populate 使用与 SilverStripe 单元测试框架相同的 FixtureFactory 设置。其基本结构如下

ClassName:
  somereference:
    FieldName: "Value"

通过引用它们的参考值来处理关系

SilverStripe\Security\Member:
    admin:
      Email: "admin@example.com"

Page:
  homepage:
    AuthorID: =>SilverStripe\Security\Member.admin

有关更多高级示例（包括 $many_many 和 $many_many_extraFields），请参阅 SilverStripe 固定文档。

实现《Versioned》扩展的对象将被自动发布。

基本的PHP操作也可以包含在YAML文件中。任何被单引号括起来并以分号结束的行将在导入器的当前作用域中评估。

Page:
  mythankyoupage:
    ThankYouText: "`Page::config()->thank_you_text`;"
    LinkedPage: "`sprintf(\"[Page](%s)\", App\\Page\\HelpPage::get()->first()->Link())`;"

更新记录

如果您没有截断整个表，模块将首先尝试查找现有记录并更新该记录。为了实现这一点，YAML必须声明用于查找的字段。您可以选择几种选项。

`PopulateMergeWhen`

包含WHERE子句以匹配，例如 "URLSegment = 'home' AND ParentID = 0"。

Mysite\PageTypes\HomePage:
  home:
    Title: "My awesome homepage"
    PopulateMergeWhen: "URLSegment = 'home' AND ParentID = 0"

`PopulateMergeMatch`

根据数据库匹配YAML中定义的字段列表，以避免重复内容。

Mysite\PageTypes\HomePage:
  home:
    Title: "My awesome homepage"
    URLSegment: 'home'
    ParentID: 0
    PopulateMergeMatch:
      - URLSegment
      - ParentID

`PopulateMergeAny`

将数据库中的第一条记录取出来与它合并。此选项适用于像 SiteConfig 这样的东西，其中通常只有一个记录。

SilverStripe\SiteConfig\SiteConfig:
  mysiteconfig:
    Tagline: "SilverStripe is awesome"
    PopulateMergeAny: true

如果标准符合超过1个实例，则从数据库中移除除第一个以外的所有实例，因此请确保您的标准足够具体，以获取唯一的字段值。

默认资产

脚本还通过 PopulateFileFrom 标志处理创建默认文件和图片记录。这将文件从另一个路径（例如mysite）复制到您的资产文件夹中。

SilverStripe\Assets\Image:
  lgoptimusl3ii:
    Filename: assets/shop/lgoptimusl3ii.png
    PopulateFileFrom: app/images/demo/large.png

Mysite\PageTypes\Product:
  lgoptimus:
    ProductImage: =>SilverStripe\Assets\Image.lgoptimusl3ii

扩展

根据项目需求，模块还提供可以选择的扩展。

PopulateMySQLExport

此扩展将 Populate::requireDefaultRecords() 的结果作为本地机器上的SQL Dump输出。如果使用 Populate 作为测试套件或其他CI服务的一部分，这将加快进程，因为您不需要手动调用任务（这将使用ORM），而是可以将原始MySQL导入到测试用例中，从而可能加快执行时间。

要应用此扩展，请将其添加到Populate，配置路径，刷新，然后运行 dev/tasks/PopulateTask。

DNADesign\Populate\PopulateMySQLExportExtension:
  export_db_path: ~/path.sql

DNADesign\Populate\Populate:
  extensions
    - DNADesign\Populate\PopulateMySQLExportExtension

发布配置

默认情况下，模块使用 publishSingle() 发布记录。如果您出于任何原因更愿意模块使用 publishRecursive()，您可以通过以下配置启用此选项。

DNADesign\Populate\Populate:
  enable_publish_recursive: true

允许 Populate 在 "实时" 环境中运行

危险区域：请理解，您将提供管理员在您的生产环境中运行Populate的能力。在设置此配置之前，您应该了解并接受与生产数据丢失相关的风险。

DNADesign\Populate\Populate:
  allow_build_on_live: true

致谢

silverstripe-populate最初由wilr和DNA Design创建。

dnadesign / silverstripe-populate

维护者

详细信息