README

Falconize 是一款简单而强大的工具，可以帮助您在 PrestaShop 模块开发过程中提升开发体验。

安装

  composer require oksydan/falconize

用法

第1步 - 创建 FalconizeConfiguration

首先，您需要创建一个实现 FalconizeConfigurationInterface 的 FalconizeConfiguration 类。这个类将用于配置 Falconize。示例 FalconizeConfiguration 类

<?php

namespace MyModule\NamespaceName;

use Doctrine\DBAL\Connection;
use Oksydan\Falconize\FalconizeConfigurationInterface;
use Oksydan\Falconize\PrestaShop\Module\PrestaShopModuleInterface;

final class FalconizeConfiguration implements FalconizeConfigurationInterface
{
    protected PrestaShopModuleInterface $module;

    protected Connection $connection;

    protected string $databasePrefix;

    protected string $prestashopVersion;

    public function __construct(
        PrestaShopModuleInterface $module,
        Connection $connection,
        string $databasePrefix,
        string $prestashopVersion
    ) {
        $this->module = $module;
        $this->connection = $connection;
        $this->databasePrefix = $databasePrefix;
        $this->prestashopVersion = $prestashopVersion;
    }

    public function getConnection(): Connection
    {
        return $this->connection;
    }

    public function getModule(): PrestaShopModuleInterface
    {
        return $this->module;
    }

    public function getConfigurationFile(): \SplFileInfo
    {
        // /../../config/configuration.yml is just an example path to configuration file
        return new \SplFileInfo(__DIR__ . '/../../config/configuration.yml');
    }

    public function getDatabasePrefix(): string
    {
        return $this->databasePrefix;
    }

    public function getPrestashopVersion(): string
    {
        return $this->prestashopVersion;
    }
}

第2步 - 创建配置文件

然后，您需要创建配置文件。配置文件是一个 yaml 文件，其中包含您要注册/注销的数据库表和钩子的信息。好的做法是将配置文件放在 /modules/my_module/config 目录中。示例配置文件

database_tables:
  my_table_name:
    columns: 
      - name: id_my_table_name 
        type: integer
        length: 11 
        notnull: true 
        autoincrement: true
      - name: active
        type: boolean
        notnull: true
        default: 0
    primary:
      - id_my_table_name
    indexes:
      - name: my_table_name_active_index
        columns:
          - active

  my_table_name_lang:
    columns:
      - name: id_my_table_name
        type: integer
        length: 11
        notnull: true
      - name: id_lang
        type: integer
        length: 11
        notnull: true
      - name: name
        type: string
        length: 255
        notnull: true
    primary:
      - id_my_table_name
      - id_lang
  constraint_keys:
    - name: my_table_name_lang_constraint_lang
      foreign_table: lang
      update: NO ACTION
      delete: CASCADE
      local_columns:
        - id_lang
      foreign_columns:
        - id_lang

hooks:
  register:
    - name: displayHome
    - name: displayModernHook
      version: '8.0.0'
      compare_operator: '>='
    - name: displayLegacyHook
      version: '8.0.0'
      compare_operator: '<'
  unregister:
    - name: displayMyOldHook

第3步 - 创建 Falconize 实例

然后，您需要创建一个 Falconize 实例，将 FalconizeConfiguration 实例传递给构造函数。您的主要模块类必须实现 Oksydan\Falconize\PrestaShop\Module\PrestaShopModuleInterface

<?php

use Oksydan\Falconize\Falconize;
use MyModule\NamespaceName\FalconizeConfiguration;
use PrestaShop\PrestaShop\Adapter\SymfonyContainer;
use Oksydan\Falconize\PrestaShop\Module\PrestaShopModuleInterface;

class MyModule extends Module implements PrestaShopModuleInterface
{
    protected Falconize $falconize;
    
    public function __construct()
    {
        ...
    }

    private function getFalconize()
    {
        if (!isset($this->falconize)) {
            $falconizeConfiguration = new FalconizeConfiguration(
                $this,
                SymfonyContainer::getInstance()->get('doctrine.dbal.default_connection'),
                _DB_PREFIX_,
                _PS_VERSION_
            );
            $this->falconize = new Falconize($falconizeConfiguration);
        }

        return $this->falconize;
    }
}

