README

加入我们的 Slack 社区

我们有一个专门的 Slack 频道，您可以在此提问、讨论新功能，并对扩展提供反馈。加入我们，保持最新动态并参与讨论！

加入 Slack 频道

我们期待在那里与您见面，并与您互动！

用智能、内容驱动的推荐提升您的 TYPO3 网站

🌟 简介

语义建议扩展彻底改变了在 TYPO3 网站上展示相关内容的方式。它超越了基于分类法和税法的传统“类似内容”功能，通过采用先进的语义分析来创建真正相关的内容关联。

主要优势

• 🎯 高度相关的链接：根据实际内容相似性自动生成关联，而不仅仅是预定义的分类。
• ⏱️ 提高用户参与度：通过提供真正相关的内客，让访客在您的网站上停留更长时间。
• 🕸️ 语义茧：为您的网站内创建一个高质量的语义网络，提升 SEO 和用户导航。
• 🤖 智能自动化：减少手动链接工作，同时提高内部链接质量。

性能考虑

尽管语义建议扩展提供了强大的功能，但请注意

• 📊 相似度计算过程随着页面数量的增加呈指数级增长。
• ⏳ 对于超过 500 个页面的网站，初始计算可能需要长达 30 秒，具体取决于服务器容量。
• 💡 我们建议使用后端模块来评估您特定设置的缓存时间。
• 🔄 当页面或内容被修改时，缓存会自动重置，以确保最新的相似度计算。

📌 专业提示：利用后端模块监控性能并优化您特定用例的设置。

通过利用语义分析的力量，此扩展为传统相关内容插件提供了一种更优的替代方案，为用户提供更准确、更有价值的内容建议。

新功能 1.4.0 版本

支持停用词

此扩展现在包含停用词功能，显著提高了内容分析的正确性。停用词是在处理内容之前过滤掉的常见单词（如“the”、“is”、“at”）。此功能通过关注有意义的内客来增强语义建议的相关性。

调试模式

已引入新的调试模式，可通过 TypoScript 激活

plugin.tx_semanticsuggestion_suggestions.settings.debugMode = 1

When enabled, this mode provides:

Detailed debug information in the backend interface
Comprehensive logs in public/typo3temp/logs/semantic_suggestion.log

This feature is invaluable for developers and administrators looking to fine-tune the extension's performance or troubleshoot issues.

### Backend Module Enhancements

The backend module has been significantly improved:

Optimized "Top 5 Most Similar Page Pairs" display, eliminating duplicate entries
Enhanced statistics and visualizations for better content insights
Improved performance for large-scale page analyses

### For Developers

New API methods are available to access stopwords statistics
The similarity calculation algorithm has been optimized, providing more accurate results



## 📚 Table of Contents

