README

目录

• 1   介绍
  • 1.1   许可
  • 1.2   致谢
• 2   使用方法
  • 2.1   即时与计划
    • 2.1.1   即时
    • 2.1.2   计划
  • 2.2   运行时选项
  • 2.3   导入中断
    • 2.3.1   从管理界面
    • 2.3.2   从命令行界面
• 3   命令行脚本
• 4   性能设置
  • 4.1   视图缓存
  • 4.2   对象索引
  • 4.3   内容对象更新
    • 4.3.1   提供特定差异处理器的数据类型
• 5   处理程序开发
  • 5.1   简化内容 API
    • 5.1.1   选项
      • 5.1.1.1   SQLIContentOptions
      • 5.1.1.2   SQLIContentPublishOptions
  • 5.2   源处理程序
• 6   差异处理程序开发

1   介绍

SQLIImport 是一个允许在 eZ Publish 中导入外部内容的扩展。它提供了一个内容操作框架和一个简单的接口用于开发导入处理程序，因此作为管理界面的 GUI 来管理您的导入。导入处理程序是您需要开发的类，以便处理外部数据（XML、CSV 等）并将其导入 eZ Publish（请参阅处理程序开发部分）。

1.1   许可

此 eZ Publish 扩展以“原样”提供，遵循 GPL v2 许可（请参阅许可）。

1.2   致谢

此扩展由 Jérôme Vieilledent 编写，并由 SQLi 赞助。

Oracle 适配由 Simone Tellini 完成。

2   使用方法

您可以通过管理界面管理您的导入。安装 SQLIImport 后，在左侧菜单中会出现一个新的 导入管理 选项卡（您需要访问 sqliimport 模块或只是管理员才能从 eZ Publish 4.3 中看到它）。点击它以开始管理您的导入

导入列表

2.1   即时与计划

有两种类型的导入

• 即时
• 计划

每个导入都存储在数据库中，作为挂起状态，等待 cronjob 处理。挂起导入可以在 cronjob 处理之前取消。

2.1.1   即时

即时导入是 单次 的，这意味着它们不会重复，与计划导入相反。要添加即时导入，请点击左侧菜单中的 请求新的即时导入。选择您的导入处理程序，并最终添加选项（请参阅下面的运行时选项部分）。

2.1.2   计划

计划导入将在选择的 开始日期 启动。它们可以是单次（频率=无）或重复的。您可以为计划导入添加标签并停用它

添加计划导入表单

要添加计划导入，请通过点击左侧菜单中的链接转到 计划导入，然后点击 添加计划导入。选择您的导入处理程序，并最终添加选项（请参阅下面的运行时选项部分）。

2.2   运行时选项

如果您的导入处理程序支持 运行时选项（见 处理程序开发 部分），您可以从管理员界面添加它们。您每行只能添加一个选项，格式为 optionName=optionValue。选项将在运行时（在处理程序构造函数中）传递给导入处理程序。

2.3   导入中断

正在运行的导入可以从管理员界面或从命令行安全中断。

2.3.1   从管理界面

从导入列表中，您可以通过点击导入的 中断 链接来中断正在运行的导入。请注意，您需要具有对当前导入处理程序的 manageimports 策略功能的访问权限。

2.3.2   从命令行界面

从版本 1.2.0 开始，SQLI Import 会捕获 SIGTERM 和 SIGINT 信号。这是由于 PCNTL 扩展（在 Windows 上无法使用）。您因此可以使用 kill 命令安全中断正在运行的导入

kill -2 <import_script_pid>
kill -15 <import_script_pid>

请注意，kill -9（SIGKILL）信号无法捕获，因此始终首选使用 SIGTERM（kill -15）或 SIGINT（kill -2）。您还可以通过按下 Ctrl+C 来请求导入中断，这会发送 SIGINT 信号。

3   命令行脚本

