├── .github
├── codecov.yml
├── dependabot.yml
└── workflows
│ ├── ci.yml
│ ├── deploy_docs_3x.yml
│ ├── deploy_docs_4x.yml
│ └── stale.yml
├── .phive
└── phars.xml
├── LICENSE.txt
├── README.md
├── composer.json
├── docker-compose.yml
├── docs
├── config
│ ├── __init__.py
│ └── all.py
├── en
│ ├── 3-0-upgrade-guide.rst
│ ├── 4-0-upgrade-guide.rst
│ ├── conf.py
│ ├── contents.rst
│ └── index.rst
├── fr
│ ├── conf.py
│ ├── contents.rst
│ └── index.rst
├── ja
│ ├── conf.py
│ ├── contents.rst
│ └── index.rst
└── pt
│ ├── conf.py
│ ├── contents.rst
│ └── index.rst
├── phpstan-baseline.neon
├── phpstan.neon
├── psalm-baseline.xml
├── psalm.xml
└── src
├── Association
├── EmbedMany.php
├── EmbedOne.php
└── Embedded.php
├── Datasource
├── Connection.php
├── IndexLocator.php
├── Log
│ └── ElasticLogger.php
├── MappingSchema.php
└── SchemaCollection.php
├── Document.php
├── Exception
├── MissingDocumentException.php
├── MissingIndexClassException.php
└── NotImplementedException.php
├── Index.php
├── IndexRegistry.php
├── Marshaller.php
├── Plugin.php
├── Query.php
├── QueryBuilder.php
├── ResultSet.php
├── Rule
└── IsUnique.php
├── TestSuite
├── Fixture
│ ├── DeleteQueryStrategy.php
│ └── MappingGenerator.php
├── TestCase.php
└── TestFixture.php
└── View
└── Form
└── DocumentContext.php
/.github/codecov.yml:
--------------------------------------------------------------------------------
1 | codecov:
2 | require_ci_to_pass: yes
3 |
4 | coverage:
5 | range: "90...100"
6 |
7 | comment: false
8 |
--------------------------------------------------------------------------------
/.github/dependabot.yml:
--------------------------------------------------------------------------------
1 | version: 2
2 | updates:
3 | - package-ecosystem: composer
4 | directory: "/"
5 | schedule:
6 | interval: daily
7 | open-pull-requests-limit: 10
8 | ignore:
9 | - dependency-name: phpunit/phpunit
10 | versions:
11 | - "> 6.0"
12 | - dependency-name: ruflin/elastica
13 | versions:
14 | - ">= 7.a, < 8"
15 |
--------------------------------------------------------------------------------
/.github/workflows/ci.yml:
--------------------------------------------------------------------------------
1 | name: CI
2 |
3 | on:
4 | push:
5 | branches:
6 | - 4.x
7 | pull_request:
8 | branches:
9 | - '*'
10 | workflow_dispatch:
11 |
12 | jobs:
13 | testsuite:
14 | runs-on: ubuntu-22.04
15 | strategy:
16 | fail-fast: false
17 | matrix:
18 | php-version: ['8.1']
19 | prefer-lowest: ['']
20 | include:
21 | - php-version: '8.1'
22 | prefer-lowest: 'prefer-lowest'
23 |
24 | services:
25 | elasticsearch:
26 | image: elasticsearch:7.17.8
27 | ports:
28 | - 9200/tcp
29 | env:
30 | discovery.type: single-node
31 | ES_JAVA_OPTS: -Xms500m -Xmx500m
32 | options: >-
33 | --health-cmd "curl http://127.0.0.1:9200/_cluster/health"
34 | --health-interval 10s
35 | --health-timeout 5s
36 | --health-retries 10
37 |
38 | steps:
39 | - uses: actions/checkout@v4
40 | with:
41 | persist-credentials: false
42 |
43 | - name: Setup PHP
44 | uses: shivammathur/setup-php@v2
45 | with:
46 | php-version: ${{ matrix.php-version }}
47 | extensions: mbstring, intl, apcu
48 | ini-values: apc.enable_cli = 1
49 | coverage: pcov
50 |
51 | - name: Get composer cache directory
52 | id: composer-cache
53 | run: echo "::set-output name=dir::$(composer config cache-files-dir)"
54 |
55 | - name: Get date part for cache key
56 | id: key-date
57 | run: echo "::set-output name=date::$(date +'%Y-%m')"
58 |
59 | - name: Cache composer dependencies
60 | uses: actions/cache@v4
61 | with:
62 | path: ${{ steps.composer-cache.outputs.dir }}
63 | key: ${{ runner.os }}-composer-${{ steps.key-date.outputs.date }}-${{ hashFiles('composer.json') }}-${{ matrix.prefer-lowest }}
64 |
65 | - name: Composer install
66 | run: |
67 | if ${{ matrix.prefer-lowest == 'prefer-lowest' }}; then
68 | composer update --prefer-lowest --prefer-stable
69 | else
70 | composer update
71 | fi
72 |
73 | - name: Setup problem matchers for PHPUnit
74 | if: matrix.php-version == '8.1'
75 | run: echo "::add-matcher::${{ runner.tool_cache }}/phpunit.json"
76 |
77 | - name: Run PHPUnit
78 | env:
79 | DB_URL: Cake\ElasticSearch\Datasource\Connection://127.0.0.1:${{ job.services.elasticsearch.ports['9200'] }}?driver=Cake\ElasticSearch\Datasource\Connection
80 | run: |
81 | if [[ ${{ matrix.php-version }} == '8.1' ]]; then
82 | export CODECOVERAGE=1 && vendor/bin/phpunit --display-incomplete --display-skipped --coverage-clover=coverage.xml
83 | else
84 | vendor/bin/phpunit
85 | fi
86 |
87 | - name: Submit code coverage
88 | if: matrix.php-version == '8.1'
89 | uses: codecov/codecov-action@v3
90 |
91 | cs-stan:
92 | name: Coding Standard & Static Analysis
93 | runs-on: ubuntu-22.04
94 |
95 | services:
96 | elasticsearch:
97 | image: elasticsearch:7.17.8
98 | ports:
99 | - 9200/tcp
100 | env:
101 | discovery.type: single-node
102 | ES_JAVA_OPTS: -Xms500m -Xmx500m
103 | options: >-
104 | --health-cmd "curl http://127.0.0.1:9200/_cluster/health"
105 | --health-interval 10s
106 | --health-timeout 5s
107 | --health-retries 10
108 |
109 | steps:
110 | - uses: actions/checkout@v4
111 | with:
112 | persist-credentials: false
113 |
114 | - name: Setup PHP
115 | uses: shivammathur/setup-php@v2
116 | with:
117 | php-version: '8.1'
118 | extensions: mbstring, intl, apcu
119 | tools: cs2pr
120 | coverage: none
121 |
122 | - name: Composer install
123 | uses: ramsey/composer-install@v2
124 |
125 | - name: Install PHIVE
126 | uses: szepeviktor/phive@v1
127 | with:
128 | home: ${{ runner.temp }}/.phive
129 | binPath: ${{ github.workspace }}/tools/phive
130 |
131 | - name: Stan setup
132 | uses: szepeviktor/phive-install@v1
133 | with:
134 | home: ${{ runner.temp }}/.phive
135 | binPath: ${{ github.workspace }}/tools/phive
136 | trustGpgKeys: "CF1A108D0E7AE720,12CE0F1D262429A5,51C67305FFC2E5C0"
137 |
138 | - name: Run PHP CodeSniffer
139 | run: vendor/bin/phpcs --report=checkstyle src/ tests/ | cs2pr
140 |
141 | - name: Run psalm
142 | env:
143 | DB_URL: Cake\ElasticSearch\Datasource\Connection://127.0.0.1:${{ job.services.elasticsearch.ports['9200'] }}?driver=Cake\ElasticSearch\Datasource\Connection
144 | if: always()
145 | run: tools/psalm --output-format=github
146 |
147 | - name: Run phpstan
148 | env:
149 | DB_URL: Cake\ElasticSearch\Datasource\Connection://127.0.0.1:${{ job.services.elasticsearch.ports['9200'] }}?driver=Cake\ElasticSearch\Datasource\Connection
150 | if: always()
151 | run: tools/phpstan analyse --error-format=github
152 |
--------------------------------------------------------------------------------
/.github/workflows/deploy_docs_3x.yml:
--------------------------------------------------------------------------------
1 | ---
2 | name: 'deploy_docs_3x'
3 |
4 | on:
5 | push:
6 | branches:
7 | - 3.x
8 | workflow_dispatch:
9 |
10 | jobs:
11 | deploy:
12 | runs-on: ubuntu-latest
13 | steps:
14 | - name: Cloning repo
15 | uses: actions/checkout@v2
16 | with:
17 | fetch-depth: 0
18 |
19 | - name: Push to dokku
20 | uses: dokku/github-action@master
21 | with:
22 | git_remote_url: 'ssh://dokku@apps.cakephp.org:22/elasticsearch-docs-3'
23 | ssh_private_key: ${{ secrets.DOKKU_SSH_PRIVATE_KEY }}
24 |
--------------------------------------------------------------------------------
/.github/workflows/deploy_docs_4x.yml:
--------------------------------------------------------------------------------
1 | ---
2 | name: 'deploy_docs_4x'
3 |
4 | on:
5 | push:
6 | branches:
7 | - 4.x
8 | workflow_dispatch:
9 |
10 | jobs:
11 | deploy:
12 | runs-on: ubuntu-latest
13 | steps:
14 | - name: Cloning repo
15 | uses: actions/checkout@v2
16 | with:
17 | fetch-depth: 0
18 |
19 | - name: Push to dokku
20 | uses: dokku/github-action@master
21 | with:
22 | git_remote_url: 'ssh://dokku@apps.cakephp.org:22/elasticsearch-docs-4'
23 | ssh_private_key: ${{ secrets.DOKKU_SSH_PRIVATE_KEY }}
24 |
--------------------------------------------------------------------------------
/.github/workflows/stale.yml:
--------------------------------------------------------------------------------
1 | name: Mark stale issues and pull requests
2 |
3 | on:
4 | schedule:
5 | - cron: "0 0 * * *"
6 |
7 | jobs:
8 | stale:
9 |
10 | runs-on: ubuntu-latest
11 |
12 | steps:
13 | - uses: actions/stale@v1
14 | with:
15 | repo-token: ${{ secrets.GITHUB_TOKEN }}
16 | stale-issue-message: 'This issue is stale because it has been open for 120 days with no activity. Remove the `stale` label or comment or this will be closed in 15 days'
17 | stale-pr-message: 'This pull request is stale because it has been open 30 days with no activity. Remove the `stale` label or comment on this issue, or it will be closed in 15 days'
18 | stale-issue-label: 'stale'
19 | stale-pr-label: 'stale'
20 | days-before-stale: 120
21 | days-before-close: 15
22 | exempt-issue-label: 'pinned'
23 | exempt-pr-label: 'pinned'
24 |
--------------------------------------------------------------------------------
/.phive/phars.xml:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
--------------------------------------------------------------------------------
/LICENSE.txt:
--------------------------------------------------------------------------------
1 | The MIT License
2 |
3 | CakePHP(tm) : The Rapid Development PHP Framework (https://cakephp.org)
4 | Copyright (c) 2005-present, Cake Software Foundation, Inc.
5 |
6 | Permission is hereby granted, free of charge, to any person obtaining a
7 | copy of this software and associated documentation files (the "Software"),
8 | to deal in the Software without restriction, including without limitation
9 | the rights to use, copy, modify, merge, publish, distribute, sublicense,
10 | and/or sell copies of the Software, and to permit persons to whom the
11 | Software is furnished to do so, subject to the following conditions:
12 |
13 | The above copyright notice and this permission notice shall be included in
14 | all copies or substantial portions of the Software.
15 |
16 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21 | FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
22 | DEALINGS IN THE SOFTWARE.
23 |
24 | Cake Software Foundation, Inc.
25 | 1785 E. Sahara Avenue,
26 | Suite 490-204
27 | Las Vegas, Nevada 89104,
28 | United States of America.
29 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Elasticsearch Datasource for CakePHP
2 |
3 | 
4 | [](https://packagist.org/packages/cakephp/elastic-search)
5 | [](https://packagist.org/packages/cakephp/elastic-search/stats)
6 | [](https://coveralls.io/r/cakephp/elastic-search?branch=master)
7 | [](LICENSE)
8 |
9 | Use [Elastic Search](https://www.elastic.co/) as an alternative ORM backend in CakePHP 5.0+.
10 |
11 | You can [find the documentation for the plugin in the Cake Book](https://book.cakephp.org/elasticsearch).
12 |
13 | ## Installing Elasticsearch via composer
14 |
15 | You can install Elasticsearch into your project using
16 | [composer](https://getcomposer.org). For existing applications you can add the
17 | following to your `composer.json` file:
18 |
19 | "require": {
20 | "cakephp/elastic-search": "^4.0"
21 | }
22 |
23 | And run `php composer.phar update`
24 |
25 | ### Versions Table
26 |
27 | | Cake\ElasticSearch | CakePHP | ElasticSearch |
28 | | --- | --- | --- |
29 | | [1.x](https://github.com/cakephp/elastic-search/tree/1.0) | 3.0 - 3.5 | 2.x - 5.x |
30 | | [2.x](https://github.com/cakephp/elastic-search/tree/2.x) | 3.6+ | 6.x |
31 | | [>3, <3.4.0](https://github.com/cakephp/elastic-search/tree/3.3.0) | 4.0+ | 6.x |
32 | | [>=3.4.0](https://github.com/cakephp/elastic-search/tree/3.x) | 4.0+ | 7.x |
33 | | [4.x](https://github.com/cakephp/elastic-search/tree/4.x) | 5.0+ | 7.x |
34 |
35 | You are seeing the 3.x version.
36 |
37 | ## Connecting the Plugin to your Application
38 |
39 | After installing, you should tell your application to load the plugin:
40 |
41 | ```php
42 | use Cake\ElasticSearch\Plugin as ElasticSearchPlugin;
43 |
44 | class Application extends BaseApplication
45 | {
46 | public function bootstrap()
47 | {
48 | $this->addPlugin(ElasticSearchPlugin::class);
49 |
50 | // If you want to disable to automatically configure the Elastic model provider
51 | // and FormHelper do the following:
52 | // $this->addPlugin(ElasticSearchPlugin::class, [ 'bootstrap' => false ]);
53 | }
54 | }
55 | ```
56 |
57 | ## Defining a connection
58 |
59 | Before you can do any work with Elasticsearch models, you'll need to define
60 | a connection:
61 |
62 | ```php
63 | // in config/app.php
64 | 'Datasources' => [
65 | // other datasources
66 | 'elastic' => [
67 | 'className' => 'Cake\ElasticSearch\Datasource\Connection',
68 | 'driver' => 'Cake\ElasticSearch\Datasource\Connection',
69 | 'host' => '127.0.0.1',
70 | 'port' => 9200
71 | ],
72 | ]
73 | ```
74 | As an alternative you could use a link format if you like to use enviroment variables for example.
75 |
76 | ```php
77 | // in config/app.php
78 | 'Datasources' => [
79 | // other datasources
80 | 'elastic' => [
81 | 'url' => env('ELASTIC_URL', null)
82 | ]
83 | ]
84 |
85 | // and make sure the folowing env variable is available:
86 | // ELASTIC_URL="Cake\ElasticSearch\Datasource\Connection://127.0.0.1:9200?driver=Cake\ElasticSearch\Datasource\Connection"
87 | ```
88 |
89 | You can enable request logging by setting the `log` config option to true. By
90 | default the `debug` Log profile will be used. You can also
91 | define an `elasticsearch` log profile in `Cake\Log\Log` to customize where
92 | Elasticsearch query logs will go. Query logging is done at a 'debug' level.
93 |
94 | ## Getting a Index object
95 |
96 | Index objects are the equivalent of `ORM\Table` instances in elastic search. You can
97 | use the `IndexRegistry` factory to get instances, much like `TableRegistry`:
98 |
99 | ```php
100 | use Cake\ElasticSearch\IndexRegistry;
101 |
102 | $comments = IndexRegistry::get('Comments');
103 | ```
104 |
105 | If you have loaded the plugin with bootstrap enabled you could load indexes using the model factory in your controllers
106 | ```php
107 | class SomeController extends AppController
108 | {
109 | public function initialize()
110 | {
111 | $this->loadModel('Comments', 'Elastic');
112 | }
113 |
114 | public function index()
115 | {
116 | $comments = $this->Comments->find();
117 | }
118 |
119 | ...
120 | ```
121 |
122 | Each `Index` object needs a correspondent Elasticsearch _index_, just like most of `ORM\Table` needs a database _table_.
123 |
124 | In the above example, if you have defined a class as `CommentsIndex` and the `IndexRegistry` can find it, the `$comments` will receive a initialized object with inner configurations of connection and index. But if you don't have that class, a default one will be initialized and the index name on Elasticsearch mapped to the class.
125 |
126 | ## The Index class
127 |
128 | You must create your own `Index` class to define the name of internal _index_
129 | for Elasticsearch, as well as to define the mapping type and define any entity
130 | properties you need like virtual properties. As you have to
131 | [use only one mapping type for each _index_](https://www.elastic.co/guide/en/elasticsearch/reference/master/removal-of-types.html),
132 | you can use the same name for both (the default behavior when _type_ is
133 | undefined is use singular version of _index_ name). Index types were removed
134 | in ElasticSearch 7.
135 |
136 | ```php
137 | use Cake\ElasticSearch\Index;
138 |
139 | class CommentsIndex extends Index
140 | {
141 | /**
142 | * The name of index in Elasticsearch
143 | *
144 | * @return string
145 | */
146 | public function getName()
147 | {
148 | return 'comments';
149 | }
150 | }
151 | ```
152 |
153 | ## Running tests
154 |
155 | We recommend using the included `docker-compose.yml` for doing local
156 | development. The `Dockerfile` contains the development environment, and an
157 | Elasticsearch container will be downloaded and started on port 9200.
158 |
159 | ```bash
160 | # Start elasticsearch
161 | docker-compose up -d
162 |
163 | # Open an terminal in the development environment
164 | docker-compose run console bash
165 | ```
166 |
167 | Once inside the container you can install dependencies and run tests.
168 |
169 | ```bash
170 | ./composer.phar install
171 | vendor/bin/phpunit
172 | ```
173 |
174 | **Warning**: Please, be very carefully when running tests as the Fixture will
175 | create and drop Elasticsearch indexes for its internal structure. Don't run tests
176 | in production or development machines where you have important data into your
177 | Elasticsearch instance.
178 |
179 | Assuming you have PHPUnit installed system wide using one of the methods stated
180 | [here](https://phpunit.de/manual/current/en/installation.html), you can run the
181 | tests for CakePHP by doing the following:
182 |
183 | 1. Copy `phpunit.xml.dist` to `phpunit.xml`
184 | 2. Run `phpunit`
185 |
--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "cakephp/elastic-search",
3 | "description": "An Elastic Search datasource and data mapper for CakePHP",
4 | "type": "cakephp-plugin",
5 | "keywords": ["cakephp", "elasticsearch"],
6 | "homepage": "https://github.com/cakephp/elastic-search",
7 | "license": "MIT",
8 | "authors": [
9 | {
10 | "name": "CakePHP Community",
11 | "homepage": "https://github.com/cakephp/elastic-search/graphs/contributors"
12 | }
13 | ],
14 | "support": {
15 | "issues": "https://github.com/cakephp/elastic-search/issues",
16 | "forum": "https://stackoverflow.com/tags/cakephp",
17 | "irc": "irc://irc.freenode.org/cakephp",
18 | "source": "https://github.com/cakephp/elastic-search"
19 | },
20 | "require": {
21 | "cakephp/cakephp": "^5.0.0",
22 | "ruflin/elastica": "^7.1"
23 | },
24 | "require-dev": {
25 | "cakephp/cakephp-codesniffer": "^5.0",
26 | "phpunit/phpunit": "^10.1.0"
27 | },
28 | "autoload": {
29 | "psr-4": {
30 | "Cake\\ElasticSearch\\": "src"
31 | }
32 | },
33 | "autoload-dev": {
34 | "psr-4": {
35 | "Cake\\ElasticSearch\\Test\\": "tests",
36 | "TestApp\\": "tests/testapp/TestApp/src/",
37 | "TestPlugin\\": "tests/testapp/Plugin/TestPlugin/src",
38 | "TestPluginTwo\\": "tests/testapp/Plugin/TestPluginTwo/src"
39 | }
40 | },
41 | "config": {
42 | "allow-plugins": {
43 | "dealerdirect/phpcodesniffer-composer-installer": true
44 | }
45 | },
46 | "scripts": {
47 | "check": [
48 | "@test",
49 | "@cs-check"
50 | ],
51 | "cs-check": "phpcs --colors -p ./src ./tests",
52 | "cs-fix": "phpcbf --colors -p src/ tests/",
53 | "test": "phpunit --colors=always",
54 | "stan": [
55 | "@phpstan",
56 | "@psalm"
57 | ],
58 | "phpstan": "tools/phpstan analyse",
59 | "psalm": "tools/psalm --show-info=false",
60 | "phpstan-baseline": "tools/phpstan --generate-baseline",
61 | "psalm-baseline": "tools/psalm --set-baseline=psalm-baseline.xml",
62 | "stan-setup": "phive install"
63 | }
64 | }
65 |
--------------------------------------------------------------------------------
/docker-compose.yml:
--------------------------------------------------------------------------------
1 | version: "3.9"
2 | services:
3 | console:
4 | build: "."
5 | environment:
6 | DB_URL: "Cake\\ElasticSearch\\Datasource\\Connection://elasticsearch:9200?driver=Cake\\ElasticSearch\\Datasource\\Connection"
7 | volumes:
8 | - .:/code
9 | elasticsearch:
10 | image: "elasticsearch:7.17.4"
11 | ports:
12 | - 9200/tcp
13 | environment:
14 | discovery.type: single-node
15 | ES_JAVA_OPTS: -Xms500m -Xmx500m
16 | healthcheck:
17 | test: "curl -f http://127.0.0.1:9200/_cluster/health || exit 1"
18 | interval: "10s"
19 | timeout: "5s"
20 | retries: 10
21 | start_period: "30s"
22 |
--------------------------------------------------------------------------------
/docs/config/__init__.py:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/cakephp/elastic-search/7614466266d6cd7260c7c89ae6f0eb4faa0dcd60/docs/config/__init__.py
--------------------------------------------------------------------------------
/docs/config/all.py:
--------------------------------------------------------------------------------
1 | # Global configuration information used across all the
2 | # translations of documentation.
3 | #
4 | # Import the base theme configuration
5 | from cakephpsphinx.config.all import *
6 |
7 | # The version info for the project you're documenting, acts as replacement for
8 | # |version| and |release|, also used in various other places throughout the
9 | # built documents.
10 | #
11 |
12 | # The full version, including alpha/beta/rc tags.
13 | release = '4.x'
14 |
15 | # The search index version.
16 | search_version = 'elasticsearch-4'
17 |
18 | # The marketing display name for the book.
19 | version_name = ''
20 |
21 | # Project name shown in the black header bar
22 | project = 'CakePHP ElasticSearch'
23 |
24 | # Other versions that display in the version picker menu.
25 | version_list = [
26 | {'name': '4.x', 'number': '/elasticsearch/4', 'title': '4.x', 'current': True},
27 | {'name': '3.x', 'number': '/elasticsearch/3', 'title': '3.x',},
28 | {'name': '2.x', 'number': '/elasticsearch/2', 'title': '2.x'},
29 | ]
30 |
31 | # Languages available.
32 | languages = ['en', 'fr', 'ja', 'pt']
33 |
34 | # The GitHub branch name for this version of the docs
35 | # for edit links to point at.
36 | branch = '4.x'
37 |
38 | # Current version being built
39 | version = '4.x'
40 |
41 | show_root_link = True
42 |
43 | repository = 'cakephp/elastic-search'
44 |
45 | source_path = 'docs/'
46 |
47 | hide_page_contents = ('search', '404', 'contents')
48 |
--------------------------------------------------------------------------------
/docs/en/3-0-upgrade-guide.rst:
--------------------------------------------------------------------------------
1 | 3.0 Upgrade Guide
2 | #################
3 |
4 | If you are upgrading from an earlier version of this plugin, this page aims to
5 | collect all the changes you may need to make to your application while
6 | upgrading.
7 |
8 | Types Renamed to Indexes
9 | ========================
10 |
11 | Because of the changes made in elasticsearch 5 and 6, this plugin no longer
12 | supports multiple types in the same index. The impact of this is that all of
13 | your type classes need to be renamed to indexes. For example
14 | ``App\Model\Type\ArticlesType`` needs to become
15 | ``App\Model\Index\ArticlesIndex``. Furthermore, Index classes assume that the
16 | type mapping has the singular name of the index. For example the ``articles``
17 | index has a type mapping of ``article``.
18 |
19 | Breaking Changes
20 | ================
21 |
22 | * ``Index::entityClass()`` was removed. Use ``getEntityClass()`` or
23 | ``setEntityClass()`` instead.
24 | * ``ResultSet::hasFacets()`` was removed as elastica no longer exposes this
25 | method.
26 | * ``ResultSet::getFacets()`` was removed as elastica no longer exposes this
27 | method.
28 | * ``ResultSet::getFacets()`` was removed as elastica no longer exposes this
29 | method.
30 | * The ``Type`` base class is now ``Index``.
31 | * ``TypeRegistry`` is now ``IndexRegistry``.
32 |
--------------------------------------------------------------------------------
/docs/en/4-0-upgrade-guide.rst:
--------------------------------------------------------------------------------
1 | 4.0 Upgrade Guide
2 | #################
3 |
4 | .. warning::
5 | CakePHP ElasticSearch 4.x requires CakePHP 5.x.
6 |
7 | Breaking Changes
8 | ================
9 |
10 | * All methods have had native types added where possible. This improves type
11 | safety within this plugin but may cause errors with application code.
12 | * ``Query`` no longer uses ``Cake\ORM\QueryTrait``. This has allowed several
13 | unused methods to be removed.
14 | * ``Query::isEagerLoaded()``, and ``Query::eagerLoaded()`` were removed.
15 | Previously these methods were inherited from ``QueryTrait`` but served no
16 | purpose here.
17 |
18 |
19 | Indexes
20 | ======
21 |
22 | IndexRegistry has been deprecated.
23 |
24 | Old code example::
25 |
26 | use Cake\ElasticSearch\IndexRegistry;
27 |
28 | $articles = IndexRegistry::get('Articles');
29 |
30 |
31 | New code example::
32 |
33 | use Cake\Datasource\FactoryLocator;
34 |
35 | $articles = FactoryLocator::get('ElasticSearch')->get('Articles');
36 |
--------------------------------------------------------------------------------
/docs/en/conf.py:
--------------------------------------------------------------------------------
1 | import sys, os
2 |
3 | # Append the top level directory of the docs, so we can import from the config dir.
4 | sys.path.insert(0, os.path.abspath('..'))
5 |
6 | # Pull in all the configuration options defined in the global config file..
7 | from config.all import *
8 |
9 | # Language in use for this directory.
10 | language = 'en'
11 |
--------------------------------------------------------------------------------
/docs/en/contents.rst:
--------------------------------------------------------------------------------
1 | Contents
2 | ########
3 |
4 | .. toctree::
5 | :maxdepth: 2
6 | :caption: CakePHP ElasticSearch
7 |
8 | /index
9 | /3-0-upgrade-guide
10 | /4-0-upgrade-guide
11 |
--------------------------------------------------------------------------------
/docs/en/index.rst:
--------------------------------------------------------------------------------
1 | ElasticSearch
2 | #############
3 |
4 | The ElasticSearch plugin provides an ORM-like abstraction on top of
5 | `elasticsearch `_. The plugin
6 | provides features that make testing, indexing documents and searching your
7 | indexes easier.
8 |
9 | Installation
10 | ============
11 |
12 | To install the ElasticSearch plugin, you can use ``composer``. From your
13 | application's ROOT directory (where ``composer.json`` file is located) run the
14 | following::
15 |
16 | php composer.phar require cakephp/elastic-search "^4.0"
17 |
18 | You will need to add the following line to your application's
19 | **src/Application.php** file::
20 |
21 | $this->addPlugin('Cake/ElasticSearch');
22 |
23 | Additionally, you will need to configure the 'elastic' datasource connection in
24 | your **config/app.php** file. An example configuration would be::
25 |
26 | // in config/app.php
27 | 'Datasources' => [
28 | // other datasources
29 | 'elastic' => [
30 | 'className' => 'Cake\ElasticSearch\Datasource\Connection',
31 | 'driver' => 'Cake\ElasticSearch\Datasource\Connection',
32 | 'host' => '127.0.0.1',
33 | 'port' => 9200,
34 | 'index' => 'my_apps_index',
35 | ],
36 | ]
37 |
38 | If your endpoint requires https, use::
39 |
40 | 'port' => 443,
41 | 'transport' => 'https'
42 |
43 | or you might get a 400 response back from the elasticsearch server.
44 |
45 | Overview
46 | ========
47 |
48 | The ElasticSearch plugin makes it easier to interact with an elasticsearch index
49 | and provides an interface similar to the `ORM
50 | `__. To get started you should
51 | create an ``Index`` object. ``Index`` objects are the "Repository" or table-like
52 | class in elasticsearch::
53 |
54 | // in src/Model/Type/ArticlesIndex.php
55 | namespace App\Model\Index;
56 |
57 | use Cake\ElasticSearch\Index;
58 |
59 | class ArticlesIndex extends Index
60 | {
61 | }
62 |
63 | You can then use your index class in your controllers::
64 |
65 | public function beforeFilter(Event $event)
66 | {
67 | parent::beforeFilter($event);
68 | // Load the Index using the 'Elastic' provider.
69 | $this->loadModel('Articles', 'Elastic');
70 | }
71 |
72 | public function add()
73 | {
74 | $article = $this->Articles->newEntity();
75 | if ($this->request->is('post')) {
76 | $article = $this->Articles->patchEntity($article, $this->request->getData());
77 | if ($this->Articles->save($article)) {
78 | $this->Flash->success('It saved');
79 | }
80 | }
81 | $this->set(compact('article'));
82 | }
83 |
84 | We would also need to create a basic view for our indexed articles::
85 |
86 | // in src/Template/Articles/add.ctp
87 | Form->create($article) ?>
88 | Form->control('title') ?>
89 | Form->control('body') ?>
90 | Form->button('Save') ?>
91 | Form->end() ?>
92 |
93 | You should now be able to submit the form and have a new document added to
94 | elasticsearch.
95 |
96 | Document Objects
97 | ================
98 |
99 | Like the ORM, the Elasticsearch ODM uses ORM-like classes. The
100 | base class you should inherit from is ``Cake\ElasticSearch\Document``. Document
101 | classes are found in the ``Model\Document`` namespace in your application or
102 | plugin::
103 |
104 | namespace App\Model\Document;
105 |
106 | use Cake\ElasticSearch\Document;
107 |
108 | class Article extends Document
109 | {
110 | }
111 |
112 | Outside of constructor logic that makes Documents work with data from
113 | elasticsearch, the interface and functionality provided by ``Document`` are the
114 | same as those in `Entities
115 | `__
116 |
117 | Searching Indexed Documents
118 | ===========================
119 |
120 | After you've indexed some documents you will want to search through them. The
121 | ElasticSearch plugin provides a query builder that allows you to build search
122 | queries::
123 |
124 | $query = $this->Articles->find()
125 | ->where([
126 | 'title' => 'special',
127 | 'or' => [
128 | 'tags in' => ['cake', 'php'],
129 | 'tags not in' => ['c#', 'java']
130 | ]
131 | ]);
132 |
133 | foreach ($query as $article) {
134 | echo $article->title;
135 | }
136 |
137 | You can use the ``QueryBuilder`` to add filtering conditions::
138 |
139 | $query->where(function ($builder) {
140 | return $builder->and(
141 | $builder->gt('views', 99),
142 | $builder->term('author.name', 'sally')
143 | );
144 | });
145 |
146 | The `QueryBuilder source
147 | `_
148 | has the complete list of methods with examples for many commonly used methods.
149 |
150 | Validating Data & Using Application Rules
151 | =========================================
152 |
153 | Like the ORM, the ElasticSearch plugin lets you validate data when marshalling
154 | documents. Validating request data, and applying application rules works the
155 | same as it does with the relational ORM. See the `validating request data
156 | `__
157 | and `Application Rules
158 | `__
159 | sections for more information.
160 |
161 | .. Need information on nested validators.
162 |
163 | Saving New Documents
164 | ====================
165 |
166 | When you're ready to index some data into elasticsearch, you'll first need to
167 | convert your data into a ``Document`` that can be indexed::
168 |
169 | $article = $this->Articles->newEntity($data);
170 | if ($this->Articles->save($article)) {
171 | // Document was indexed
172 | }
173 |
174 | When marshalling a document, you can specify which embedded documents you wish
175 | to marshall using the ``associated`` key::
176 |
177 | $article = $this->Articles->newEntity($data, ['associated' => ['Comments']]);
178 |
179 | Saving a document will trigger the following events:
180 |
181 | * ``Model.beforeSave`` - Fired before the document is saved. You can prevent the
182 | save operation from happening by stopping this event.
183 | * ``Model.buildRules`` - Fired when the rules checker is built for the first
184 | time.
185 | * ``Model.afterSave`` - Fired after the document is saved.
186 |
187 | .. note::
188 | There are no events for embedded documents, as the parent document and all
189 | of its embedded documents are saved as one operation.
190 |
191 | Updating Existing Documents
192 | ===========================
193 |
194 | When you need to re-index data, you can patch existing entities and re-save
195 | them::
196 |
197 | $query = $this->Articles->find()->where(['user.name' => 'jill']);
198 | foreach ($query as $doc) {
199 | $doc->set($newProperties);
200 | $this->Articles->save($doc);
201 | }
202 |
203 | Additionally Elasticsearch ``refresh`` request can be triggered by passing
204 | ``'refresh' => true`` in the ``$options`` argument. A refresh makes recent
205 | operations performed on one or more indices available for search::
206 |
207 | $this->Articles->save($article, ['refresh' => true]);
208 |
209 | Saving Multiple Documents
210 | =========================
211 |
212 | Using this method you can bulk save multiple documents::
213 |
214 | $result = $this->Articles->saveMany($documents);
215 |
216 | Here ``$documents`` is an array of documents. The result will be ``true`` on success or ``false`` on failure.
217 | ``saveMany`` can have second argument with the same options as accepted by ``save()``.
218 |
219 |
220 | Deleting Documents
221 | ==================
222 |
223 | After retrieving a document you can delete it::
224 |
225 | $doc = $this->Articles->get($id);
226 | $this->Articles->delete($doc);
227 |
228 | You can also delete documents matching specific conditions::
229 |
230 | $this->Articles->deleteAll(['user.name' => 'bob']);
231 |
232 | Embedding Documents
233 | ===================
234 |
235 | By defining embedded documents, you can attach entity classes to specific
236 | property paths in your documents. This allows you to provide custom behavior to
237 | the documents within a parent document. For example, you may want the comments
238 | embedded in an article to have specific application specific methods. You can
239 | use ``embedOne`` and ``embedMany`` to define embedded documents::
240 |
241 | // in src/Model/Index/ArticlesIndex.php
242 | namespace App\Model\Index;
243 |
244 | use Cake\ElasticSearch\Index;
245 |
246 | class ArticlesIndex extends Index
247 | {
248 | public function initialize()
249 | {
250 | $this->embedOne('User');
251 | $this->embedMany('Comments', [
252 | 'entityClass' => 'MyComment'
253 | ]);
254 | }
255 | }
256 |
257 | The above would create two embedded documents on the ``Article`` document. The
258 | ``User`` embed will convert the ``user`` property to instances of
259 | ``App\Model\Document\User``. To get the Comments embed to use a class name
260 | that does not match the property name, we can use the ``entityClass`` option to
261 | configure a custom class name.
262 |
263 | Once we've setup our embedded documents, the results of ``find()`` and ``get()``
264 | will return objects with the correct embedded document classes::
265 |
266 | $article = $this->Articles->get($id);
267 | // Instance of App\Model\Document\User
268 | $article->user;
269 |
270 | // Array of App\Model\Document\Comment instances
271 | $article->comments;
272 |
273 | Configuring Connections
274 | =======================
275 |
276 | By default all index instances use the ``elastic`` connection. If your
277 | application uses multiple connections you will want to configure which
278 | index use which connections. This is the ``defaultConnectionName()`` method::
279 |
280 | namespace App\Model\Index;
281 |
282 | use Cake\ElasticSearch\Index;
283 |
284 | class ArticlesIndex extends Index
285 | {
286 | public static function defaultConnectionName() {
287 | return 'replica_db';
288 | }
289 | }
290 |
291 | .. note::
292 |
293 | The ``defaultConnectionName()`` method **must** be static.
294 |
295 | Getting Index Instances
296 | =======================
297 |
298 | Like the ORM, the ElasticSearch plugin provides a factory/registry for getting
299 | ``Index`` instances::
300 |
301 | use Cake\ElasticSearch\IndexRegistry;
302 |
303 | $articles = IndexRegistry::get('Articles');
304 |
305 | Flushing the Registry
306 | ---------------------
307 |
308 | During test cases you may want to flush the registry. Doing so is often useful
309 | when you are using mock objects, or modifying a index's dependencies::
310 |
311 | IndexRegistry::flush();
312 |
313 | Test Fixtures
314 | =============
315 |
316 | The ElasticSearch plugin provides a seamless test suite integration. Just like
317 | database fixtures, you can create test schema and fixture data elasticsearch.
318 | Much like database fixtures we load our Elasticsearch mappings during
319 | ``tests/bootstrap.php`` of our application::
320 |
321 | // In tests/bootstrap.php
322 | use Cake\Elasticsearch\TestSuite\Fixture\MappingGenerator;
323 |
324 | $generator = new MappingGenerator('tests/mappings.php', 'test_elastic');
325 | $generator->reload();
326 |
327 | The above will create the indexes and mappings defined in ``tests/mapping.php``
328 | and insert them into the ``test_elastic`` connection. The mappings in your
329 | ``mappings.php`` should return a list of mappings to create::
330 |
331 | // in tests/mappings.php
332 | return [
333 | [
334 | // The name of the index and mapping.
335 | 'name' => 'articles',
336 | // The schema for the mapping.
337 | 'mapping' => [
338 | 'id' => ['type' => 'integer'],
339 | 'title' => ['type' => 'text'],
340 | 'user_id' => ['type' => 'integer'],
341 | 'body' => ['type' => 'text'],
342 | 'created' => ['type' => 'date'],
343 | ],
344 | // Additional index settings.
345 | 'settings' => [
346 | 'number_of_shards' => 2,
347 | 'number_of_routing_shards' => 2,
348 | ],
349 | ],
350 | // ...
351 | ];
352 |
353 | Mappings use the `native elasticsearch mapping format
354 | `_.
355 | You can safely omit the type name and top level ``properties`` key. With our
356 | mappings loaded, we can define a test fixture for our Articles index with the
357 | following::
358 |
359 | namespace App\Test\Fixture;
360 |
361 | use Cake\ElasticSearch\TestSuite\TestFixture;
362 |
363 | /**
364 | * Articles fixture
365 | */
366 | class ArticlesFixture extends TestFixture
367 | {
368 | /**
369 | * The table/index for this fixture.
370 | *
371 | * @var string
372 | */
373 | public $table = 'articles';
374 |
375 | public $records = [
376 | [
377 | 'user' => [
378 | 'username' => 'billy'
379 | ],
380 | 'title' => 'First Post',
381 | 'body' => 'Some content'
382 | ]
383 | ];
384 | }
385 |
386 | .. versionchanged:: 3.4.0
387 | Prior to CakePHP 4.3.0 schema was defined on each fixture in the ``$schema``
388 | property.
389 |
390 | Once your fixtures are created you can use them in your test cases by including
391 | them in your test's ``fixtures`` properties::
392 |
393 | public $fixtures = ['app.Articles'];
394 |
--------------------------------------------------------------------------------
/docs/fr/conf.py:
--------------------------------------------------------------------------------
1 | import sys, os
2 |
3 | # Append the top level directory of the docs, so we can import from the config dir.
4 | sys.path.insert(0, os.path.abspath('..'))
5 |
6 | # Pull in all the configuration options defined in the global config file..
7 | from config.all import *
8 |
9 | # Language in use for this directory.
10 | language = 'fr'
11 |
--------------------------------------------------------------------------------
/docs/fr/contents.rst:
--------------------------------------------------------------------------------
1 | Contents
2 | ########
3 |
4 | .. toctree::
5 | :maxdepth: 2
6 | :caption: CakePHP ElasticSearch
7 |
8 | /index
9 |
--------------------------------------------------------------------------------
/docs/fr/index.rst:
--------------------------------------------------------------------------------
1 | ElasticSearch
2 | #############
3 |
4 | Le plugin ElasticSearch fournit une abstraction de type ORM au-dessus de
5 | `elasticsearch `_. Le plugin
6 | fournit des fonctionnalités qui facilitent les tests, l'indexation des
7 | documents et la recherche de vos index.
8 |
9 | Installation
10 | ============
11 |
12 | Pour installer le plugin elasticsearch, vous pouvez utiliser ``composer``.
13 | A partir du répertoire ROOT de votre application (où se trouve le fichier
14 | composer.json), lancez ce qui suit::
15 |
16 | php composer.phar require cakephp/elastic-search "@stable"
17 |
18 | Vous devrez ajouter la ligne suivante au fichier **config/bootstrap.php** de
19 | votre application::
20 |
21 | Plugin::load('Cake/ElasticSearch', ['bootstrap' => true]);
22 |
23 | De plus, vous devrez configurer la connection à la source de donnée 'elastic'
24 | dans votre fichier **config/app.php**. Un exemple de configuration serait::
25 |
26 | // Dans config/app.php
27 | 'Datasources' => [
28 | // Autres sources de données
29 | 'elastic' => [
30 | 'className' => 'Cake\ElasticSearch\Datasource\Connection',
31 | 'driver' => 'Cake\ElasticSearch\Datasource\Connection',
32 | 'host' => '127.0.0.1',
33 | 'port' => 9200,
34 | 'index' => 'my_apps_index',
35 | ],
36 | ]
37 |
38 | Vue d'Ensemble
39 | ==============
40 |
41 | Le plugin elasticsearch facilite l'interaction avec un index elasticsearch
42 | et fournit une interface similaire à celle de l'`ORM
43 | `__. Pour commencer,
44 | vous devrez créer un objet ``Type``. Les objets ``Type`` sont le "Repository"
45 | ou la classe de type table dans elasticsearch::
46 |
47 | // Dans src/Model/Type/ArticlesType.php
48 | namespace App\Model\Type;
49 |
50 | use Cake\ElasticSearch\Type;
51 |
52 | class ArticlesType extends Type
53 | {
54 | }
55 |
56 | Vous pouvez utiliser votre classe type dans vos controllers::
57 |
58 | public function beforeFilter(Event $event)
59 | {
60 | parent::beforeFilter($event);
61 | // Charge le Type en utilisant le provider 'Elastic'.
62 | $this->loadModel('Articles', 'Elastic');
63 | }
64 |
65 | public function add()
66 | {
67 | $article = $this->Articles->newEntity();
68 | if ($this->request->is('post')) {
69 | $article = $this->Articles->patchEntity($article, $this->request->getData());
70 | if ($this->Articles->save($article)) {
71 | $this->Flash->success('It saved');
72 | }
73 | }
74 | $this->set(compact('article'));
75 | }
76 |
77 | Nous devrons aussi créer une vue basique pour nos articles indexés::
78 |
79 | // Dans src/Template/Articles/add.ctp
80 | Form->create($article) ?>
81 | Form->control('title') ?>
82 | Form->control('body') ?>
83 | Form->button('Save') ?>
84 | Form->end() ?>
85 |
86 | Vous devriez maintenant pouvoir soumettre le formulaire et avoir un nouveau
87 | document ajouté à elasticsearch.
88 |
89 | Objets Document
90 | ===============
91 |
92 | Comme l'ORM, l'ODM Elasticsearch utilise les classes de type `Entities
93 | `__ . La classe de base que
94 | vous devrez hériter est ``Cake\ElasticSearch\Document``. Les classes de Document
95 | se trouvent dans le namespace ``Model\Document`` dans votre application ou votre
96 | plugin::
97 |
98 | namespace App\Model\Document;
99 |
100 | use Cake\ElasticSearch\Document;
101 |
102 | class Article extends Document
103 | {
104 | }
105 |
106 | En dehors de la logique de constructeur qui fait fonctionner les Documents avec
107 | les données de elasticsearch, l'interface et les fonctionnalités fournies par
108 | ``Document`` sont les mêmes que celles des `Entities `__.
109 |
110 | Recherche des Documents Indexés
111 | ===============================
112 |
113 | Après avoir indexé quelques documents, vous voudrez chercher parmi ceux-ci. Le
114 | plugin elasticsearch fournit un constructeur de requête qui vous permet de
115 | construire les requêtes de recherche::
116 |
117 | $query = $this->Articles->find()
118 | ->where([
119 | 'title' => 'special',
120 | 'or' => [
121 | 'tags in' => ['cake', 'php'],
122 | 'tags not in' => ['c#', 'java']
123 | ]
124 | ]);
125 |
126 | foreach ($query as $article) {
127 | echo $article->title;
128 | }
129 |
130 | Vous pouvez utiliser le ``QueryBuilder`` pour ajouter des conditions de
131 | filtrage::
132 |
133 | $query->where(function ($builder) {
134 | return $builder->and(
135 | $builder->gt('views', 99),
136 | $builder->term('author.name', 'sally')
137 | );
138 | });
139 |
140 | La `source de QueryBuilder
141 | `_
142 | a la liste complète des méthodes avec des exemples pour beaucoup de méthodes
143 | couramment utilisées.
144 |
145 | Validation des Données & Utilisation des Règles d'Application
146 | =============================================================
147 |
148 | Comme pour l'ORM, le plugin ElasticSearch vous laisse valider les données
149 | lors de la prise en compte des documents. Valider les données requêtées, et
150 | appliquer les règles d'application fonctionne de la même façon que pour
151 | l'ORM relationnel. Regardez les sections `Valider les Données Avant de Construire les Entities
152 | `__
153 | et `Appliquer des Règles pour l’Application `__ s pour plus d'informations.
154 |
155 | Sauvegarder les Nouveaux Documents
156 | ==================================
157 |
158 | Quand vous êtes prêt à indexer quelques données dans elasticsearch, vous
159 | devrez d'abord convertir vos données dans un ``Document`` qui peut être
160 | indexé::
161 |
162 | $article = $this->Articles->newEntity($data);
163 | if ($this->Articles->save($article)) {
164 | // Document a été indexé
165 | }
166 |
167 | Lors de la prise en compte d'un document, vous pouvez spécifier les documents
168 | intégrés que vous souhaitez prendre en compte en utilisant la clé
169 | ``associated``::
170 |
171 | $article = $this->Articles->newEntity($data, ['associated' => ['Comments']]);
172 |
173 | Sauvegarder un document va récupérer les events suivants:
174 |
175 | * ``Model.beforeSave`` - Lancé avant que le document ne soit sauvegardé. En
176 | stoppant cet event, vous pouvez empêcher l'opération de sauvegarde de se
177 | produire.
178 | * ``Model.buildRules`` - Lancé quand les vérificateurs de règles sont
179 | construits pour la première fois.
180 | * ``Model.afterSave`` - Lancé après que le document est sauvegardé.
181 |
182 | .. note::
183 | Il n'y a pas d'events pour les documents intégrés, puisque le document
184 | parent et tous ses documents intégrés sont sauvegardés en une opération.
185 |
186 | Mettre à Jour les Documents Existants
187 | =====================================
188 |
189 | Quand vous devez réindexer les données, vous pouvez patch les entities
190 | existantes et les re-sauvegarder::
191 |
192 | $query = $this->Articles->find()->where(['user.name' => 'jill']);
193 | foreach ($query as $doc) {
194 | $doc->set($newProperties);
195 | $this->Articles->save($doc);
196 | }
197 |
198 | Supprimer les Documents
199 | =======================
200 |
201 | Après la récupération d'un document, vous pouvez le supprimer::
202 |
203 | $doc = $this->Articles->get($id);
204 | $this->Articles->delete($doc);
205 |
206 | Vous pouvez aussi supprimer les documents qui matchent des conditions
207 | spécifiques::
208 |
209 | $this->Articles->deleteAll(['user.name' => 'bob']);
210 |
211 | Documents Intégrés
212 | ==================
213 |
214 | En définissant les documents intégrés, vous pouvez attacher des classes entity
215 | à des chemins de propriété spécifique dans vos documents. Ceci vous permet
216 | de fournir un comportement personnalisé pour les documents dans un document
217 | parent. Par exemple, vous pouvez vouloir les commentaires intégrés à un
218 | article pour avoir des méthodes spécifiques selon l'application. Vous pouvez
219 | utiliser ``embedOne`` et ``embedMany`` pour définir les documents intégrés::
220 |
221 | // Dans src/Model/Type/ArticlesType.php
222 | namespace App\Model\Type;
223 |
224 | use Cake\ElasticSearch\Type;
225 |
226 | class ArticlesType extends Type
227 | {
228 | public function initialize()
229 | {
230 | $this->embedOne('User');
231 | $this->embedMany('Comments', [
232 | 'entityClass' => 'MyComment'
233 | ]);
234 | }
235 | }
236 |
237 | Ce qui au-dessus va créer deux documents intégrés sur le document ``Article``.
238 | L'``User`` intégré va convertir la propriété ``user`` en instances de
239 | ``App\Model\Document\User``. Pour récupérer les Commentaires intégrés et
240 | utiliser un nom de classe qui ne correspond pas au nom de la propriété, nous
241 | pouvons utiliser l'option ``entityClass`` pour configurer un nom de classe
242 | personnalisé.
243 |
244 | Une fois que vous avez configuré nos documents intégrés, les résultats de
245 | ``find()`` et ``get()`` vont retourner les objets avec les bonnes classes
246 | de document intégré::
247 |
248 | $article = $this->Articles->get($id);
249 | // Instance de App\Model\Document\User
250 | $article->user;
251 |
252 | // Array des instances App\Model\Document\Comment
253 | $article->comments;
254 |
255 | Récupérer les Instances Type
256 | ============================
257 |
258 | Comme pour l'ORM, le plugin elasticsearch fournit un factory/registre pour
259 | récupérer les instances ``Type``::
260 |
261 | use Cake\ElasticSearch\TypeRegistry;
262 |
263 | $articles = TypeRegistry::get('Articles');
264 |
265 | Nettoyer le Registre
266 | --------------------
267 |
268 | Pendant les cas de test, vous voudrez nettoyer le registre. Faire cela est
269 | souvent utile quand vous utilisez les objets de mock, ou quand vous modifiez
270 | les dépendances d'un type::
271 |
272 | TypeRegistry::flush();
273 |
274 | Fixtures de Test
275 | ================
276 |
277 | Le plugin elasticsearch fournit seamless test suite integration. Un peu comme
278 | les fixtures de base de données, vous pouvez créer des fixtures de test pour
279 | elasticsearch. Nous pourrions définir une fixture de test pour notre type
280 | Articles avec ce qui suit::
281 |
282 | namespace App\Test\Fixture;
283 |
284 | use Cake\ElasticSearch\TestSuite\TestFixture;
285 |
286 | /**
287 | * Articles fixture
288 | */
289 | class ArticlesFixture extends TestFixture
290 | {
291 | /**
292 | * La table/type pour cette fixture.
293 | *
294 | * @var string
295 | */
296 | public $table = 'articles';
297 |
298 | /**
299 | * The mapping data.
300 | *
301 | * @var array
302 | */
303 | public $schema = [
304 | 'id' => ['type' => 'integer'],
305 | 'user' => [
306 | 'type' => 'nested',
307 | 'properties' => [
308 | 'username' => ['type' => 'string'],
309 | ]
310 | ]
311 | 'title' => ['type' => 'string'],
312 | 'body' => ['type' => 'string'],
313 | ];
314 |
315 | public $records = [
316 | [
317 | 'user' => [
318 | 'username' => 'billy'
319 | ],
320 | 'title' => 'First Post',
321 | 'body' => 'Some content'
322 | ]
323 | ];
324 | }
325 |
326 | La propriété ``schema`` utilise le format de mapping `natif d'elasticsearch
327 | `_.
328 | Vous pouvez sans problème ne pas mettre le nom du type et la clé de niveau
329 | supérieur ``properties``. Une fois que vos fixtures sont créées, vous pouvez les
330 | utiliser dans vos cas de test en les incluant dans vos propriétés de test
331 | ``fixtures``::
332 |
333 | public $fixtures = ['app.articles'];
334 |
--------------------------------------------------------------------------------
/docs/ja/conf.py:
--------------------------------------------------------------------------------
1 | import sys, os
2 |
3 | # Append the top level directory of the docs, so we can import from the config dir.
4 | sys.path.insert(0, os.path.abspath('..'))
5 |
6 | # Pull in all the configuration options defined in the global config file..
7 | from config.all import *
8 |
9 | # Language in use for this directory.
10 | language = 'ja'
11 |
--------------------------------------------------------------------------------
/docs/ja/contents.rst:
--------------------------------------------------------------------------------
1 | Contents
2 | ########
3 |
4 | .. toctree::
5 | :maxdepth: 2
6 | :caption: CakePHP ElasticSearch
7 |
8 | /index
9 |
--------------------------------------------------------------------------------
/docs/ja/index.rst:
--------------------------------------------------------------------------------
1 | ElasticSearch
2 | #############
3 |
4 | ElasticSearch プラグインは、`elasticsearch `_
5 | の上に ORM のような抽象化を提供します。そのプラグインは、テストの作成、
6 | ドキュメントのインデックス作成、インデックスをより簡単に検索などの機能を提供します。
7 |
8 | インストール
9 | ============
10 |
11 | ElasticSearch プラグインをインストールするには、 ``composer`` が利用できます。(composer.json
12 | ファイルが置かれている) アプリケーションの ROOT ディレクトリーから次のコマンドを実行します。 ::
13 |
14 | php composer.phar require cakephp/elastic-search "@stable"
15 |
16 | 以下の1行をあなたのアプリケーションの **src/Application.php** ファイルに追加する必要があります。 ::
17 |
18 | $this->addPlugin('Cake/ElasticSearch', ['bootstrap' => true]);
19 |
20 | // 3.6.0 より前は、Plugin::load() を使用する必要があります
21 |
22 | 追加で 'elastic' のデータソースの接続を **config/app.php** ファイルに設定する必要があります。
23 | 設定例は以下のようになります。 ::
24 |
25 | // config/app.php の中で
26 | 'Datasources' => [
27 | // 他のデータソース
28 | 'elastic' => [
29 | 'className' => 'Cake\ElasticSearch\Datasource\Connection',
30 | 'driver' => 'Cake\ElasticSearch\Datasource\Connection',
31 | 'host' => '127.0.0.1',
32 | 'port' => 9200,
33 | 'index' => 'my_apps_index',
34 | ],
35 | ]
36 |
37 | 概要
38 | ====
39 |
40 | ElasticSearch プラグインは elasticsearch インデックスと作用することを簡単にし、
41 | `ORM `__ に似たインターフェイスを提供します。まず最初に ``Type`` オブジェクトを
42 | 作成しなければいけません。 ``Type`` オブジェクトは elasticsearch 内では "Repository"
43 | もしくは Table のようなクラスです。 ::
44 |
45 | // src/Model/Type/ArticlesType.php の中で
46 | namespace App\Model\Type;
47 |
48 | use Cake\ElasticSearch\Type;
49 |
50 | class ArticlesType extends Type
51 | {
52 | }
53 |
54 | コントローラーで Type クラスを利用できます。 ::
55 |
56 | public function beforeFilter(Event $event)
57 | {
58 | parent::beforeFilter($event);
59 | // 'Elastic' プロバイダーを利用して Type を読み込む
60 | $this->loadModel('Articles', 'Elastic');
61 | }
62 |
63 | public function add()
64 | {
65 | $article = $this->Articles->newEntity();
66 | if ($this->request->is('post')) {
67 | $article = $this->Articles->patchEntity($article, $this->request->getData());
68 | if ($this->Articles->save($article)) {
69 | $this->Flash->success('It saved');
70 | }
71 | }
72 | $this->set(compact('article'));
73 | }
74 |
75 | インデックスされた articles の基本的なビューを作成する必要があります。 ::
76 |
77 | // src/Template/Articles/add.ctp の中で
78 | Form->create($article) ?>
79 | Form->control('title') ?>
80 | Form->control('body') ?>
81 | Form->button('Save') ?>
82 | Form->end() ?>
83 |
84 | これで、フォームの送信が可能になり、新しいドキュメントが elasticsearch に追加されました。
85 |
86 | Document オブジェクト
87 | =====================
88 |
89 | ORM と同様に、Elasticsearch ODM は `エンティティー `__ のようなクラスを使用しています。
90 | 継承しなければならない基底クラスは ``Cake\ElasticSearch\Document`` です。
91 | Document クラスは、アプリケーションやプラグイン内の ``Model\Document`` 名前空間に配置します。 ::
92 |
93 | namespace App\Model\Document;
94 |
95 | use Cake\ElasticSearch\Document;
96 |
97 | class Article extends Document
98 | {
99 | }
100 |
101 | elasticsearch からのデータで Document を動作させるコンストラクターロジックの外側、
102 | インターフェイスと ``Document`` によって提供される機能は、 `Entities
103 | `__
104 | 内にあるものと同じです。
105 |
106 | インデックス付きドキュメントの検索
107 | ==================================
108 |
109 | いくつかのドキュメントをインデックスに登録した後、あなたはそれらを検索したいと思うでしょう。
110 | ElasticSearch プラグインを使用すると、検索クエリーを構築するためのクエリービルダーを提供します。 ::
111 |
112 | $query = $this->Articles->find()
113 | ->where([
114 | 'title' => 'special',
115 | 'or' => [
116 | 'tags in' => ['cake', 'php'],
117 | 'tags not in' => ['c#', 'java']
118 | ]
119 | ]);
120 |
121 | foreach ($query as $article) {
122 | echo $article->title;
123 | }
124 |
125 | フィルタリング条件を追加するために ``QueryBuilder`` を使用することができます。 ::
126 |
127 | $query->where(function ($builder) {
128 | return $builder->and(
129 | $builder->gt('views', 99),
130 | $builder->term('author.name', 'sally')
131 | );
132 | });
133 |
134 | `QueryBuilder のソース
135 | `_
136 | は、多くの一般的に使用されるメソッドの例となるメソッドの完全なリストを持っています。
137 |
138 | データのバリデーションとアプリケーションルールの使用
139 | ====================================================
140 |
141 | ORMと同様に、ElasticSearch プラグインは、ドキュメントをマーシャリングするときに
142 | データを検証することができます。リクエストデータのバリデート、およびアプリケーションルールの
143 | 適用は、リレーショナルORMと同じ動作をします。詳細については、 `エンティティー構築前のデータ検証 `__ と
144 | `条件付き/動的なエラーメッセージ `__ のセクションをご覧ください。
145 |
146 | .. ネストされたバリデータに関する情報を必要としています。
147 |
148 | 新しいドキュメントの保存
149 | ========================
150 |
151 | elasticsearch にいくつかのデータをインデックスする準備ができたら、最初にインデックスが付けられる
152 | ``Document`` にデータを変換する必要があります。 ::
153 |
154 | $article = $this->Articles->newEntity($data);
155 | if ($this->Articles->save($article)) {
156 | // Document はインデックスされました
157 | }
158 |
159 | ドキュメントをマーシャリングするとき、 ``associated`` キーを使用してマーシャリングしたい
160 | 埋め込みドキュメントを指定することができます。 ::
161 |
162 | $article = $this->Articles->newEntity($data, ['associated' => ['Comments']]);
163 |
164 | ドキュメントを保存すると、次のイベントがトリガーされます：
165 |
166 | * ``Model.beforeSave`` - ドキュメントが保存される前に発生します。
167 | このイベントを停止することによって保存操作を防ぐことができます。
168 | * ``Model.buildRules`` - ルールチェッカーが最初に構築されているときに発生します。
169 | * ``Model.afterSave`` - ドキュメントが保存された後に発生します。
170 |
171 | .. note::
172 | 親ドキュメントとすべての埋め込みドキュメントを1つの操作で保存するため、
173 | 埋め込みドキュメントのためのイベントはありません。
174 |
175 | 既存ドキュメントの更新
176 | ======================
177 |
178 | データの再インデックスが必要な場合、既存のエンティティーにパッチを適用すると再保存できます。 ::
179 |
180 | $query = $this->Articles->find()->where(['user.name' => 'jill']);
181 | foreach ($query as $doc) {
182 | $doc->set($newProperties);
183 | $this->Articles->save($doc);
184 | }
185 |
186 | ドキュメントの削除
187 | ==================
188 |
189 | ドキュメントを検索した後、それを削除することができます。 ::
190 |
191 | $doc = $this->Articles->get($id);
192 | $this->Articles->delete($doc);
193 |
194 | また、特定の条件に一致するドキュメントを削除することができます。 ::
195 |
196 | $this->Articles->deleteAll(['user.name' => 'bob']);
197 |
198 | 埋め込みドキュメント
199 | ====================
200 |
201 | 埋め込みドキュメントを定義することで、ドキュメント内の特定のプロパティーのパスに
202 | エンティティークラスを添付することができます。これは、親ドキュメント内のドキュメントに
203 | 独自の振る舞いを提供することができます。たとえば、あなたが記事に埋め込まれたコメントは、
204 | 特定のアプリケーション固有のメソッドを持っている場合があります。あなたが埋め込みドキュメントを
205 | 定義するために ``embedOne`` と ``embedMany`` を使用することができます。 ::
206 |
207 | // in src/Model/Type/ArticlesType.php
208 | namespace App\Model\Type;
209 |
210 | use Cake\ElasticSearch\Type;
211 |
212 | class ArticlesType extends Type
213 | {
214 | public function initialize()
215 | {
216 | $this->embedOne('User');
217 | $this->embedMany('Comments', [
218 | 'entityClass' => 'MyComment'
219 | ]);
220 | }
221 | }
222 |
223 | 上記の ``Article`` ドキュメント上の2つの埋め込みドキュメントを作成します。
224 | ``User`` 埋め込みは ``App\Model\Document\User`` のインスタンスに ``user`` プロパティーを変換します。
225 | プロパティー名と一致していないクラス名を使用する埋め込みコメントを得るためには、カスタムクラス名を
226 | 設定するための ``entityClass`` オプションを使用することができます。
227 |
228 | 埋め込みドキュメントをセットアップしたら、 ``find()`` と ``get`` の結果は
229 | 正しい埋め込みドキュメントクラスのオブジェクトを返します。 ::
230 |
231 | $article = $this->Articles->get($id);
232 | // App\Model\Document\User のインスタンス
233 | $article->user;
234 |
235 | // App\Model\Document\Comment インスタンスの配列
236 | $article->comments;
237 |
238 | Type インスタンスの取得
239 | =======================
240 |
241 | ORM と同様に、ElasticSearch プラグインは ``Type`` のインスタンスを取得するための
242 | ファクトリー/レジストリーを提供します。 ::
243 |
244 | use Cake\ElasticSearch\TypeRegistry;
245 |
246 | $articles = TypeRegistry::get('Articles');
247 |
248 | レジストリーのフラッシュ
249 | ------------------------
250 |
251 | テストケースの中で、レジストリーをフラッシュすることができます。
252 | そうすることでモックオブジェクトを使用したり、Type の依存関係を変更する際に便利です。 ::
253 |
254 | TypeRegistry::flush();
255 |
256 | テストフィクスチャー
257 | ====================
258 |
259 | ElasticSearch プラグインは、シームレスなテストスイートの統合を提供します。ちょうどデータベースの
260 | フィクスチャーのように、elasticsearch のためのテストフィクスチャーを作成することができます。
261 | 次のように Articles タイプのテストフィクスチャーを定義することができます。 ::
262 |
263 | namespace App\Test\Fixture;
264 |
265 | use Cake\ElasticSearch\TestSuite\TestFixture;
266 |
267 | /**
268 | * Articles fixture
269 | */
270 | class ArticlesFixture extends TestFixture
271 | {
272 | /**
273 | * The table/type for this fixture.
274 | *
275 | * @var string
276 | */
277 | public $table = 'articles';
278 |
279 | /**
280 | * The mapping data.
281 | *
282 | * @var array
283 | */
284 | public $schema = [
285 | 'id' => ['type' => 'integer'],
286 | 'user' => [
287 | 'type' => 'nested',
288 | 'properties' => [
289 | 'username' => ['type' => 'string'],
290 | ]
291 | ],
292 | 'title' => ['type' => 'string'],
293 | 'body' => ['type' => 'string'],
294 | ];
295 |
296 | public $records = [
297 | [
298 | 'user' => [
299 | 'username' => 'billy'
300 | ],
301 | 'title' => 'First Post',
302 | 'body' => 'Some content'
303 | ]
304 | ];
305 | }
306 |
307 | ``schema`` プロパティーは `ネイティブ elasticsearch マッピングフォーマット
308 | `_ を使用します。
309 | 安全にタイプ名およびトップレベルの ``properties`` キーを省略することができます。
310 | フィクスチャーが作成されたら、あなたのテストの ``fixtures`` プロパティーに含めることによって、
311 | あなたのテストケースで使用することができます。 ::
312 |
313 | public $fixtures = ['app.Articles'];
314 |
315 |
--------------------------------------------------------------------------------
/docs/pt/conf.py:
--------------------------------------------------------------------------------
1 | import sys, os
2 |
3 | # Append the top level directory of the docs, so we can import from the config dir.
4 | sys.path.insert(0, os.path.abspath('..'))
5 |
6 | # Pull in all the configuration options defined in the global config file..
7 | from config.all import *
8 |
9 | # Language in use for this directory.
10 | language = 'pt'
11 |
--------------------------------------------------------------------------------
/docs/pt/contents.rst:
--------------------------------------------------------------------------------
1 | Contents
2 | ########
3 |
4 | .. toctree::
5 | :maxdepth: 2
6 | :caption: CakePHP ElasticSearch
7 |
8 | /index
9 |
--------------------------------------------------------------------------------
/docs/pt/index.rst:
--------------------------------------------------------------------------------
1 | ElasticSearch
2 | #############
3 |
4 | O plugin ElasticSearch disponibiliza uma abstração semelhante a do ORM para
5 | conversar com o
6 | `elasticsearch `_. O plugin
7 | disponibiliza recursos que tornam testes, indexação de documentos e busca por
8 | seus índices uma tarefa mais fácil de se executar.
9 |
10 | Instalação
11 | ==========
12 |
13 | Para instalar o plugin ElasticSearch, você pode usar o ``composer``. A partir do
14 | diretório raiz de sua aplicação (onde o arquivo composer.json está localizado)
15 | execute o seguinte::
16 |
17 | php composer.phar require cakephp/elastic-search "@stable"
18 |
19 | Você precisará adicionar a seguinte linha ao arquivo **config/bootstrap.php** da
20 | sua aplicação::
21 |
22 | Plugin::load('Cake/ElasticSearch', ['bootstrap' => true]);
23 |
24 | Adicionalmente, você precisará configurar a conexão como um *datasource* chamado
25 | 'elastic' no seu arquivo **config/app.php**. Um exemplo de configuração ficaria
26 | assim::
27 |
28 | // No config/app.php
29 | 'Datasources' => [
30 | // outros datasources
31 | 'elastic' => [
32 | 'className' => 'Cake\ElasticSearch\Datasource\Connection',
33 | 'driver' => 'Cake\ElasticSearch\Datasource\Connection',
34 | 'host' => '127.0.0.1',
35 | 'port' => 9200,
36 | 'index' => 'my_apps_index',
37 | ],
38 | ]
39 |
40 | Visão geral
41 | ===========
42 |
43 | O plugin ElasticSearch torna fácil interagir com um índice do *elasticsearch* e
44 | disponibiliza uma interface similar ao `ORM
45 | `__. Para começar, você deve
46 | criar um objeto ``Type``. Objetos ``Type`` são a classe similar a um
47 | "repositório" ou "tabela" no *elasticsearch*::
48 |
49 | // No src/Model/Type/ArticlesType.php
50 | namespace App\Model\Type;
51 |
52 | use Cake\ElasticSearch\Type;
53 |
54 | class ArticlesType extends Type
55 | {
56 | }
57 |
58 | Você pode então usar a sua classe *type* nos seus *controllers*::
59 |
60 | public function beforeFilter(Event $event)
61 | {
62 | parent::beforeFilter($event);
63 | // Carrega o Type usando o provedor 'Elastic'
64 | $this->loadModel('Articles', 'Elastic');
65 | }
66 |
67 | public function add()
68 | {
69 | $article = $this->Articles->newEntity();
70 | if ($this->request->is('post')) {
71 | $article = $this->Articles->patchEntity($article, $this->request->getData());
72 | if ($this->Articles->save($article)) {
73 | $this->Flash->success('It saved');
74 | }
75 | }
76 | $this->set(compact('article'));
77 | }
78 |
79 | Nós também precisamos criar um *template* básico para exibir nossos artigos
80 | indexados::
81 |
82 | // No src/Template/Articles/add.ctp
83 | Form->create($article) ?>
84 | Form->input('title') ?>
85 | Form->input('body') ?>
86 | Form->button('Save') ?>
87 | Form->end() ?>
88 |
89 | Agora você deve conseguir submeter o formulário e ter um novo documento
90 | adicionado ao *elasticsearch*.
91 |
92 | Objetos Document
93 | ================
94 |
95 | Como no ORM, o ODM do ElasticSearch usa classes semelhantes a `Entidades
96 | `__. A classe base a partir
97 | da qual você deve indicar herança é a ``Cake\ElasticSearch\Document``. Classes
98 | de documento podem ser encontradas sob o *namespace* ``Model\Document`` da sua
99 | aplicação ou *plugin*::
100 |
101 | namespace App\Model\Document;
102 |
103 | class Article extends Document
104 | {
105 | }
106 |
107 | Fora da lógica do construtor que faz *Documents* trabalharem com dados do
108 | *elasticsearch*, a interface e as funcionalidades disponibilizadas pelo objeto
109 | ``Document`` são as mesmas do `Entidades
110 | `__.
111 |
112 | Buscando documentos indexados
113 | =============================
114 |
115 | Depois que você indexar alguns documentos, é hora de buscar por eles. O plugin
116 | ElasticSearch disponibiliza um *query builder* que permite a você construir
117 | *queries* de busca::
118 |
119 | $query = $this->Articles->find()
120 | ->where([
121 | 'title' => 'special',
122 | 'or' => [
123 | 'tags in' => ['cake', 'php'],
124 | 'tags not in' => ['c#', 'java']
125 | ]
126 | ]);
127 |
128 | foreach ($query as $article) {
129 | echo $article->title;
130 | }
131 |
132 | Você pode usar o ``QueryBuilder`` para adicionar condições de filtragem::
133 |
134 | $query->where(function ($builder) {
135 | return $builder->and(
136 | $builder->gt('views', 99),
137 | $builder->term('author.name', 'sally')
138 | );
139 | });
140 |
141 | A lista completa de métodos com exemplos práticos pode ser encontradda no código
142 | fonte do `QueryBuilder
143 | `_.
144 |
145 | Validando dados & Usando regras da aplicação
146 | ============================================
147 |
148 | Como no ORM, o plugin ElasticSearch permite validar dados ao ordenar documentos.
149 | Validar dados da requisição e aplicar regras da aplicação funcionam da mesma
150 | forma como no ORM relacional. Veja a seção `validating request data
151 | `__ e a
152 | seção `Application Rules
153 | `__ para mais informações.
154 |
155 | .. Precisa de informações para validadores aninhados.
156 |
157 | Salvando novos documentos
158 | =========================
159 |
160 | Quando você estiver pronto para indexar dados no *elasticsearch*, primeiramente
161 | será necessário converter seus dados em um ``Document`` para que possam ser
162 | indexados::
163 |
164 | $article = $this->Articles->newEntity($data);
165 | if ($this->Articles->save($article)) {
166 | // Document indexado
167 | }
168 |
169 | Ao ordenar um documento, você pode especificar quais incorporações você deseja
170 | processar usando a chave ``associated``::
171 |
172 | $article = $this->Articles->newEntity($data, ['associated' => ['Comments']]);
173 |
174 | Salvar um documento irá disparar os seguintes eventos:
175 |
176 | * ``Model.beforeSave`` - Disparado antes do documento ser salvo. Você pode
177 | prevenir a operação ao parar este evento.
178 | * ``Model.buildRules`` - Disparado quando o verificador de regras é construído
179 | pela primeira vez.
180 | * ``Model.afterSave`` - Disparado depois do documento ser salvo.
181 |
182 | .. note::
183 | Não existem eventos para documentos incorporados devido ao documento pai e todos
184 | os seus documentos incorporados serem salvos em uma única operação.
185 |
186 | Atualizando documentos existentes
187 | =================================
188 |
189 | Quando você precisar re-indexar dados, você pode acrescentar informações a
190 | *entities* existentes e salvá-las novamente::
191 |
192 | $query = $this->Articles->find()->where(['user.name' => 'jill']);
193 | foreach ($query as $doc) {
194 | $doc->set($newProperties);
195 | $this->Articles->save($doc);
196 | }
197 |
198 | Deletando documentos
199 | ====================
200 |
201 | Depois de requisitar um documento, você pode deletá-lo::
202 |
203 | $doc = $this->Articles->get($id);
204 | $this->Articles->delete($doc);
205 |
206 | Você também pode deletar documentos que correspondem condições específicas::
207 |
208 | $this->Articles->deleteAll(['user.name' => 'bob']);
209 |
210 | Incorporando documentos
211 | =======================
212 |
213 | Ao definir documentos incorporados, você pode anexar classes de entidade a
214 | caminhos de propriedade específicos em seus documentos. Isso permite a você
215 | sobrescrever o comportamento padrão dos documentos relacionados a um
216 | parente. Por exemplo, você pode querer ter os comentários incorporados a um
217 | artigo para ter acesso a métodos específicos da aplicação. Você pode usar os
218 | métodos ``embedOne`` e ``embedMany`` para definir documentos incorporados::
219 |
220 | // No src/Model/Type/ArticlesType.php
221 | namespace App\Model\Type;
222 |
223 | use Cake\ElasticSearch\Type;
224 |
225 | class ArticlesType extends Type
226 | {
227 | public function initialize()
228 | {
229 | $this->embedOne('User');
230 | $this->embedMany('Comments', [
231 | 'entityClass' => 'MyComment'
232 | ]);
233 | }
234 | }
235 |
236 | O código acima deve criar dois documentos incorporados ao documento ``Article``.
237 | O ``User`` incorporado irá converter a propriedade ``user`` em instâncias de
238 | ``App\Model\Document\User``. Para que os comentários incorporados usem um nome
239 | de classe que não correspondem ao nome da propriedade, podemos usar a opção
240 | ``entityClass`` para configurar um nome de classe opcional.
241 |
242 | Uma vez que configuramos nossos documentos incorporados, os resultados do
243 | ``find()`` e ``get()`` retornarão objetos com as classes de documentos
244 | incorporados corretas::
245 |
246 | $article = $this->Articles->get($id);
247 | // Instância de App\Model\Document\User
248 | $article->user;
249 |
250 | // Array das instâncias App\Model\Document\Comment
251 | $article->comments;
252 |
253 | Recebendo instâncias Type
254 | =========================
255 |
256 | Como no ORM, o plugin ElasticSearch disponibiliza um *factory/registry* para
257 | receber instâncias ``Type``::
258 |
259 | use Cake\ElasticSearch\TypeRegistry;
260 |
261 | $articles = TypeRegistry::get('Articles');
262 |
263 | Descarregando o Registry
264 | ------------------------
265 |
266 | Durante casos de testes você pode querer descarregar o *registry*. Fazê-lo é
267 | frequentemente útil quando
268 |
269 | During test cases you may want to flush the registry. Doing so is often useful
270 | when you are using mock objects, or modifying a type's dependencies::
271 |
272 | TypeRegistry::flush();
273 |
274 | Suites de testes
275 | ================
276 |
277 | O plugin ElasticSearch disponibiliza integração com suites de testes sem
278 | remendos. Tais como nas suites de banco de dados, você criar suites de testes
279 | para o *elasticsearch*. Podemos definir uma suite de teste para nosso *articles
280 | type* com o seguinte código::
281 |
282 | namespace App\Test\Fixture;
283 |
284 | use Cake\ElasticSearch\TestSuite\TestFixture;
285 |
286 | /**
287 | * Articles fixture
288 | */
289 | class ArticlesFixture extends TestFixture
290 | {
291 | /**
292 | * A table/type para essa fixture.
293 | *
294 | * @var string
295 | */
296 | public $table = 'articles';
297 |
298 | /**
299 | * O mapeamento de dados.
300 | *
301 | * @var array
302 | */
303 | public $schema = [
304 | 'id' => ['type' => 'integer'],
305 | 'user' => [
306 | 'type' => 'nested',
307 | 'properties' => [
308 | 'username' => ['type' => 'string'],
309 | ]
310 | ]
311 | 'title' => ['type' => 'string'],
312 | 'body' => ['type' => 'string'],
313 | ];
314 |
315 | public $records = [
316 | [
317 | 'user' => [
318 | 'username' => 'birl'
319 | ],
320 | 'title' => 'Primeiro post',
321 | 'body' => 'Conteúdo'
322 | ]
323 | ];
324 | }
325 |
326 | A propriedade ``Schema`` usa o `formato de mapeamento para elasticsearch nativo
327 | `_.
328 | Você pode seguramente omitir o *type name* e a chave ``propertires``. Uma vez
329 | que suas *fixtures* estejam criadas, você pode usá-las nos seus casos de testes
330 | ao incluí-las nas propriedades dos seus ``fixtures`` de testes::
331 |
332 | public $fixtures = ['app.articles'];
333 |
334 |
--------------------------------------------------------------------------------
/phpstan-baseline.neon:
--------------------------------------------------------------------------------
1 | parameters:
2 | ignoreErrors:
3 | -
4 | message: '#^Strict comparison using \!\=\= between string and array\{\} will always evaluate to true\.$#'
5 | identifier: notIdentical.alwaysTrue
6 | count: 1
7 | path: src/Document.php
8 |
9 | -
10 | message: '#^Access to an undefined property Cake\\Datasource\\EntityInterface\:\:\$version\.$#'
11 | identifier: property.notFound
12 | count: 1
13 | path: src/Index.php
14 |
15 | -
16 | message: '#^Method Cake\\ElasticSearch\\Query\:\:find\(\) should return static\(Cake\\ElasticSearch\\Query\\) but returns Cake\\ElasticSearch\\Query\\.$#'
17 | identifier: return.type
18 | count: 1
19 | path: src/Query.php
20 |
21 | -
22 | message: '#^PHPDoc tag @return with type Cake\\ElasticSearch\\Query\ is not subtype of native type static\(Cake\\ElasticSearch\\Query\\)\.$#'
23 | identifier: return.phpDocType
24 | count: 1
25 | path: src/Query.php
26 |
27 | -
28 | message: '#^Strict comparison using \!\=\= between mixed and null will always evaluate to true\.$#'
29 | identifier: notIdentical.alwaysTrue
30 | count: 1
31 | path: src/QueryBuilder.php
32 |
--------------------------------------------------------------------------------
/phpstan.neon:
--------------------------------------------------------------------------------
1 | includes:
2 | - phpstan-baseline.neon
3 |
4 | parameters:
5 | level: 6
6 | paths:
7 | - src/
8 | bootstrapFiles:
9 | - tests/bootstrap.php
10 | ignoreErrors:
11 | - identifier: missingType.iterableValue
12 | - identifier: missingType.generics
13 |
14 |
--------------------------------------------------------------------------------
/psalm-baseline.xml:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 | _client->getConfig()]]>
6 |
7 |
8 | id]]>
17 | id]]>
18 | id]]>
19 | id]]>
20 | version]]>
21 |
22 |
23 |
24 |
25 | id]]>
26 |
27 |
28 |
29 |
30 |