5.x docs

.github/workflows/deploy_docs_5x.yml

@@ -0,0 +1,23 @@
+---
+name: 'deploy_docs_5x'
+
+on:
+  push:
+    branches:
+      - 5.x
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Cloning repo
+        uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+
+      - name: Push to dokku
+        uses: dokku/github-action@master
+        with:
+          git_remote_url: 'ssh://dokku@apps.cakephp.org:22/elasticsearch-docs-5'
+          ssh_private_key: ${{ secrets.DOKKU_SSH_PRIVATE_KEY }}

docs/config/all.py

@@ -10,10 +10,10 @@
 #
 
 # The full version, including alpha/beta/rc tags.
-release = '4.x'
+release = '5.x'
 
 # The search index version.
-search_version = 'elasticsearch-4'
+search_version = 'elasticsearch-5'
 
 # The marketing display name for the book.
 version_name = ''
@@ -23,20 +23,21 @@
 
 # Other versions that display in the version picker menu.
 version_list = [
-    {'name': '4.x', 'number': '/elasticsearch/4', 'title': '4.x', 'current': True},
-    {'name': '3.x', 'number': '/elasticsearch/3', 'title': '3.x',},
+    {'name': '5.x', 'number': '/elasticsearch/5', 'title': '5.x', 'current': True},
+    {'name': '4.x', 'number': '/elasticsearch/4', 'title': '4.x'},
+    {'name': '3.x', 'number': '/elasticsearch/3', 'title': '3.x'},
     {'name': '2.x', 'number': '/elasticsearch/2', 'title': '2.x'},
 ]
 
 # Languages available.
-languages = ['en', 'fr', 'ja', 'pt']
+languages = ['en', 'ja']
 
 # The GitHub branch name for this version of the docs
 # for edit links to point at.
-branch = '4.x'
+branch = '5.x'
 
 # Current version being built
-version = '4.x'
+version = '5.x'
 
 show_root_link = True
 

docs/en/5-0-upgrade-guide.rst

