Small understability improvements

README.md

@@ -12,17 +12,27 @@ mapping migration and so on.
 
 At current moment, everything is aimed only for ES 6.0+ compatibility. 
 
-## Usage
+## Installation
+
+```bash
+composer require ama-team/elasticsearch
+```
 
-### Conventions
+## Conventions
 
 This library embraces type deprecation, and they take as little place
 as possible. It means you'll probably use a separate index for every 
 entity.
 
-### Mapping
+Classes are interpreted as index mapping: it is implied that documents
+and inner/nested objects are (usually) mapped to PHP objects. Every 
+class that takes a part in document is called *embeddable*, and the 
+document class is called as *entity* (though you can embed entity in 
+other entity).
 
-#### Concepts
+## Usage
+
+### Mapping
 
 Mapping is *the* number one problem in ElasticSearch usage, since every
 complex setup requires precise mapping, but there's no decent 
@@ -37,7 +47,7 @@ nested)
 - Every property in such class resembles a field (unless there is no 
 type specified or it is explicitly ignored)
 - Every property may map to any ElasticSearch type (end user is 
-responsible for inconsistencies)
+responsible if he/she specified invalid one)
 - Every property may also specify PHP class which will be used to
 populate that field and generate sub-mapping for that field 
 - Every class may provide some mapping parameters
@@ -54,12 +64,12 @@ property)
 So, there are two ways of mapping representation in this project:
 
 - "Source" mapping that specifies views and different mappings for 
-classes and properties (`DocumentMappingInterface` and 
+classes and properties (`ClassMappingInterface` and 
 `PropertyMappingInterface`)
 - "Target" mapping, which is ElasticSearch-ready (`MappingInterface`),
 and which doesn't have concept of separate mapping sources - every 
 field specified in `MappingInterface` is another `MappingInterface`;
-"merged" mapping may be serialized as json and used in ElasticSearch
+"target" mapping may be serialized as json and used in ElasticSearch
 as-is
 
 As an end-user you will define mapping in "raw" format, while boiling

src/API/Annotation/Embeddable.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AmaTeam\ElasticSearch\API\Annotation;
+
+/**
+ * @Annotation
+ * @Target("CLASS")
+ */
+class Embeddable
+{
+    /**
+     * Multi-type attribute:
+     * - If set to null, real class parent will be used
+     * - If set to string, it will be treated as parent class name
+     * - If set to false, inheritance will be turned off
+     */
+    public $inherits;
+}

src/API/Annotation/Entity.php

@@ -8,13 +8,18 @@
  * @Annotation
  * @Target("CLASS")
  */
-class Entity
+class Entity extends Embeddable
 {
     /**
-     * Multi-type attribute:
-     * - If set to null, real class parent will be used
-     * - If set to string, it will be treated as parent class name
-     * - If set to false, inheritance will be turned off
+     * @var array<string>
      */
-    public $inherits;
+    public $writeIndices = [];
+    /**
+     * @var array<string>
+     */
+    public $readIndices = [];
+    /**
+     * @var string
+     */
+    public $type = 'doc';
 }

src/Entity/Annotation/Listener/EmbeddableAnnotationListener.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AmaTeam\ElasticSearch\Entity\Annotation\Listener;
+
+use AmaTeam\ElasticSearch\API\Annotation\Embeddable;
+use AmaTeam\ElasticSearch\Entity\Annotation\ClassAnnotationListenerInterface;
+use AmaTeam\ElasticSearch\Entity\Entity;
+use ReflectionClass;
+
+class EmbeddableAnnotationListener implements ClassAnnotationListenerInterface
+{
+    public function accept(ReflectionClass $class, Entity $entity, $annotation): void
+    {
+        if (!($annotation instanceof Embeddable)) {
+            return;
+        }
+        $parent = $annotation->inherits;
+        if ($parent === null || $parent === true) {
+            $parent = $class->getParentClass() ? $class->getParentClass()->getName() : null;
+        }
+        if (is_string($parent)) {
+            $entity->setParentName($parent);
+        }
+    }
+}

src/Entity/Annotation/Listener/EntityAnnotationListener.php

@@ -5,6 +5,7 @@
 namespace AmaTeam\ElasticSearch\Entity\Annotation\Listener;
 
 use AmaTeam\ElasticSearch\API\Annotation\Entity as EntityAnnotation;
+use AmaTeam\ElasticSearch\API\Entity\Indexing\Indexing;
 use AmaTeam\ElasticSearch\Entity\Annotation\ClassAnnotationListenerInterface;
 use AmaTeam\ElasticSearch\Entity\Entity;
 use ReflectionClass;
@@ -16,12 +17,14 @@ public function accept(ReflectionClass $class, Entity $entity, $annotation): voi
         if (!($annotation instanceof EntityAnnotation)) {
             return;
         }
-        $parent = $annotation->inherits;
-        if ($parent === null || $parent === true) {
-            $parent = $class->getParentClass() ? $class->getParentClass()->getName() : null;
-        }
-        if (is_string($parent)) {
-            $entity->setParentName($parent);
-        }
+        $writeIndices = $annotation->writeIndices ?: [$class->getShortName()];
+        $readIndices = $annotation->readIndices ?: [$class->getShortName()];
+        $target = Indexing::from($entity->getIndexing())
+            ->setWriteIndices($writeIndices)
+            ->setReadIndices($readIndices)
+            ->setType($annotation->type);
+        $entity
+            ->setIndexing($target)
+            ->setRootLevelDocument(true);
     }
 }

