如何在 ServBay 中启用和配置 SCWS PHP 模块

ServBay 是一款专为 macOS 设计的强大本地 Web 开发环境，集成了 PHP、Node.js、Python、Go、Java 等多种语言运行时，以及 MySQL、PostgreSQL、MongoDB、Redis 等数据库，并支持 Caddy 和 Nginx 等 Web 服务器。对于需要在 PHP 应用中处理中文文本的开发者而言，ServBay 预置了高效的 SCWS (Simple Chinese Word Segmentation) 中文分词模块，且启用过程非常简便。

本文将详细介绍如何在 ServBay 中启用 SCWS PHP 扩展，配置其字典文件，并通过示例代码演示其基本用法。

SCWS 模块概述

SCWS 是一个开源的中文分词引擎，以其高性能和高准确率著称。它采用词典匹配和统计模型相结合的方式，能够快速、准确地对中文文本进行分词处理，非常适用于构建中文搜索引擎、进行文本挖掘、内容分析、关键词提取以及词性标注等应用场景。

主要特性

1. 高性能分词: SCWS 采用优化的分词算法，能够高效处理大规模中文文本数据。
2. 高准确率: 结合词典和统计模型，SCWS 在中文分词任务上表现出较高的准确性。
3. 功能丰富: 除了基本分词，还支持关键词提取、词性标注等高级功能。
4. 易于集成: 提供简洁的 API 接口，方便开发者将其集成到 PHP 应用中。
5. 开源免费: SCWS 是开源软件，可免费使用和根据需求进行定制。

ServBay 中预置的 SCWS 版本

ServBay 支持多个 PHP 版本，并为每个版本预装了对应的 SCWS 模块。截至本文撰写时，ServBay 为 PHP 5.6 到 PHP 8.4 版本均预置了 SCWS 1.2.3 扩展。

如何启用 SCWS 模块

默认情况下，SCWS 模块在 ServBay 中是禁用的。启用它有两种主要方式：通过 ServBay 图形界面或手动修改配置文件。

推荐方式：通过 ServBay 图形界面启用

这是最简单快捷的方式：

1. 打开 ServBay 主界面。
2. 在左侧导航栏中，点击 语言 (Languages)，然后选择 PHP。
3. 在右侧列出的 PHP 版本列表中，找到您想要启用 SCWS 的 PHP 版本（例如，PHP 8.4）。
4. 点击该 PHP 版本右侧的 扩展 (Extensions) 按钮。
5. 在弹出的扩展列表中，找到 SCWS 模块。
6. 点击 SCWS 左侧的开关，将其切换为开启状态（通常变为绿色）。
7. 点击窗口底部的 保存 (Save) 按钮。
8. ServBay 会提示您需要重启 PHP 软件包以应用更改。点击 重启 (Restart) 按钮。

完成上述步骤后，SCWS 模块就已成功为您选定的 PHP 版本启用。

手动修改配置文件启用 (适用于高级用户或故障排查)

如果您需要更精细的控制或进行故障排查，也可以直接修改 PHP 的配置文件：

1. 定位配置文件: 首先，找到对应 PHP 版本的 conf.d 目录。SCWS 的配置位于该目录下的 scws.ini 文件。文件路径通常遵循以下格式：

   /Applications/ServBay/etc/php/X.Y/conf.d/scws.ini

   请将 X.Y 替换为您具体的 PHP 版本号，例如 8.4。

