README

A tool to connect to Jina with PHP. This client will not work without a running Jina installation.

To see how that is set up go here: Jina Installation

Jina Documentation

For more information about Jina go here: Jina

Install with composer command

    composer require dco-ai/php-jina

Install using composer.json

from GitHub directly:

Add this to your composer.json file or create the file and put this in it.

{
  "name":  "dco-ai/php-jina",
  "repositories": [
    {
      "type": "svn",
      "url": "https://github.com/Dco-ai/php-jina.git"
    }
  ],
  "require": {
    "dco-ai/php-jina": "main"
  }
}

or from Packagist:

{
  "require": {
    "dco-ai/php-jina": "v1.*"
  }
}

now run composer with composer update

Configuration

This client needs to know a few things about your Jina project to make the connection.

The configuration is an associative array with the following fields:

Usage

A small example is src/example.php. This shows you how to load the class and then create/update Jina's Document and DocumentArray structures.

First include the package in the header:

<?php
use DcoAi\PhpJina\JinaClient;

Then Instantiate the JinaClient class with your configuration:

$config = [
    "url" => "localhost", // The URL or endpoint of your Jina installation
    "port" => "1234", // The port used for your Jina Installation
    "endpoints" => [ // These are the active endpoints in your Jina application with the corresponding method
        "/status" => "GET",
        "/post" => "POST",
        "/index" => "POST",
        "/search" => "POST",
        "/delete" => "DELETE",
        "/update" => "PUT",
        "/" => "GET"
    ]
];
$jina = new JinaClient($config);

Now you can use these functions:

// this creates a Document that you can add data to the structure
$d = $jina->document();

// This creates a DocumentArray that Documents can be added to
$da = $jina->documentArray();

// This adds Documents to a DocumentArray
$jina->addDocument($da, $d);

// This sends the DocumentArray to your JinaClient application and returns the result.
$jina->submit("/index",$da);

Structures

Document

DocumentArray

Filters

Filters are unique to each Data Store in DocArray. the structure and how they are passed is dependent on how you have your Executors set up. For every example I am providing I am assuming your Executors accept a filter key in the parameters section of the request. If your Executors are set up to accept filters in a different way you will need to modify the request accordingly.

In this client you can build a filter by chaining together filter functions. First you have to create an instance of the Filter class with the useFilterFormatter() function.

use DcoAi\PhpJina\JinaClient;
// set the config and create a new instance of the JinaClient
$config = [
    "url" => "localhost",
    "port" => "1234",
    "endpoints" => [
        "/status" => "GET",
        "/post" => "POST",
        "/index" => "POST",
        "/search" => "POST",
        "/delete" => "DELETE",
        "/update" => "PUT",
        "/" => "GET",
    ]
];
$jina = new JinaClient($config);

// create a new instance of the filter class
$filterBuilder = $jina->useFilterFormatter();

Now that you have the filter this is how you would chain together a basic filter:

$filterBuilder->
    and()->
        equal("env","dev")->
        equal("userId","2")->
    endAnd()->
    or()->
        notEqual("env","2")->
        greaterThan("id","5")->
    endOr()->
    equal("env","dev")->
    notEqual("env","prod");

Some Data Stores will have grouping operators like and and or that will allow you to group filters together. If the Data Store has these operators there will be a closing function which corresponds to the opening function.

Once you have your filter built you will need to retrieve it from the Filter class and add it to the request. This is not done automatically.

// Lets make an empty DocumentArray
$da = $jina->documentArray();
// And add the filter to the parameters 
$da->parameters->filter = $filterBuilder->createFilter();
// print ths document and see what we got
print_r(json_encode($da, JSON_PRETTY_PRINT));

This filter will produce a string like this:

{
    "data": [],
    "parameters": {
        "filter": [
            {
                "$and": [
                    {
                        "env": {
                            "$eq": "dev"
                        }
                    },
                    {
                        "userId": {
                            "$eq": "2"
                        }
                    }
                ]
            },
            {
                "$or": [
                    {
                        "env": {
                            "$ne": "2"
                        }
                    },
                    {
                        "id": {
                            "$gt": 5
                        }
                    }
                ]
            },
            {
                "env": {
                    "$eq": "dev"
                }
            },
            {
                "env": {
                    "$ne": "prod"
                }
            }
        ]
    }
}

This example is a bit complicated and probably not useful, but it shows what can be done.

Default Filter

DocArray has a default filter structure that can be used by this client without any configuration changes. Documentation can be found here: Documentation

This is a list of the operators that are supported by the Default filter. The $column is the field you are filtering on and the $value is the value you are filtering on.

The list of combining functions for the Default filter is here:

AnnLite Filter

This filter uses the AnnLite Data Store and is very similar to the Default filter with some minor differences. Documentation can be found here: Documentation

To use this filter you must add the "type" => "annlite" key to the dataStore array in the configuration.

use DcoAi\PhpJina\JinaClient;
// set the config and create a new instance of the JinaClient
$config = [
    "url" => "localhost",
    "port" => "1234",
    "endpoints" => [
        "/status" => "GET",
        "/post" => "POST",
        "/index" => "POST",
        "/search" => "POST",
        "/delete" => "DELETE",
        "/update" => "PUT",
        "/" => "GET",
    ],
    "dataStore" => [
        "type" => "annlite",
    ]
];
$jina = new JinaClient($config);

Like all other filters you can build it using the chaining method. Here are the specific fields using this Data Store:

The list of combining functions for the Default filter is here:

Weaviate Filter

This filter uses the Weaviate Data Store and uses GraphQL as the query language. Since this language is dependent on the schema in the DB we need to connect to your Weaviate instance and retrieve the schema to build the query. This is done automatically, but you will need to add the url and port parameters when creating the JinaClient instance. Documentation can be found here: Documentation

To use this filter you must add the "type" => "weaviate" key to the dataStore array in the configuration.

use DcoAi\PhpJina\JinaClient;
// set the config and create a new instance of the JinaClient
$config = [
    "url" => "localhost",
    "port" => "1234",
    "endpoints" => [
        "/status" => "GET",
        "/post" => "POST",
        "/index" => "POST",
        "/search" => "POST",
        "/delete" => "DELETE",
        "/update" => "PUT",
        "/" => "GET",
    ],
    "dataStore" => [
        "type" => "weaviate",
        "url" => "localhost",
        "port" => "8080",
    ]
];
$jina = new JinaClient($config);

Here are the specific fields using this Data Store:

The list of combining functions for the Default filter is here:

All Other Data Store Filters

Currently, these are not supported but are planned for future releases. If you would like to contribute to this project please feel free to submit a pull request and reach out to me for any questions.

Response

To save on data transfer and memory when making calls to your Jina application this client will clean up the request and response automatically by removing any key where the value is not set. Keep this in mind when performing evaluations on the response by checking if the key exists first.

If you want all the values returned you can set a flag when using the submit() function

// setting the third parameter to false will not remove any empty values from the response
$jina->submit("/index", $da, false);