- [Introduction](#-introduction)
- [Features](#-features)
- [Requirements](#-requirements)
- [Installation](#-installation)
- [Configuration](#-configuration)
- [Usage](#-usage)
- [Backend Module](#-backend-module)
- [Similarity Logic](#-similarity-logic)
- [Display Customization](#-display-customization)
- [Multilingual Support](#-multilingual-support)
- [Debugging and Maintenance](#-debugging-and-maintenance)
- [Security](#-security)
- [Performance](#-performance)
- [File Structure](#-file-structure)
- [Unit Tests](#-unit-tests)
- [Contributing](#-contributing)
- [License](#-license)
- [Support](#-support)



### Frontend View
![Frontend view with the same theme](Documentation/Medias/frontend_on_the_same_theme_view.jpg)

## 🚀 Features

- 🔍 Analyzes subpages of a specified parent page
- 📊 Displays title, associated media, and enhanced text excerpt of suggested pages
- ⚙️ Highly configurable via TypoScript
- 🎛 Customizable parent page ID, proximity threshold, and search depth
- 💾 Optimized performance with database caching of proximity scores
- 🌐 Built-in multilingual support
- 🧩 Improved compatibility with various TYPO3 content structures, including Bootstrap Package
- 🚫 Option to exclude specific pages from analysis and suggestions

## 🛠 Requirements

- TYPO3 12.0.0-13.9.99
- PHP 8.0 or higher

## 💻 Installation

<details>
<summary><strong>Composer Installation (recommended)</strong></summary>

1. Install the extension via composer:
   ```bash
   composer require talan-hdf/semantic-suggestion

1. 在 TYPO3 扩展管理器中激活扩展

⚙️ 配置

编辑您的 TypoScript 设置以配置扩展

plugin.tx_semanticsuggestion {
    settings {
        parentPageId = 1
        proximityThreshold = 0.7
        maxSuggestions = 3
        excerptLength = 150
        recursive = 1
        excludePages = 8,9,3456
        recencyWeight = 0.2

        analyzedFields {
            title = 1.5
            description = 1.0
            keywords = 2.0
            abstract = 1.2
            content = 1.0
        }
    }
}

分析字段的权重系统

analyzedFields 部分允许您配置在相似度计算中不同内容字段的重要性

相似度计算中近期的权重（0-1）

recencyWeight参数确定发布或修改日期在相似度计算中的重要性

• 0：近期没有影响
• 1：近期有最大影响

finalSimilarity = (contentSimilarity * (1 - recencyWeight)) + (recencyBoost * recencyWeight)

🖥 使用方法

在流体模板中

要直接在您的流体模板中添加插件，请使用

<f:cObject typoscriptObjectPath='lib.semantic_suggestion' />

此方法使用TypoScript配置，适用于简单的集成。

TypoScript集成

您还可以使用TypoScript集成语义建议插件。将以下TypoScript设置添加到您的配置中

lib.semantic_suggestion = USER
lib.semantic_suggestion {
    userFunc = TYPO3\CMS\Extbase\Core\Bootstrap->run
    extensionName = SemanticSuggestion
    pluginName = Suggestions
    vendorName = TalanHdf
    controller = Suggestions
    action = list
}

然后，您可以在您的TypoScript模板中这样使用它

page.10 = < lib.semantic_suggestion

或在特定内容元素中

tt_content.semantic_suggestion = COA
tt_content.semantic_suggestion {
    10 = < lib.semantic_suggestion
}

请记住，在您的站点配置或页面设置中包含您的TypoScript模板。

🎛 后端模块

语义建议扩展包括一个强大的后端模块，可提供关于您页面之间语义关系的全面见解。

功能

• 📊 相似度分析：可视化页面之间的语义相似度
• 🔝 最相似对：快速识别最相关的页面对
• 📈 相似度评分分布：内容相似度的概述
• ⚙️ 可配置分析：设置自定义参数（父页面ID、深度、阈值）
• 📊 可视化表示：直观的图表和进度条
• 📑 详细统计：深入页面相似度和内容关系数据

在TYPO3后端“网络”菜单下访问该模块。

💡 提示：语义分析的有效性取决于内容质量和数量。确保您的页面有有意义的标题、描述和内容，以获得最佳结果。

性能指标

后端模块提供关键性能指标，以帮助优化扩展的操作

优化性能

1. 缓存：调整缓存配置以匹配您的更新频率
2. 分析深度：平衡全面性和性能
3. 排除页面：使用excludePages设置排除无关页面
4. 内容结构：组织内容以最小化分析的页面数量，同时不牺牲质量

监控这些指标以微调扩展配置以适应您的特定用例。

🧮 相似度逻辑

该扩展采用自定义的相似度计算方法来确定相关页面

1. 数据收集：收集指定父页面的每个子页面的标题、描述、关键词和内容。
2. 相似度计算：使用词交集和并集方法比较页面对。相似度得分是共同单词与总唯一单词的比例，按字段重要性加权。
3. 邻近度阈值：只有相似度得分高于配置阈值的页面才被视为相关并显示。
4. 缓存分数：计算出的分数存储在tx_semanticsuggestion_scores表中，以优化性能。这些分数会定期更新或在页面内容更改时更新。

🎨 显示定制

通过覆盖Fluid模板（List.html）来自定义建议的显示。在TypoScript中配置自己的模板路径

plugin.tx_semanticsuggestion {
    view {
        templateRootPaths.10 = EXT:your_extension/Resources/Private/Templates/
    }
}

🌐 多语言支持

该扩展完全支持TYPO3的多语言结构，分析和建议当前站点的语言页面。

🐛 调试和维护

语义建议扩展利用TYPO3的日志系统进行全面的调试和维护

• 📝 配置日志以获取分析和建议过程的详细信息
• 🔍 监控扩展行为和性能
• 🚀 根据日志数据优化

$GLOBALS['TYPO3_CONF_VARS']['LOG']['TalanHdf']['SemanticSuggestion']['writerConfiguration'] = [
    \TYPO3\CMS\Core\Log\LogLevel::DEBUG => [
        \TYPO3\CMS\Core\Log\Writer\FileWriter::class => [
            'logFile' => 'typo3temp/logs/semantic_suggestion.log'
        ],
    ],
];

🔒 安全性

语义建议扩展实施了几项安全措施

• 🛡️ 通过TYPO3的安全查询机制（QueryBuilder）防止SQL注入
• 🔐 通过Fluid模板中的自动输出转义防止XSS攻击
• 🚫 限制访问权限仅限于具有适当权限的用户

⚡ 性能

优化以高效运行，即使在大量页面的情况下

• 💾 在数据库中缓存相似度分数
• 🔄 定期更新分数并在内容更改时刷新
• 🚀 优化内容检索过程
• 🎯 有效地处理排除的页面
• ⚖️ 批量处理页面分析以管理服务器负载

📁 文件结构和逻辑

semantic_suggestion/
├── Classes/
│   ├── Controller/
│   │   ├── SemanticBackendController.php
│   │   └── SuggestionsController.php
│   └── Service/
│       └── PageAnalysisService.php
├── Configuration/
│   ├── Backend/
│   │   ├── Modules.php
│   │   └── Routes.php
│   ├── TCA/
│   │   └── Overrides/
│   │       ├── sys_template.php
│   │       └── tt_content.php
│   ├── TypoScript/
│   │   ├── constants.typoscript
│   │   └── setup.typoscript
│   └── Services.yaml
├── Documentation/
│   ├── Index.rst
│   ├── Installation/
│   │   └── Index.rst
│   ├── Introduction/
│   │   └── Index.rst
│   └── Medias/
│       ├── backend_module.png
│       ├── backend_module_performance_metrics.jpg
│       └── frontend_on_the_same_theme_view.jpg
├── Resources/
│   ├── Private/
│   │   ├── Language/
│   │   │   ├── locallang.xlf
│   │   │   ├── locallang_be.xlf
│   │   │   ├── locallang_mod.xlf
│   │   │   └── locallang_semanticproximity.xlf
│   │   ├── Layouts/
│   │   │   └── Default.html
│   │   └── Templates/
│   │       ├── SemanticBackend/
│   │       │   ├── Index.html
│   │       │   └── List.html
│   │       └── Suggestions/
│   │           └── List.html
│   └── Public/
│       ├── Css/
│       │   └── SemanticSuggestion.css
│       └── Icons/
│           ├── Extension.svg
│           ├── module-semantic-suggestion.svg
│           └── user_mod_semanticproximity.svg
├── Tests/
│   ├── Fixtures/
│   │   └── pages.xml
│   ├── Integration/
│   │   └── Service/
│   │       └── PageAnalysisServiceIntegrationTest.php
│   └── Unit/
│       └── Service/
│           └── PageAnalysisServiceTest.php
├── .env
├── .gitignore
├── CHANGELOG.md
├── IMPROVEMENTS.MD
├── LICENSE
├── README.md
├── ROADMAP_TO_STABLE.md
├── composer.json
├── ext_conf_template.txt
├── ext_emconf.php
├── ext_localconf.php
├── ext_tables.php
└── phpunit.xml.dist

🧪 单元测试

语义建议扩展包含一套全面的单元测试，以确保核心功能（特别是相似度计算算法）的可靠性和正确性。

测试覆盖率

1. 加权词计算：验证根据字段重要性和词频正确加权单词。
2. 相似度计算：确保使用余弦相似度进行页面相似度计算的准确性。
3. 字段特定相似度：测试对单个字段（标题、内容、关键词等）的相似度得分计算。
4. 近期增强集成：验证在最终相似度得分中集成近期因素的整合。
5. 页面数据处理：检查相似度分析的正确数据准备和预处理。
6. 常见关键词检测：测试在页面之间查找共享关键词的功能。
7. 相关性确定：验证基于计算出的相似度得分的相关性确定逻辑。
8. 边缘情况处理：测试空页面、单词内容以及极其大量内容的处理行为。
9. 多语言内容处理：验证不同语言内容的正确相似度计算。
10. 性能测试：评估使用大型数据集进行相似度计算的效率。
11. 缓存处理：确保适当使用缓存机制以提高性能。

运行测试

要运行单元测试

1. 请确保您已使用DDEV设置了开发环境。
2. 打开终端并导航到您的项目根目录。
3. 执行以下命令

ddev exec vendor/bin/phpunit -c packages/semantic_suggestion/phpunit.xml.dist --testdox --colors=always

对于特定测试，请添加--filter选项

ddev exec vendor/bin/phpunit -c packages/semantic_suggestion/phpunit.xml.dist --filter testMethodName

PageAnalysisService的测试命令

在PageAnalysisServiceTest中测试所有测试

要执行PageAnalysisServiceTest类中的所有测试

ddev exec vendor/bin/phpunit -c packages/semantic_suggestion/phpunit.xml.dist --testdox --colors=always --filter PageAnalysisServiceTest

测试特定方法

要测试特定方法，例如testGetWeightedWordsReturnsCorrectWeights

ddev exec vendor/bin/phpunit -c packages/semantic_suggestion/phpunit.xml.dist --testdox --colors=always --filter "PageAnalysisServiceTest::testGetWeightedWordsReturnsCorrectWeights"

使用命名模式测试

要执行所有名称中包含"Similarity"的测试

ddev exec vendor/bin/phpunit -c packages/semantic_suggestion/phpunit.xml.dist --testdox --colors=always --filter "/::test.*Similarity/"

带有代码覆盖率执行

要执行带有代码覆盖率的测试

ddev exec vendor/bin/phpunit -c packages/semantic_suggestion/phpunit.xml.dist --testdox --colors=always --filter PageAnalysisServiceTest --coverage-text

以详细模式测试

要获取更多有关测试执行的详细信息

ddev exec vendor/bin/phpunit -c packages/semantic_suggestion/phpunit.xml.dist --testdox --colors=always --filter PageAnalysisServiceTest -v

解析结果

• ✅ 绿色勾选：通过测试
• ❌ 红色交叉：失败测试
• ⚠️ 黄色感叹号：风险或未完成测试

详细的输出有助于快速识别和解决问题。

💡 提示：建议定期运行测试，尤其是在代码更改后，以确保功能持续运行并尽早捕获回归。

🤝 贡献

我们欢迎为语义建议扩展做出贡献！以下是您可以如何贡献的方式

1. 🍴 分叉存储库
2. 🌿 为您的功能或错误修复创建新分支
3. 🛠️ 进行更改并使用清晰的提交消息提交它们
4. 🚀 将您的更改推送到您的分叉
5. 📬 向主存储库提交拉取请求

请遵守现有的编码标准，并为您的更改包括适当的测试。

📄 许可证

本项目采用GNU通用公共许可证v2.0或更高版本。请参阅LICENSE文件以获取完整详细信息。

🆘 支持

有关支持和更多信息

👤 联系：Wolfangel Cyril
Email: cyril.wolfangel@gmail.com

🐛 错误报告和功能请求：请使用GitHub问题跟踪器

📚 文档和更新：访问我们的GitHub存储库

📘 完整文档 | 🐛 报告错误 | 💡 请求功能