README

Phikl（发音为 "fickle”）是苹果 PKL 语言的 PHP 绑定。此库使用苹果的官方 PKL CLI 工具，并提供对它的 PHP 接口。

安装

您可以使用 composer 安装此库

composer require alexandre-daubois/phikl

CLI 工具必须安装在您的系统上。您可以手动安装它，并将 PKL_CLI_BIN 环境变量设置为二进制文件的路径，或者使用 pkl 命令的 install 子命令将最新支持的 PKL CLI 工具版本下载到 vendor/bin 目录。

vendor/bin/phikl install

您还可以使用 --location 选项设置下载位置

vendor/bin/phikl install --location=/usr/local/bin

如果您这样做，则必须将 PKL_CLI_BIN 环境变量设置为二进制文件的路径。

用法

⚠️ 如果您计划在生产中使用此工具，强烈建议 缓存 PKL 模块。

使用 CLI 工具

此包提供了一个 CLI 工具来与 PKL CLI 工具交互。您可以使用 phikl 命令与其他事物一起与 PKL CLI 工具交互。

以下是如何使用 phikl 命令的一些示例

# Install the PKL CLI tool
vendor/bin/phikl install

# Update/Force install the last supported PKL CLI tool
vendor/bin/phikl update

# Print current PKL CLI tool version
vendor/bin/phikl version

# Evaluate one or many PKL file
vendor/bin/phikl eval config/simple.pkl config/nested.pkl

在 PHP 中使用 Pkl

使用此库的主要方法是评估 PKL 代码。您可以通过使用 Pkl 类的 evaluate 方法来完成此操作。

使用 PklModule 的基本用法

假设您有以下 PKL 代码

/// config/simple.pkl

name = "Pkl: Configure your Systems in New Ways"
attendants = 100
isInteractive = true
amountLearned = 13.37

您可以像这样评估此代码

use Phikl\Pkl;

$module = Pkl::eval('config/simple.pkl');

// you can then interact with the module
echo $module->get('name'); // Pkl: Configure your Systems in New Ways
echo $module->get('attendants'); // 100
echo $module->get('isInteractive'); // true
echo $module->get('amountLearned'); // 13.37

这也适用于嵌套模块

/// config/nested.pkl

woodPigeon {
    name = "Common wood pigeon"
    diet = "Seeds"
    taxonomy {
        species = "Columba palumbus"
    }
}

use Phikl\Pkl;

$module = Pkl::eval('config/nested.pkl');

// you can then interact with the module
echo $module->get('woodPigeon')->get('name'); // Common wood pigeon
echo $module->get('woodPigeon')->get('diet'); // Seeds
echo $module->get('woodPigeon')->get('taxonomy')->get('species'); // Columba palumbus

转换为其他类型

您可以使用具有表示您数据的类的 cast 方法将值转换为其他类型。以下是一个 PKL 代码示例

myUser {
    id = 1
    name = "John Doe"
    address {
        street = "123 Main St"
        city = "Springfield"
        state = "IL"
        zip = "62701"
    }
}

您可以将此转换为 User 类，如下所示

use Phikl\Pkl;

class User
{
    public int $id;
    public string $name;
    public Address $address;
}

class Address
{
    public string $street;
    public string $city;
    public string $state;
    public string $zip;
}

$module = Pkl::eval('config/user.pkl');
$user = $module->get('myUser')->cast(User::class);

您还可以将 User::class 作为第二个参数传递给 eval 方法。这将自动将模块转换为给定的类。请注意，它返回一个由 PKL 实例名称索引的数组

use Phikl\Pkl;

// ...

$user = Pkl::eval('config/user.pkl', User::class)['myUser'];

PklProperty 属性

您可以使用 PklProperty 属性来指定 PKL 文件中属性的名称。当 PKL 文件中的属性名称与 PHP 类中的属性名称不同时，这很有用。以下是一个 PKL 代码示例

myUser {
    id = 1
    name = "John Doe"
    address {
        street = "123 Main St"
        city = "Springfield"
        state = "IL"
        zip = "62701"
    }
}

您可以定义一个如下的 User 类

use Phikl\PklProperty;

class User
{
    #[PklProperty('id')]
    public int $userId;

    #[PklProperty('name')]
    public string $userName;

    public Address $address;
}

在转换时，PklProperty 属性将用于将 PKL 文件中的属性名称映射到 PHP 类中的属性名称。

缓存

您（应该）可以缓存 PKL 模块以提高性能。这在评估相同的 PKL 文件多次时特别有用。

⚠️ 使用 Phikl 与缓存可以避免执行 PKL CLI 工具来评估模块，并且应该在部署应用程序时进行，以获得更好的性能。

预热缓存

您可以使用 warmup 命令将 PKL 模块默认转储到缓存文件。然后 Phikl 将在评估 PKL 文件时自动使用缓存文件。如果缓存中找不到 PKL 文件，Phikl 将立即评估 PKL 文件。

Phikl 将遍历您的项目中的所有 .pkl 文件并将它们转储到缓存文件。

以下是使用 warmup 命令的示例

vendor/bin/phikl warmup

# you can also specify the file if you want to use a custom location
# don't forget to set the `PHIKL_CACHE_FILE` environment variable
vendor/bin/phikl warmup --cache-file=cache/pkl.cache

如果您需要验证缓存文件，可以通过使用 validate-cache 命令来实现。

vendor/bin/phikl validate-cache

# optionally, set the `PHIKL_CACHE_FILE` environment variable
# or use the `--cache-file` option
vendor/bin/phikl validate-cache --cache-file=.cache/.phikl

关于 Phikl 缓存，以下是一些需要注意的事项：

• 您可以通过调用 Pkl::toggleCache(false) 来禁用缓存，这在开发过程中很有用，但在生产环境中强烈不建议使用。
• 如果自上次预热以来修改了 PKL 模块，Phikl 会自动刷新缓存。
• 任何损坏的缓存条目都会自动刷新。

缓存后端

如果您有自己的缓存系统，可以使用 Pkl::setCache() 方法将缓存系统设置为使用。您可以通过它传递任何符合 PSR-16 缓存系统接口的实例。如果您想使用，例如，Redis 服务器作为 Pkl 模块的缓存系统，这很有用。

Phikl 随附以下缓存后端：

• PersistentCache，这是 Phikl 默认使用的。它使用文件来存储缓存；
• ApcuCacheAdapter，它使用 APCu 扩展在内存中存储缓存；
• MemcachedCacheAdapter，它使用 Memcached 扩展在内存中存储缓存。