2. 编辑 scws.ini 文件: 使用文本编辑器打开 scws.ini 文件。找到以下内容：

   [scws]
   ; Uncomment the following line to enable scws
   ;extension = scws.so
   ;scws.default.charset = gbk
   ;scws.default.fpath = /Applications/ServBay/etc/scws

   取消注释 (去掉行首的 ;) extension = scws.so` 这一行，使其变为：

   [scws]
   ; Uncomment the following line to enable scws
   extension = scws.so
   ;scws.default.charset = gbk
   ;scws.default.fpath = /Applications/ServBay/etc/scws

   （可选）您也可以在此处设置默认的字符集和词典路径，但通常建议在 PHP 代码中动态设置，以获得更大的灵活性。如果在此处设置，也需要取消对应行的注释并修改值。例如，如果您的字典是 UTF-8 编码：

   [scws]
   ; Uncomment the following line to enable scws
   extension = scws.so
   scws.default.charset = utf8
   scws.default.fpath = /Applications/ServBay/etc/scws

   保存并关闭 scws.ini 文件。

3. 重启 PHP 软件包: 打开 ServBay 主界面，导航到 软件包 (Packages)，找到您修改配置的 PHP 版本（例如，PHP 8.4），点击其右侧的重启按钮（通常是一个圆形的箭头图标）。

验证 SCWS 模块是否成功加载

启用模块后，验证其是否成功加载是重要的一步。最常用的方法是查看 PHP 的 phpinfo() 输出：

1. 在 ServBay 建议的网站根目录 /Applications/ServBay/www 下，创建一个新的子目录用于测试，例如 scws-test。
2. 在该子目录 (/Applications/ServBay/www/scws-test) 中创建一个名为 phpinfo.php 的文件。
3. 将以下 PHP 代码复制到 phpinfo.php 文件中：

   <?php
   phpinfo();
   ?>

4. 确保您的 ServBay Web 服务器（如 Caddy 或 Nginx）已配置并运行，并且可以访问到 /Applications/ServBay/www 目录下的网站。ServBay 默认会配置一个 servbay.demo 域名指向 /Applications/ServBay/www。
5. 在浏览器中访问 https://servbay.demo/scws-test/phpinfo.php。
6. 在打开的 PHP 信息页面中，滚动查找名为 "SCWS" 的部分。如果找到了 SCWS 的相关配置和信息（例如，版本号、配置选项），说明模块已成功加载。

(注意：图片路径为示例，请参考实际 ServBay 文档中的图片)

创建和配置 SCWS 字典

SCWS 是一个基于词典的分词引擎，其分词效果在很大程度上依赖于使用的词典。ServBay 预置了 SCWS 的默认词典和规则文件，通常位于 /Applications/ServBay/etc/scws 目录下。您也可以创建或使用自己的词典。

SCWS 字典文件格式

SCWS 支持普通文本格式和二进制格式的 xdb 字典文件。推荐使用 xdb 格式，因为它加载速度更快，占用内存更少。

普通文本字典文件格式如下，每行一个词条，词条后可选择性地跟着词频（数字，越大表示越常用）和词性：

词汇1 [词频1] [词性1]
词汇2 [词频2] [词性2]
...

例如：

人工智能 1000 n
自然语言处理 800 n
ServBay 500 nz

将您自定义的词汇保存为一个文本文件，例如 my_dict.txt。请确保文件编码与您期望的字符集一致（推荐 UTF-8）。

生成 xdb 格式字典文件

ServBay 预置了 SCWS 提供的 scws-gen-dict 工具，用于将文本格式字典转换为 xdb 格式。

1. 打开 macOS 的终端 (Terminal) 应用。
2. 使用 cd 命令进入 ServBay 的 bin 目录，或者直接指定 scws-gen-dict 的完整路径。该工具通常位于 ServBay 的 bin 目录下：

   /Applications/ServBay/bin/scws-gen-dict -i /path/to/your/my_dict.txt -o /Applications/ServBay/etc/scws/my_dict.utf8.xdb -c utf8

   请将 /path/to/your/my_dict.txt 替换为您实际的文本字典文件路径。-o 参数指定输出的 xdb 文件路径和名称，建议放在 /Applications/ServBay/etc/scws 目录下。-c utf8 指定输入文件的编码。

配置 SCWS 使用字典文件

生成 xdb 文件后，您可以在 PHP 代码中指定 SCWS 使用该字典：

<?php
$scws = scws_new();
$scws->set_charset('utf8'); // 设置字符集，需与字典文件编码一致
// 设置主词典路径，可以是 ServBay 默认词典或您生成的 xdb 文件
$scws->set_dict('/Applications/ServBay/etc/scws/dict.utf8.xdb');
// 如果有多个字典，可以追加加载
$scws->add_dict('/Applications/ServBay/etc/scws/my_dict.utf8.xdb', SCWS_XDICT_TXT); // SCWS_XDICT_TXT 表示追加用户词典
$scws->set_rule('/Applications/ServBay/etc/scws/rules.utf8.ini'); // 设置规则文件，用于词性标注等，ServBay 已预置

// ... 后续分词操作 ...
?>

set_dict() 用于设置主词典，通常是 SCWS 官方提供的大型词典。add_dict() 用于追加加载用户自定义词典。SCWS_XDICT_TXT 是一个常量，表示追加的是用户自定义词典。

SCWS 使用示例

启用 SCWS 模块并配置好字典后，您就可以在 PHP 代码中调用 SCWS 函数进行分词了。以下是一个基本的使用示例：

<?php

// 确保 SCWS 扩展已加载
if (!extension_loaded('scws')) {
    die('SCWS extension is not loaded.');
}

// 初始化 SCWS 对象
$scws = scws_new();
if (!$scws) {
    die('Failed to initialize SCWS.');
}

// 设置字符集 (必须与您的文本和字典编码一致)
$scws->set_charset('utf8');

// 设置词典文件路径 (ServBay 预置路径)
// set_dict() 用于设置主词典
$scws->set_dict('/Applications/ServBay/etc/scws/dict.utf8.xdb');
// add_dict() 可以用于追加用户自定义词典
// $scws->add_dict('/Applications/ServBay/etc/scws/my_dict.utf8.xdb', SCWS_XDICT_TXT);

// 设置规则文件路径 (ServBay 预置路径)，用于词性标注等
$scws->set_rule('/Applications/ServBay/etc/scws/rules.utf8.ini');

// 设置分词模式 (可选，默认为 SCWS_XDICT_XPINYIN | SCWS_XDICT_DUALITY)
// SCWS_XDICT_XPINYIN: 分割 x 字符 (非汉字)，如 email, url 等
// SCWS_XDICT_DUALITY: 复合分词 (二元分词)
// $scws->set_ignore(true); // 是否忽略标点符号
// $scws->set_multi(SCWS_MULTI_WORD | SCWS_MULTI_ZHONGCI); // 设置复合分词的级别

// 要分词的中文文本
$text = "ServBay 是一个强大的本地 Web 开发环境，支持 PHP、Node.js 和多种数据库。";

// 将文本发送给 SCWS 进行处理
$scws->send_text($text);

// 获取分词结果
echo "原始文本: " . $text . "\n\n";
echo "分词结果:\n";

// 循环获取所有分词结果
while ($result = $scws->get_result()) {
    foreach ($result as $word) {
        // $word 是一个关联数组，包含 'word', 'idf', 'attr' (词性) 等信息
        echo "词语: " . $word['word'] . " (词性: " . $word['attr'] . ")\n";
    }
}

// 释放 SCWS 资源
$scws->close();

?>

将上述代码保存为 .php 文件（例如 scws_example.php）并放置在 ServBay 的网站目录下（如 /Applications/ServBay/www/scws-test/）。通过浏览器访问 https://servbay.demo/scws-test/scws_example.php 即可看到分词结果输出。

注意事项

• 确保您启用的 SCWS 模块版本与您正在使用的 PHP 版本兼容。ServBay 已为您处理了兼容性问题，但手动配置时需注意。
• SCWS 的分词效果与词典质量密切相关。对于特定领域的文本，建议使用或创建专业的行业词典。
• 确保 SCWS 配置文件 (scws.ini)、字典文件 (.xdb) 和规则文件 (.ini) 的路径设置正确，并且 PHP 进程对这些文件有读取权限。
• 修改 PHP 配置后，务必重启对应的 PHP 软件包才能使更改生效。

常见问题解答 (FAQ)

Q: 我通过 ServBay UI 启用了 SCWS，但 phpinfo() 中没有看到？

A: 请确保您重启了 正确 的 PHP 软件包。有时可能有多个 PHP 版本在运行，您需要重启与您的网站关联的那个 PHP 版本。如果问题依旧，尝试手动修改 scws.ini 文件并仔细检查文件路径和语法错误。

Q: 如何创建和使用自定义词典？

A: 请参考本文档中“创建和配置 SCWS 字典”一节，使用 scws-gen-dict 工具将文本字典转换为 xdb 格式，然后在 PHP 代码中使用 add_dict() 方法加载您的自定义词典。

Q: SCWS 的规则文件 (rules.utf8.ini) 是做什么用的？

A: 规则文件主要用于词性标注和一些特殊的分词规则。ServBay 已经预置了默认的规则文件，通常您无需修改。

总结

ServBay 为开发者提供了便捷的方式来启用和管理 SCWS PHP 中文分词模块。无论是通过直观的图形界面还是灵活的手动配置，您都可以轻松地将 SCWS 集成到您的 PHP 开发工作流程中。结合 ServBay 预置的 SCWS 工具和默认字典，您可以快速上手，利用 SCWS 高效、准确地处理中文文本，为您的 Web 应用（如搜索、内容分析）提供强大的中文处理能力。作为 ServBay 丰富软件包生态的一部分，SCWS 的集成进一步提升了 ServBay 作为本地开发环境的全面性和实用性。