第4步 - 使用 Falconize

当完成第3步时，您可以使用 Falconize 来处理您的安装和卸载过程。Falconize 将自动注册/注销钩子并创建/删除数据库表。如果安装/卸载过程中出现错误，Falconize 将抛出异常，并提供有关错误的信息。

<?php

...

class MyModule extends Module implements PrestaShopModuleInterface
{
    ...
    
    public function install()
    {
        return parent::install() &&
               $this->getFalconize()->install();
    }

    public function uninstall()
    {
        return parent::uninstall() &&
               $this->getFalconize()->uninstall();
    }
}

升级过程期间的使用

当您想要升级您的模块时，您可以使用 Falconize 来处理您的升级过程。Falconize 将自动注册/注销钩子并根据您的更新配置文件升级数据库模式。如果您在配置文件中更改列类型、添加新列或删除列、添加索引等，Falconize 将在 Falconize::install() 调用时自动升级您的数据库模式。

<?php

function upgrade_module_1_1_0($module) // 1.1.0 is example version
{
    return $module->getFalconize()->install();
}

配置 yaml 文件

配置 yaml 文件包含两个主要部分：database_tables 和 hooks。

数据库表：database_tables (数组)

database_tables 部分包含您想要创建的数据库表的信息。模式基于 Doctrine DBAL 模式。

表名 (字符串)

表名是 database_tables 部分的键。它必须是唯一的。它只接受字母数字字符和下划线。

示例

database_tables:
  my_table_name:
    ...

重要

表的顺序很重要。它和执行顺序相同。

列：columns (数组)

列部分包含有关表列的信息。它是一个列数组。每个列都必须有 name 和 type 键。其他键是可选的。

示例

database_tables:
  my_table_name:
    columns:
      - name: id_my_table_name
        ...
      - name: active
        ...

列名：name (字符串)

列名是列部分的键。它必须是唯一的。它只接受字母数字字符和下划线。

示例

database_tables:
  my_table_name:
    columns:
      - name: id_my_table_name
        ...

列类型：type (字符串)

列类型是列部分的键。它必须是有效的数据库列类型。您可以在 这里 找到所有可用的类型。

示例

database_tables:
  my_table_name:
    columns:
      - name: id_my_table_name
        type: integer
        ...

列长度 length (整数) - 可选

列长度是列部分的键。它必须是有效的列长度。

示例

database_tables:
  my_table_name:
    columns:
      - name: id_my_table_name
        ...
        length: 11
        ...

列非空：notnull (布尔值) - 可选

列非空是列部分的键。它必须是布尔值。

示例

database_tables:
  my_table_name:
    columns:
      - name: id_my_table_name
        ...
        notnull: true
        ...

列自增：autoincrement (布尔值) - 可选

列自增是列部分的键。它必须是布尔值。

示例

database_tables:
  my_table_name:
    columns:
      - name: id_my_table_name
        ...
        autoincrement: true
        ...

列默认值：default (混合型) - 可选

列默认值是列部分的键。它必须是有效的列默认值。

示例

database_tables:
  my_table_name:
    columns:
      - name: active
        ...
        default: 0
        ...

主键：primary (数组) - 可选

主键部分包含关于主键的信息。它是一个包含列名的数组。

示例

database_tables:
  my_table_name:
    columns:
      - name: id_my_table_name
        ...
    primary:
      - id_my_table_name

索引：indexes (数组) - 可选

索引部分包含关于索引的信息。它是一个索引数组。每个索引都必须有 name 和 columns 键。

索引名称：name (字符串)

索引名称是索引部分的键。它必须是唯一的。它只接受字母数字字符和下划线。

索引列：columns (数组)

索引列是索引部分的键。它必须是一个包含列名的数组。

示例

database_tables:
  my_table_name:
    columns:
      - name: active
        ...
    indexes:
      - name: my_table_name_active_index
        columns:
          - active

约束键：constraint_keys (数组) - 可选

约束键部分包含关于约束键的信息。它是一个约束键数组。每个约束键都必须有 name、foreign_table、update、delete、local_columns 和 foreign_columns 键。

