Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DOCS] Fine-tunes breaking changes and community DSLs pages in PHP client book #1025

Merged
merged 2 commits into from
Jun 10, 2020
Merged

[DOCS] Fine-tunes breaking changes and community DSLs pages in PHP client book #1025

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c0f17b0
[DOCS] Fine-tunes breaking changes and community DSLs pages in PHP cl…
szabosteve Apr 30, 2020
e8d582d
[DOCS] Adds note on E_USER_DEPRICATED.
szabosteve Jun 9, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 31 additions & 11 deletions docs/breaking-changes.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,24 +3,44 @@

### E_USER_DEPRECATED notice when using deprecated parameters

Starting from elasticsearch-php 7.4.0, we generate a PHP [E_USER_DEPRECATED](https://www.php.net/manual/en/errorfunc.constants.php)
notice every time you use a deprecated parameters for Elasticsearch.
We decided to add this notice to facilitate the code refactoring with the
new API specification of Elasticsearch (e.g. the usage of typeless APIs, see below).
Starting from elasticsearch-php 7.4.0, we generate a PHP
https://www.php.net/manual/en/errorfunc.constants.php[E_USER_DEPRECATED] notice
every time you use a deprecated parameters for {es}. We decided to add this
notice to facilitate the code refactoring with the new API specification of {es}
(for example the usage of typeless APIs, see below).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I forgot to mention here that we silent the E_USER_DEPRECATED warning in 7.4.1 (using the @ operator) due to BC break issues in other libraries using elasticsearch-php. The full story can be found here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ezimuel
Thank you for the review and for the note. I added the story to the E_USER_DEPRECATED section in e8d582d. Please let me know if you want to change/add anything.


### Moving from types to typeless APIs in Elasticsearch 7.0
From 7.4.1, we mitigated the usage of E_USER_DEPRICATED warning by using the `@`
https://www.php.net/manual/en/language.operators.errorcontrol.php[operator]. The
operator suppresses the error message, however, it is still possible to catch it
by using a custom error handler:

Elasticsearch 7.0 deprecated APIs that accept types, introduced new typeless
APIs, and removed support for the _default_ mapping. Read [this](https://www.elastic.co/blog/moving-from-types-to-typeless-apis-in-elasticsearch-7-0)
[source,php]
----
set_error_handler(function ($errno, $errstr) {
var_dump($errstr);
}, E_USER_DEPRECATED);

@trigger_error('Deprecation message here', E_USER_DEPRECATED);
----


### Moving from types to typeless APIs in {es} 7.0

{es} 7.0 deprecated APIs that accept types, introduced new typeless APIs, and
removed support for the _default_ mapping. Read
https://www.elastic.co/blog/moving-from-types-to-typeless-apis-in-elasticsearch-7-0[this]
blog post for more information.


### Type hint and return type

Added type hints and return type declarations in all the code base, where possible.
See PR [#897](https://github.com/elastic/elasticsearch-php/pull/897).
Added type hints and return type declarations in all the code base where
possible. See PR https://github.com/elastic/elasticsearch-php/pull/897[#897].


### PHP 7.1+ Requirement

We require using PHP 7.1+ for elasticsearch-php. PHP 7.0 is not supported since
1st Jan 2019. See [PHP supported version](https://www.php.net/supported-versions.php) for
more information.
1st Jan 2019. Refer
https://www.php.net/supported-versions.php[PHP supported version] for more
information.
66 changes: 43 additions & 23 deletions docs/community.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,38 +6,48 @@
https://github.com/ongr-io/ElasticsearchDSL[Link: ElasticsearchDSL]
[quote, ElasticsearchDSL]
__________________________
Introducing Elasticsearch DSL library to provide objective query builder for Elasticsearch bundle and elasticsearch-php client. You can easily build any Elasticsearch query and transform it to an array.
Introducing {es} DSL library to provide objective query builder for {es} bundle
and elasticsearch-php client. You can easily build any {es} query and transform
it to an array.
__________________________


=== elasticsearcher

https://github.com/madewithlove/elasticsearcher[Link: elasticsearcher]

[quote, elasticsearcher]
__________________________
This agnostic package is a lightweight wrapper on top of the Elasticsearch PHP client. Its main goal is to allow for easier structuring of queries and indices in your application. It does not want to hide or replace functionality of the Elasticsearch PHP client.
This agnostic package is a lightweight wrapper on top of the {es} PHP client.
Its main goal is to allow for easier structuring of queries and indices in your
application. It does not want to hide or replace functionality of the {es} PHP
client.
__________________________


=== ElasticSearchQueryDSL

https://github.com/gskema/elasticsearch-query-dsl-php[Link: ElasticSearchQueryDSL]

[quote, ElasticSearchQueryDSL]
__________________________
Feature complete, object oriented, composable, extendable ElasticSearch query DSL builder for PHP. Deliberately built to be as simple as possible, easily usable and with explicit naming.
Feature complete, object oriented, composable, extendable {es} query DSL builder
for PHP. Deliberately built to be as simple as possible, easily usable and with
explicit naming.
__________________________


== Community Integrations

=== Symfony

==== ONGR Elasticsearch Bundle

https://github.com/ongr-io/ElasticsearchBundle[Link: ONGR Elasticsearch Bundle]
https://github.com/ongr-io/ElasticsearchBundle[Link: ONGR {es} Bundle]

[quote, ONGR Elasticsearch Bundle]
[quote, ONGR {es} Bundle]
__________________________
Elasticsearch Bundle was created in order to serve the need for professional elasticsearch
{es} Bundle was created in order to serve the need for professional {es}
integration with enterprise level Symfony 2 systems. This bundle is:

- Supported by ONGR.io development team.
Expand All @@ -46,10 +56,13 @@ integration with enterprise level Symfony 2 systems. This bundle is:

Technical goodies:

- Provides nestable and DSL query builder to be executed by type repository services.
- Uses Doctrine-like document / entities document-object mapping using annotations.
- Provides nestable and DSL query builder to be executed by type repository
services.
- Uses Doctrine-like document / entities document-object mapping using
annotations.
- Query results iterators are provided for your convenience.
- Registers console commands for index and types management and data import / export.
- Registers console commands for index and types management and data import /
export.
- Designed in an extensible way for all your custom needs.
__________________________

Expand All @@ -60,23 +73,26 @@ https://github.com/FriendsOfSymfony/FOSElasticaBundle[Link: FOS Elastica Bundle]

[quote, FOS Elastica Bundle]
__________________________
This bundle provides integration with https://github.com/ruflin/Elastica[Link: Elastica] for Symfony. Features include:
This bundle provides integration with
https://github.com/ruflin/Elastica[Link: Elastica] for Symfony. Features
include:

- Integrates the Elastica library into a Symfony environment
- Automatically generate mappings using a serializer
- Listeners for Doctrine events for automatic indexing
- Integrates the Elastica library into a Symfony environment.
- Automatically generate mappings using a serializer.
- Listeners for Doctrine events for automatic indexing.
__________________________


=== Drupal

==== Elasticsearch Connector
==== {es} Connector

https://www.drupal.org/project/elasticsearch_connector[Link: Elasticsearch Connector]
https://www.drupal.org/project/elasticsearch_connector[Link: {es} Connector]

[quote, Elasticsearch Connector]
[quote, {es} Connector]
__________________________
Elasticsearch Connector is a set of modules designed to build a full Elasticsearch eco system in Drupal.
{es} Connector is a set of modules designed to build a full {es} eco system in
Drupal.
__________________________

=== Laravel
Expand All @@ -87,7 +103,7 @@ https://github.com/shift31/laravel-elasticsearch[Link: shift31/Laravel-Elasticse

[quote, Laravel-Elasticsearch]
__________________________
This is a Laravel (4+) Service Provider for the official Elasticsearch low-level client.
This is a Laravel (4+) Service Provider for the official {es} low-level client.
__________________________


Expand All @@ -97,7 +113,7 @@ https://github.com/cviebrock/laravel-elasticsearch[Link: cviebrock/Laravel-Elast

[quote, Laravel-Elasticsearch]
__________________________
An easy way to use the official Elastic Search client in your Laravel applications.
An easy way to use the official {es} client in your Laravel applications.
__________________________


Expand All @@ -107,7 +123,9 @@ https://github.com/sleimanx2/plastic[Link: Plastic]

[quote, Plastic]
__________________________
Plastic is an Elasticsearch ODM and mapper for Laravel. It renders the developer experience more enjoyable while using Elasticsearch, by providing a fluent syntax for mapping, querying, and storing eloquent models.
Plastic is an {es} ODM and mapper for Laravel. It renders the developer
experience more enjoyable while using {es} by providing a fluent syntax for
mapping, querying, and storing eloquent models.
__________________________

=== Helper
Expand All @@ -118,7 +136,9 @@ https://github.com/Nexucis/es-php-index-helper[Link: nexucis/es-php-index-helper

[quote, Index Helper]
_____________________
This helper is a light library which wrap the official client elasticsearch-php. It will help you to manage your ES Indices with no downtime.
This helper implements the philosophy described in the https://www.elastic.co/guide/en/elasticsearch/guide/master/index-aliases.html[official documentation]
which can be summarized in a few words : *use alias instead of index directly*
This helper is a light library which wrap the official client elasticsearch-php.
It will help you to manage your ES Indices with no downtime. This helper
implements the philosophy described in the
https://www.elastic.co/guide/en/elasticsearch/guide/master/index-aliases.html[official documentation]
which can be summarized in a few words : *use alias instead of index directly*.
_____________________