README


                                                 /'\
                                                /   \
                                               /     \
                             _                /   ..' \_                      /\/'\
                            / \              / './       \                   /     \
                          _/   \            /             \        _        / oO    \
                /'\      /  '._'\          /               \      / \      /      /''\
               /   \    /        \        /      /          \    /   \    / \_ ..'    \
              /     \  /          \__    /      /            \  /     \__/             \
                     \/              \  /      /              \/__     \                \
                      \               \/    __/                   \     \                \
                       \              /                            \     \
                                              ))))                        \__
                 _________ _______     __ooO_(O o)_Ooo____
                |          \      \   /     | (_)         \\===========\===========\
                |     __    \      \ /      |     __      |            |           |
                |    |__)    \      V      /|    |__)     |            |           |
                |            |\           / |            <            ┌┴┐         ┌┴┐
                |        ___/  |         |  |             \          _ \ \       /  |
                |       |      |         |  |      |\      \        | \_| |     |    \_
                |       |      |         |  |      | \      \        \___/  __  \      `-_
                |_______|      |_________|  |______|  |______|             /   \  ''-.    \
                 ____   __ __  ____  _     ___      ___  ____             /    /      \    \
                |    \ |  |  ||    || |   |   \    /  _||    \            |   |        |   |
                | ()  )|  |  | |  | | |\\\\    \  /  |_ | ()  )           \    \      /    /
                |     ||  |  | |  | |  ( oo) () ||    _||    /             \    `-..-'    /
                | ()  ||  :  | |  | |   (_)     ||   |_ |    \       - --   '-_        _-'
                |_____| \__,_||____||____||_____||_____||__|\_|                `------'
                Addons scaffolder for maximum coding pleasure            - -- --------- -- -

此 PyroCMS 3 扩展一旦安装，将成为您搭建 Pyro 模块、主题、扩展和流实体的编码伴侣。

动机

以下是构建构建器扩展的一些思考和原因：

从开发者的角度来看，Pyro 3 通过其模块化设计（模块、扩展等）和数据结构抽象（ADT）实现了在 Stream 平台中，简化了构建大型 Web 应用程序的复杂性，

然而，结构带来了重复，需要使用样板代码和一系列预定义步骤来与您的应用程序集成。通常这都在文档中有所说明，但谁有时间去看呢？

此扩展试图消除一些繁琐的工作，以便开发者可以专注于编写应用程序的业务逻辑。为了实现这一点，构建器提供了一系列命令和用于构建 Pyro 应用程序不同方面的脚手架，

例如，一旦安装，该扩展将为使用 make:stream 命令生成的每个流迁移脚手架一个称为实体的软件结构。生成的代码包括 模型、存储库、表生成器、表单生成器、管理员控制器、播种器等。此外，借助 PHP 解析器，它还将配置模块类以使用路由、绑定、语言文件条目以及甚至播种和辅助函数。

安装

在您的项目文件夹中，使用 composer 引入扩展，然后按照以下步骤安装，

composer require websemantics/builder-extension
php artisan extension:install websemantics.extension.builder

入门

当使用构建器扩展开发 Pyro 应用程序时，第一个要使用的命令是 make:addon。默认的 make:addon 命令已被扩展，以启用基于模板的代码脚手架。

创建插件

像往常一样使用 make:addon 命令，文档用于创建模块、主题和其他插件类型。然而，此扩展引入了两个新概念，

1- 为每种插件类型指定了一个默认模板（如果可用），构建器将其下载并用于生成代码。

2- 每个模板都附带一个模式（例如，变量列表，例如 vendor、slug 等），构建器使用它来脚手架代码。这些变量有默认值，但除非使用 --defaults 选项来跳过该过程，否则用户将交互式地更改它们的值。

创建模块

php artisan make:addon vendor.module.name

之前的命令基于默认模块模板创建了一个模块。下载的模块模板将被缓存到 storage/streams/default/builder/default-module。

注意：根据Pyro 3默认的make:addon命令行为，将不会生成字段迁移文件。构建器扩展为每个流迁移生成一个单独的字段迁移文件。

制作主题

有两种模板可以生成主题插件，一个是admin，另一个是前端。

php artisan make:addon vendor.theme.name --force --admin

使用--force选项强制扩展下载模板的新副本，使用--admin创建admin主题。省略--admin选项以创建前端主题。

创建插件

之前的make:addon使用假设在创建插件时要使用的模板（如默认模块，pyrocms-theme等）。可以通过提供可选的模板名称来更改此行为，如下所示default-module。

php artisan make:addon websemantics.module.name default-module --defaults

使用defaults选项禁用用户交互模式并强制使用模板默认值。此命令还支持--shared和--migrate选项。

制作模板

模板就像一个食谱，扩展程序使用它来为插件类型或任何软件包构建代码。

php artisan make:addon websemantics.module.name --template

之前的命令将创建指定插件类型的模板，使用defaults，并为模板模式提供默认值vendor和slug。有关模板及其如何在本地上使用的更多详细信息，请参阅template-template文档。

列出模板

此命令将列出来自注册表的所有可用插件模板。

php artisan builder:list

结果：

 ____   __ __  ____  _     ___      ___  ____
|    \ |  |  ||    || |   |   \    /  _||    \
| ()  )|  |  | |  | | |\\\\    \  /  |_ | ()  )
|     ||  |  | |  | |  ( oo) () ||    _||    /
| ()  ||  :  | |  | |   (_)     ||   |_ |    \
|_____| \__,_||____||____||_____||_____||__|\_|
Addons scaffolder for maximum coding pleasure

Builder Commands:
- make:addon Create an addon from a template if avilable
- builder:list List available templates from the registry
- builder:clear Clear cache and locally stored templates

Retrieving a list of available templates
+-------------------+-----------------------------------------------------------------------+---+
| Name              | Description                                                           | ★ |
+-------------------+-----------------------------------------------------------------------+---+
| default-module    | The default module template for Pyro Builder                          | 2 |
| default-skin      | The default skin template for PyroCMS Plus Theme                      | 0 |
| pyrocms-theme     | A customizable release of the official PyroCMS admin theme            | 2 |
| starter-theme     | A customizable release of PyroCMS started theme                       | 4 |
| template-template | The default Pyro Builder template for building Pyro Builder templates | 3 |
+-------------------+-----------------------------------------------------------------------+---+

注意每个模板只有一个星号！ :/ 您可以通过在这些仓库这里点赞来更改它 :)。

清除缓存

要清除构建器缓存并删除所有本地下载的模板，请运行以下命令：

php artisan builder:clear

制作流

构建器引入了新的能力到make:stream命令，例如，指定流属性和字段。

使用Auto-pyro中提供的示例来创建todo模块，以下将创建一个Task流及其所有分配。

php make:stream 'task:tc(name),name,description:t(anomaly.field_type.textarea),completed:t(anomaly.field_type.boolean)' websemantics.module.todo

除了指定流的slug之外，现在make:stream命令还接受一个逗号分隔的字段列表，跟在流slug和属性之后。

以下是可用于流和字段的完整选项列表。如果适用，则选项值提供在括号内（如上面的示例所示），

Inheritable列表示如果其某个字段设置为true，流将继承哪些属性。例如，

# First, generate the module
php artisan make:addon vendor.module.name

# Then generate the stream migration files
php artisan make:stream 'comment:title_column(name),name:trans' vendor.module.name

# This can also be expressed as
php artisan make:stream 'comment:title_column(name),name:translatable(true)' vendor.module.name

# Or as,
php artisan make:stream 'comment:title_column(name):translatable(true),name:type(anomaly.field_type.text):translatable(true)' vendor.module.name

这将生成以下流迁移，

  protected $stream = [
			'slug'                        => 'comment',
			'title_column'                => 'name',
			'translatable'                => true
	];

  protected $assignments = [
			'name'                          => [
					'translatable'              => true
			]
	];

如果字段的type属性未设置，则构建器扩展将假设默认值为anomaly.field_type.text。

环境变量

此处列出了扩展程序使用的所有环境变量。

配置文件位于，./resources/config/config.php。可以在项目的.env文件中覆盖默认行为。

流实体

除了从构建器模板中生成脚手架插件外，构建器还提供从迁移中生成流实体的功能。实体是对象类型的表示，可能与流相对应。例如，人、公司或动物都可以通过流和实体来表示。

为实体生成的代码包括实体模型、仓库、插件、种子、合约、表构建器和表单构建器。

请阅读以下部分以更好地理解此过程。

构建博客

此示例的源代码可在此处找到。目标是构建一个需要最少努力和经验的模块，以了解构建器扩展的工作方式。

创建并安装一个新的PyroCMS项目，并将其命名为blogger。

# first, create a fresh pyro project and change folder,
composer create-project pyrocms/pyrocms --prefer-dist blogger
cd blogger

# install from the command line,
php artisan install

安装构建器扩展。

composer require websemantics/builder-extension
php artisan extension:install websemantics.extension.builder

创建一个新模块，blog。

php artisan make:addon websemantics.module.blog

创建posts流及其字段。

php artisan make:stream 'posts:tc(title),title:r:u,content:r' websemantics.module.blog

结果。

    protected $stream = [
        'slug'         => 'posts',
        'title_column' => 'title'
    ];

    protected $assignments = [
        'title'        => [
            'required' => true,
            'unique'   => true
        ],
        'content'     => [
            'required' => true,
        ]
    ];

这还将为该实体生成一个种子模板（见下文）。

将种子数据添加到，blog/addons/default/websemantics/blog-module/resources/seeders/post.php（单文件名）。

  ['title' => 'Laravel', 'content' => 'PHP framework'],
  ['title' => 'PyroCMS', 'content' => 'PHP CMS']

内容必须是一系列条目值，没有<?php。当代码（重新）生成时，这将被添加到实体种子类中。此过程将在不久的将来通过更好的代码解析得到增强。

通过安装/重新安装模块来应用更改。

php artisan module:reinstall websemantics.module.blog

检查管理员面板以查看新模块的效果，url: admin/blog/posts。

注册表

目标是收集可重复使用的Pyro 3插件模板，可以从命令行生成，类似于vue-cli提供的内容。

要查看Builder扩展提供的完整列表，请查看PyroCMS Templates或使用builder:list artisan命令。

开发

一旦生成了插件代码，创建了每个流实体的文件并且它们与Pyro正确工作，您可能想要单独修改和开发这些类，添加自定义代码。

该扩展提供了配置选项，可以使您的任务更容易，例如，列出在重新安装模块并重新生成实体代码时意外覆盖的文件。

另一个例子，如果您已编辑了blog-module/src/Blog/Post/PostModel.php，请确保在构建器配置文件blog-module/resources/config/builder.php中列出该文件，以便扩展在它们存在的情况下避免覆盖这些文件。

以下是一个示例。

  'avoid_overwrite' => [
    'Model.php',
    'Repository.php',
    'TableColumns.php'
  ],

请注意，仅使用文件名的最后一部分（省略了实体名称）来确保这可以应用于同类型所有生成的实体。

配置

Builder扩展提供许多配置选项，可微调和增强您的开发体验，这些选项可在blog-module/resources/config/builder.php中找到。

添加支持的命名空间列表。

  'namespaces' => [
    'blog' => [],
    'discussion' => []
  ]

这指示构建器扩展您的模块支持的流namespaces。根据需要将命名空间添加到该列表中。

将实体代码分组在命名空间文件夹下。

当为实体生成代码时，构建器扩展默认将其保存到src/{namespace}。当您的模块处理来自不同命名空间的流时，这很有用。

要更改此行为并将存储在模块src/文件夹中，将group选项设置为false。

  'group' => true,

要成功安装后进行种子，请设置builder.php中的seed选项。

  'seed' => true

根据需要使用true / false值打开和关闭。

要生成字段和流权限，请将 permissions 设置为 true。

  'permissions' => true

要生成网站地图，请设置模块主流的 stream_slug，例如 pages 流。

	'sitemap' => [ 'stream_slug' => 'pages',
                 'url_method' => '->getPath()',
                 'entries_method' => '->accessible()->visible()',
                 'priority' => 0.5,
                 'frequency' => 'monthly',
                 'images' => '[]',
                 'title' => 'null'
               ],

url_method 用于检索资源路径，而 entries_method 应返回流条目的筛选集合。

指定要包含在生成的类中的项目 docblock。

'docblock' =>
' * @link      http://yourcompany.com
 * @author    name, <name@email.com>'

更多设置请参阅 builder.php 文件。

内部工作原理

安装后，此扩展主要监听三种事件类型：StreamWasCreated、AssignmentWasCreated 和 ModuleWasInstalled。

要为当前模块启用此扩展，请创建一个位于 resources/config/builder.php 的配置文件，并列出扩展需要生成代码的命名空间。您可以为多个命名空间监听/生成代码。

    'namespaces' => ['blogger', 'navigation', 'etc']

以下是一个来自 builder 配置文件的示例，该配置文件取自 Boxed 示例模块的 github 仓库。

完成后，创建您的流迁移文件，如常。当扩展接收到上述列出的事件时，它将启动：

对于 StreamWasCreated 事件，扩展将从位于 builder-extension/resources/assets/entity/code 的模板生成流的实体文件夹。实体文件夹映射如下

BlogEntity
  |
  +-- Contract
  |      |
  |      +--- BlogInterface.php
  |      |
  |      +--- BlogRepositoryInterface.php
  |
  |
  +-- Form
  |    |
  |    +--- BlogFormBuilder.php
  |
  |
  +-- Table
  |     |
  |     +--- BlogTableBuilder.php
  |     |
  |     +--- BlogTableColumns.php
  |
  |
  +---- BlogModule.php
  |
  +---- BlogRepository.php
  |
  +---- BlogSeeder.php
  |
  +---- BlogPlugin.php

默认情况下，此文件夹结构将生成在 src 的子文件夹中。子文件夹的名称是创建的流的 命名空间，如上所述。

然后，扩展将为每个实体在 blog-module/src/Http/Controller/Admin/BlogController.php 生成一个控制器，并修改 Module、ServiceProvider、Seeder 类和语言文件，以设置实体与模块的正确工作方式。

对于 AssignmentWasCreated 事件，扩展将修改两个文件 BlogTableColumns.php 和 BlogFormBuilder.php，并为每个流分配添加一个 field slug。
对于 ModuleWasInstalled 事件，这将向模块和服务提供者添加 routes 和 sections。如果根据构建器配置文件进行了相应设置，它还将对模块进行播种。

屏幕录像

要生成屏幕录像，请按照以下步骤操作：

安装 Asciinema 和 Asciinema 2 Gif

brew install asciinema
brew install asciinema2gif

录制屏幕录像并将其转换为 gif 图像。

asciinema rec -y -t "title"
asciinema2gif --size small --speed 3 https://asciinema.org/api/asciicasts/{{id}}

asciinema 命令将生成指向录制的 URL，例如，https://asciinema.org/a/e32g9nqayq1dqb9txd063ez8m。将提供的 URL 中的 {{id}} 替换为 asciinema URL 中的唯一 ID，e32g9nqayq1dqb9txd063ez8m。有关有关有效 URL 格式的更多详细信息，请参阅文档。

将当前目录中生成的文件 asciicast.gif 复制到所需位置。

支持

需要帮助或有问题？请在 StackOverflow 上发帖提问。

请勿使用问题跟踪器来寻求支持/提问。

贡献

最后，我们非常乐意接受对项目的外部贡献，形式为反馈、错误报告，甚至更好的是拉取请求 :)

资源

Auto Pyro，一个 PyroCMS 部署工具，用于更快地获得开发体验。
Template Template，用于构建 Pyro Builder 模板的默认 Pyro Builder 模板。
注册表，Pyro Builder 可用模板的列表。
出色的 PyroCMS，一个精心挑选的 PyroCMS 插件和资源列表。
PyroCMS 快捷指南，PyroCMS 3 的命令和功能列表。
PyroCMS，一个易于使用、主题化和开发的 MVC PHP 内容管理系统。它被全球的各个规模的个人和组织使用。

许可证

MIT 许可证版权（c）Web Semantics，Inc.

websemantics / builder-extension

维护者

详细信息

README

动机

安装

入门

创建插件

创建模块

制作主题

创建插件

制作模板

列出模板

清除缓存

制作流

环境变量

流实体

构建博客

注册表

开发

配置

内部工作原理

屏幕录像

支持

贡献

资源

许可证