README

MDL 库是一个 PHP 工具二进制文件，内部使用 @drewlabs/code-generator 包根据在 YAML 或 JSON 语言中编写的文本 UML 定义语言创建项目源代码。

MDL 定义语言

mdl 定义语言是一个快速 OOP 原型设计 工具，通过一个 YAML 或 JSON 配置文件抽象出 UML 设计图形工具，该配置文件由客户端用于生成源代码。以下是一个用 YAML 编写的 mdl 建模语言的基本示例。

name: 'Drewlabs\\MiaccSdk'
path: "/Users/azandrewsidoine/Workspace/azlabs/lib/php/mdl/src"
directories:
  interfaces: "Contracts"
  mixins: "Traits"

mixins:
  -
    name: "BaseTrait"
    methods:
      -
        name: "baseTraitMethod"

  - name: "MyTrait"
    mixins:
      - "Traits\\BaseTrait"
    methods:
      - name: "sayHello"
        comment: "Say Hello to application users" # optional
        returns: "void" # Optional
        modifier: "public" # Optional
        static: false # Optional
        parameters:
          - name: "name"
            type: string
            default: "PHP"
            optional: true
            variadic: false # Optional
            reference: false # Optional

interfaces:
  - name: "LoggerInterface"
    methods: # Optional
      - name: "log"
        comment: "Log to the console or the standard ouput"
        returns: "void"
        modifier: "public"
        parameters:
          - name: "args"
            default: "PHP"
            optional: false
            variadic: true # Optional
            reference: false # Optional
      -
        name: "baseTraitMethod"
  - 
    name: "MyInterface"
    extends: "Contracts\\LoggerInterface"

classes:
  - name: "BaseClass"
    directory: "Core"
    abstract: true
    implements:
      - "Contracts\\LoggerInterface"
      - 'App\\ValueInterface'
  - name: "AbstractClass"
    abstract: true
    extends: "Core\\BaseClass"
  - name: "MyClass"
    final: true
    extends: "AbstractClass"
    constructor: true
    mixins:
      - 
        "Traits\\DatabaseTrait"
    implements:
      - "Contracts\\TestInterface"
    setter: true
    immutable: true
    properties:
      - name: "console"
        comment: "Injected console object"
        type: 'App\\Console' # Optional
        modifier: "protected" # Optional
        readonly: false  # Optional
        # default: null # Optional
        # constant: false # Optional
    methods:
      - name: "__invoke"
        comment: "Used when the class is invoked as function" # Optional
        returns: "array" # Optional
        modifier: "public" # Optional
        static: false # Optional
        throws:
          - "\\RuntimeException"

设计语言由两个主要部分组成

• 项目元数据定义 如其名所示，项目元数据包含有关要生成的组件的项目元数据。以下是必须为特定项目定义的元数据属性列表

  • name：名称 metadata 定义了在哪个 PSR-4 兼容命名空间下生成组件
  • path：此 metadata 定义了从其中生成 OOP 组件路径的基本路径。
  • directories：此 metadata 是 可选的，但有助于 mdl-cli 将 接口 从核心实现中分离出来，并提供 混入 的目录，混入 是 PHP trait 组件。

• OOP 组件定义 OOP 组件由为特定项目生成的实际 类、接口/合同 和 混入/PHP Trait 对象组成。 OOP 组件按以下方式分组

  • classes：包含 PHP 或 UML 类组件
  • mixins：不是 UML 定义语言的一部分，但有助于在开发软件应用程序时实现 DRY 建议。基本上，它们由 PHP traits 组件组成，并在元数据配置中指定的 mixins 目录下生成。
  • interfaces：包含可能实现于给定项目的 接口/合同 列表。

MDL CLI

一旦编写了定义语言，我们使用 mdl-cli 工具来生成我们的项目源代码。从 语言定义 文件生成源代码的语法是

<二进制目录路径>/mdl <语言定义目录路径>/name.yml

对于基于 composer 的项目，假设语言定义文件位于项目根目录下

./vendor/bin/mdl $(pwd)/mdl.yml

命令选项

mdl-cli 命令支持选项，允许开发者更改命令行客户端的行为。

• 设置器

设置器在配置文件中的类级别进行配置。但为了告诉 cli 工具为所有类的属性生成设置器，我们使用 --set 或 --setters 命令行选项。

./vendor/bin/mdl $(pwd)/mdl.yml --set

• 获取器

与 setters 一样，getters 通常在类定义级别进行配置。但我们也可以告诉 cli 工具为生成的代码中的所有类生成获取器类，使用 --get 或 getters 标志。

./vendor/bin/mdl $(pwd)/mdl.yml --get

• 严格规则

PHP 在脚本文件中添加 declare_strict(...) 时表现不同。默认情况下，cli 不将此指令添加到生成的脚本中。要告诉 cli 工具添加所需的指令，我们使用命令行中的 --strict 标志。

./vendor/bin/mdl $(pwd)/mdl.yml --get --strict

版本 0.3.x 的变更

从版本 0.3.x 开始，客户端支持以下标志

• force

添加 force 标志允许用户绕过因配置无效而产生的警告消息。

./vendor/bin/mdl $(pwd)/mdl.yml --strict --force

• reflect & reflection

API 的最新更改允许应用程序用户声明一些类是 jsonnable，这在使用 class::fromJson 实现时使用了 PHP 反射 API。由于使用反射 API 的成本，此行为默认被阻止。

要添加此行为，CLI 支持在运行 CLI 时使用 --reflect 或 --reflection 类。

./vendor/bin/mdl $(pwd)/mdl.yml --strict --reflection

注意 反射可以通过将 reflection 属性设置为 true 或 false 在类级别启用或禁用。

注意 文档仍在开发中，并可能随着 API 的变化而更改。