Skip to content

Commit 2730fd3

Browse files
Spamerczclaude
Spamercz
and
claude
committed
docs: comprehensive documentation update
- Update README.md with features list, requirements, and quick start example - Add CLAUDE.md with project architecture and coding standards - Expand doc/01-usage.md with more query building examples - Update doc/02-query-objects.md with missing queries (PhrasePrefix, Nested, GeoDistance, Exists, MultiMatch) - Update doc/03-aggregation-objects.md with missing aggregations (Min, Max, Avg, TopHits, Filter, Nested) - Update doc/04-result-objects.md with ResultVersion and detailed usage examples - Add doc/05-options.md for pagination, sorting, and scroll API - Add doc/06-highlight-function-score.md for highlighting and custom scoring - Add doc/07-mapping-settings.md for index mapping configuration 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent c6bd7b8 commit 2730fd3

9 files changed

Lines changed: 1902 additions & 108 deletions

‎CLAUDE.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
ElasticQuery is a PHP library that converts Elasticsearch query DSL into typed PHP objects. Instead of building queries as arrays, developers can use strongly-typed classes that mirror the Elasticsearch documentation.
8+
9+
## Development Commands
10+
11+
```bash
12+
# Install/update dependencies
13+
make composer
14+
15+
# Run static analysis (PHPStan level 7)
16+
make phpstan
17+
18+
# Run code style checks (Slevomat coding standard)
19+
make cs
20+
21+
# Auto-fix code style issues
22+
make cbf
23+
24+
# Run tests (Nette Tester)
25+
make tests
26+
27+
# Run a single test file
28+
vendor/bin/tester -s -p php --colors 1 -C tests/SpameriTests/ElasticQuery/Path/To/Test.phpt
29+
```
30+
31+
## Architecture
32+
33+
### Core Query Building
34+
35+
**ElasticQuery** (`src/ElasticQuery.php`) - Main entry point for building queries. Composes:
36+
- `QueryCollection` - Boolean query with must/should/mustNot collections
37+
- `FilterCollection` - Filter context queries
38+
- `AggregationCollection` - Aggregation definitions
39+
- `Options` - Pagination, sorting, scroll settings
40+
- `Highlight` - Search result highlighting
41+
- `FunctionScore` - Custom scoring functions
42+
43+
All query/aggregation objects implement `toArray()` to serialize to Elasticsearch-compatible format.
44+
45+
### Query Objects (`src/Query/`)
46+
47+
Leaf queries implement `LeafQueryInterface`:
48+
- `ElasticMatch`, `MatchPhrase`, `MultiMatch`, `PhrasePrefix` - Full-text queries
49+
- `Term`, `Terms`, `Range`, `Exists`, `WildCard` - Term-level queries
50+
- `Nested`, `GeoDistance`, `Fuzzy` - Specialized queries
51+
52+
Collection queries (`MustCollection`, `ShouldCollection`, `MustNotCollection`) also implement `LeafQueryInterface`, enabling nested boolean logic.
53+
54+
### Aggregations (`src/Aggregation/`)
55+
56+
- `LeafAggregationCollection` wraps aggregation definitions with nested sub-aggregations
57+
- Metric aggregations: `Min`, `Max`, `Avg`, `TopHits`
58+
- Bucket aggregations: `Term`, `Range`, `Histogram`, `Nested`, `Filter`
59+
60+
### Response Mapping (`src/Response/`)
61+
62+
`ResultMapper` converts Elasticsearch array responses to typed objects:
63+
- `ResultSearch` - Standard search results with hits and aggregations
64+
- `ResultSingle` - Single document retrieval
65+
- `ResultBulk` - Bulk operation results
66+
- `ResultVersion` - Cluster version info
67+
68+
### Index Mapping (`src/Mapping/`)
69+
70+
Classes for defining Elasticsearch index mappings:
71+
- Analyzers: Standard, custom dictionary analyzers for multiple languages
72+
- Filters: Stemming, synonyms, stop words, edge n-grams
73+
- Tokenizers: Pattern, whitespace, etc.
74+
- `Settings` - Index settings configuration
75+
76+
### Document Handling (`src/Document.php`, `src/Document/`)
77+
78+
`Document` wraps index name, body, and optional ID for Elasticsearch client calls.
79+
80+
### Options & Sorting (`src/Options.php`, `src/Options/`)
81+
82+
- `Options` - Pagination (size, from), scroll support, min_score, version inclusion
83+
- `Sort` - Field sorting with ASC/DESC and missing value handling
84+
- `GeoDistanceSort` - Geo-spatial sorting by distance from a point
85+
- `SortCollection` - Manages multiple sort criteria
86+
87+
### Function Score (`src/FunctionScore.php`, `src/FunctionScore/`)
88+
89+
Custom scoring with multiple score functions:
90+
- `FieldValueFactor` - Score based on numeric field values with modifiers (log, sqrt, etc.)
91+
- `Weight` - Constant weight multiplier when filter matches
92+
- `RandomScore` - Randomized scoring with optional seed for consistency
93+
94+
Score modes: multiply, sum, avg, first, max, min
95+
96+
## Coding Standards
97+
98+
- PHP 8.2+ with strict types
99+
- Fully qualified class names in annotations
100+
- Fully qualified global functions and constants
101+
- Tab indentation (no spaces)
102+
- Trailing commas in arrays, function calls, and declarations
103+
- Constructor property promotion where applicable
104+
- No Yoda comparisons
105+
- Strict equality operators only (`===`, `!==`)