@@ -0,0 +1,215 @@
+5.0 Upgrade Guide
+#################
+
+.. warning::
+    CakePHP ElasticSearch 5.x requires CakePHP 5.2+, ElasticSearch 9.x, and PHP 8.1+.
+
+Requirements
+============
+
+* CakePHP 5.2+
+* ElasticSearch 9.x
+* Elastica 9.x (via ruflin/elastica)
+* PHP 8.1+
+
+Breaking Changes
+================
+
+Version 5.x includes several breaking changes to support ElasticSearch 9.x via
+the Elastica 9.x library upgrade, along with compatibility updates for the latest
+CakePHP 5.x features.
+
+* Connection configuration format has changed to use ``hosts`` array.
+* ``IndexRegistry`` class has been removed (was deprecated since 3.4.3).
+* Several deprecated methods have been removed.
+* Elastica API changes require updated client initialization.
+
+Configuration Changes
+=====================
+
+Connection Configuration Format
+--------------------------------
+
+The recommended configuration format now uses a ``hosts`` array instead
+of separate ``host`` and ``port`` keys. This aligns with Elastica 9.x
+and provides better support for clustering.
+
+Legacy configuration format (still supported)::
+
+    // in config/app.php
+    'Datasources' => [
+        'elastic' => [
+            'className' => 'Cake\ElasticSearch\Datasource\Connection',
+            'driver' => 'Cake\ElasticSearch\Datasource\Connection',
+            'host' => '127.0.0.1',
+            'port' => 9200,
+        ],
+    ]
+
+New configuration format (recommended)::
+
+    // in config/app.php
+    'Datasources' => [
+        'elastic' => [
+            'className' => 'Cake\ElasticSearch\Datasource\Connection',
+            'driver' => 'Cake\ElasticSearch\Datasource\Connection',
+            'hosts' => ['127.0.0.1:9200'],
+        ],
+    ]
+
+For HTTPS endpoints::
+
+    'hosts' => ['https://127.0.0.1:443']
+
+Multiple hosts can be specified in the array::
+
+    'hosts' => [
+        '127.0.0.1:9200',
+        '127.0.0.1:9201',
+        '127.0.0.1:9202',
+    ]
+
+Deprecated Method Removals
+===========================
+
+Several deprecated methods have been removed in this version. Update your code
+to use the replacement methods.
+
+QueryBuilder Methods
+--------------------
+
+* ``QueryBuilder::and_()`` → use ``QueryBuilder::and()``
+* ``QueryBuilder::or_()`` → use ``QueryBuilder::or()``
+
+The underscore suffix is no longer needed as modern PHP allows these method names.
+
+Old code::
+
+    $query->where(function ($builder) {
+        return $builder->and_(
+            $builder->gt('views', 99),
+            $builder->term('author.name', 'sally')
+        );
+    });
+
+New code::
+
+    $query->where(function ($builder) {
+        return $builder->and(
+            $builder->gt('views', 99),
+            $builder->term('author.name', 'sally')
+        );
+    });
+
+Embedded Association Methods
+-----------------------------
+
+* ``Embedded::property()`` → use ``setProperty()`` / ``getProperty()``
+* ``Embedded::entityClass()`` → use ``setEntityClass()`` / ``getEntityClass()``
+* ``Embedded::indexClass()`` → use ``setIndexClass()`` / ``getIndexClass()``
+
+Old code::
+
+    $association->property('comments');
+    $class = $association->entityClass();
+    $association->entityClass('App\Model\Document\Comment');
+
+New code::
+
+    $association->setProperty('comments');
+    $class = $association->getEntityClass();
+    $association->setEntityClass('App\Model\Document\Comment');
+
+Query Methods
+-------------
+
+* ``Query::repository()`` → use ``setRepository()``
+
+Old code::
+
+    $query->repository($index);
+
+New code::
+
+    $query->setRepository($index);
+
+.. note::
+    ``Query::order()`` remains available as it's required by the
+    ``Cake\Datasource\QueryInterface`` contract, but ``orderBy()`` is preferred.
+
+IndexRegistry Removal
+=====================
+
+The deprecated ``IndexRegistry`` class has been completely removed. Use ``IndexLocator``
+or ``IndexLocatorAwareTrait`` instead.
+
+Old approach (no longer available)::
+
+    use Cake\ElasticSearch\IndexRegistry;
+
+    $articles = IndexRegistry::get('Articles');
+    IndexRegistry::flush();
+
+New approach using IndexLocator directly::
+
+    use Cake\ElasticSearch\Datasource\IndexLocator;
+
+    $locator = new IndexLocator();
+    $articles = $locator->get('Articles');
+    $locator->clear();
+
+New approach using IndexLocatorAwareTrait::
+
+    use Cake\ElasticSearch\Datasource\IndexLocatorAwareTrait;
+
+    class MyController extends Controller
+    {
+        use IndexLocatorAwareTrait;
+
+        public function index()
+        {
+            $articles = $this->fetchIndex('Articles');
+        }
+    }
+
+Alternative using FactoryLocator::
+
+    use Cake\Datasource\FactoryLocator;
+
+    $articles = FactoryLocator::get('ElasticSearch')->get('Articles');
+
+Migration Steps
+===============
+
+1. **Update Dependencies**
+
+   Update your ``composer.json`` to require version 5.x::
+
+       composer require cakephp/elastic-search:^5.0
+
+2. **Update Configuration (Optional but Recommended)**
+
+   Consider updating your datasource configuration in ``config/app.php`` to use
+   the ``hosts`` array format for better clustering support. The old ``host``
+   and ``port`` format still works for backward compatibility.
+
+3. **Update Code**
+
+   Search your codebase for the deprecated methods and replace them:
+
+   * Replace ``IndexRegistry`` usage with ``IndexLocator`` or ``IndexLocatorAwareTrait``
+   * Replace ``and_()`` with ``and()``
+   * Replace ``or_()`` with ``or()``
+   * Replace getter/setter methods on embedded associations
+   * Replace ``repository()`` with ``setRepository()``
+
+4. **Test ElasticSearch 9.x Compatibility**
+
+   Ensure your ElasticSearch cluster is running version 9.x and test your
+   application thoroughly.
+
+5. **Run Tests**
+
+   Run your test suite to catch any compatibility issues::
+
+       vendor/bin/phpunit

