Lableb Cloud Search php sdk

Installation

Install using composer:

$ composer require lableb/php-sdk

Usage

To use the sdk, first of all require composer's autoload file in your php code:

require_once 'vendor/autoload.php';

Then you can initialize the sdk as follows:

use Lableb\LablebSDK;

$lableb = new LablebSDK(
  "project name",
  "search token",
  "indexing token"
);

Notice

All LablebSDK methods throws LablebException exception in case of an exception happens. Use the sdk with try-catch

Index Documents

$lableb->index( $collection, $documents )

• $collection: what collection you want to index documents on, e.x posts.
• $documents: a document or an array of documents to be indexed.

Example:

$collection = 'posts';
$documents = [
  [
    'id' => 1,
    'title_t_bi' => 'Using the php sdk'
    'contnet_t_bi' => 'Lableb cloud search php sdk',
    'date_dta' => [ '2013-02-05', new DateTime(), date('Y-d-m') ]
  ]
];

try
{
  $response = $lableb->index( $collection, $documents );
}
catch ( \Lableb\LablebException $e )
{
  echo $e->getStatus();
  echo $e->getMessage();
}

Example response:

[
  "indexed" => true,
  "message" => "2 documents has been indexed"
]

Search Documents

$lableb->search( $collection, $queryOptions, [$handler] )

• $collection: collection name you want to search in.
• $queryOptions: an associative array of search parameters.
• $handler: an optional parameter that has the value of default by default, specify it if you want to use a custom search handler.

Search Parameters ($queryOptions):

Option	Description	Required	Example
q	search term	yes	'how to make pizza'
filter	search filters	no	[ 'tags_sa' => 'delicious' ]
limit	how many documents to fetch	no	10
skip	how many documents to skip (offset)	no	50
sort	order of documents	no	'date_dt asc' or 'date_dt desc', in general it's field_name + order
user_id	a unique user id	no	1254
user_ip	user IP address	no	'55.22.11.6'
user_country	user country code	no	'CA'

You can specify any additional query string parameters if you need to, for example 'lang' => 'ar' or 'tag' => ['tag1', 'tag2']].

Example:

try
{
  $response = $lableb->search( 'posts', [
    'q' => 'how to make pizza',
    'filter' => [
      'category_sa' => 'Food',
      'tags_sa' => [ 'delicious', 'pizza' ]
    ]
  ] );
}
catch( \Lableb\LablebException $e )
{
  echo $e->getMessage();
}

Example Response:

[
  'totalDocuments' => 50,
  'results' => [
    [
      'id' => 1,
      'title' => 'How to make italian pizza',
      'content' => 'The italian pizza, margherita ...',
      'date' => '2018-12-06T12:16:00.000+0000',
      'url' => 'https://funfunfood.com/2018/12/06/pizza',
      'image' => 'https://funfunfood.com/static/pizza.png',
      'feedbackUrl' => 'https://api-bahuth.lableb.com/api/v1/....'
    ],
  ],
  'totalFacets' => 50,
  'facets' => [
    'categories' => [
      [
        'value' => 'Food',
        'count' => 8
      ]
    ],
    'tags' => [],
    'authors' => [],
    'year' => []
  ]
]

Notice

Each result will have an additional field called feedbackUrl which you can perform a GET request on to submit search feedback

Autocomplete

$lableb->autocomplete( $collection, $queryOptions, [$handler] )

• $collection: collection name you want to search for suggestions in.
• $queryOptions: an associatve array with search parameters.
• $handler: an optional parameter that has the value of suggest by default, specify it if you want to use a custom autocomplete handler.

Search Options ($queryOptions):

Option	Description	Required	Example
q	search term	yes	'how to ma'
user_id	a unique user id	no	1254
user_ip	user IP address	no	'55.22.11.6'
user_country	user country code	no	'CA'

You can specify any additional query string parameters if you need to.

Example:

try
{
  $response = $lableb->autocomplete( 'posts', [
    'q' => 'how to ma'
  ] );
}
catch ( \Lableb\LablebException $e )
{
  echo $e->getMessage();
}

Example response:

There are two types of suggestions:

1. Navigational suggestion which refers to an article
2. Filter suggestion which has search filters that can be used with search

[
  'totalSuggestions' => 33,
  'suggestions' => [
    [
      'suggestion_type' => 'navigational',
      'id' => 1,
      'phrase' => 'How to make italian pizza',
      'date' => '2018-12-06T12:16:00.000+0000',
      'url' => 'https://funfunfood.com/2018/12/06/pizza',
      'feedbackUrl' => 'https://api-bahuth.lableb.com/api/v1/....'
    ],
    [
      'suggestion_type' => 'filter',
      'phrase' => 'Posts about pizza',
      'filters' => [
        'meta_sa' => ['Pizza', 'Food']
      ]
    ]
  ]
]

