Getting Started

First Steps

Installation Add the package via Composer:

composer require ezsystems/ezplatform-search

Publish the configuration (if needed):

php artisan vendor:publish --provider="EzSystems\EzPlatformSearch\EzPlatformSearchServiceProvider"

Basic Setup Register the search service in your config/services.php:

'ezplatform-search' => [
    'default' => env('SEARCH_CONNECTION', 'default'),
    'connections' => [
        'default' => [
            'driver' => 'ezplatform',
            'options' => [
                'repository' => 'ezpublish.api.repository',
            ],
        ],
    ],
],

First Query Inject the search service into a controller or command:

use EzSystems\EzPlatformSearch\SearchService;

public function __construct(SearchService $searchService) {
    $this->searchService = $searchService;
}

public function searchContent() {
    $search = $this->searchService->createSearch();
    $result = $search->find('content', ['query' => 'marketing']);
    return $result->getResults();
}

Key Documentation
- EzPlatformSearch API Docs (if available)
- Check vendor/ezsystems/ezplatform-search/src/ for core classes like SearchService, Search, and Query.

Implementation Patterns

Common Workflows

Searching Content Use SearchService to create a Search instance and execute queries:

$search = $searchService->createSearch();
$query = new Query\Query();
$query->query = new Query\Criteria\Query('marketing');
$query->filter = new Query\Criteria\Filter\ContentTypeFilter('marketing_page');

$result = $search->find('content', $query);
$hits = $result->getResults();

Pagination Limit and paginate results:

$query->limit = 10;
$query->offset = 20;

Sorting Sort by relevance or custom fields:

$query->sort = [
    new Query\Criteria\Sort\FieldSort('content', 'modified', 'desc'),
];

Highlighting Enable snippet highlighting:

$query->highlight = new Query\Criteria\Highlight();
$query->highlight->fields = ['content'];

Integration with Eloquent If using a hybrid setup, map results to Eloquent models:

$results = $result->getResults();
$mapped = $results->map(fn ($hit) => new MyModel($hit->getContent()));

Advanced Patterns

Custom Query Builders Extend Query\Query for reusable logic:

class MarketingQuery extends Query\Query {
    public function __construct() {
        $this->filter = new Query\Criteria\Filter\ContentTypeFilter('marketing_page');
        $this->sort = [new Query\Criteria\Sort\FieldSort('content', 'modified', 'desc')];
    }
}

Event-Driven Search Listen for search events (e.g., SearchEvent::POST_SEARCH):
```
event(new SearchEvent($query, $result));
```

Caching Results Cache frequent queries (e.g., using Laravel Cache):

$cacheKey = 'search:marketing';
$results = Cache::remember($cacheKey, now()->addHours(1), function () use ($search) {
    return $search->find('content', $query)->getResults();
});

Search in API Resources Return search results in API responses:
```
return new SearchResource($result->getResults());
```

Gotchas and Tips

Pitfalls

Deprecation Warnings

The package is older (last release 2023-05-31). Check for deprecated methods like:

// Deprecated in newer versions
$search->search($query);
// Use instead:
$search->find('content', $query);

Criteria vs. Query Confusion
- Query\Criteria is used for filtering/sorting, while Query\Query wraps the entire search request.
- Mixing them incorrectly may throw InvalidArgumentException.
Performance with Large Datasets
- Avoid unbounded queries (e.g., no limit/offset). Use:
```
$query->limit = 100; // Always set a limit
```
Content Not Found
- If results are empty, verify:
  - The ContentType exists in the repository.
  - The query or filter is correctly configured.
  - The SearchService is bound to the right repository.
Case Sensitivity
- Search is case-sensitive by default. Use Query\Criteria\Query::setCaseSensitive(false) if needed.

Debugging Tips

Log Queries Enable debug mode in config:

'debug' => env('APP_DEBUG', false),

Log raw queries for troubleshooting:

\Log::debug('Search Query:', $query->toArray());

Check Repository Binding Ensure the repository option in config points to a valid EzPublish repository:
```
'options' => [
    'repository' => 'ezpublish.api.repository', // Must match your DI container
],
```

Validate Criteria Use Query\Criteria\Validator to check syntax:

$validator = new Query\Criteria\Validator();
$errors = $validator->validate($query);

Test with Simple Queries Start with a broad query (e.g., *) to isolate issues:
```
$query->query = new Query\Criteria\Query('*');
```

Extension Points

Custom Drivers Extend the Driver interface to support new backends (e.g., Elasticsearch):

class ElasticsearchDriver implements DriverInterface {
    // Implement search logic
}

Query Transformers Modify queries before execution:

$search->addTransformer(function (Query\Query $query) {
    $query->highlight = new Query\Criteria\Highlight();
    return $query;
});

Result Mappers Transform raw results into custom objects:

$search->addMapper(function (Result\Result $result) {
    return $result->getResults()->map(fn ($hit) => new MyModel($hit));
});

Event Listeners Hook into search lifecycle events:

// In a service provider
$this->app->booted(function () {
    event(new SearchEvent($query, $result));
});

Configuration Quirks

Default Connection Ensure SEARCH_CONNECTION in .env matches your config:
```
SEARCH_CONNECTION=default
```

Repository Dependency The package requires ezpublish.api.repository. If using Symfony DI:

# config/services.yaml
EzSystems\EzPlatformSearch\EzPlatformSearchServiceProvider:
    arguments:
        $repository: '@ezpublish.api.repository'

Timeouts Adjust timeout settings in config:

'options' => [
    'timeout' => 30, // seconds
],

Ezplatform Search Laravel Package