README

处理文本中占位符的简单系统

内容

• 要求
• 安装
• 用法
  • 1. 步骤 - 准备自定义占位符处理器
  • 2. 步骤 - 创建一个新的实例
  • 3. 步骤 - 使用
  • 严格模式

要求

可以从 Composer 配置文件 获取所有依赖项的完整列表

• PHP 5.4 或更高版本

安装

安装 Kappa\PlaceholderProcessor 的最佳方式是使用 Composer

$ composer require kappa/placeholderprocessor

用法

1. 步骤 - 准备自定义占位符处理器

创建自定义占位符处理器有一些规则。每个占位符处理器必须实现 \Kappa\PlaceholderProcessor\IPlaceholderProcessor 接口，或者建议您从实现此接口并准备简单快速使用的逻辑的 \Kappa\PlaceholderProcessor\PlaceholderProcessor 类扩展您的类。

例如

<?php
use Kappa\PlaceholderProcessor\PlaceholderProcessor;

class MySuperPlaceholderProcessor extends PlaceholderProcessor
{
	private $db;
	
	public function __construct(Database $db) 
	{
	    $this->db = $db;
	}
	
	public function configure()
	{
		$this->setName("mySuperPlaceholderProcessor");
		$this->setExternalSources(['user_id']);
	}

	public function run(array $sources = [])
	{
		return $this->db->find('users', $sources['user_id'])->getName();
	}
}

此占位符将使用外部源设置的 ID 替换 %mySuperPlaceholderProcessor% 占位符的用户名。

您必须在 configure 方法中配置您的处理器。在此方法中，您必须设置占位符的名称，如果格式为 %<name>%。在这种情况下，此占位符将与 %mySuperPlaceholderProcessor% 占位符一起工作。

第二个重要设置是外部源列表。此列表将用于在 run 方法中自动与 $source 进行比较。您可以从 TextFormatter::format($text, $sources) 获取这些源。

run 方法的返回值将用于替换占位符。

2. 步骤 - 创建一个新的实例

要翻译占位符，您需要 Kappa\PlaceholderProcessor\TextFormatter 的实例。

您可以手动创建此实例

$textFormatter = new TextFormatter([
    new MySuperPlaceholderProcessor()
]);

或者您可以使用 setPlaceholders(array) 方法

$textFormatter = new TextFormatter();
$textFormatter->setProcessors([
  new MySuperPlaceholderProcessor()
]);

或者当您使用 Nette 框架 时，可以将此包注册为扩展

services:
	mySuperProcessor:
	    class: MySuperPlaceholderProcessor
	    tags: [kappa.placeholder_processor]

extensions: 
    placeholderProcessor: Kappa\PlaceholderProcessor\DI\PlaceholderProcessorExtension
    
placeholderProcessor:
	strict: true

```php
public function __construct(TextFormatter $textFormatter) {
    
}

当然，您可以添加单个处理器 $textFormatter->addProcessor(new MySuperPlaceholderProcessor());。

3. 步骤 - 使用

现在我们有了自定义占位符和格式化程序实例，您可以尝试将此文本 Hello %mySuperPlaceholderProcessor%, %foo% 翻译

$textFormatter = new TextFormatter([
    new mySuperPlaceholderProcessor($db)
]);

$output = $textFormatter->format('Hello %mySuperPlaceholderProcessor%, %foo%', ['user_id' => 1]);

格式化程序将使用 MySuperPlaceholderProcessor 类中的逻辑替换 %mySuperPlaceholderProcessor%。此处理器从外部源（format 方法的第二个参数）获取 user_id，在数据库中查找用户，并返回可用于替换原始占位符的名称。占位符 %foo% 将被忽略，因为没有以该名称命名的处理器。

输出：Hello Joe, %foo%。

严格模式

严格模式默认关闭。

当您需要严格模式，并且当文本中有没有处理器的占位符时抛出异常（如上一个示例中的 %foo%）。您可以通过 setStrictMode(true) 方法打开（或关闭）它，或者当您使用 Nette 框架 时，在配置文件中通过 strict: true 打开。