typesense-php

typesense-php copied to clipboard

Pull Request Not Yet Completed

Feel free to provide any ideas and suggestions.

---

This Pull Request completely reworks this package to achieve the following goals:

1. Remove non-API-related features, such as health check, nodes, etc.
2. Drop non-active-support PHP versions(< 8.2).
3. Support the latest Typesense version(0.25.1).
4. Add strict types to all parameters, methods, and classes.
5. Add static checks(PHPStan).
6. Add tests(Pest) and use GitHub Actions to run tests automatically.
7. Change coding style linter to Pint.

Implemented APIs:

• [x] Collections (2023-12-10)
• [x] Documents (2023-12-10)
• [ ] Search
• [ ] GeoSearch
• [ ] Vector Search
• [ ] Federated / Multi Search
• [x] Analytics & Query Suggestions (2024-03-24)
• [x] API Keys (2024-03-24)
• [x] Curation (2024-03-24)
• [x] Collection Alias (2024-03-24)
• [x] Synonyms (2024-03-24)
• [x] Cluster Operations (2024-03-24)

Documentation:

• [ ] README
• [ ] CHANGELOG
• [ ] UPGRADE

To be supplemented...

@bepsvpt I appreciate the PR, but we are unfortunately unable to entertain a full rewrite of the library, because we want to maintain consistency in the code layout between all the language libraries we officially maintain.

@bepsvpt I appreciate the PR, but we are unfortunately unable to entertain a full rewrite of the library, because we want to maintain consistency in the code layout between all the language libraries we officially maintain.

what do you mean with "consistency in the code layout between all the language libraries"? different languages use a different standard in the project structure, which helps developers keeping their processes lean when dealing with multiple libraries.

I do not see a blocker introducing static-code analysis (Phpstan or PSalm) and strict-types, and tests is a blocking issue. I was personally testing out if TypeSense would be a good fit for our project, but from the missing strict-types, no static analysis and no tests of this library I initially thought that this PHP implementation was abandoned.

I'd be down to accept a PR to add types, and any static analysis tools, to the existing library.

What I meant was, I'd not be down to change the internal file structure and method parameter signatures, to reduce maintenance overhead as we add new features.

I see your point, but I still believe that the current implementation is still leading to headaches.

An example is: how do you know if a collection exists? (this is just one of the examples I found out):

Try 1:

$this->client->getCollections()['collection_name];

Does not work, as the collection is always returned/generated even if it does not exist on the server.

Try 2:

$this->client->getCollections()->offsetExists('collection_name');

this is always false if the API is not yet called under the hood

Try3:

$this->client->getCollections()->retrieve();
// Then one of the (1) or (2) abve

Nope, the API call is invoked, but the results not used to populate the collection

Try4 - conter intiutive (IMO)

$this->client->getCollections()['collection_name]->retrieve()`

Additional notes:

I believe there is a very low DX with this client, which should be tackled IMO I was close to drop Typesense integration, just because of such bad DX I had

how can we help to make the PHP client better?

The actual method call to retrieve a collection is:

$client->collections['companies']->retrieve();

Essentially collections is an "array" of collection objects that you call retrieve() on to make an API call to the server.

Documented under the PHP tab in the docs: https://typesense.org/docs/0.25.2/api/collections.html#retrieve-a-collection

It's been a long time since I wrote production-level PHP, but is that not idiomatic PHP?