README

jahuty-php

欢迎使用Jahuty API的PHP SDK！

安装

此库需要PHP 7.3+。

它是多平台的，我们努力使其在Windows、Linux和OSX上运行得同样好。

应通过Composer安装。要这样做，请将以下行添加到您的composer.json文件的require部分，并运行composer update

{
   "require": {
       "jahuty/jahuty-php": "^5.4"
   }
}

使用方法

使用您的API密钥实例化库，并使用snippets->render()方法渲染您的代码片段

$jahuty = new \Jahuty\Client('YOUR_API_KEY');

$render = $jahuty->snippets->render(YOUR_SNIPPET_ID);

然后，通过将其转换为string或使用其getContent()方法来输出渲染的内容

$jahuty = new \Jahuty\Client('YOUR_API_KEY');

$render = $jahuty->snippets->render(YOUR_SNIPPET_ID);

echo $render;
echo $render->getContent();

在HTML视图中

<?php
  $jahuty = new \Jahuty\Client('YOUR_API_KEY');
?>
<!doctype html>
<html>
<head>
    <title>Awesome example</title>
</head>
<body>
    <?php echo $jahuty->snippets->render(YOUR_SNIPPET_ID); ?>
</body>

您还可以使用标签通过snippets->allRenders()方法选择一组代码片段

$jahuty = new \Jahuty\Client('YOUR_API_KEY');

$renders = $jahuty->snippets->allRenders('YOUR_TAG');

foreach ($renders as $render) {
  echo $render;
}

内容版本

默认情况下，此库将渲染代码片段的已发布内容。如果您想渲染其最新的预发布内容，您可以在客户端或渲染级别使用prefer_latest配置选项

// Prefer the latest content for all renders.
$jahuty = new \Jahuty\Client('YOUR_API_KEY', ['prefer_latest' => true]);

// Use the default published content for all renders.
$jahuty = new \Jahuty\Client('YOUR_API_KEY');

// And, render the latest content for this one.
$render = $jahuty->snippets->render(YOUR_SNIPPET_ID, ['prefer_latest' => true]);

参数

您可以使用params配置选项将参数传递给渲染

$jahuty = new \Jahuty\Client('YOUR_API_KEY');

$render = $jahuty->snippets->render(YOUR_SNIPPET_ID, [
  'params' => [
    'foo' => 'bar'
  ]
]);

上述参数相当于在您的代码片段中分配以下变量

{% assign foo = "bar" %}

如果您正在渲染一组代码片段，则params键的第一个维度决定了参数的作用域。使用星号键（*）将相同的参数传递给所有代码片段，或使用代码片段ID作为键将参数传递给特定的代码片段。

$jahuty = new \Jahuty\Client('YOUR_API_KEY');

$renders = $jahuty->snippets->allRenders('YOUR_TAG', [
  'params' => [
    '*' => [
      'foo' => 'bar'
    ],
    1 => [
      'baz' => 'qux'
    ]
  ]
]);

两个参数列表将被递归合并，代码片段的参数将具有优先级。在下面的示例中，变量foo将为所有代码片段分配值"bar"，除了代码片段1，其中它将分配值"qux"

$jahuty = new \Jahuty\Client('YOUR_API_KEY');

$renders = $jahuty->snippets->allRenders('YOUR_TAG', [
  'params' => [
    '*' => [
      'foo' => 'bar'
    ],
    1 => [
      'foo' => 'qux'
    ]
  ]
]);

跟踪渲染

您可以使用render()方法中的location配置选项来报告代码片段正在渲染的绝对URL。这有助于您的团队预览更改，并有助于您查找和替换已弃用的代码片段。

$jahuty = new \Jahuty\Client('YOUR_API_KEY');

$render = $jahuty->snippets->render(YOUR_SNIPPET_ID, [
  'location' => 'https://example.com'
]);

注意，位置仅在发送到Jahuty API的请求时才会报告。因此，在某些情况下，位置不会被报告。例如，如果对render()的调用导致缓存命中，则不会发送请求到Jahuty API，并且位置不会被报告。

此配置选项不支持allRenders()方法。

缓存

缓存控制此库从Jahuty API请求内容的频率。

在开发中，由于内容经常更改且流量较低，您可以使用默认的内存存储来即时查看内容更改。
在生产中，由于内容更稳定且流量较高，您可以配置持久缓存以减少网络请求并提高应用程序的响应时间。

内存中的缓存（默认）

默认情况下，Jahuty 使用内存缓存来避免在相同的请求生命周期内多次请求相同的渲染。例如：

$jahuty = new \Jahuty\Client('YOUR_API_KEY');