‎README.md‎

Lines changed: 56 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,65 @@
11
# ElasticQuery
2-
Elastic documentation converted to php objects for easy using.
32

4-
Installation
5-
------------
3+
A PHP library that converts Elasticsearch query DSL into strongly-typed PHP objects. Instead of building queries as arrays, use type-safe classes that mirror the Elasticsearch documentation.
64

7-
The best way to install Spameri/ElasticQuery is using [Composer](http://getcomposer.org/):
5+
## Features
6+
7+
- **Type-safe queries** - Full-text, term-level, compound, geo, and nested queries
8+
- **Aggregations** - Metric (min, max, avg) and bucket (terms, histogram, range, filter) aggregations
9+
- **Response mapping** - Automatic mapping of Elasticsearch responses to typed objects
10+
- **Index mapping** - Define index settings, analyzers, tokenizers, and filters
11+
- **Function scoring** - Custom scoring with field value factors, weights, and random scores
12+
- **Highlighting** - Search result highlighting support
13+
- **Pagination & sorting** - Options for size, offset, scroll, and geo-distance sorting
14+
15+
## Requirements
16+
17+
- PHP 8.2 or higher
18+
19+
## Installation
20+
21+
Install via [Composer](http://getcomposer.org/):
822

923
```sh
10-
$ composer require spameri/elastic-query
24+
composer require spameri/elastic-query
1125
```
1226

13-
Documentation
14-
------------
27+
## Quick Start
28+
29+
```php
30+
use Spameri\ElasticQuery\ElasticQuery;
31+
use Spameri\ElasticQuery\Query\ElasticMatch;
32+
use Spameri\ElasticQuery\Query\Term;
33+
34+
// Create a query
35+
$query = new ElasticQuery();
36+
37+
// Add a must query (AND condition)
38+
$query->addMustQuery(new ElasticMatch('title', 'Elasticsearch'));
39+
40+
// Add a filter (cached, no scoring)
41+
$query->addFilter(new Term('status', 'published'));
42+
43+
// Set pagination
44+
$query->options()->changeSize(10);
45+
$query->options()->changeFrom(0);
46+
47+
// Convert to array for Elasticsearch client
48+
$body = $query->toArray();
49+
```
50+
51+
## Documentation
52+
53+
Learn more in the [documentation](https://github.com/Spameri/ElasticQuery/tree/master/doc):
54+
55+
- [Usage](https://github.com/Spameri/ElasticQuery/tree/master/doc/01-usage.md) - Integration examples
56+
- [Query Objects](https://github.com/Spameri/ElasticQuery/tree/master/doc/02-query-objects.md) - All query types
57+
- [Aggregation Objects](https://github.com/Spameri/ElasticQuery/tree/master/doc/03-aggregation-objects.md) - Aggregation types
58+
- [Result Objects](https://github.com/Spameri/ElasticQuery/tree/master/doc/04-result-objects.md) - Response mapping
59+
- [Options & Sorting](https://github.com/Spameri/ElasticQuery/tree/master/doc/05-options.md) - Pagination, sorting, scroll
60+
- [Highlight & Function Score](https://github.com/Spameri/ElasticQuery/tree/master/doc/06-highlight-function-score.md) - Highlighting and custom scoring
61+
- [Mapping & Settings](https://github.com/Spameri/ElasticQuery/tree/master/doc/07-mapping-settings.md) - Index configuration
1562

16-
Learn more in the [documentation](https://github.com/Spameri/ElasticQuery/tree/master/doc).
63+
## License
1764

18-
- [Usage](https://github.com/Spameri/ElasticQuery/tree/master/doc/01-usage.md)
19-
- [Query objects](https://github.com/Spameri/ElasticQuery/tree/master/doc/02-query-objects.md)
20-
- [Aggregation objects](https://github.com/Spameri/ElasticQuery/tree/master/doc/03-aggregation-objects.md)
21-
- [Result objects](https://github.com/Spameri/ElasticQuery/tree/master/doc/04-result-objects.md)
65+
MIT

0 commit comments

Comments
 (0)