126. 占位符替换token服务
在系统很多地方进行设置时，事先并不知道具体的设置值，典型的比如：当用户注册时，系统可以发送一封欢迎邮件，但在设置邮件内容时并不知道用户的名字，该名字需要等到用户注册后才知道，此时可以先设置一个占位符，等到发送时进行替换即可，这样的占位符就是“token”，这样的需求有很多，又比如文件上传的保存目录如果是日期，那么也需要先使用占位符，上传保存时需要替换为真实的日期。系统统一使用“token”服务来识别和替换占位符。
占位符格式：
为了便于描述，下文“token”和“占位符”是相同意思，为了能够自动识别和替换token，需要token自带含义，因此需要具备一定格式，系统通过派发钩子的方式来收集替换值，钩子又通过token的格式进行解析并生成替换值，因此token格式尤为重要，需要有统一规范，drupal标准token格式如下：
[$type:$name]
这里$type是类型名，如node、user、comment、site、date等（通常采用模块名，但不一定是，准确讲应该称为类型名，理解为token类型，用于识别是哪一种占位符），$name是该类型下给定占位符的名字
示例如下：
[node:title]、[user:display-name]
token也可以分层级，格式如下：
[$type:$pointer:$name]
示例如下：
[node:author:mail]：被替换为节点作者的邮件
[date:custom:Y]：被替换为4位数的年份
这种层级可以理解为：第一个冒号后面的部分均是$name，只不过$name内部又继续采用了冒号分隔，这里的冒号和第一个冒号在含义上是有区别的，第一个冒号可以严格称为token分隔符，而$name里面的冒号仅供提供该token的钩子使用，其含义和层级的数量也由钩子决定
token规则是：
整个token字符串用英文方括号包裹，方括号内不允许再包括方括号，里面至少有一个英文冒号将字符分隔为两部分，第一部分字符称为类型标识符（$type），标识符可以是除空白字符和方括号以外的任意字符，第一个冒号后面的全部字符称为占位符名（$name），占位符名可以包含英文冒号做进一步的层级规划，可以包含方括号以外的任意字符，甚至空格，占位符名的规则和解析均由提供该token的钩子实现。
token服务：
用于识别字符串中的token并替换
服务id：token
类：Drupal\Core\Utility\Token
获取方式：\Drupal::token();
使用示例（替换目录中的日期token）：
$data = [];
$destination = '[date:custom:Y]-[date:custom:m]';
$destination = trim($destination, '/');
$destination = \Drupal::token()->replace($destination, $data);
$destination = \Drupal\Component\Render\PlainTextOutput::renderFromHtml($destination);
print_r($destination);
该服务各方法说明如下：
public function replace($text, array $data = [], array $options = [], BubbleableMetadata $bubbleable_metadata = NULL)
参数如下：
$text：
包含占位符的字符串，可以是html字符串，不可以为对象
$data：
部分token的转化需要传递额外的对象，比如节点token就需要节点对象，用该数组传递所需的对象，如不需要可以留空
$options：
选项数组，用于控制方法的行为，有两个通用选项：$options['clear']如果不为空，则在没有替换值时删除占位符；$options['callback']是一个回调（在PHP7前仅允许函数名或静态方法，不能为数组），可以用该回调来调整即将使用的替换数组；不同token可以按序传递选项数组
$bubbleable_metadata：
渲染数组的可冒泡元数据对象，用于收集缓存或附属物
该方法返回替换后的字符串，调用者负责转义，如果没有传递可冒泡元数据，那么收集的可冒泡元数据将被自动添加到当前渲染上下文，如果有传递，那么由调用者处理
public function scan($text)
传入一个字符串，扫描其中所有可能包含的占位符，返回一个多维数组，第一级键名为$type，第二级键名为占位符中除开$type剩余的部分，值为完整占位符，示例如下：
如果输入值$text为：
$text='我是[a:b]和[x:y:z]';
那么输出值$var为：
$var['a']['b']='[a:b]';
$var['x']['y:z']='[x:y:z]';
如果没有扫描到token将返回空数组
public function generate($type, array $tokens, array $data, array $options, BubbleableMetadata $bubbleable_metadata)
收集可冒泡渲染元数据及派发钩子收集替换信息，派发tokens钩子：
hook_tokens($type, $tokens, array $data, array $options, $bubbleable_metadata)
其中$type为占位符中类型部分，$tokens为一个数组，键名为余下的占位符部分，键值为完整占位符，其他参数与replace方法中的一样，钩子应返回一个数组，键名为完整占位符字符串，键值为替换字符串，如键值不想再被转义，应该用MarkupInterface对象表示，可返回空数组
修改钩：
hook_tokens_alter(array &$replacements, array $context, $bubbleable_metadata)
其中$replacements为全系统收集到的替换数组，$context为上下文数组，如下：
$context = [
'type' => $type,
'tokens' => $tokens,
'data' => $data,
'options' => $options,
];
含义同上
注：tokens相关钩子存放在模块的“.tokens.inc”文件中的，该文件不默认加载，那么是如何加载的呢？详见本系列钩子主题，了解钩子函数加载机制以及钩子信息钩子：system_hook_info()
public function findWithPrefix(array $tokens, $prefix, $delimiter = ':')
从占位符扫描结果中提取具备某前缀的部分，假设输入$tokens如下：
$data = array(
'author:name' => '[node:author:name]',
'title' => '[node:title]',
'created' => '[node:created]',
);
前缀$prefix为author，那么返回：
array('name' => '[node:author:name]');
public function getInfo()
返回系统所支持的全部token的元数据描述，这通过钩子“token_info”及其修改钩收集，通常实现了tokens钩子的模块应该实现该钩子
钩子实现情况：
在系统默认安装中，以下模块实现了tokens钩子，模块名及钩子函数名如下：
comment : comment_tokens
file : file_tokens
node : node_tokens
statistics : statistics_tokens
system : system_tokens
taxonomy : taxonomy_tokens
user : user_tokens
views : views_tokens
没有模块实现其修改钩，你可以用本系列配套模块“yunke_help”查看钩子实现情况
钩子“token_info”的实现情况同上
自定义token：
模块只需要实现以上的tokens和token_info钩子即可，在钩子逻辑中规划token格式
可通过以下代码测试查看token：
$data = [];
$token = "token is :\n[date:custom:Y]\n[site:url-brief]\n[site:login-url]";
$token = \Drupal::token()->replace($token, $data);
print_r($token);
die;
常用token：
[date:short]
短时间，如：10/21/2019 - 20:38
[date:medium]
中长日期，如：周一, 10/21/2019 - 20:38
[date:long]
长日期，如：星期一, 十月 21, 2019 - 20:38
[date:raw]
时间戳原始输出，如：1571661728
[date:since]
在数据参数中给出一个时间，该占位符返回一个用本地语言显示的时间差，如：
$data = ['date'=>time()-300];
$token = "[date:since] ";
$token = \Drupal::token()->replace($token, $data);
将输出类似：4 分钟 58 秒
通常用于显示已注册时间
[date:custom:Y]
四位数的年份，如2019
[date:custom:m]
带前导0的两位月份，如09
[date:custom:d]
带前导0的两位日期，如08、21
[date:custom:Y-m-d H:i:s]
将输出完整的年月日时分秒，如：“2019-10-22 19:27:01”，如你所见，在“date:custom:”后面可以使用和php函数date第一个参数相同的格式字符，这就是自定义的含义，请参考：
https://www.php.net/manual/zh/function.date.php
除此之外，drupal还很贴心的进行了本地化翻译，如：
[date:custom:F(D)]
在翻译系统有数据时，将输出“十月(周二)”，而php的date函数只能输出“October(Tue)”
[site:name]
在网站基本设置中设置的站点名
[site:slogan]
在网站基本设置中设置的站点口号或标语
[site:mail]
在网站基本设置中设置的邮件地址
[site:url]
完整的站点首页地址，带协议及域名部分
[site:url-brief]
简洁版首页地址，带域名但不带协议部分
[site:login-url]
用户登录地址
补充：
1、并非设置了token就会被替换，而是仅允许使用token的地方才会替换，如在文章正文中设置就不会被替换
2、注意占位符不要使用中文的方括号或冒号，这样将无效
3、不要将token占位符和渲染数组中的占位符（$element['#attached']['placeholders']）搞混淆，这是完全不同的两个概念