Skip to content

Commit eefb2b2

Browse files
SpamerczSpamercz
committed
Documentation
1 parent d1b09ed commit eefb2b2

12 files changed

Lines changed: 379 additions & 41 deletions

‎doc/01_intro.md‎

Lines changed: 37 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -11,49 +11,71 @@ Use composer `composer require spameri/elastic`
1111
In your config neon, enable extensions. Kdyby/Console is there because we need it to do some command line commands.
1212
Monolog is required by elasticsearch/elasticsearch and we can use existing extension in Kdyby/Monolog.
1313

14-
```
14+
```neon
1515
extensions:
1616
elasticSearch: \Spameri\Elastic\DI\ElasticSearchExtension
1717
console: Kdyby\Console\DI\ConsoleExtension
1818
monolog: Kdyby\Monolog\DI\MonologExtension
1919
```
2020

2121
Then configure where is your ElasticSearch.
22-
```
22+
```neon
2323
elasticSearch:
2424
host: 127.0.0.1
2525
port: 9200
2626
```
2727

28-
For more config options see default values in `\Spameri\Elastic\DI\ElasticSearchExtension::$defaults`.
28+
For more config options see default values in `\Spameri\Elastic\DI\ElasticSearchExtension::$defaults`. [Here](../src/DI/ElasticSearchExtension.php#L9).
29+
30+
---
2931

3032
### 2. First entity
3133

32-
#### [Neon file configuration](../blob/master/doc/02_neon_configuration.md)
34+
#### [Neon file configuration](02_neon_configuration.md)
35+
36+
#### [Create entity class](03_entity_class.md)
37+
38+
#### [Create entity service](12_entity_service.md)
3339

34-
#### [Create Entity class](../blob/master/doc/03_entity_class.md)
40+
#### [Create entity factory](11_entity_factory.md)
41+
42+
---
3543

3644
### 3. Mapping
3745

38-
#### [Create new index with mapping]((../blob/master/doc/05_new_index_with_mapping.md))
46+
#### [Create new index with mapping](05_new_index_with_mapping.md)
47+
48+
---
3949

4050
### 4. Fill with data
41-
TODO
51+
52+
#### [Create and save entity](06_fill_data.md)
53+
54+
#### [Saving process explained](07_save_explained.md)
55+
56+
---
4257

4358
### 5. Get data from ElasticSearch
44-
TODO Tady factories
45-
TODO
46-
TODO
47-
TODO
48-
TODO
59+
60+
#### [Get data by ID](08_basic_get.md)
61+
62+
#### [Get data by tag](13_advanced_get.md)
63+
64+
---
4965

5066
### 6. Filter data from ElasticSearch
51-
TODO
67+
68+
#### [Match data](09_match_get.md)
69+
70+
---
5271

5372
### 7. Aggregate data from ElasticSearch
54-
TODO
73+
74+
#### [Aggregate data](10_aggregate.md)
75+
76+
---
5577

5678
### x. Other
5779

58-
#### [Data interfaces]((../blob/master/doc/04_data_interfaces.md))
80+
#### [Data interfaces](04_data_interfaces.md)
5981

‎doc/02_neon_configuration.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
# Define structure in neon file
2+
TODO convert to video example
23

34
- Create neon file for example in `app/ProductModule/Config/Product.neon`
45
- Import created file to your application config neon. Usually located in`app/config/config.neon`.

‎doc/03_entity_class.md‎

Lines changed: 129 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
# Entity class
22

3-
Lets create entity class, continuing our example, in folder `app/ProductModule/Entity/Product.php` given file contents:
3+
Lets create entity class, continuing our example, in folder `tests/SpameriTests/Data/Entity/Video.php` given file contents:
44
```php
5-
namespace App\ProductModule\Entity;
5+
namespace SpameriTests\Data\Entity;
66

77

8-
class Product implements \Spameri\Elastic\Entity\IElasticEntity
8+
class Video implements \Spameri\Elastic\Entity\IElasticEntity
99
{
1010

1111
/**
@@ -38,7 +38,7 @@ class Product implements \Spameri\Elastic\Entity\IElasticEntity
3838

3939
### Lets look at class part by part.
4040

41-
- Entity is in our defined namespace for `ProductModule` in own folder `Entity` which is shared for multiple entities.
41+
- Entity is in our defined namespace in own folder `Entity` which is shared for multiple entities.
4242
- Class extends interface `\Spameri\Elastic\Entity\IElasticEntity`, this is core interface for ElasticSearch document.
4343
It has to have `id` provided by ElasticSearch, library takes care of handling this field, no need to add in mapping.
4444
- Based on this interface, library figures out how to save this class.
@@ -47,26 +47,26 @@ It has to have `id` provided by ElasticSearch, library takes care of handling th
4747
- Interface requires function `id()` based on returned value it updates or creates entity.
4848
- Interface requires `entityVariables()` in this exact form. (This may be changed in future versions, but now is required)
4949

50-
### Adding properties to product entity
50+
### Adding properties to video entity
5151

52-
#### Single value property - `name`
52+
#### Single value property - `Video.Story.KeyWord`
5353

54-
- Lets say our product has limited name length to maximum of 255 characters and also 0 characters is not enough to
55-
describe product.
54+
- Lets say our Video has limited keyword length to maximum of 55 characters and also 0 characters is not enough to
55+
describe keyword.
5656
- We do not have reliable data input so lets validate this with help of interface `\Spameri\Elastic\Entity\IValue`.
57-
- First create value object for name `\App\ProductModule\Entity\Product\Name`.
57+
- First create value object for keyword `\SpameriTests\Data\Entity\Video\Story\KeyWord`.
5858
- Class should implement interface `\Spameri\Elastic\Entity\IValue`.
5959
- `__construct` should have one parameter **string $value**.
60-
- In construct do our validation for product name.
60+
- In construct do our validation for keyword.
6161
- Implement `value()` method.
62-
- Add property to `\App\ProductModule\Entity\Product` constructor.
63-
- Generate getter in `\App\ProductModule\Entity\Product` entity.
62+
- Add property to `\SpameriTests\Data\Entity\Video` constructor.
63+
- Generate getter in `\SpameriTests\Data\Entity\Video` entity for KeyWord.
6464
- Result:
6565
```php
66-
namespace App\ProductModule\Entity\Product;
66+
namespace SpameriTests\Data\Entity\Video\Story;
6767

6868

69-
class Name implements \Spameri\Elastic\Entity\IValue
69+
class KeyWord implements \Spameri\Elastic\Entity\IValue
7070
{
7171

7272
/**
@@ -79,11 +79,11 @@ class Name implements \Spameri\Elastic\Entity\IValue
7979
string $value
8080
)
8181
{
82-
if (\strlen($value) < 0) {
83-
throw new \InvalidArgumentException('Empty string is not supported for product name: ' . $value);
82+
if ($value === '') {
83+
throw new \InvalidArgumentException();
8484
}
85-
if (\strlen($value) > 255) {
86-
$value = \substr($value, 0, 255);
85+
if (\strlen($value) > 55) {
86+
throw new \InvalidArgumentException();
8787
}
8888

8989
$this->value = $value;
@@ -98,14 +98,117 @@ class Name implements \Spameri\Elastic\Entity\IValue
9898
}
9999
```
100100

101-
#### Value collection property - `details.tags`
102-
TODO
101+
#### Value collection property - `Video.Story.KeyWordCollection`
102+
TODO Description
103+
```php
104+
namespace SpameriTests\Data\Entity\Video\Story;
105+
106+
107+
class KeyWordCollection implements \Spameri\Elastic\Entity\IValueCollection
108+
{
109+
110+
/**
111+
* @var array<\SpameriTests\Data\Entity\Video\Story\KeyWord>
112+
*/
113+
private $collection;
114+
115+
116+
public function __construct(
117+
KeyWord ... $entities
118+
)
119+
{
120+
$this->collection = [];
121+
foreach ($entities as $keyWord) {
122+
$this->add($keyWord);
123+
}
124+
}
125+
126+
127+
public function add(
128+
KeyWord $keyWord
129+
) : void
130+
{
131+
$this->collection[$keyWord->value()] = $keyWord;
132+
}
103133

104-
#### Single entity property - `details`
105-
TODO
106134

107-
#### Entity collection property - `parameterValues`
108-
TODO
135+
public function getIterator() : \ArrayIterator
136+
{
137+
return new \ArrayIterator($this->collection);
138+
}
139+
}
140+
```
141+
142+
#### Single entity property - `Video.Story`
143+
TODO Description
144+
```php
145+
namespace SpameriTests\Data\Entity\Video;
146+
147+
148+
class Story implements \Spameri\Elastic\Entity\IEntity
149+
{
150+
151+
/**
152+
* @var \SpameriTests\Data\Entity\Video\Story\KeyWordCollection
153+
*/
154+
private $keyWords;
155+
156+
157+
public function __construct(
158+
\SpameriTests\Data\Entity\Video\Story\KeyWordCollection $keyWord
159+
)
160+
{
161+
$this->keyWords = $keyWord;
162+
}
163+
164+
165+
public function entityVariables() : array
166+
{
167+
return \get_object_vars($this);
168+
}
169+
170+
171+
public function key() : string
172+
{
173+
174+
}
175+
}
176+
```
177+
178+
#### Entity collection property - `Video.Connections.FollowsCollection`
179+
TODO Description
180+
```php
181+
namespace SpameriTests\Data\Entity\Video\Connections;
182+
183+
184+
class FollowsCollection extends \Spameri\Elastic\Entity\Collection\EntityCollection
185+
{
186+
187+
}
188+
```
189+
190+
#### ElasticEntity collection property - `Video.People`
191+
TODO Description
192+
```php
193+
namespace SpameriTests\Data\Entity\Video;
194+
195+
196+
class People extends \Spameri\Elastic\Entity\Collection\ElasticEntityCollection
197+
{
198+
199+
public function personByImdb(
200+
\SpameriTests\Data\Entity\Property\ImdbId $imdb
201+
) : ?\SpameriTests\Data\Entity\Person
202+
{
203+
/** @var \SpameriTests\Data\Entity\Person $entity */
204+
foreach ($this->collection() as $entity) {
205+
if ($imdb->value() === $entity->identification()->imdb()->value()) {
206+
return $entity;
207+
}
208+
}
209+
210+
return NULL;
211+
}
212+
}
213+
```
109214

110-
#### ElasticEntity collection property - `details.accessories`
111-
TODO

‎doc/05_new_index_with_mapping.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Create index with mapping for entity
2+
3+
Entity is configured (link) and defined in php (link) and next thing is to get these settings to ElasticSearch.
4+
5+
## Index creating
6+
7+
### New index - no previous data
8+
TODO
9+
```bash
10+
php www/index spameri:elastic:create-index
11+
```
12+
13+
### New index - deleting previous data
14+
TODO
15+
16+
### New index - preserving previous data
17+
TODO
18+
19+
20+

‎doc/06_fill_data.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Create and save entity
2+
3+
## Create
4+
TODO
5+
[Example](../tests/SpameriTests/Model/Insert.phpt#L16)
6+
```php
7+
$video = new \SpameriTests\Data\Entity\Video(
8+
new \Spameri\Elastic\Entity\Property\EmptyElasticId(),
9+
new \SpameriTests\Data\Entity\Video\Identification(
10+
new \SpameriTests\Data\Entity\Property\ImdbId(4154796)
11+
)
12+
);
13+
```
14+
15+
## Save
16+
TODO
17+
```php
18+
$videoService->insert($video);
19+
```
20+

‎doc/07_save_explained.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Insert explained
2+
3+
- Converter
4+
- ElasticSearch point of view
5+
TODO

‎doc/08_basic_get.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Basic Get
2+
3+
## Description
4+
Basic get by id from ElasticSearch, with exact match.
5+
6+
## Example
7+
```php
8+
$video = $videoService->get(
9+
new \Spameri\Elastic\Entity\Property\ElasticId($id)
10+
);
11+
```

‎doc/09_match_get.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Filter data
2+
3+
## Description
4+
TODO
5+
6+
## Example
7+
```php
8+
$elasticQuery = new \Spameri\ElasticQuery\ElasticQuery();
9+
$elasticQuery->query()->must()->add(
10+
new \Spameri\ElasticQuery\Query\Range(
11+
'year',
12+
2018,
13+
2019
14+
)
15+
);
16+
$elasticQuery->query()->must()->add(
17+
new \Spameri\ElasticQuery\Query\Match(
18+
'name',
19+
'Avengers'
20+
)
21+
);
22+
23+
$video = $videoService->getBy($elasticQuery);
24+
```

0 commit comments

Comments
 (0)