Lableb Cloud Search Laravel Package

Easily integrate with Lableb to add powerful search capabilities in-website/in-app :

• search (instant results & highly configurable)
• autocomplete (super fast & understand what you want)
• recommend (direct links between your data can be fetching using smart recommendation)
• index new data(documents) (indexing data make it available in search results)
• update existing data (documents get updated all the times...no problem, you can update it easily)
• delete documents(easily remove from search results)

To get your tokens and other config options

• login to Lableb Dashboard
• open API Keys tab
• generate new tokens(or use the existing ones)
• copy project name as it is(in small letters)

Installation

Install using composer:

$ composer require lableb/laravel-sdk

Then To Publish lableb.php File To Your Config Directory:

$ php artisan vendor:publish --provider="Lableb\ServiceProviders\LablebServiceProvider"

Add The Following Keys To Your Environment Variables File .env file

( You Can Get The Values From https://dashboard.lableb.com/dashboard/login ) :

LABLEB_PROJECT_NAME=your_project_name
LABLEB_SEARCH_TOKEN=xxxxx-search-token-xxxxxx
LABLEB_INDEX_TOKEN=xxxxx-index-token-xxxxxx

You May Probably Need To Clear Cache After That Using The Following Commands :

$ php artisan config:clear

Usage

you can initialize the Package:

use Lableb\LablebSDK;

$lableb = new LablebSDK(); 

You Can Also Pass Parameters Like This

use Lableb\LablebSDK;

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

Notice

it is preferred to keep your tokens out of your source code you can save them in an environment variables file then add it to .gitignore for example .

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" => "this is a title 1",
  "content" => "this is article content",
  "category" => ["cat1", "cat2"],
  "tags" => ["tag1", "tag2"],
  "url" => "https://solutions.lableb.com/en/doc/laravel-sdk/index-documents",
  "authors" => ["Lableb Team"],
  "date" => new \DateTime()
]];

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

Example response:

[
  "indexed" => true,
  "message" => "1 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):

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' => 'Food',
      'tags' => [ 'delicious', 'pizza' ]
    ]
  ] );
}
catch( \Lableb\Exceptions\LablebException $e )
{
  echo $e->getStatus()." - ".$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/v2/....'
    ],
  ],
  '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.

Autocomplete Options ($queryOptions):

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

Example:

try
{
  $response = $lableb->autocomplete( 'posts', [
    'q' => 'how to ma'
  ] );
}
catch( \Lableb\Exceptions\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/v2/....'
    ],
    [
      'suggestion_type' => 'filter',
      'phrase' => 'Posts about pizza',
      'filters' => [
        'meta' => ['Pizza', 'Food']
      ]
    ]
  ]
  'totalFacets' => 0
  'facets' => Array
        (
        )
]

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):

try
{
  $response = $lableb->recommend( 'posts', [
    'id' => 1
  ] );
}
catch( \Lableb\Exceptions\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/v2/....'
    ],
  ],
  'totalFacets' => 0
  'facets' => Array
        (
        )
]

Notice

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

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):

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\Exceptions\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\Exceptions\LablebException $e )
{
  echo $e->getMessage();
}

Example response:

[
  'submitted' => true
]

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\Exceptions\LablebException $e )
{
  echo $e->getMessage();
}

Example response:

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

SDK offers:

• indexing documents function (indexing data make it available in search results)
• delete document function (easily remove from search results)
• search function that enable you to send queries to Lableb API
• autocomplete function that help your user predicting what they are searching for
• recommend function help you get similar document given an existing document
• feedback function for search & autocomplete & recommend which is highly important to you to track your users search choices & recommendation in Lableb dashboard

Security

If you discover any security related issues, please email support@lableb.com instead of using the issue tracker.

Credits

• Lableb

License

The MIT License (MIT). Please see License File for more information.