约束键名称：name (字符串)

约束键名称是约束键部分的键。它必须是唯一的。它只接受字母数字字符和下划线。

约束键外键表：foreign_table (字符串)

约束键外键表是约束键部分的键。它必须是有效的表名。

约束键更新：update (字符串)

约束键更新是约束键部分的键。它必须是有效的约束键更新值。您可以在以下值中找到所有可用的值：'NO ACTION'、'CASCADE'、'SET NULL'、'RESTRICT'、'SET DEFAULT'。

约束键删除：delete (字符串)

约束键删除是约束键部分的键。它必须是有效的约束键删除值。您可以在以下值中找到所有可用的值：'NO ACTION'、'CASCADE'、'SET NULL'、'RESTRICT'、'SET DEFAULT'。

约束键本地列：local_columns (数组)

约束键本地列是约束键部分的键。它必须是一个包含列名的数组。

约束键外键列：foreign_columns (数组)

约束键外键列是约束键部分的键。它必须是一个包含列名的数组。

示例

database_tables:
  my_table_name_lang:
    columns:
      - name: id_lang
        ...
    constraint_keys:
      - name: my_table_name_lang_constraint_lang
        foreign_table: lang
        update: NO ACTION
        delete: CASCADE
        local_columns:
          - id_lang
        foreign_columns:
          - id_lang

钩子：hooks (数组)

钩子部分包含您想要注册/注销的钩子的信息。

注册：register (数组)

注册部分包含您想要注册的钩子的信息。它是一个钩子数组。

注销：unregister (数组)

注销部分包含您想要注销的钩子的信息。它是一个钩子数组。

钩子名称：name (字符串)

钩子名称是 register/unregister 部分的键。它必须是有效的钩子名称。

钩子版本 version (字符串) - 可选

钩子版本是 register/unregister 部分的键。它基于比较运算符，是 PrestaShop 版本，从该版本开始注册/注销钩子。

钩子比较运算符 compare_operator (字符串) - 可选

钩子比较运算符是 register/unregister 部分的键。它必须是有效的钩子比较运算符。您可以在以下值中找到所有可用的值：'<'、'>'、'='、'<='、'>='。

示例

hooks:
  register:
    - name: displayHome
    - name: displayModernHook
      version: '8.0.0'
      compare_operator: '>='
    - name: displayLegacyHook
      version: '8.0.0'
      compare_operator: '<'
  unregister:
    - name: displayMyOldHook

拆分配置文件

您可以将配置文件拆分为多个文件。当您的 .yml 文件越来越大时，这可能很有用。

您可以创建多个配置文件，然后将它们导入到主配置文件中。

示例

文件：my_table_name.yml

database_tables:
  my_table_name:
    columns: 
      - name: id_my_table_name 
        type: integer
        length: 11 
        notnull: true 
        autoincrement: true
      - name: active
        type: boolean
        notnull: true
        default: 0
    primary:
      - id_my_table_name
    indexes:
      - name: my_table_name_active_index
        columns:
          - active

文件：my_table_name_lang.yml

my_table_name_lang:
  columns:
    - name: id_my_table_name
      type: integer
      length: 11
      notnull: true
    - name: id_lang
      type: integer
      length: 11
      notnull: true
    - name: name
      type: string
      length: 255
      notnull: true
  primary:
    - id_my_table_name
    - id_lang
constraint_keys:
  - name: my_table_name_lang_constraint_lang
    foreign_table: lang
    update: NO ACTION
    delete: CASCADE
    local_columns:
      - id_lang
    foreign_columns:
      - id_lang

文件：hooks.yml

hooks:
  register:
    - name: displayHome
    - name: displayModernHook
      version: '8.0.0'
      compare_operator: '>='
    - name: displayLegacyHook
      version: '8.0.0'
      compare_operator: '<'
  unregister:
    - name: displayMyOldHook

主配置文件

imports:
  - { resource: 'my_table_name.yml' }
  - { resource: 'my_table_name_lang.yml' }
  - { resource: 'hooks.yml' }

重要

导入顺序很重要。配置文件将以导入的顺序合并。