// This call sends a synchronous API request; caches the result in memory; and,
// returns the resulting render.
$render1 = $jahuty->snippets->render(YOUR_SNIPPET_ID);

// This call skips sending an API request and uses the cached render instead.
$render2 = $jahuty->snippets->render(YOUR_SNIPPET_ID);

但是，内存缓存只持续到原始请求的持续时间。在请求生命周期的末尾，缓存将被丢弃。为了在请求之间存储渲染，您需要一个持久缓存。

持久缓存

持久缓存允许渲染跨多个请求进行缓存。这减少了向 Jahuty API 的同步网络请求次数，并提高了您应用程序的响应时间。

要配置持久缓存，请通过 cache 配置选项将 PSR-16 CacheInterface 实现传递给客户端

$jahuty = new \Jahuty\Client('YOUR_API_KEY', ['cache' => CACHE_INSTANCE]);

您选择的持久缓存实现和配置取决于您自己。有许多库可用，大多数框架都提供了自己的实现。任何 PSR-16 兼容的实现都可以。

过期

有三种方法可以配置渲染的生存时间（TTL），即存储和认为它过时之间的时间。从优先级最低到最高，方法如下：

配置您的缓存实现，
配置此库的默认 TTL，
配置渲染的 TTL。

配置您的缓存实现

您通常可以使用默认 TTL 配置您的缓存实现。如果没有配置其他 TTL，则此库将回退到缓存实现的默认 TTL。具体如何配置取决于您选择的库。

配置此库的默认 TTL

您可以通过客户端的 ttl 配置选项传递整数秒数或 DateInterval 实例来为此库的所有渲染配置默认 TTL

// Cache all renders for sixty seconds.
$jahuty = new \Jahuty\Client('YOUR_API_KEY', [
  'cache' => $cache,
  'ttl'   => 60
]);

如果设置了此库的默认 TTL，它将优先于缓存实现的默认 TTL。

配置渲染的 TTL

您可以通过传递整数秒数或 DateInterval 实例通过其 ttl 配置选项来配置一个渲染的 TTL

// Use the caching implementation's TTL for all renders.
$jahuty = new \Jahuty\Client('YOUR_API_KEY', ['cache' => $cache]);

// But, cache this render for 60 seconds.
$render = $jahuty->snippets->render(1, [
  'ttl' => 60
]);

如果设置了渲染的 TTL，它将优先于库的默认 TTL 和缓存实现的 TTL。

缓存集合

默认情况下，此库将缓存由 allRenders() 返回的每个渲染

$jahuty = new \Jahuty\Client('YOUR_API_KEY');

// This call sends a network request, caches each render, and returns the
// collection.
$jahuty->snippets->allRenders('YOUR_TAG');

// ... later in your application

// If this snippet exists in the previously rendered collection, the cached
// render will be used.
$render = $jahuty->snippets->render(YOUR_SNIPPET_ID);

这是一个强大的功能。通过使用标签和 allRenders() 方法，您可以使用单个网络请求渲染和缓存整个应用程序的内容。

此外，当 allRenders() 可以在您的请求周期之外定期调用（例如，在后台作业中）时，您可以将您的持久缓存转换为内容存储机制。您可以像您喜欢的频率一样渲染和缓存动态内容，而不会影响您应用程序的响应时间。

禁用缓存

您可以通过传递零（0）或负整数（例如，-1）作为任何上述方法中的 ttl 来禁用缓存，即使是默认的内存缓存。例如：

// Disable all caching
$jahuty1 = new \Jahuty\Client('YOUR_API_KEY', ['ttl' => 0]);

// Disable caching for this render
$jahuty2 = new \Jahuty\Client('YOUR_API_KEY');
$jahuty2->snippets->render(1, ['ttl' => 0]);

错误

如果 Jahuty API 返回任何除 2xx 之外的状态码，则会抛出 Jahuty\Exception\Error

try {
  $jahuty = new \Jahuty\Client('YOUR_API_KEY');
  $render = $jahuty->snippets->render(YOUR_SNIPPET_ID);
} catch (\Jahuty\Exception\Error $e) {
  // The API returned something besides 2xx status code. Access the problem
  // object for more information.
  $problem = $e->getProblem();

  echo $problem->getStatus();  // returns status code
  echo $problem->getType();    // returns URL to more information
  echo $problem->getDetail();  // returns description of error
}

就是这样！

许可

此库根据 MIT 许可证许可。

贡献

欢迎贡献！如果您发现错误，请打开一个问题或告诉我们。

jahuty / jahuty-php

维护者

详细信息