README

这是一个小型PHP/Composer包（旨在供WordPress插件/主题开发者使用），它提供了一个简单的面向对象的API，用于在WordPress文章上注册“虚拟字段”（适用于内置和自定义文章类型）。

安装

使用Composer在项目根目录中要求此包。

composer require cloak-labs/wp-virtual-fields

什么是虚拟字段？

术语“虚拟字段”用于描述在运行时动态填充的字段——它不存储在数据库中。

当您需要访问或操作不需要存储在数据库中的数据时，虚拟字段是最佳选择。这是一个极其有用的功能，具有无数的可能性。以下是一些常见的用例

• 动态连接用户名和姓氏的全名字段
• 动态标题字段，将几个文本字段的值组合起来
• 用户计数字段，对用户文章类型执行获取请求并返回用户总数
• 字段读取其他数字字段的值，进行计算并返回输出
• 引用字段，从另一个文章获取并返回数据

为什么使用此包？

WordPress没有单个过滤器可以钩入以修改所有WP_Post对象，无论它们是从哪个上下文中获取的。因此，如果您想在获取文章对象时始终包含虚拟字段，无论是通过核心函数还是REST API，您将不得不处理多个核心过滤器/函数（每个字段一个）——您将陷入寻找正确过滤器钩子的兔子洞中，重复自己，或最终编写自己对这个包的实现。我们为您完成了这项工作，提供了一个简单、可重用和可维护的抽象，覆盖了所有丑陋的东西。

在Cloak Labs，我们发现对这种抽象的需求特别适用于无头WordPress项目；如果您还没有这样做，请查看我们的全栈无头WordPress框架CloakWP。

它的工作原理

该抽象负责将这些字段添加到由核心WP函数（如get_posts和WP_Query）返回的Post对象以及REST API响应（包括修订端点）中。

以下将两个虚拟字段pathname和featured_image添加到所有文章、页面和 testimonials自定义文章类型中

register_virtual_fields(['post', 'page', 'testimonial'], [
  VirtualField::make('pathname')
    ->value(fn ($post) => parse_url(get_permalink($post->ID), PHP_URL_PATH),
  VirtualField::make('featured_image')
    ->value(function ($post) {
      $image_id = get_post_thumbnail_id($post->ID);
      $sizes = ['medium', 'large', 'full'];
      $result = [];

      foreach ($sizes as $size) {
        $img = wp_get_attachment_image_src($image_id, $size);
        $url = is_array($img) ? $img['0'] : false;
        $result[$size] = $url;
      }

      return $result;
    })
]);

有了以上内容，每次您通过核心WP函数或通过REST API获取文章/页面/testimonial时，这些虚拟字段都会出现在返回的Post对象中，如下所示

[ // WP_Post object
  ...
  'pathname' => '/blog/post-xyz/',
  'featured_image' => [
    'medium' => 'https://example.com/wp-content/uploads/2023/10/example-img-300x225.jpg',
    'large' => 'https://example.com/wp-content/uploads/2023/10/example-img-1024x768.jpg',
    'full' => 'https://example.com/wp-content/uploads/2023/10/example-img.jpg',
  ]
  ...
]

VirtualField类的value方法是一个回调，它为每个WP_Post对象运行，您返回的任何内容都将分配给该字段。

您可以通过以下方式从特定上下文的post对象响应中排除虚拟字段

register_virtual_fields(['post', 'page'], [
  VirtualField::make('pathname')
    ->value(fn ($post) => parse_url(get_permalink($post->ID), PHP_URL_PATH)
    ->excludeFrom(['rest']) // exclude from REST API
]);

将字符串数组传递给excludeFrom方法，包括以下值之一

• rest —— 从父REST API响应中排除
• rest_revisions —— 从修订REST API响应中排除
• core —— 从核心WP函数响应中排除（即get_posts和WP_Query）

如果例如你有一个特别昂贵的 value 获取函数，而你只通过 REST API 使用该字段，在这种情况下，使用 excludeFrom(['core']) 将有助于提高整体性能。