README

OOPI

OOPI（"面向对象，编程和导入"的首字母缩写）是一个WordPress插件，提供了一个面向对象的库，简化并提供了从外部来源导入数据到WordPress的结构。

安装

使用Composer安装插件

composer require devgeniem/wp-oopi

然后从WordPress仪表板或使用WP-CLI激活插件。

wp plugin activate wp-oopi

它是如何工作的？

插件提供了导入各种数据类型的函数。您可以将导入器视为您的自定义数据源和WordPress数据库之间的集成层。您的任务是手动使用类构造函数或提供的辅助工厂将数据格式化为OOPI对象。如果您的外部数据源可以提供OOPI数据格式的数据，那么您的任务就是将数据解码为PHP对象，然后将其传递给可导入工厂中的create方法。

OOPI通过使用WordPress函数与数据库交互来提供您的数据的保存过程。使用OOPI，您可以得到一个标准化的方式来构建开发者友好的导入器，并且通过提供诸如错误处理和日志记录等重要功能，帮助您编写更好的代码。

导入帖子

导入是一个两步过程。第一步是创建一个可导入对象。如果您正在导入帖子，那么您创建一个\Geniem\Oopi\Importable\PostImportable对象。您可以直接使用类构造函数或使用提供的工厂方法。PostFactory::create方法接受一个唯一的OOPI ID和一个完整的导入器对象作为参数，验证所有字段并将数据转换为严格类型对象。在导入过程中，OOPI ID存储在（帖子）元数据中，并在对象最初创建后用于识别导入的对象。具有相同OOPI ID的后续导入将更新匹配的帖子。

数据设置完成后，实际的导入是通过调用可导入对象的import()方法完成的。此方法使用组合调用导入器的实际导入方法。所有导入器都实现了\Geniem\Oopi\Intefaces\Importer接口，所有可导入对象都应包含一个导入器。import方法将处理将附加到可导入对象的所有数据保存到WordPress数据库中。

可导入对象允许通过为类构造函数传递导入器对象来更改导入过程。如果没有设置，所有可导入对象将获得OOPI在实例化期间提供的默认导入器。

示例用法

请参阅帖子示例。

导入术语

您可以在帖子中导入术语。但如果您需要更控制术语导入，例如防止在错误的术语导入后导入帖子，您可以使用OOPI术语导入过程。

开始使用时，通过直接实例化 \Geniem\Oopi\Importable\TermImportable 创建可导入对象，并使用设置器设置数据，或者使用 \Geniem\Oopi\Factory\Importable\TermFactory::create 方法。设置数据后，通过调用其 import 方法导入术语对象。与后导入类似，这将调用附加的术语导入器的 import 方法。

示例用法

请参阅 术语示例。

导入附件

附件可以与文章导入对象一起导入，但如果需要，您也可以在专用过程中导入附件。导入附件的过程与文章和术语相同。通过实例化 \Geniem\Oopi\Importable\AttachmentImportable 类或调用 \Geniem\Oopi\Factory\Importable\AttachmentFactory::create 方法创建附件导入对象。设置所有数据后，调用导入对象的 import 方法。这将通过调用附加导入器的 import 方法触发导入过程。

当将数据导入WordPress时，附件可能会出现问题。OOPI试图通过处理从提供的源（src 属性）传输文件来使其尽可能简单，但请注意，从外部源下载和上传文件到WordPress将花费时间。使用OOPI，您可以完全控制导入过程，如果您的服务器配置未正确设置以处理工作负载，则可能会遇到超时。

注意！OOPI目前仅支持图像MIME类型。

自定义导入过程

要自定义术语导入过程，创建自己的导入类，扩展OOPI提供的相应导入器，或者直接实现 \Geniem\Oopi\Interfaces\Importable 接口。例如，要自定义附件导入过程，扩展 \Geniem\Oopi\Importer\AttachmentImporter 并根据需要重写其方法。要在导入对象中重写默认导入器实例，实例化您的自定义导入器并将其传递给导入对象构造函数或工厂。

属性

导入对象具有在导入过程中 保存 的属性。每个属性类应有一个相应的保存器来处理数据库交互。例如，文章元数据是可以附加到文章导入对象的属性。当文章导入时，文章元数据属性使用WordPress文章元数据函数通过文章元数据保存器保存。

