Skip to content
This repository was archived by the owner on Apr 10, 2025. It is now read-only.

Commit cf19fff

Browse files
ezimuelezimuel
committed
Updated the README and CONTRIBUTING guide
1 parent ab58e02 commit cf19fff

File tree

2 files changed

+47
-52
lines changed

2 files changed

+47
-52
lines changed

‎CONTRIBUTING.md

Lines changed: 24 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,32 @@
1-
Describe how to install the library for development purposes.
1+
## Contribute 🚀
22

3-
### Run Tests
3+
We welcome contributors to the project. Before you begin, some useful info...
44

5+
+ If you want to contribute to this project you need to subscribe to a
6+
[Contributor Agreement](https://www.elastic.co/contributor-agreement).
7+
+ Before opening a pull request, please create an issue to
8+
[discuss the scope of your proposal](https://github.com/elastic/elasticsearch-serverless-php/issues).
9+
+ If you want to send a PR for version `8.0` please use the `8.0` branch, for
10+
`8.1` use the `8.1` branch and so on.
11+
+ Never send PR to `master` unless you want to contribute to the development
12+
version of the client (`master` represents the next major version).
13+
+ Each PR should include a **unit test** using [PHPUnit](https://phpunit.de/).
14+
If you are not familiar with PHPUnit you can have a look at the
15+
[reference](https://phpunit.readthedocs.io/en/9.5/).
516

17+
## Testing
618

7-
### Run Elasticsearch Serverless Docker container
19+
To execute the tests, you can use the following command:
820

21+
```bash
22+
composer run-script test
23+
```
924

25+
We also use [PHPStan](https://phpstan.org/) for code static analysis.
26+
Please remember to run this command before sending the PR:
1027

11-
### Contributing Code Changes
28+
```bash
29+
composer run-script phpstan
30+
```
1231

13-
1. Please make sure you have signed the [Contributor License
14-
Agreement](http://www.elastic.co/contributor-agreement/). We are not
15-
asking you to assign copyright to us, but to give us the right to distribute
16-
your code without restriction. We ask this of all contributors in order to
17-
assure our users of the origin and continuing existence of the code. You only
18-
need to sign the CLA once.
19-
2. Rebase your changes. Update your local repository with the most recent code
20-
from the main `elasticsearch-serverless-php` repository and rebase your branch
21-
on top of the latest `main` branch.
22-
3. Submit a pull request. Push your local changes to your forked repository
23-
and [submit a pull request](https://github.com/elastic/elasticsearch-serverless/pulls)
24-
and mention the issue number if any (`Closes #123`) Make sure that you
25-
add or modify tests related to your changes so that CI will pass.
26-
4. Sit back and wait. There may be some discussion on your pull request and
27-
if changes are needed we would love to work with you to get your pull request
28-
merged into `elasticsearch-serverless-php`.
32+
Thanks in advance for your contribution! :heart:

‎README.md

Lines changed: 23 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -2,52 +2,39 @@
22

33
[![main](https://github.com/elastic/elasticsearch-serverless-php/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/elastic/elasticsearch-serverless-php/actions/workflows/tests.yml)
44

5-
This is the official Elastic client for the **Elasticsearch Serverless** service. If you're looking to develop your PHP application with the Elasticsearch Stack, you should look at the [Elasticsearch Client](https://github.com/elastic/elasticsearch-php) instead. If you're looking to develop your {LANG} application with Elastic Enterprise Search, you should look at the [Enterprise Search Client](https://github.com/elastic/enterprise-search-php/).
5+
This is the official Elastic client for the **Elasticsearch Serverless** service. If you're looking to develop your PHP application with the Elasticsearch Stack, you should look at the [Elasticsearch Client](https://github.com/elastic/elasticsearch-php) instead. If you're looking to develop your PHP application with Elastic Enterprise Search, you should look at the [Enterprise Search Client](https://github.com/elastic/enterprise-search-php/).
66

77
## Installation
88

9+
You can install the library using [composer](https://getcomposer.org/) with the following command:
910

10-
### Instantiate a Client
11+
```bash
12+
composer require elastic/elasticsearch-serverless
13+
```
1114

15+
### Instantiate a Client
1216

13-
### Using the API
17+
When you have installed elasticsearch-php you can start using it with the `Client`` class.
18+
You can use the ClientBuilder class to create this object:
1419

20+
```php
21+
require 'vendor/autoload.php';
1522

16-
Once you've instantiated a client with your API key and Elasticsearch endpoint, you can start ingesting documents into Elasticsearch Service. You can use the **Bulk API** for this. This API allows you to index, update and delete several documents in one request. You call the `bulk` API on the client with a body parameter, an Array of hashes that define the action and a document. Here's an example of indexing some classic books into the `books` index:
23+
use Elastic\Elasticsearch\Serverless\ClientBuilder;
1724

18-
```php
19-
# First we build our data:
20-
body = [
21-
{ index: { _index: 'books', data: {name: "Snow Crash", "author": "Neal Stephenson", "release_date": "1992-06-01", "page_count": 470} } },
22-
{ index: { _index: 'books', data: {name: "Revelation Space", "author": "Alastair Reynolds", "release_date": "2000-03-15", "page_count": 585} } },
23-
{ index: { _index: 'books', data: {name: "1984", "author": "George Orwell", "release_date": "1985-06-01", "page_count": 328} } },
24-
{ index: { _index: 'books', data: {name: "Fahrenheit 451", "author": "Ray Bradbury", "release_date": "1953-10-15", "page_count": 227} } },
25-
{ index: { _index: 'books', data: {name: "Brave New World", "author": "Aldous Huxley", "release_date": "1932-06-01", "page_count": 268} } },
26-
{ index: { _index: 'books', data: {name: "The Handmaid's Tale", "author": "Margaret Atwood", "release_date": "1985-06-01", "page_count": 311} } }
27-
]
28-
# Then we send the data via the bulk api:
29-
> response = client.bulk(body: body)
30-
# And we can check that the items were indexed and given an id in the response:
31-
> response['items']
32-
=>
33-
[{"index"=>{"_index"=>"books", "_id"=>"Pdink4cBmDx329iqhzM2", "_version"=>1, "result"=>"created", "_shards"=>{"total"=>2, "successful"=>1, "failed"=>0}, "_seq_no"=>0, "_primary_term"=>1, "status"=>201}},
34-
{"index"=>{"_index"=>"books", "_id"=>"Ptink4cBmDx329iqhzM2", "_version"=>1, "result"=>"created", "_shards"=>{"total"=>2, "successful"=>1, "failed"=>0}, "_seq_no"=>1, "_primary_term"=>1, "status"=>201}},
35-
{"index"=>{"_index"=>"books", "_id"=>"P9ink4cBmDx329iqhzM2", "_version"=>1, "result"=>"created", "_shards"=>{"total"=>2, "successful"=>1, "failed"=>0}, "_seq_no"=>2, "_primary_term"=>1, "status"=>201}},
36-
{"index"=>{"_index"=>"books", "_id"=>"QNink4cBmDx329iqhzM2", "_version"=>1, "result"=>"created", "_shards"=>{"total"=>2, "successful"=>1, "failed"=>0}, "_seq_no"=>3, "_primary_term"=>1, "status"=>201}},
37-
{"index"=>{"_index"=>"books", "_id"=>"Qdink4cBmDx329iqhzM2", "_version"=>1, "result"=>"created", "_shards"=>{"total"=>2, "successful"=>1, "failed"=>0}, "_seq_no"=>4, "_primary_term"=>1, "status"=>201}},
38-
{"index"=>{"_index"=>"books", "_id"=>"Qtink4cBmDx329iqhzM2", "_version"=>1, "result"=>"created", "_shards"=>{"total"=>2, "successful"=>1, "failed"=>0}, "_seq_no"=>5, "_primary_term"=>1, "status"=>201}}]
25+
$client = ClientBuilder::create()
26+
->setEndpoint('<elasticsearch-endpoint>')
27+
->setApiKey('<api-key>')
28+
->build();
3929

30+
# $client is an object of Elastic\Elasticsearch\Serverless\Client class
4031
```
4132

42-
When you use the client to make a request to Elasticsearch, it will return an API Response object. You can see the HTTP return code by calling `status` and the HTTP headers by calling `headers` on the response object. The Response object behaves as a Hash too, so you can access the body values directly as seen on the previous example with `response['items']`.
4333

44-
Now that some data is available, you can search your documents using the **Search API**:
34+
### Usage
4535

46-
```php
47-
> response = client.search(index: 'books', q: 'snow')
48-
> response['hits']['hits']
49-
=> [{"_index"=>"books", "_id"=>"Pdink4cBmDx329iqhzM2", "_score"=>1.5904956, "_source"=>{"name"=>"Snow Crash", "author"=>"Neal Stephenson", "release_date"=>"1992-06-01", "page_count"=>470}}]
50-
```
36+
You can read to the [official documentation]()
37+
page for a getting started guide.
5138

5239
## Development
5340

@@ -56,3 +43,7 @@ See [CONTRIBUTING](./CONTRIBUTING.md).
5643
### Docs
5744

5845
Some questions, assumptions and general notes about this project can be found in [the docs directory](./docs/questions-and-assumptions.md).
46+
47+
## License 📗
48+
49+
[MIT](LICENSE) © [Elastic](https://www.elastic.co/)

0 commit comments

Comments
 (0)