Notice

Each result will have an additional field called feedbackUrl which you can perform a GET request on to submit autocomplete feedback.

Recommendations (Related Articles)

To fetch other posts that are related to some post

$lableb->recommend( $collection, $options, [$handler] )

• $collection: collection name you want to search for recommendations in.
• $options: an associative describing the source document.
• $handler: an optional parameter that has the value of recommend by default, specify it if you want to use a custom search handler.

Source document parameters ($options):

Option	Description	Required	Example
id	ID of the source document	yes	1
title	title of the source document	no	'How to make italian pizza'
url	url of the source document	no	'https://funfunfood.com/2018/12/06/pizza'
limit	how many documents to fetch	no	5
user_id	a unique user id	no	1254
user_ip	user IP address	no	'55.22.11.6'
user_country	user country code	no	'CA'

try
{
  $response = $lableb->recommend( 'posts', [
    'id' => 1
  ] );
}
catch( \Lableb\LablebException $e )
{
  echo $e->getMessage();
}

Example response:

[
  'totalDocuments' => 50,
  'results' => [
    [
      'id' => 1,
      'title' => 'How to make italian pizza',
      'content' => 'The italian pizza, margherita ...',
      'date' => '2018-12-06T12:16:00.000+0000',
      'url' => 'https://funfunfood.com/2018/12/06/pizza',
      'image' => 'https://funfunfood.com/static/pizza.png',
      'feedbackUrl' => 'https://api-bahuth.lableb.com/api/v1/....'
    ],
  ]
]

Delete Documents

$lableb->delete( $collection, $id )

• $collection: collection name you want to delete the document from.
• $id: ID of the document to be deleted.

Example:

try
{
  $response = $lableb->delete( 'posts', 1 );
}
catch( \Lableb\LablebException $e )
{
  echo $e->getMessage();
}

Example response:

[
  'deleted' => true,
  'message' => 'Document with ID of 1 has been deleted'
]

Submit Feedback

There are three types of feedback:

• Search feedback: this feedback is submitted when a user searches then hits a search result.
• Autocomplete feedback: this feedback is submitted when a user hits an autocomplete suggestion.
• Recommendation feedback: this feedback is submitted when a user hits a recommended article.

Submit Search Feedback

$lableb->submitSearchFeedback( $collection, $options, [$handler] )

• $collection: collection name that search has been made in.
• $options: an associative describing the hit document.
• $handler: an optional parameters which defaults to default and it is handler name used in search.

Search Feedback Options ($options):

Option	Description	Required	Example
query	what was the query user searched for	yes	'how to make pizza'
item_id	the ID of the hit result	yes	1
item_order	the order of the hit in the results starting from 1 not from 0	yes	1
url	url of the source document	yes	'https://funfunfood.com/2018/12/06/pizza'
user_id	a unique user id	no	1254
user_ip	user IP address	no	'55.22.11.6'
user_country	user country code	no	'CA'

Example:

try
{
  $lableb->submitSearchFeedback( 'posts', [
    'query' => 'How to make pizza',
    'item_id' => 1,
    'item_order' => 1,
    'url' => 'https://funfunfood.com/2018/12/06/pizza'
  ] );
}
catch( \Lableb\LablebException $e )
{
  echo $e->getMessage();
}

Example response:

[
  'submitted' => true
]

Submit Autocomplete Feedback

$lableb->submitAutocompleteFeedback( $collection, $options, [$handler] )

Exactly same as Search feedback submission but item_id and url are not required for navigational suggestions.

Submit Recommendation Feedback

$lableb->submitRecommendationFeedback( $collection, $source, $target, [$handler] )

• $collection: collection name that search for recommendations has been made in.
• $source: the source document.
• $target: the hit document.
• $handler: an optional parameters which defaults to default and it is handler name used in search.

Example:

try
{
  $source = [
    'id' => 1, // REQUIRED
    'title' => 'How to make italian pizza',
    'url' => 'https://funfunfood.com/2018/12/06/pizza',

    // OPTIONAL fields and only specified in source
    'user_id' => 2582,
    'user_ip' => '25.25.12.4',
    'user_country' => 'CA'
  ];

  $target = [
    'id' => 2, // REQUIRED
    'title' => 'How to make margherita',
    'url' => 'https://funfunfood.com/2018/12/06/margherita',

    // Only in target
    'item_order' => 1
  ];

  $response = $lableb->submitRecommendationFeedback( 'posts', $source, $target );
}
catch( \Lableb\LablebException $e )
{
  echo $e->getMessage();
}

Example response:

[
  'submitted' => true
]