Skip to content

Commit 2e15f5e

Browse files
josbeirjosbeir
committed
Merge pull request #339 from cakephp/5.x-docs
Adding 5.x docs
2 parents 1914d90 + 43326b6 commit 2e15f5e

14 files changed

Lines changed: 335 additions & 734 deletions

File tree

‎.github/workflows/deploy_docs_5x.yml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
name: 'deploy_docs_5x'
3+
4+
on:
5+
push:
6+
branches:
7+
- 5.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-5'
23+
ssh_private_key: ${{ secrets.DOKKU_SSH_PRIVATE_KEY }}

‎Dockerfile‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Basic docker based environment
2+
# Necessary to trick dokku into building the documentation
3+
# using dockerfile instead of herokuish
4+
FROM ubuntu:22.04
5+
6+
ENV TZ="Etc/UTC"
7+
RUN apt-get update && \
8+
apt-get install -y tzdata && \
9+
ln -fs /usr/share/zoneinfo/Etc/UTC /etc/localtime && \
10+
dpkg-reconfigure -f noninteractive tzdata
11+
12+
# Add basic tools
13+
RUN apt-get update && \
14+
apt-get install -y build-essential \
15+
software-properties-common \
16+
curl \
17+
git \
18+
libxml2 \
19+
libffi-dev \
20+
libssl-dev
21+
22+
RUN LC_ALL=C.UTF-8 add-apt-repository ppa:ondrej/php && \
23+
apt-get update && \
24+
apt-get install -y \
25+
php8.1-cli \
26+
php8.1-mbstring \
27+
php8.1-xml \
28+
php8.1-zip \
29+
php8.1-intl \
30+
php8.1-opcache \
31+
php8.1-sqlite \
32+
php8.1-curl \
33+
composer
34+
35+
# This prevents permission errors with the mounted vendor directory.
36+
RUN git config --global --add safe.directory /code/vendor/cakephp/cakephp
37+
38+
WORKDIR /code
39+
40+
VOLUME ["/code"]
41+
42+
CMD [ "/bin/bash" ]

‎docker-compose.yml‎

Lines changed: 0 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,4 @@
11
services:
2-
console:
3-
build: "."
4-
environment:
5-
DB_URL: "Cake\\ElasticSearch\\Datasource\\Connection://elasticsearch:9200?driver=Cake\\ElasticSearch\\Datasource\\Connection"
6-
volumes:
7-
- .:/code
8-
depends_on:
9-
elasticsearch:
10-
condition: service_healthy
112
elasticsearch:
123
image: "elasticsearch:9.1.5"
134
ports:

‎docs.Dockerfile‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
FROM ghcr.io/cakephp/docs-builder as builder
33

44
COPY docs /data/docs
5-
ENV LANGS="en fr ja pt"
5+
ENV LANGS="en ja"
66

77
# Build docs with sphinx
88
RUN cd /data/docs-builder && \
@@ -13,9 +13,9 @@ RUN cd /data/docs-builder && \
1313
FROM ghcr.io/cakephp/docs-builder:runtime as runtime
1414

1515
# Configure search index script
16-
ENV LANGS="en fr ja pt"
16+
ENV LANGS="en ja"
1717
ENV SEARCH_SOURCE="/usr/share/nginx/html"
18-
ENV SEARCH_URL_PREFIX="/elasticsearch/4"
18+
ENV SEARCH_URL_PREFIX="/elasticsearch/5"
1919

2020
COPY --from=builder /data/docs /data/docs
2121
COPY --from=builder /data/website /data/website

‎docs/config/all.py‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,10 @@
1010
#
1111

1212
# The full version, including alpha/beta/rc tags.
13-
release = '4.x'
13+
release = '5.x'
1414

1515
# The search index version.
16-
search_version = 'elasticsearch-4'
16+
search_version = 'elasticsearch-5'
1717

1818
# The marketing display name for the book.
1919
version_name = ''
@@ -23,20 +23,21 @@
2323

