Documentation change

Author: jdrda

readme.md

@@ -1,5 +1,4 @@
 ## Laravel Google Custom Search Engine
-
 Laravel package to get Google Custom Search results from Google Custom Search Engine API for both free and paid version.
 
 ##### Brief history
@@ -8,21 +7,21 @@ The best I found was [Spatie's Google Search package](https://github.com/spatie/
 some research and develop package similar way, but independent to Google CSE version. 
 
 ## Installation
-1. Install with Composer
+1/ Install with Composer
 
 ```bash
 composer require jdrda/laravel-google-custom-search-engine
 ```
 
-2. Add the service provider to config/app.php
+2/ Add the service provider to config/app.php
 
 ```php
 'providers' => [
     '...',
     'JanDrda\LaravelGoogleCustomeSearchEngine\LaravelGoogleCustomeSearchEngineProvider'
 ];
 ```
-3. Add alias for Facade to config/app.php
+3/ Add alias for Facade to config/app.php
 ```php
 'aliases' => [
 	...
@@ -31,18 +30,97 @@ composer require jdrda/laravel-google-custom-search-engine
 ]
 ```
 
-4. Publish the config file
+4/ Publish the config file
 ```bash
 php artisan vendor:publish --provider="JDrda\LaravelGoogleCustomeSearchEngine\LaravelGoogleCustomeSearchEngineProvider"
 ```
 
-## Fast configuration
+## Configuration
+
+### Creating your custom search engine
+1. If you create your engine at https://cse.google.com/cse/ you will find the ID after you click at Settings
+2. Just check the URL you have like https://cse.google.com/cse/setup/basic?cx=search_engine_id and the string after cx= is your search engine ID
+     
+!! Attention !! If you change style of your Custom search engine, the ID can be changed
+
+### Get your API key
+1. go to https://console.developers.google.com, than
+2. click on the menu on the right side of the GoogleAPI logo and click on 'Create project'
+3. enter the name of the new project - it is up to you, you can use 'Google CSE'
+4. wait until project is created - the indicator is color circle on the top right corner around the bell icon
+5. API list is shown - search for 'Google Custom Search API' and click on it
+6. click on 'Enable' icone on the right side of Custom Search API headline
+7. click on the 'Credentials' on the left menu under the 'Library' section
+8. click on the 'Create credentials' and choose 'API key'
+9. your API key is shown, so copy and paste it here
+
+### Save the configuration values
+Save search engine ID and api ID in your config/laravelGoogleCustomSearchEngine
+
+## Usage
+
+### Simple usage
+Create an object and call the function getResults to get first 10 results
+```php
+$fulltext = new LaravelGoogleCustomSearchEngine(); // initialize
+$results = $fulltext->getResults('some phrase'); // get first 10 results for query 'some phrase' 
+```
+
+You can also get information about the search like total records and search time
+```php
+$fulltext = new LaravelGoogleCustomSearchEngine(); // initialize
+$results = $fulltext->getResults('some phrase'); // get first 10 results for query 'some phrase' 
+$info = $fulltext->getSearchInformation(); // get search information
+```
+
+### Advanced usage
+You can use any parameter supported at Google. List of parameters is here:
+https://developers.google.com/custom-search/json-api/v1/reference/cse/list#parameters
+
+E.g. you want to get next 10 results
+```php
+$parameters = array(
+    'start' => 10 // start from the 10th results,
+    'num' => 10 // number of results to get, 10 is maximum and also default value
+)
+
+$fulltext = new LaravelGoogleCustomSearchEngine(); // initialize
+$results = $fulltext->getResults('some phrase', $parameters); // get second 10 results for query 'some phrase'
+```
+
+You can also get the raw result from Google including other information
+Full list of response variables is available here:
+https://developers.google.com/custom-search/json-api/v1/reference/cse/list#response
+```php
+$fulltext = new LaravelGoogleCustomSearchEngine(); // initialize
+$results = $fulltext->getResults('some phrase'); // get first 10 results for query 'some phrase'
+$rawResults = $fulltext->getRawResults(); // get complete response from Google
+```
+
+For getting the number of results only use
+```php
+$fulltext = new LaravelGoogleCustomSearchEngine(); // initialize
+$results =  $fulltext->getResults('some phrase'); // get first 10 results for query 'some phrase'
+$noOfResults = $fulltext->getTotalNumberOfResults(); // get total number of results (it can be less than 10)
+```
+
+If you have more engines / more api keys, you can override the config variables with following functions
+
+```php
+$fulltext = new LaravelGoogleCustomSearchEngine(); // initialize
+
+$fulltext->setEngineId('someEngineId'); // sets the engine ID
+$fulltext->setApiKey($apiKey); // sets the API key
+
+$results =  $fulltext->getResults('some phrase'); // get first 10 results for query 'some phrase'
+```
 
 ## Documentation
 Essetial documentation will be at [Github Wiki](https://github.com/jdrda/laravelgooglecsesearch/wiki)
+Now is under the development.
 
 ### License
-The Olapus is open-sourced software licensed under the [MIT license](http://opensource.org/licenses/MIT) 
+This package is open-sourced software licensed under the [MIT license](http://opensource.org/licenses/MIT) 
 
 ## About
 I am independent senior software consultant living in the Czech republic in IT business from 1997.

src/JanDrda/LaravelGoogleCustomSearchEngine/Facades/LaravelGoogleCustomSearchEngineFacade.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace JanDrda\LaravelGoogleCustomSearchEngine\Facades;
+
+use Illuminate\Support\Facades\Facade;
+
+class LaravelGoogleCustomSearchEngineFacade extends Facade
+{
+    /**
+     * Get the registered name of the component.
+     *
+     * @return string
+     */
+    protected static function getFacadeAccessor()
+    {
+        return 'laravelGoogleCustomSearchEngine';
+    }
+}

src/JanDrda/LaravelGoogleCustomSearchEngine/LaravelGoogleCustomSearchEngine.php

@@ -3,9 +3,9 @@
 namespace JanDrda\LaravelGoogleCustomSearchEngine;
 
 use Exception;
-use JDrda\LaravelGoogleCustomSearchEngine\Interfaces\LaravelGoogleCustomSearchEngineInterface;
+use JanDrda\LaravelGoogleCustomeSearchEngine\Interfaces\LaravelGoogleCustomSearchEngineInterface;
 
-class LaravelGoogleCustomSearchEngine implements LaravelGoogleCustomSearchEngineInterface
+class LaravelGoogleCustomSearchEngine
 {
 
     /**
@@ -36,10 +36,10 @@ class LaravelGoogleCustomSearchEngine implements LaravelGoogleCustomSearchEngine
      * @param $engineId
      * @param $apiKey
      */
-    public function __construct($engineId, $apiKey)
+    public function __construct()
     {
-        $this->engineId = $engineId;
-        $this->apiKey = $apiKey;
+        $this->engineId = config('laravelGoogleCustomSearchEngine.engineId');
+        $this->apiKey = config('laravelGoogleCustomSearchEngine.apiKey');
     }
 
     /**
@@ -63,14 +63,31 @@ public function setApiKey($apiKey){
     /**
      * Get search results
      *
+     * Gets results from CSE only as array of objects where the most important variables are
+     * [title] - page title
+     * [htmlTitle] - page title with HTML tags
+     * [link] - page URL
+     * [displayLink] - displayed part of page URL
+     * [snippet] - short text from page with the searched phrase
+     * [htmlSnippet] - short text from page with the searched phrase with HTML tags
+     * complete list of parameters with description is located at
+     * https://developers.google.com/custom-search/json-api/v1/reference/cse/list#response
+     *
+     * Input parameters are available here
+     * https://developers.google.com/custom-search/json-api/v1/reference/cse/list#parameters
+     *
      * @param $phrase
      * @return array
      * @throws Exception
+     * @link https://developers.google.com/custom-search/json-api/v1/reference/cse/list#response
+     * @link https://developers.google.com/custom-search/json-api/v1/reference/cse/list#parameters
      */
-    public function getResults($phrase)
+    public function getResults($phrase, $parameters = array())
     {
-        $searchResults = array();
 
+        /**
+         * Check required parameters
+         */
         if ($phrase == '') {
             return $searchResults;
         }
@@ -83,28 +100,100 @@ public function getResults($phrase)
             throw new \Exception('You must specify a apiKey');
         }
 
-        // create a new cURL resource
+        /**
+         * Create search aray
+         */
+        $searchArray = http_build_query(array_merge(
+            ['key' => $this->apiKey],
+            ['q' => $phrase],
+            $parameters
+        ));
+
+        /**
+         * Add unencoded search engine id
+         */
+        $searchArray = '?cx=' . $this->engineId . '&' . $searchArray;
+
+        /**
+         * Prepare CUrl and get result
+         */
         $ch = curl_init();
 
-        curl_setopt($ch, CURLOPT_URL, "http://www.example.com/");
+        curl_setopt($ch, CURLOPT_URL, "https://www.googleapis.com/customsearch/v1" . $searchArray);
         curl_setopt($ch, CURLOPT_HEADER, 0);
+        curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
         curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
         curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
+        curl_setopt($ch, CURLOPT_POST, 0);
 
         $output = curl_exec($ch);
 
         $info = curl_getinfo($ch);
 
         curl_close($ch);
 
+        /**
+         * Check HTTP code of the result
+         */
         if ($output === false || $info['http_code'] != 200) {
 
             throw new \Exception("No data returned, code [". $info['http_code']. "] - " . curl_error($ch));
+        }
+
+        /**
+         * Convert JSON format to object and save
+         */
+        $this->originalResponse = json_decode($output);
 
+        /**
+         * If there are some results, return them, otherwise return blank array
+         */
+        if(isset($this->originalResponse->items)){
+            return $this->originalResponse->items;
+        }
+        else{
+            return array();
         }
 
+    }
 
-        return $searchResults;
+    /**
+     * Get full original response
+     *
+     * Gets full originated response converted from JSON to StdClass
+     * Full list of parameters is located at
+     * complete list of parameters with description is located at
+     * https://developers.google.com/custom-search/json-api/v1/reference/cse/list#response
+     *
+     * @return \stdClass
+     * @url https://developers.google.com/custom-search/json-api/v1/reference/cse/list#response
+     */
+    public function getRawResult(){
+        return $this->originalResponse;
+    }
+
+    /**
+     * Get search information
+     *
+     * Gets basic information about search
+     * [searchTime] - time costs of the search
+     * [formattedSearchTime] - time costs of the search formatted according to locale style
+     * [totalResults] - number of results
+     * [formattedTotalResults] - number of results formatted according to locale style
+     *
+     * @return \stdClass
+     */
+    public function getSearchInformation(){
+        return $this->originalResponse->searchInformation;
+    }
+
+    /**
+     * Get the total number of pages where the search phrase is located
+     *
+     * @return integer
+     */
+    public function getTotalNumberOfpages(){
+        return $this->originalResponse->searchInformation->totalResults;
     }
 
 }