added readme and refactoring

DieSchittigs · Oct 22, 2017 · 34f9a7a · 34f9a7a
1 parent 8631073
commit 34f9a7a
Show file tree

Hide file tree

Showing 11 changed files with 285 additions and 44 deletions.
diff --git a/composer.json b/composer.json
@@ -1,6 +1,7 @@
 {
     "require": {
-        "facebook/graph-sdk": "^5.6"
+        "facebook/graph-sdk": "^5.6",
+        "markrogoyski/math-php": "0.*"
     },
     "autoload": {
         "psr-4": {

diff --git a/composer.lock b/composer.lock
diff --git a/index.php → example.php b/index.php → example.php
@@ -3,10 +3,12 @@
 use DieSchittigs\StarScraper\StarRating;
 use DieSchittigs\StarScraper\GooglePlaceProvider;
 use DieSchittigs\StarScraper\FacebookPageProvider;
+use DieSchittigs\StarScraper\FakeRatingsProvider;
 
 require 'vendor/autoload.php';
 
 $starRating = new StarRating();
+
 $starRating->addProvider(
 	new GooglePlaceProvider(
 		'{{GoogleApiKey}}',
@@ -17,12 +19,22 @@
 	new FacebookPageProvider(
 		'{{FacebookAppID}}',
 		'{{FacebookAppSecret}}',
-		'{{FacebookPage}}'
+		'{{FacebookPageID}}'
 	)
 );
 
+$starRating->addProvider(
+	new FakeRatingsProvider([5,4,3,5,4])
+);
+
+$starRating->addProvider(
+	new FakeRatingsProvider([1,2,1,3,1,3])
+);
+
 $rating = $starRating->getRating();
 
+print_r($rating);
+
 echo '
 "aggregateRating": {
 	"@type": "AggregateRating",

diff --git a/readme.md b/readme.md
@@ -0,0 +1,118 @@
+# Star Scraper
+
+A PHP library by [Die Schittigs](https://www.dieschittigs.de).
+
+## What's this?
+
+Star Scraper is built to aggregate ratings from different websites (e.g. Google Places, Facebook) into one average rating intended to be visibe on your website. This is especially useful for local businesses, that have reviews on Facebook *and* other platforms and want these ratings to be displayed on their homepage in a unified way. It may also be used to display those little stars besides Google search results.
+
+## Installation
+
+Install via [Composer](https://getcomposer.org).
+
+    composer require dieschittigs/star-scraper
+
+## Usage
+
+First, do some imports and initialize StarRating
+
+    use DieSchittigs\StarScraper\StarRating;
+    use DieSchittigs\StarScraper\GooglePlaceProvider;
+    use DieSchittigs\StarScraper\FacebookPageProvider;
+    use DieSchittigs\StarScraper\FakeRatingsProvider;
+
+    $starRating = new StarRating();
+
+Now you may add RatingProviders (that's where your ratings are coming from). For now we only have support for Google Places (also called Google My Business) and Facebook Pages.
+
+### Google My Business / Google Maps Places
+
+    You'll need an [Google API-key](https://console.developers.google.com) (activate *Google Places API Web Service*) and your [PlaceID](https://developers.google.com/maps/documentation/javascript/examples/places-placeid-finder) (your business on Google Maps).
+
+    $starRating->addProvider(
+        new GooglePlaceProvider(
+            '{{GoogleApiKey}}',
+            '{{GoogleMapsPlaceID}}'
+        )
+    );
+
+### Facebook Pages
+
+    You'll need an [Facebook App ID and App Secret](https://developers.facebook.com) and your [PageID](https://findmyfbid.com/).
+
+    $starRating->addProvider(
+        new FacebookPageProvider(
+            '{{FacebookAppID}}',
+            '{{FacebookAppSecret}}',
+            '{{FacebookPageID}}'
+        )
+    );
+
+### Fake Ratings
+
+If you just want to try things out, use some fake ratings.
+
+    $starRating->addProvider(
+        new FakeRatingsProvider([5,4,3,5,4])
+    );
+
+    $starRating->addProvider(
+        new FakeRatingsProvider([1,2,1,3,1,3])
+    );
+
+### Get the average rating
+
+To get the *median* ratings from all of your providers, simply call
+
+    $rating = $starRating->getRating();
+
+This will give you the median - if you prefer the less accurate mean average, call
+
+    $rating = $starRating->getRating('mean');
+
+The result will look like this
+
+    DieSchittigs\StarScraper\Rating Object
+    (
+        [bestRating] => 5
+        [ratingCount] => 18
+        [ratingValue] => 4.5
+    )
+
+## Extend
+
+If you want to add you own RatingProviders, it's pretty straighforward.
+
+    use DieSchittigs\StarScraper\RatingProvider;
+    use DieSchittigs\StarScraper\Rating;
+
+    class CustomRatingsProvider extends RatingProvider{
+        private $reviews;
+        public function __construct($apiKeysOrWhatever){
+            $this->bestRating = 100;
+            // call an API or fetch your results from a DB
+            $this->reviews = $reviews;
+        }
+        public function getRating($method = 'median'){
+            // Return null if e.g. your api call died
+            if(!$this->reviews) return null;
+            $rating = new Rating($this->bestRating, count($this->reviews));
+            $scores = [];
+            foreach($this->reviews as $review){
+                $scores[] = $review->rating;
+            }
+            $rating->avgRatingValue($scores, $method);
+            return $rating;
+        }
+    }
+
+## Contribute
+
+We need more RatingProviders! Sources for Ratings are:
+
+- Yelp
+- LinkedIN
+- Xing
+- ...
+
+Your help is very welcome :)
diff --git a/src/FacebookPageProvider.php b/src/FacebookPageProvider.php
@@ -4,8 +4,7 @@
 
 use Facebook\Facebook;
 
-class FacebookPageProvider implements iRatingProvider{
-    private $BEST_RATING = 5;
+class FacebookPageProvider extends RatingProvider{
     private $result;
 
     public function __construct($appID, $appSecret, $pageId){
@@ -24,17 +23,18 @@ public function __construct($appID, $appSecret, $pageId){
             echo 'Facebook SDK returned an error: ' . $e->getMessage();
         }
     }
-    public function getRating(){
+    public function getRating($method = 'median'){
         if(
             !$this->result ||
             !$this->result['id'] ||
             !$this->result['rating_count'] ||
             !$this->result['overall_star_rating']
         ) return null;
-        $rating = new Rating();
-        $rating->bestRating = $this->BEST_RATING;
-        $rating->ratingCount = $this->result['rating_count'];
-        $rating->ratingValue = $this->result['overall_star_rating'];
+        $rating = new Rating(
+            $this->bestRating,
+            $this->result['rating_count'],
+            $this->result['overall_star_rating']
+        );
         return $rating;
     }
 }

diff --git a/src/FakeRatingsProvider.php b/src/FakeRatingsProvider.php
@@ -0,0 +1,19 @@
+<?php
+
+namespace DieSchittigs\StarScraper;
+
+use Facebook\Facebook;
+
+class FakeRatingsProvider extends RatingProvider{
+    private $scores;
+
+    public function __construct(Array $scores = [3,1,4,2,5]){
+        $this->scores = $scores;
+    }
+    public function getRating($method = 'median'){
+        $rating = new Rating($this->bestRating);
+        $rating->avgRatingValue($this->scores, $method, true);
+        return $rating;
+    }
+}
+
diff --git a/src/GooglePlaceProvider.php b/src/GooglePlaceProvider.php
@@ -2,9 +2,8 @@
 
 namespace DieSchittigs\StarScraper;
 
-class GooglePlaceProvider implements iRatingProvider{
+class GooglePlaceProvider extends RatingProvider{
     private $reviews;
-    private $BEST_RATING = 5;
 
     public function __construct($GoogleApiKey, $GoogleMapsPlaceID){
         $placeReviews = [];
@@ -20,16 +19,14 @@ public function __construct($GoogleApiKey, $GoogleMapsPlaceID){
             $this->reviews = $placeReviews;
         }
     }
-    public function getRating(){
+    public function getRating($method = 'median'){
         if(!$this->reviews) return null;
-        $rating = new Rating();
-        $rating->bestRating = $this->BEST_RATING;
-        $rating->ratingCount = count($this->reviews);
-        $score = 0;
+        $rating = new Rating($this->bestRating);
+        $scores = [];
         foreach($this->reviews as $review){
-            $score += $review->rating;
+            $scores[] = $review->rating;
         }
-        $rating->ratingValue = $score / $rating->ratingCount;
+        $rating->avgRatingValue($scores, $method, true);
         return $rating;
     }
 }

diff --git a/src/Rating.php b/src/Rating.php
@@ -2,8 +2,34 @@
 
 namespace DieSchittigs\StarScraper;
 
+use MathPHP\Statistics\Average;
+
 class Rating{
-    public $bestRating = 0;
-    public $ratingCount = 0;
-    public $ratingValue = 0;
+    public $bestRating;
+    public $ratingCount;
+    public $ratingValue;
+    public function __construct($bestRating = 0, $ratingCount = 0, $ratingValue = 0){
+        $this->bestRating = $bestRating;
+        $this->ratingCount = $ratingCount;
+        $this->ratingValue = $ratingValue;
+    }
+    public function isValid(){
+        return (
+            $this->bestRating > 0 &&
+            $this->ratingCount > 0 &&
+            $this->ratingValue >= 0
+        );
+    }
+    public function avgRatingValue(Array $scores, $method = 'median', $doSetRatingCount = false){
+        if($doSetRatingCount) $this->ratingCount = count($scores);
+        switch($method){
+            case 'mean':
+                $this->ratingValue = Average::mean($scores);
+                return true;
+            case 'median':
+                $this->ratingValue = Average::median($scores);
+                return true;
+        }
+        return false;
+    }
 }
diff --git a/src/RatingProvider.php b/src/RatingProvider.php
@@ -0,0 +1,14 @@
+<?php
+
+namespace DieSchittigs\StarScraper;
+
+abstract class RatingProvider{
+    public $bestRating = 5;
+
+    public function getRating($method = 'median'){
+        $scores = [2,4,1,5];
+        $rating = new Rating($this->bestRating, count($scores));
+        $rating->setAvgRatingValue($scores, $method);
+        return $rating;
+    }
+}