2424
# Other versions that display in the version picker menu.
2525
version_list = [
26-
{'name': '4.x', 'number': '/elasticsearch/4', 'title': '4.x', 'current': True},
27-
{'name': '3.x', 'number': '/elasticsearch/3', 'title': '3.x',},
26+
{'name': '5.x', 'number': '/elasticsearch/5', 'title': '5.x', 'current': True},
27+
{'name': '4.x', 'number': '/elasticsearch/4', 'title': '4.x'},
28+
{'name': '3.x', 'number': '/elasticsearch/3', 'title': '3.x'},
2829
{'name': '2.x', 'number': '/elasticsearch/2', 'title': '2.x'},
2930
]
3031

3132
# Languages available.
32-
languages = ['en', 'fr', 'ja', 'pt']
33+
languages = ['en', 'ja']
3334

3435
# The GitHub branch name for this version of the docs
3536
# for edit links to point at.
36-
branch = '4.x'
37+
branch = '5.x'
3738

3839
# Current version being built
39-
version = '4.x'
40+
version = '5.x'
4041

4142
show_root_link = True
4243

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

Lines changed: 215 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,215 @@
1+
5.0 Upgrade Guide
2+
#################
3+
4+
.. warning::
5+
CakePHP ElasticSearch 5.x requires CakePHP 5.2+, ElasticSearch 9.x, and PHP 8.1+.
6+
7+
Requirements
8+
============
9+
10+
* CakePHP 5.2+
11+
* ElasticSearch 9.x
12+
* Elastica 9.x (via ruflin/elastica)
13+
* PHP 8.1+
14+
15+
Breaking Changes
16+
================
17+
18+
Version 5.x includes several breaking changes to support ElasticSearch 9.x via
19+
the Elastica 9.x library upgrade, along with compatibility updates for the latest
20+
CakePHP 5.x features.
21+
22+
* Connection configuration format has changed to use ``hosts`` array.
23+
* ``IndexRegistry`` class has been removed (was deprecated since 3.4.3).
24+
* Several deprecated methods have been removed.
25+
* Elastica API changes require updated client initialization.
26+
27+
Configuration Changes
28+
=====================
29+
30+
Connection Configuration Format
31+
--------------------------------
32+
33+
The recommended configuration format now uses a ``hosts`` array instead
34+
of separate ``host`` and ``port`` keys. This aligns with Elastica 9.x
35+
and provides better support for clustering.
36+
37+
Legacy configuration format (still supported)::
38+
39+
// in config/app.php
40+
'Datasources' => [
41+
'elastic' => [
42+
'className' => 'Cake\ElasticSearch\Datasource\Connection',
43+
'driver' => 'Cake\ElasticSearch\Datasource\Connection',
44+
'host' => '127.0.0.1',
45+
'port' => 9200,
46+
],
47+
]
48+
49+
New configuration format (recommended)::
50+
51+
// in config/app.php
52+
'Datasources' => [
53+
'elastic' => [
54+
'className' => 'Cake\ElasticSearch\Datasource\Connection',
55+
'driver' => 'Cake\ElasticSearch\Datasource\Connection',
56+
'hosts' => ['127.0.0.1:9200'],
57+
],
58+
]
59+
60+
For HTTPS endpoints::
61+
62+
'hosts' => ['https://127.0.0.1:443']
63+
64+
Multiple hosts can be specified in the array::
65+
66+
'hosts' => [
67+
'127.0.0.1:9200',
68+
'127.0.0.1:9201',
69+
'127.0.0.1:9202',
70+
]
71+
72+
Deprecated Method Removals
73+
===========================
74+
75+
Several deprecated methods have been removed in this version. Update your code
76+
to use the replacement methods.
77+
78+
QueryBuilder Methods
79+
--------------------
80+
81+
* ``QueryBuilder::and_()`` → use ``QueryBuilder::and()``
82+
* ``QueryBuilder::or_()`` → use ``QueryBuilder::or()``
83+
84+
The underscore suffix is no longer needed as modern PHP allows these method names.
85+
86+
Old code::
87+
88+
$query->where(function ($builder) {
89+
return $builder->and_(
90+
$builder->gt('views', 99),
91+
$builder->term('author.name', 'sally')
92+
);
93+
});
94+
95+
New code::
96+
97+
$query->where(function ($builder) {
98+
return $builder->and(
99+
$builder->gt('views', 99),
100+
$builder->term('author.name', 'sally')
101+
);
102+
});
103+
104+
Embedded Association Methods
105+
-----------------------------
106+
107+
* ``Embedded::property()`` → use ``setProperty()`` / ``getProperty()``
108+
* ``Embedded::entityClass()`` → use ``setEntityClass()`` / ``getEntityClass()``
109+
* ``Embedded::indexClass()`` → use ``setIndexClass()`` / ``getIndexClass()``
110+
111+
Old code::
112+
113+
$association->property('comments');
114+
$class = $association->entityClass();
115+
$association->entityClass('App\Model\Document\Comment');
116+
117+
New code::
118+
119+
$association->setProperty('comments');
120+
$class = $association->getEntityClass();
121+
$association->setEntityClass('App\Model\Document\Comment');
122+
123+
Query Methods
124+
-------------
125+
126+
* ``Query::repository()`` → use ``setRepository()``
127+
128+
Old code::
129+
130+
$query->repository($index);
131+
132+
New code::
133+
134+
$query->setRepository($index);
135+
136+
.. note::
137+
``Query::order()`` remains available as it's required by the
138+
``Cake\Datasource\QueryInterface`` contract, but ``orderBy()`` is preferred.
139+
140+
IndexRegistry Removal
141+
=====================
142+
143+
The deprecated ``IndexRegistry`` class has been completely removed. Use ``IndexLocator``
144+
or ``IndexLocatorAwareTrait`` instead.
145+
146+
Old approach (no longer available)::
147+
148+
use Cake\ElasticSearch\IndexRegistry;
149+
150+
$articles = IndexRegistry::get('Articles');
151+
IndexRegistry::flush();
152+
153+
New approach using IndexLocator directly::
154+
155+
use Cake\ElasticSearch\Datasource\IndexLocator;
156+
157+
$locator = new IndexLocator();
158+
$articles = $locator->get('Articles');
159+
$locator->clear();
160+
161+
New approach using IndexLocatorAwareTrait::
162+
163+
use Cake\ElasticSearch\Datasource\IndexLocatorAwareTrait;
164+
165+
class MyController extends Controller
166+
{
167+
use IndexLocatorAwareTrait;
168+
169+
public function index()
170+
{
171+
$articles = $this->fetchIndex('Articles');
172+
}
173+
}
174+
175+
Alternative using FactoryLocator::
176+
177+
use Cake\Datasource\FactoryLocator;
178+
179+
$articles = FactoryLocator::get('ElasticSearch')->get('Articles');
180+
181+
Migration Steps
182+
===============
183+
184+
1. **Update Dependencies**
185+
186+
Update your ``composer.json`` to require version 5.x::
187+
188+
composer require cakephp/elastic-search:^5.0
189+
190+
2. **Update Configuration (Optional but Recommended)**
191+
192+
Consider updating your datasource configuration in ``config/app.php`` to use
193+
the ``hosts`` array format for better clustering support. The old ``host``
194+
and ``port`` format still works for backward compatibility.
195+
196+
3. **Update Code**
197+
198+
Search your codebase for the deprecated methods and replace them:
199+
200+
* Replace ``IndexRegistry`` usage with ``IndexLocator`` or ``IndexLocatorAwareTrait``
201+
* Replace ``and_()`` with ``and()``
202+
* Replace ``or_()`` with ``or()``
203+
* Replace getter/setter methods on embedded associations
204+
* Replace ``repository()`` with ``setRepository()``
205+
206+
4. **Test ElasticSearch 9.x Compatibility**
207+
208+
Ensure your ElasticSearch cluster is running version 9.x and test your
209+
application thoroughly.
210+
211+
5. **Run Tests**
212+
213+
Run your test suite to catch any compatibility issues::
214+
215+
vendor/bin/phpunit

‎docs/en/contents.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,4 @@ Contents
88
/index
99
/3-0-upgrade-guide
1010
/4-0-upgrade-guide
11+
/5-0-upgrade-guide

0 commit comments

Comments
 (0)