SQLIImport 提供了 cronjob 和 常规 命令行脚本来处理导入。cronjob 用于处理从管理员界面添加的导入（立即和计划）。常规 CLI 脚本可以用于触发快速的单次导入，而无需进入管理员界面。

用法： php extension/sqliimport/bin/php/sqlidoimport.php [OPTION]...

选项

4   性能设置

在 sqliimport.ini 配置文件中设置了几个 性能设置。有关更多详细信息，请阅读 INI 文件中的内联注释。

4.1   视图缓存

出于性能原因，默认禁用视图缓存。仅对导入脚本来禁用。通过 sqliimport_cleanup cronjob（在 sqliimport_run 之后启动）清除 ViewCache，导入完成后

4.2   对象索引

与上面的 ViewCaching 相同。将 ObjectIndexing 设置为禁用后，导入将更快。只会激活当前导入脚本中的 site.ini SearchSettings.DelayedIndexing。内容对象将在导入完成后通过 sqliimport_cleanup cronjob 进行索引。

4.3   内容对象更新

如果使用捆绑的内容操作框架，系统将进行比较，以检查是否真的需要创建新的内容对象版本。默认情况下，它比较每个属性内容的字符串表示形式，但差异系统是可扩展的。因此，可以为每个数据类型定义新的差异处理程序。

有关更多信息，请参阅 差异处理程序开发 部分。

4.3.1   提供特定差异处理器的数据类型

• ezimage
• ezbinaryfile

5   处理程序开发

要将外部内容导入到 eZ Publish 并使用 SQLIImport，您需要开发一个处理程序，该处理程序 理解 外部源（无论是什么）并将其映射到您的 eZ Publish 内容结构。

开发导入处理程序相当简单。您只需要创建一个扩展 SQLIImportAbstractHandler 并实现 ISQLIImportHandler 的 PHP 类。您还需要在 sqliimport.ini 的覆盖中声明它，通过创建一个专用部分（请阅读 INI 文件中的内联注释以获取更多详细信息）。

导入处理程序的 UML 图

处理程序方法调用顺序

• __construct() - 您需要在其内调用父构造函数
• initialize() - 调用来初始化您的处理程序的主要方法。在这里，您可以读取您的外部数据源
• getProcessLength() - 获取完成过程所需的迭代次数
• getHandlerName()
• getHandlerIdentifier()
• getNextRow() - 必须返回要处理的下一行或当处理程序完成导入过程时返回 false
• process() - 在由 getNextRow 主导的循环中调用。将 getNextRow 的结果传递到该方法
• getProgressionNotes() - 在循环内调用，在 process() 之后
• cleanup() 在处理程序过程结束时调用的最终方法

提供了一个完整的工作示例（SQLIRSSImportHandler）。检查它以了解机制。

请注意，您在 sqliimport.ini 中的 INI 处理程序块中设置的配置将在您的处理程序中可用，在 $this->handlerConfArray 中。

5.1   简化内容 API

提供了一个框架，无需麻烦即可管理 eZ Publish 内容（请阅读 API 文档中的示例）

<?php
  $cli->notice( 'Creation of a new "comment" object' );
  $options = new SQLIContentOptions( array(
      'class_identifier'      => 'comment',
      'remote_id'             => 'my_ubber_cool_remote_id',
      'language'              => 'fre-FR'
  ) );
  $comment = SQLIContent::create( $options );
  $cli->notice( 'Current version : '.$comment->current_version );
  $comment->fields->subject = 'Mon super sujet';
  $comment->fields->author = 'Moi !';
  $comment->fields->message = 'Le commentaire de la mort';

  $comment->addTranslation( 'eng-US' );
  $comment->fields['eng-US']->subject = 'My great subject';
  $comment->fields['eng-US']->author = 'Batman';
  $comment->fields['eng-US']->message = 'Death comment';

  $comment->addLocation( SQLILocation::fromNodeID( 2 ) );
  $comment->addLocation( SQLILocation::fromNodeID( 43 ) );

  $publisher = SQLIContentPublisher::getInstance();
  $publisher->publish( $comment );

  $cli->notice( 'Current version : '.$comment->current_version );

  // Loop against locations
  foreach( $comment->locations as $nodeID => $location )
  {
      // Regular node attributes are available as virtual properties
      $cli->notice( $nodeID.' => '.$location->path_string.
                    ' ('.$comment->locations[$nodeID]->path_identification_string.')' );
  }

  // Now free memory.
  // unset() on SQLIContent triggers eZContentObject::clearCache()
  // and eZContentObject::resetDataMap()
  unset( $comment );