请在此处查看所有可用属性的列表 这里。

语言属性

OOPI使用 \Geniem\Oopi\Attribute\Language 属性支持本地化。目前，OOPI为 Polylang 提供语言保存器，并能够本地化文章、术语和附件。

语言属性的性质包括

• importable (必需) - 相关导入对象。
• locale (必需) - 区域字符串 (例如 'en')。
• main_oopi_id (可选) - 主要语言的导入对象OOPI ID。它用于映射翻译。
• saver (可选) - 语言保存器。

要自动将导入对象映射为彼此的翻译，为主语言以外的导入对象设置 main_oopi_id。例如，如果您的WordPress网站的主要语言是英语，则为主语言英语导入对象的OOPI ID设置为翻译的主要OOPI ID。始终首先导入主要语言，以便OOPI能够为主语言映射主要对象。

AcfField属性

OOPI 支持使用 \Geniem\Oopi\Attribute\AcfField 属性导入 高级自定义字段 字段数据。\Geniem\Oopi\Attribute\Saver\AcfFieldSaver 控制保存过程，可以处理文章和术语字段。请注意，字段保存受 ACF 的 update_field 函数 功能限制。

工厂

\Geniem\Oopi\Factory\Importable\PostFactory

::create( $oopi_id, $data )

• $oopi_id (string) (必需) 导入对象的唯一外部标识符。
• $data (array|object) (必需) 包含以下键的数组/对象
  • post (object) (必需) 一个 WP_Post 实例，或者包含 WP_Post 类属性的键和值的数组/对象。
  • attachments (array) (可选) 包含以下内容的附件对象数组
    • oopi_id (string) (必需) 在外部数据源中标识对象的一个唯一 id。
    • src (string) (必需) 从中上传图像到 WordPress 的来源。
    • alt (string) (可选) 图像的 alt 文本。这将保存到文章元数据中。
    • caption (string) (可选) 文件标题文本。
    • description (string) (可选) 文件描述文本。
    • is_thumbnail (bool) (可选) 定义附件是否应设置为文章缩略图。
  • meta (array) (可选) 包含以下内容的数组数组或对象数组
    • key (string) (必需) 元数据键。
    • value (mixed) (必需) 元数据值。
  • terms (array) (可选) 包含以下任一内容的数组
    • (Geniem\Oopi\Importable\TermImportable) OOPI 术语导入。
      • 如果 OOPI 术语导入包含 WP_Term 对象，导入将覆盖现有术语数据。
    • (array|object)
      • oopi_id (string) (必需) 所有术语都必须包含一个 id。
      • term WP_Term|object|array (可选) 包含 WP_Term 对象属性的对象/数组或 WP_Term 对象。如果设置，将从对象映射术语导入的数据。
      • slug (string) (必需) 分类术语 slug。术语 slugs 必须是唯一的，即它们不能在不同语言版本之间冲突。
      • name (string) (必需) 分类术语显示名称。
      • taxonomy (string) (必需) 分类名称，例如 category。
  • acf (array) (可选) 包含以下内容的 Advanced Custom Fields 数据对象数组
    • type (string) (必需) ACF 字段类型 (类型)。
    • key (string) (必需) ACF 字段键。这必须是字段的唯一键。
    • value (mixed) (必需) 与字段类型规范匹配的数据值。
  • language (Geniem\Oopi\Attribute\Language|object|array) (可选) 使用 OOPI 语言对象或原始数据的本地化信息。原始数据将被转换为语言实例。

\Geniem\Oopi\Factory\Importable\TermFactory

参阅： TermFactory。

\Geniem\Oopi\Factory\Importable\AttachmentFactory

参阅： AttachmentFactory。

插件设置

使用 \Geniem\Oopi\Settings\ 类来设置和加载所有插件设置。它使用以下设置，这些设置可以用常量覆盖。

可用设置