src/Entity/Annotation/ListenerProvider.php

@@ -4,7 +4,7 @@
 
 namespace AmaTeam\ElasticSearch\Entity\Annotation;
 
-use AmaTeam\ElasticSearch\Entity\Annotation\Listener\DocumentAnnotationListener;
+use AmaTeam\ElasticSearch\Entity\Annotation\Listener\EmbeddableAnnotationListener;
 use AmaTeam\ElasticSearch\Entity\Annotation\Listener\EntityAnnotationListener;
 use AmaTeam\ElasticSearch\Entity\Annotation\Listener\Mapping\Clazz\ClassParameterAnnotationListener;
 use AmaTeam\ElasticSearch\Entity\Annotation\Listener\Mapping\Clazz\ClassTypeAnnotationListener;
@@ -23,7 +23,7 @@ class ListenerProvider
     public static function getClassListeners(): array
     {
         return [
-            new DocumentAnnotationListener(),
+            new EmbeddableAnnotationListener(),
             new EntityAnnotationListener(),
             new ClassParameterAnnotationListener(),
             new ClassTypeAnnotationListener(),

src/Entity/Annotation/Loader.php

@@ -4,7 +4,7 @@
 
 namespace AmaTeam\ElasticSearch\Entity\Annotation;
 
-use AmaTeam\ElasticSearch\API\Annotation\Entity as EntityAnnotation;
+use AmaTeam\ElasticSearch\API\Annotation\Embeddable as EntityAnnotation;
 use AmaTeam\ElasticSearch\API\Entity\EntityInterface;
 use AmaTeam\ElasticSearch\API\Entity\LoaderInterface;
 use AmaTeam\ElasticSearch\Entity\Entity;

src/Mapping/Mapping.php

@@ -114,4 +114,23 @@ public static function asObject(MappingInterface $source)
         }
         return $result;
     }
+
+    public static function asArray(MappingInterface $source): array
+    {
+        $result = [];
+        foreach ($source->getParameters() as $parameter => $value) {
+            $result[$parameter] = $value;
+        }
+        if (!empty($source->getProperties())) {
+            $properties = [];
+            foreach ($source->getProperties() as $property => $mapping) {
+                $properties[$property] = static::asArray($mapping);
+            }
+            $result['properties'] = $properties;
+        }
+        if ($source->getType() && $source->getType() !== RootType::ID) {
+            $result['type'] = $source->getType();
+        }
+        return $result;
+    }
 }

tests/Support/ElasticSearch/Dummy/Building.php

@@ -4,12 +4,12 @@
 
 namespace AmaTeam\ElasticSearch\Test\Support\ElasticSearch\Dummy;
 
-use AmaTeam\ElasticSearch\API\Annotation\Document;
+use AmaTeam\ElasticSearch\API\Annotation\Entity;
 use AmaTeam\ElasticSearch\API\Annotation\Mapping;
 use AmaTeam\ElasticSearch\API\Annotation\Mapping\Parameter;
 
 /**
- * @Document()
+ * @Entity()
  * @Mapping\Type("nested")
  * @Parameter\Dynamic(false)
  */

tests/Support/ElasticSearch/Dummy/PlainStructure.php

@@ -4,7 +4,7 @@
 
 namespace AmaTeam\ElasticSearch\Test\Support\ElasticSearch\Dummy;
 
-use AmaTeam\ElasticSearch\API\Annotation\Document;
+use AmaTeam\ElasticSearch\API\Annotation\Entity;
 use AmaTeam\ElasticSearch\API\Annotation\Mapping;
 use AmaTeam\ElasticSearch\API\Annotation\Mapping\Parameter;
 use AmaTeam\ElasticSearch\Mapping\Type\Parameter\IndexOptionsParameter;