?>

SQLIContent 框架依赖于内容属性的字符串表示。它使用自 eZ Publish 3.9 以来在内核数据类型中实现的 fromString() / toString() 方法。如果您使用自定义数据类型，请确保它们实现了这些方法以获得更好的结果。如果它们不存在，框架将使用 data_text 代替。

有关内核数据类型的字符串表示的更多信息，请阅读附录中的 fromString.txt。

关于 HTML 内容的说明

有一个简写方法可用于处理 HTML 内容导入。它在 导入处理程序 和导入处理程序之外都可用。

<?php
// Code below is available in an import handler
$content->fields->intro = $this->getRichContent( $myHTMLContent );

// Code below is available everywhere
$content->fields->intro = SQLIContentUtils::getRichContent( $myHTMLContent );
?>

有关更多示例，请检查位于 stubs/ 目录中的脚本。

您还可以查看下面的 UML 图。

SQLIContent 框架的 UML 图

5.1.1   选项

当操作 SQLIContent 框架时，您可以调整几个选项。所有这些选项都打包到对象中，通常传递给构造函数/单例（SQLIContent、SQLIContentPublisher）。

5.1.1.1   SQLIContentOptions

这些选项用于实例化 SQLIContent 对象

• remote_id => 内容的远程ID。使用它来稍后检索/更新您的内容。默认为 NULL。
• section_id => 内容的 SectionID。默认为 0（让 eZ Publish 决定有关树继承）。
• creator_id => 内容的 CreatorID。默认为 false（当前登录用户）。
• language => 内容语言。默认为您的默认语言（cf eZContentObject::defaultLanguage()）。
• class_identifier => 内容的类标识符。默认为 NULL。 必填

5.1.1.2   SQLIContentPublishOptions

这些选项用于实例化 SQLIContentPublisher 对象。由于发布者是单例对象，您可以使用其 setOptions() 方法更改其选项。

• parent_node_id => 已弃用，请使用内容位置代替。为内容定义 ParentNodeID。
• modification_check => 如果为 true，则发布者会在发布前检查是否至少有一个属性已被修改。如果没有，则不发布内容。默认为 true。
• update_null_field => 如果为 true，则即使数据未设置（null），也将更新数据库中的所有属性，并将其设置为 null。默认为 false。

5.2   源处理程序

提供了 2 个源处理程序

• SQLIXMLParser - 捕获解析错误并获取 XML 字符串。将 PHP 错误转换为异常。与 DOM 或 SimpleXML（在 stubs/xml.php 中的示例）一起工作。
• SQLICSVDoc - 一组类，可以像使用 SimpleXML 一样轻松地管理 CSV 结构（在 stubs/csv.php 中的示例）。

CSVDoc 类的 UML 图

6   差异处理程序开发

更新内容时，默认情况下，SQLIContentPublisher 只会发布实际修改的内容。它通过差异处理程序在已存储的内容和新内容之间进行差异比较。

默认提供了 3 个差异处理程序

• SQLIDefaultDiffHandler - 主要比较属性字符串表示
• SQLIImageDiffHandler
• SQLIBinaryFileDiffHandler

您可以通过创建一个实现 ISQLIDiffHandler 接口的类来为您的数据类型开发自己的差异处理程序。只需一个静态方法即可：contentIsModified()。请阅读接口 PHPDoc 以获取更多信息。您还可以检查提供的处理程序的代码以获取示例。