• 设置键 id_prefix，常量 OOPI_ID_PREFIX，默认值 'oopi_id_'。
• 设置键 attachment_prefix，常量 OOPI_ATTACHMENT_PREFIX，默认值 'oopi_attachment_'。
• 设置键 log_errors，常量 OOPI_LOG_ERRORS，默认值 false。
• 设置键 transient_key，常量 OOPI_TRANSIENT_KEY，默认值 'oopi_'。
• 设置键 transient_expiration，常量 OOPI_TRANSIENT_EXPIRATION，默认值 HOUR_IN_SECOND。
• 设置键 tmp_folder，常量 OOPI_TMP_FOLDER，默认值 '/tmp/'。用于处理附件。
• 设置键 table_name，常量 OOPI_TABLE_NAME，默认值 geniem_importer_log。
• 设置键 log_status_ok，常量 OOPI_LOG_STATUS_OK，默认值 'OK'。
• 设置键 log_status_fail，常量 OOPI_LOG_STATUS_FAIL，默认值 'FAIL'。
• 设置键 cron_interval_clean_log，常量 OOPI_CRON_INTERVAL_CLEAN_LOG，默认 'daily'。

访问设置

示例用法

$oopi_id_prefix = \Geniem\Oopi\Settings::get( 'id_prefix' );

覆盖设置

要覆盖瞬态过期时间，请在第一次使用设置之前设置以下常量。

define( 'OOPI_TRANSIENT_EXPIRATION', MONTH_IN_SECONDS );

要在导入器中忽略SSL证书验证错误，可以将 OOPI_IGNORE_SSL 定义为 true。

define( 'OOPI_IGNORE_SSL', true );

请参阅 \Geniem\Oopi\Post::insert_attachment_from_url。

日志记录

错误日志

OOPI 使用通用的错误处理。将错误处理程序的实例作为依赖项传递给所有附加到可导入项的实例。如果发生错误，错误处理程序会记录（默认情况下启用了记录）并将错误存储在处理程序实例中。如果在导入过程中出现错误，则会抛出异常供您捕获。

您可以通过覆盖默认错误处理程序来自定义错误处理过程。要这样做，创建一个实现 Geniem\Oopi\Interfaces\ErrorHandler 接口的类，并通过将您的实例传递给工厂或类构造函数来用您的实例覆盖默认处理程序实例。

导入日志

插件在 WordPress 数据库中创建了一个名为 oopi_log 的自定义表。此表包含导入的日志条目（目前仅用于帖子）并包含以下列

• id 日志条目 ID。
• oopi_id 导入对象 ID。
• wp_id 导入对象的 WordPress 帖子 ID。仅在成功运行 save() 时存储。
• import_date_gmt MySQL datetime 格式的导入日期的 GMT 时间戳。
• data 包含所有属性（包括错误）的导入对象数据。
• status 导入状态：OK|FAIL。

回滚

日志提供回滚功能。如果导入失败，导入器会尝试回滚之前的成功导入。如果没有找到状态为 OK 的先前导入，则将导入对象设置为 草稿 状态，以防止前端用户访问格式不正确的帖子。

要禁用回滚功能，请将 OOPI_ROLLBACK_DISABLE 常量设置为 true。

日志清理

插件在插件激活时注册了一个日志清理 cron 作业。该 cron 作业根据状态和导入日期阈值从日志表中删除所有行。状态和阈值都可以通过过滤器 oopi_cron_log_cleaner_statuses 和 oopi_cron_log_cleaner_threshold 进行修改。

默认情况下，cron 作业以 'daily' 间隔运行，可以通过 OOPI_CRON_INTERVAL_CLEAN_LOG 常量进行更改。可以通过将常量定义为 false 来禁用 cron 作业调度。

测试

本地测试

插件代码使用PHPUnit进行测试。可以使用提供的Docker容器和Docker Compose运行本地测试。以下命令将构建容器并启动它。容器的CMD脚本将运行PHPUnit一次，然后设置pywatch来监视./tests目录中的更改。如果发生更改，则重新运行测试。

$ docker compose up

如果您需要调试测试，容器自带Xdebug 3进行逐步调试。您需要使用提供的docker容器作为远程解释器来设置PHPUnit。为此，使用Docker Compose文件中的php服务和PHPUnit可执行文件vendor/bin/phpunit。容器内部可执行文件的全路径是/usr/src/app/vendor/bin/phpunit。

Travis CI

此存储库还包含Travis CI的GitHub集成。所有提交到master分支的代码都将自动由Travis进行测试。

变更日志

CHANGELOG.md

贡献者

• Geniem
• 维尔·希尔特拉
• 蒂米-阿尔图里·马凯拉