docs/en/contents.rst

@@ -8,3 +8,4 @@ Contents
     /index
     /3-0-upgrade-guide
     /4-0-upgrade-guide
+    /5-0-upgrade-guide

docs/en/index.rst

@@ -13,7 +13,7 @@ To install the ElasticSearch plugin, you can use ``composer``. From your
 application's ROOT directory (where ``composer.json`` file is located) run the
 following::
 
-    php composer.phar require cakephp/elastic-search "^4.0"
+    $ composer require cakephp/elastic-search "^5.0"
 
 You will need to add the following line to your application's
 **src/Application.php** file::
@@ -29,18 +29,28 @@ your **config/app.php** file. An example configuration would be::
         'elastic' => [
             'className' => 'Cake\ElasticSearch\Datasource\Connection',
             'driver' => 'Cake\ElasticSearch\Datasource\Connection',
-            'host' => '127.0.0.1',
-            'port' => 9200,
+            'hosts' => ['127.0.0.1:9200'],
             'index' => 'my_apps_index',
         ],
     ]
 
+The legacy configuration format with separate ``host`` and ``port`` is still supported::
+
+    'elastic' => [
+        'className' => 'Cake\ElasticSearch\Datasource\Connection',
+        'driver' => 'Cake\ElasticSearch\Datasource\Connection',
+        'host' => '127.0.0.1',
+        'port' => 9200,
+        'index' => 'my_apps_index',
+    ]
+
 If your endpoint requires https, use::
 
-    'port' => 443,
-    'transport' => 'https'
+    'hosts' => ['https://127.0.0.1:443']
 
-or you might get a 400 response back from the elasticsearch server.
+.. note::
+    The ``hosts`` array format is recommended for new applications and provides
+    better support for multiple hosts and clustering.
 
 Overview
 ========
@@ -295,20 +305,39 @@ index use which connections. This is the ``defaultConnectionName()`` method::
 Getting Index Instances
 =======================
 
-Like the ORM, the ElasticSearch plugin provides a factory/registry for getting
+Like the ORM, the ElasticSearch plugin provides a locator for getting
 ``Index`` instances::
 
-    use Cake\ElasticSearch\IndexRegistry;
+    use Cake\ElasticSearch\Datasource\IndexLocator;
+
+    $locator = new IndexLocator();
+    $articles = $locator->get('Articles');
+
+Using IndexLocatorAwareTrait
+-----------------------------
+
+For convenient access to the index locator, you can use the ``IndexLocatorAwareTrait``
+in your classes::
 
-    $articles = IndexRegistry::get('Articles');
+    use Cake\ElasticSearch\Datasource\IndexLocatorAwareTrait;
 
-Flushing the Registry
+    class MyController extends Controller
+    {
+        use IndexLocatorAwareTrait;
+
+        public function index()
+        {
+            $articles = $this->fetchIndex('Articles');
+        }
+    }
+
+Flushing the Locator
 ---------------------
 
-During test cases you may want to flush the registry. Doing so is often useful
-when you are using mock objects, or modifying a index's dependencies::
+During test cases you may want to flush the locator. Doing so is often useful
+when you are using mock objects, or modifying an index's dependencies::
 
-    IndexRegistry::flush();
+    $locator->clear();
 
 Test Fixtures
 =============
@@ -387,6 +416,7 @@ following::
     Prior to CakePHP 4.3.0 schema was defined on each fixture in the ``$schema``
     property.
 
+
 Once your fixtures are created you can use them in your test cases by including
 them in your test's ``fixtures`` properties::