README

ATK 框架的代码生成工具

这是什么？

atk-builder 是 ATK 框架（见 https://github.com/Sintattica/atk ）的代码生成工具。

安装

atk-builder 需要 php-xml 扩展，此扩展在 Ubuntu 中不会自动安装，因此请在出现错误前执行

sudo apt-get install php7.0-xml

或者遵循您操作系统的相应程序。安装所需的扩展后，您可以使用以下命令创建一个新的项目：

composer create-project sintattica/atk-skeleton myproject

这将创建一个新的空 atk 项目，现在我们需要通过以下命令使用 atk-builder 代码生成器：

cd myproject
composer require sanotto/atk-builder

然后使用以下命令运行 composer update：

composer update

一旦所有软件组件都已更新，在项目目录外部，使用以下命令初始化应用程序：

./myproject/vendor/bin/atk-builder inzapp myproject --db-name=myproject --db-user=youruser --db-passwd=yourdbpass

应用程序初始化后，您可以使用以下命令启动本地 Web 服务器以提供项目服务：

cd myproject
php -S localhost:8080 -t web

现在您可以将浏览器指向 http:\localhost:8080 并使用用户 administrator 密码 demo 进入应用程序。登录后，请运行设置选项以创建所需的数据库对象。

它是如何工作的？

atk-builder 的理念是用最少的代码来创建一个完全功能性的 ATK 应用程序。一个 ATK 应用程序是围绕模块、节点和属性构建的，您通常在模块文件夹内创建一个文件夹，并在该文件夹中填充从 Node.class 派生的类，该节点将对应于一个数据库表。在节点类中，您声明表并为表中的每一列添加一个属性，每次更改表结构时，您都必须修复节点类以反映更改，虽然这个过程很简单，但很耗时。Atk-builder 允许您避免大量工作，Atk-builder 允许您声明一个名为 DefFile 的简单文本文件，该文件包含有关包含在 ATK 应用程序中的模块、节点和属性的声明。解析此 DefFile 后，atk-builder 将

创建或删除所需的表。
向表中添加或删除所需的列。
为模块类/类和/或节点类/类编写或重新编写所需的代码。

一个简单的 DefFile 看起来像这样

appnme:myapp
db:myappdb:root:pass

module:payroll
	node:employees
		name
		date_of_birth
		salary_ammount
		notes

它定义了应用程序名称（myapp）、数据库名称（myappdb）、数据库的用户名和密码（root 和 pass），它定义了一个包含节点（employees）的模块（payroll），该节点具有多个属性（name、date_of_birth、salary_ammount 和 notes）

在没有任何参数的情况下运行 atk-builder 将在当前目录中查找名为 DefFile 的文件，使用前面的定义运行工具将

如果不存在，则创建 payroll_employee 表。
如果表存在，则会添加或删除相应的列，以便调整表以符合定义。
将创建模块文件夹。
将创建必要的模块类。
将创建必要的节点类。

模块和节点类成对创建，为员工创建的节点类将创建两个源文件，一个名为Employees_base.php，另一个名为Employees.php，Employee继承自Employee_base。每次运行RUNGEN命令（RUNGEN是默认命令，如果您不带任何参数运行/vendor/bin/atk-builder，则将运行/vendor/bin/atk-builder rungen），Employee_base将被Atk-builder覆盖，但Employee.php只创建一次，Employee.php是您表达验证和业务规则的地方。每当属性列表发生变化时，都会重写基类，使用它们的名称推断属性/列的类型，因此date_of_birth将导致名为date_of_birth的列，其类型为DATE，并且有一个DateAttribute类型的属性。不仅类型根据名称推断，标志也根据名称推断，名称列将具有Attribute::AF_SEARCH标志，因为搜索名称是一个明显的要求，它还将具有Attribute::AF_OBLIGATORY标志，因为显然名称总是必需的。atk-builder将尽可能地根据您的DefFile推断，但您可以微调代码生成，例如

appnme:myapp
db:myappdb:root:pass

module:payroll
	node:employees
		name:Employe Name:Attribute:AF_OBLIGATORY, 30
		date_of_birth
		salary_ammount
		notes

修改的行

name:Employe Name:Attribute:AF_OBLIGATORY, 30

表示表单中名称列的标签将是员工名称，它将渲染为宽度为30个字符的简单属性，并将设置AF_OBLIGATORY标志。

如何编写DefFile？

DefFile的完整语法如下

appnme:myapp
db:myappdb:root:pass
module:payroll
	node:employees:[label]:[actions]:[node_flags]:[show_in_menu]
		name:[label]:[attribute_type]:[attribute_flags]:[tab]

