README

Kiwa 页面搜索

为您的 Kiwa 项目添加页面搜索功能。

安装

此库是为与 Composer 一起使用而制作的。通过运行 $ composer require kiwa/page-search 将其添加到您的项目中。

使用

在您的网站上实现页面搜索需要几个步骤。

1. 使用传统表单

1.1 设置 HTML 表单

首先，您需要一个表单，让网站访客可以输入搜索词并提交。它可以看起来像这样

<form action="" method="get">
    <input type="search" placeholder="Search ..." name="q" id="search" required autofocus>
    <label for="search">
        <button type="submit">Search</button>
    </label>
</form>

您如何实现它，您如何想设计您的表单以及任何其他事情都取决于您。

1.2 处理搜索词并发送结果

现在您需要一个页面来处理请求。根据我们上面的例子，它将是同一个页面，但这不是必需的。

接下来是这个库提供的内容。

1.2.1 从请求中获取搜索词

<?php

use Kiwa\DI;

$searchTerm = DI::getRequest()->query->get('q');

考虑使用 htmlspecialchars 函数使请求更安全。

1.2.2 使用您的搜索词初始化 PageSearch 类

<?php

use Kiwa\PageSearch\PageSearch;

$pageSearch = new PageSearch($searchTerm);

您可以使用 excludeFromSearch 方法排除搜索的页面

<?php

use Kiwa\URL\URLFromFile;

$pageSearch->excludeFromSearch(
    new URLFromFile('imprint'),
    new URLFromFile('login'),
    // and whatever more...
);

要开始实际搜索，您需要调用

<?php

$pageSearch->search();

1.2.3 获取结果并显示它们

现在，您可以通过调用 getMatches 方法来获取搜索结果。它将返回一个包含有关页面信息的 SearchResult 对象数组。

<?php

$matches = $pageSearch->getMatches();

总的来说，它可能看起来像这样

<?php

use Kiwa\DI;
use Kiwa\PageSearch\PageSearch;
use Kiwa\PageSearch\SearchResult;
use Kiwa\URL\URLFromFile;

$searchTerm = DI::getRequest()->query->get('q');

/** @var array<int, SearchResult> $matches */
$matches = [];

if (true === is_string($searchTerm)) {
    $searchTerm = htmlspecialchars($searchTerm);

    $pageSearch = new PageSearch($searchTerm);
    $pageSearch
        ->setLogger(DI::getLog())
        ->excludeFromSearch(
            new URLFromFile('imprint'),
            new URLFromFile('login'),
        )
        ->search()
    ;

    $matches = $pageSearch->getMatches();
}

foreach ($matches as $match) {
    $url = $match->getUrl();
    $title = $match->getTitle();
    $preview = $match->getPreview();
    // Create some HTML and display the results here...
}

2. 执行异步搜索

如果您想实现异步搜索，您需要一些 JavaScript 和一个端点。

2.1 创建端点

向您的 /public 文件夹添加一个页面，它可以接收 AJAX 请求，执行搜索，并发送一些 JSON。例如，它可以是名为 pagesearch.php 的页面，看起来可能是这样的

<?php

use App\PageSearchFactory;
use Kiwa\DI;

require_once '../../vendor/autoload.php';

/**
 * Change the content type if the response into JSON.  
 */
DI::getResponse()->headers->set('content-type', 'application/json');

$searchTerm = DI::getRequest()->query->get('q');

/**
 * Send and empty response in case the search term is missing.  
 */
if (false === is_string($searchTerm)) {
    echo json_encode([]);
    return;
}

/**
 * Initialize the PageSearch as described earlier. 
 * This has been striped here to make the code easier to understand... 
 */
//$pageSearch = ...

/**
 * Define your response here and finally send it back. 
 */
$response = [
    'matches' => array_values(
        $pageSearch->getMatches()
    ),
];

echo json_encode($response, JSON_PRETTY_PRINT);

2.2 通过 AJAX 发送搜索词

现在，您必须实现一些 JavaScript 来处理表单提交并向您的端点发送请求。这可能看起来像这样

const handleSubmit = (event) => {
    const searchTerm = event.target.value;
    const results = fetch(`/pagesearch.php?q=${searchTerm}`)
        .then((result) => {
            return result.json();
        })
    ;
    // Do something with the results...
};

const form = document.querySelector("form");
form.addEventListener("submit", handleSubmit);

3. 使用 PageSearch 工厂

如果您正在使用传统的搜索表单以及异步方式，我们建议使用 工厂模式 创建一个 PageSearch 工厂。

帮助

如果您有任何问题，请随时通过 hello@bitandblack.com 联系我们。

有关 Bit&Black 的更多信息，请访问 www.bitandblack.com。