README

此包提供了一个用于与Vespa搜索引擎交互的Laravel服务提供者和客户端。它包括查询构建、速率限制、缓存、插件集成等功能。

目录

• 安装
• 配置
• 使用
  • 基本搜索
  • 查询构建器
  • 缓存
  • 自定义插件
  • 外观
• 测试
• 许可

安装

要开始使用Laravel Vespa客户端，您需要遵循以下步骤

1. 通过Composer安装包

   composer require ostah/laravel-vespa

2. 发布配置文件

   这将允许您自定义应用程序的Vespa设置。

   php artisan vendor:publish --tag=config --provider="YourVendor\Vespa\VespaServiceProvider"

3. 添加必要的环境变量

   将以下行添加到您的.env文件中

   VESPA_URL=https://:8080
   VESPA_API_KEY=your-api-key-here
   VESPA_HTTP_TIMEOUT=30
   VESPA_RATE_LIMIT=100
   VESPA_THROTTLE_LIMIT=10
   VESPA_DEFAULT_LANGUAGE=en
   VESPA_LOG_CHANNEL=default
   VESPA_AUDIT_LOG_CHANNEL=audit
   VESPA_ERROR_LOG_CHANNEL=vespa_errors

配置

Vespa客户端的配置存储在config/vespa.php。此文件包括Vespa URL、API密钥、速率限制、节流和日志记录的设置。您可以调整这些设置以满足应用程序的需求。

以下是一个config/vespa.php文件的示例

return [

    'url' => env('VESPA_URL', 'https://:8080'),

    'api_key' => env('VESPA_API_KEY', null),

    'timeout' => env('VESPA_HTTP_TIMEOUT', 30),

    'rate_limit' => env('VESPA_RATE_LIMIT', 100),

    'throttle_limit' => env('VESPA_THROTTLE_LIMIT', 10),

    'language' => env('VESPA_DEFAULT_LANGUAGE', 'en'),

    'log_channel' => env('VESPA_LOG_CHANNEL', 'default'),
    'audit_log_channel' => env('VESPA_AUDIT_LOG_CHANNEL', 'audit'),
    'error_log_channel' => env('VESPA_ERROR_LOG_CHANNEL', 'vespa_errors'),
];

使用

Laravel Vespa客户端提供多种与Vespa搜索引擎交互的方式。以下是一些如何在应用程序中使用客户端的示例。

基本搜索

您可以使用VespaClient执行基本搜索

use YourVendor\Vespa\VespaClient;

$vespa = app(VespaClient::class);

$response = $vespa->search('your search query');

dd($response);

查询构建器

VespaQueryBuilder类允许您使用流畅的API构建复杂的查询

use YourVendor\Vespa\VespaQueryBuilder;

$builder = new VespaQueryBuilder();
$query = $builder->select(['title', 'description'])
                 ->from('documents')
                 ->where('status', 'published')
                 ->orderBy('created_at', 'desc')
                 ->limit(10)
                 ->getQuery();

$response = $vespa->searchWithBuilder($builder);

dd($response);

缓存

要缓存搜索结果，您可以使用cachedSearch方法

$response = $vespa->cachedSearch('your search query', [], 600); // Cache for 10 minutes

dd($response);

自定义插件

您可以创建自定义插件来在查询发送到Vespa之前修改它们。以下是如何使用自定义插件的方法

use YourVendor\Vespa\Plugins\ExamplePlugin;

$plugin = new ExamplePlugin(['append' => 'AND status:published']);
$vespa->registerPlugin($plugin);

$response = $vespa->search('your search query');

dd($response);

外观

如果您更喜欢使用外观，可以像这样访问VespaClient

use Vespa;

$response = Vespa::search('your search query');

dd($response);

测试

为了确保Vespa客户端正常工作，提供了一套测试套件。这些测试涵盖了基本搜索功能、查询构建、缓存、插件集成、速率限制和节流。

要运行测试，请使用PHPUnit

vendor/bin/phpunit

以下是一个基本测试类的示例

<?php

namespace YourVendor\Vespa\Tests;

use YourVendor\Vespa\VespaClient;
use YourVendor\Vespa\VespaQueryBuilder;
use YourVendor\Vespa\Plugins\ExamplePlugin;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;

class VespaClientTest extends TestCase
{
    use RefreshDatabase;

    protected $vespaClient;

    protected function setUp(): void
    {
        parent::setUp();

        $this->vespaClient = $this->app->make(VespaClient::class);
    }

    public function testBasicSearch()
    {
        $response = $this->vespaClient->search('test query');

        $this->assertNotNull($response);
        $this->assertIsArray($response);
    }

    public function testQueryBuilderSearch()
    {
        $builder = new VespaQueryBuilder();
        $query = $builder->select(['title', 'description'])
                         ->from('documents')
                         ->where('status', 'published')
                         ->orderBy('created_at', 'desc')
                         ->limit(10)
                         ->getQuery();

        $response = $this->vespaClient->searchWithBuilder($builder);

        $this->assertNotNull($response);
        $this->assertIsArray($response);
    }

    public function testCachedSearch()
    {
        $response = $this->vespaClient->cachedSearch('test query', [], 600);

        $this->assertNotNull($response);
        $this->assertIsArray($response);

        // Check that the response is cached
        $cachedResponse = $this->vespaClient->cachedSearch('test query', [], 600);
        $this->assertEquals($response, $cachedResponse);
    }

    public function testPluginIntegration()
    {
        $plugin = new ExamplePlugin(['append' => 'AND status:published']);
        $this->vespaClient->registerPlugin($plugin);

        $response = $this->vespaClient->search('test query');

        $this->assertNotNull($response);
        $this->assertIsArray($response);
    }

    public function testRateLimitExceeded()
    {
        $this->expectException(\Exception::class);

        config(['vespa.rate_limit' => 1]);

        $this->vespaClient->search('test query');
        $this->vespaClient->search('another query'); // This should trigger the rate limit exception
    }

    public function testThrottlingExceeded()
    {
        $this->expectException(\Exception::class);

        config(['vespa.throttle_limit' => 1]);

        $this->vespaClient->search('test query');
        $this->vespaClient->search('another query'); // This should trigger the throttling exception
    }
}

许可

此包是开源软件，根据MIT许可证许可。