README

Loop54 是一个面向电子商务的学习型搜索引擎。这个库旨在使将服务与您的PHP站点集成变得尽可能简单。

安装

我们建议使用 Composer 来处理您的依赖项；如果您正在这样做，可以通过运行以下命令安装Loop54 PHP连接器：

$ composer require loop54/php-connector

这将将其安装到 composer 使用的 vendor 子目录中，用于第三方依赖项。Composer 还会为它管理的所有依赖项设置自动加载，但为了告诉您的 PHP 关于这些依赖项，您可能需要在应用程序的早期添加以下调用。

require_once(__DIR__ . '/vendor/autoload.php');

使用PHAR存档

所有版本都有独立的PHAR存档可供下载。它们不会自动更新，所以如果您需要这些中的任何一个，请与我们联系。

用法

此连接器分为一个简单的高层库和一个高级的低层API绑定。您可以在 lib 目录中找到高层库，在 lib/OpenAPI 目录中找到低层绑定。

对于最常见任务，高层库应该足够使用。这包括以下内容：

• 制作搜索请求
• 添加分面
• 列出分类中的产品
• 过滤出例如缺货的产品
• 根据价格对产品进行排序
• 在结果之间分页
• 获取与搜索查询相关的结果
• 获取自动完成建议
• 发送用户交互事件
• 提供用户拼写建议

然而，某些更高级的功能仅通过低层绑定可用。这些功能的例子包括：

• 同时根据多个属性进行排序（例如，主要按制造商，然后在同一制造商内部，按价格递增）
• 自定义引擎返回的分面顺序
• 获取搜索查询的总命中数
• 提交任意数据用于客户端特定目的
• 显示所有符合复杂标准的产品

高层库是在低层库的基础上实现的，旨在与低层库完全兼容。这意味着对于大多数操作，可以使用高层连接器，然后在需要时仅将操作降级到低层绑定。

配置

您与连接器的大部分交互都是从 \Loop54\API\Client 类的一个实例开始的。对于Web应用程序，最常见的实例化方法是

$remoteClientInfo = new \Loop54\API\RemoteClientInfo\WebClient();
$connector = new \Loop54\API\Client(
    'URL_TO_YOUR_ENDPOINT',
    'YOUR_API_KEY',
    $remoteClientInfo
);

为了使 Loop54 引擎能够正确注册用户交互，需要告诉它有关终端用户的IP地址和用户代理等信息。 \Loop54\API\RemoteClientInfo\WebClient 对象将自动从 PHP 环境中获取这些信息。

另一个重要参数是用户 ID（userId），对于每个访客应该是恒定的。在您的代码中，您应该创建一个名为 Loop54User 的 cookie，并使用生成的唯一 userId 值。您可以在 examples/app/templates/base.html.twig 中找到如何生成它的示例。

如果您想有更多的控制权，\Loop54\API\RemoteClientInfo\Client 接口包含实现这些方法的函数。一个简单地返回静态值的示例实现是 \Loop54\API\RemoteClientInfo\SimpleClient。

实现指南

配置连接器后，您就可以开始使用了！接下来需要阅读的是Loop54技术文档和开发者指南，其中包含了一般的实施指导和建议——以及该PHP连接器的代码示例。

示例

这里包含了两个使用库的示例。

examples/Simple.php

这是一个简单的控制台应用程序，专注于展示连接器的核心功能，而不涉及诸如路由、模板、错误处理和其他现实世界的关注点。

examples/app

这是一个完整的Symfony Web应用程序，实现了一些功能，以展示在实际场景中使用连接器可能的样子。

高级库

处理高级库的最佳方法可以在上面的实施指南中找到。

低级绑定

由于低级绑定实际上是引擎用于通信的JSON API的1:1映射，熟悉这个API有助于导航低级绑定。

低级绑定是通过使用OpenAPI生成器从API规范生成的。生成器产生的类在设计中非常规范，因此一旦您学会了将API模式转换为生成的PHP类，您将能够流畅地处理它们。

贡献

我们欢迎任何形式的贡献！我们都不是PHP专家，所以如果您认为您发现了一些看起来不正确的地方——那可能就是。请随意提交问题或发送拉取请求。

设置

首先确保您已经安装了所有依赖项，包括开发依赖项

$ composer install

运行Symphony应用程序

该库使用Symphony Web框架有一个测试应用程序。这可以在开发过程中用来验证和测试功能。该应用程序可以通过以下方式在本地Web服务器上运行端口5001：

$ cd examples/app
$ php -S localhost:5001

选择您喜欢的任何端口。然后在浏览器中打开localhost:5001（或您选择的端口），您就可以尝试该应用程序。它非常简单，但支持搜索、自动完成和创建事件。

运行示例

/examples下的代码是可运行的，并作为测试库的一部分。可以通过以下方式运行它们：

$ php examples/Simple.php

这些配置为向https://helloworld.54proxy.com/执行一系列请求，不应抛出任何异常。

测试

可以通过以下方式运行单元和集成测试：

./vendor/bin/phpunit test

要测试多个PHP版本（使用Docker），运行

./test-matrix.sh

这将运行（示例）（### 运行示例）以及单元和集成测试。

生成低级库

lib/OpenAPI下的代码是通过半手动过程从OpenAPI规范生成的。首先，从https://docs.loop54.com/latest/api/schema.json下载模式。然后，我们从规范生成代码并将其写入临时位置。

openapi-generator-cli generate \
    -g php -i schema.json -o ~/tmp/phpgen -t templates \
    --invoker-package 'Loop54\API\OpenAPI'

如果您没有openapi-generator-cli，可以通过以下方式获取它：

npm install @openapitools/openapi-generator-cli -g

如果上述命令在生成没有反斜杠的名字时遇到问题（例如'Loop54APIOpenAPI'），请尝试双重转义命令：--invoker-package 'Loop54\\API\\OpenAPI'（或甚至\\\\）

这会生成一些我们不怎么感兴趣的辅助代码，所以我们只将有趣的片段复制到存储库中。（注意，这里的点号是必需的，以便rsync正确猜测我们的意图。）

rsync -a ~/tmp/phpgen/lib/. lib/OpenAPI/.

构建phar存档

使用phar-composer

1. 首先，确保清理了开发需求，并且只安装了运行时依赖。如果不执行这一步，归档中会包含例如示例 Symfony 应用，这没有任何好处却占用大量空间。

   $ composer install --no-dev

2. 然后，从连接器源和所有已安装的依赖中创建一个 phar 归档。

   $ php -d phar.readonly=off phar-composer.phar build .
   Loop54PHPConnector-1.0.0.phar