方括号内的项是可选的，如果省略，将根据上下文推断适当的值。以下是对参数的简要讨论

label：如果省略，则将Module/Node/Attribute的名称用作标签，用于菜单和/或表单标签。
actions：这些是注册的节点操作，如果省略，则使用标准操作（admin、add、update、view和delete），如果您需要非标准操作，则需要声明所有标准操作（例如，如果您需要print_order操作，除了标准操作外，还必须声明admin、add、update、view、print_order）
node_flags：您希望为此节点设置的节点标志（见vendor/sintattica/atk/src/Node.class）
show_in_menu：如果此节点应在菜单中显示，则在此处使用false，用于主从细节设置中的详细节点。
attribute_type：属性的属性类型，如果为空，则Atk-Builder将推断类型。
attribute_flags：属性的标志，如果为空，Atk-Builder将根据属性名称推断适当的标志。
tab：如果提供，则属性将在参数中指定的标签中显示，如果为空，则属性将放入主标签中。

到目前为止，一切都很好...那么下一步该做什么？

在您使用

composer create-project sintattica/atk-skeleton MyApp

通过

cd MyApp

将sanotto/atk-builder添加到您的项目需求中

composer require sanotto/atk-builder
composer update
composer dumpautoload

更新完成后，您需要使用以下命令初始化atk-builder应用程序

vendor/bin/atk-builder inzapp --db-user=user --db-passwd=password

初始化将

重写配置文件。
在MyApp/src/Modules中添加一个Setup模块。
编写一个标准DefFile，包含安全模块的定义（它将替换atk-skeleton提供的安全模块）。现在您可以开始工作了，编辑提供的DefFile，并在其中添加一些模块、节点和属性定义，然后运行。

/vendor/bin/atk-builder

不带参数，将触发rungen命令，更新一切，包括模块、节点和表格，然后您再次编辑DefFile，添加一些模块、节点或属性，或删除它们，然后再次运行生成。在此期间，您可以编辑非基本类以添加验证和业务逻辑。使用atk-builder的常见开发会话如下：

composer create-project sintattica/atk-skeleton MyApp
cd MyApp
composer require sanotto/atk-builder
composer update
composer dumpautoload
vendor/bin/atk-builder inzapp --db-user=user --db-passwd=password
php -S localhost:8080 -t web  
# Open a Web Browser Log in with user administrator password demo (The provided defaults) and run setup to install/change the database
vim DefFile //Add some defs, create new modules and nodes into the DefFile
/vendor/bin/atk-builder
php -s 0.0.0.0:8000 -t web //Check them out
# Open a Web Browser Log in and test the new modules/nodes
vim DefFile //Add some more, update old defs
/vendor/bin/atk-builder
php -s 0.0.0.0:8000 -t web //Check them out
# Open a Web Browser Log in and test the new modules/nodes
/vendor/bin/atk-builder
php -s 0.0.0.0:8000 -t web //Check them out
# Open a Web Browser Log in and test the new modules/nodes

.
.
.

清洗，冲洗，重复，直到您的应用程序足够好，可以投入使用。

DefFile组织

当多个人需要在一个项目中工作时，他们将并发地编辑DefFile，当尝试提交更改到DefFile时，将创建一个“合并问题”，因为每个人都必须将其副本与第一个进入仓库的副本进行Diff。为了避免（或最小化）上述问题，可以将DefFile分成几个部分，这些部分可以“包含”在“主要”DefFile中。include标签为您提供了将DefFile分割成多个文件的能力，即：

appnme:myapp
db:myappdb:root:pass

include:Module1DefFile
include:Module2DefFile
include:Module3DefFile

包含的文件Module1DefFile、Module2DefFile和Module3DefFile必须位于主DefFile的同一目录中，每个文件将包含一个模块定义（或更多，这取决于您）包含的DefFile将按原样搜索，即：

include:Module1DefFile

将搜索名为Module1DefFile的文件

include:Module1DefFile.txt

将搜索名为Module1DefFile.txt的文件，是否使用扩展名取决于您。

将DefFile分割成模块（或您认为满意的任何其他组织单元）将有助于团队合作。

关于config/atk.php的注意事项

atk-builder重新编写模块配置条目。为了保留您对该文件的修改，请在标记////end-of-atk-builder-automatic-list之后添加它们。在modules =>[和////end-of-atk-builder-automatic-list之间的所有条目将被重写。在////end-of-atk-builder-automatic-list和]之间的所有条目将被保留。

sanotto / atk-builder

维护者

详细信息