Merge branch 'release/1.0.0'

README.md

@@ -5,6 +5,8 @@
 [![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE.md)
 [![Build Status](https://img.shields.io/travis/utvarp/music-helper/master.svg?style=flat-square)](https://travis-ci.org/utvarp/music-helper)
 
+*In development.*
+
 There is a lot of source for music information around. Maybe you just want to search one of them. Maybe you need to have many of the at the same time. This package is here for you!
 
 ## Installation
@@ -15,36 +17,94 @@ You can install the package via composer:
 composer require utvarp/music-helper
 ```
 
-### Provider
-
-Then add the ServiceProvider to your `config/app.php` file:
+## Usage
 
 ```php
-'providers' => [
-    ...
+$music = new Utvarp\Music();
+
+// sets a source, takes string, array or collection. Defaults to 'all' if no parameters.
+$music->sources('all');
+$music->artist('Lady Gaga'); // sets an artist to search for
+$music->track('Poker Face'); // sets a track to search for
+
+$search = $music->search(15); // value is to set a limit to the results. Default is 25.
 
-    Utvarp\MusicHelper\MusicHelperServiceProvider::class
+// It could also be chained as such
+$search = $music->sources('all')->artist('Lady Gaga')->track('Poker Face')->search(15);
 
-    ....
-]
+// You can then call the corresponding method to get the results, or use $search direcly
+$search->getResults(); // no parameters = all. Returns a collection or the requested value
+$search->getResultsCount('deezer'); // same comment as getResults()
 ```
 
-## Usage
+## Examples and what to expect in the results
+
+For now, this package will only fetch _basic_ informations:
+
+- The track name and id from requested source; 
+- (If available) The artist name and id from requested source;
+- (If available) The album name and id from requested source;
+
+_For now_, you need to make extra call to the source API (with the ID) to fetch more detailed information.
+
+In addition to the information from the source API, the package will also perform a string similarity check between a result's track and artist name against the actual searched for result. That way, you could decide not to trust the source' listing order and sort yourself by one of the smililarity score.
+
+Here's how you could play with the package:
 
 ```php
 $music = new Utvarp\Music();
-echo $music->echoPhrase('Útvarp means radio, in Icelandic.');
+$search = $music->search->source('all')->artist('Lady Gaga')->track('Poker Face')->search(15);
+$deezerResults = $search->getResults('deezer');
+
+$count = $deezerResults->count; // fetch the total results count
+$results = $deezerResults->results; // get the actual result collection
+
+// access a result
+$result = $results->first(); // Since it's a collection
+//or
+$result = $results[0]; // But you can still access it as an array
+
+// from here you can play with the track, artist or album object.
+$trackId = $result->track->id;
+$trackName = $result->track->name;
+$albumName = $result->album->name;
+
+// the similarity score isn't available for the album, since we don't (yet?) search by album
+$similarTextScore = $result->track->similarityScores->similar_text; // maximum score of 100.0
+$smgScore = $result->track->similarityScores->smg; // Smith Waterman Gotoh score, maximum of 1.0
+$levenshteinScore = $result->track->similarityScores->levenshtein; // Levenshtein score, maximum of 1
+
 ```
 
+## Wishlist / Roadmap / Help wanted 👷🚧👷‍♀️
+
+- Caching search so we don't hit any API rate limit too quickly
+- More source
+- Add more information to source (?)
+- Add methods to make more precise search in sources' APIs (for ex.: searching by the ID returned by the basic search)?
+
+## How to create new source
+
+This should be easy. Follow the next steps and check the corresponding files for the `deezer` source and just build from there!
+
+1. Create a new search class in `src\Searches\{SourceName}.php`. This class should be only responsible to make the search to the source's api.
+2. Create a new model class in `src\Models\{SourceName}Result.php`. This class should be only responsible to correctly _format_ the results received by the API  and set the `track`, `artist` and `album` values using the corresponding methods you can find in the base `Result` model.
+3. Add `sourceName` to the `possibleSources` collection in the constructor of `src\Music.php`.
+4. Test your things, but it should now be all ok!
+
 ## Testing
 
 ```bash
 $ composer test
 ```
 
+## Changelog
+
+Changes can be found [in the release pages of the repo](https://github.com/Utvarp/music-helper/releases).
+
 ## Contributing
 
-Contributions are welcome, [thanks to y'all](https://github.com/utvarp/music-helper/graphs/contributors) :)
+Contributions are welcome, [thanks to everyone who sent something out way](https://github.com/utvarp/music-helper/graphs/contributors) :)
 
 ## License
 

composer.json

@@ -19,7 +19,10 @@
         }
     ],
     "require": {
-        "php": "^7.0"
+        "php": "^7.0",
+        "atomescrochus/laravel-string-similarities": "^1.1",
+        "deezer/deezer-php-sdk": "dev-master",
+        "illuminate/support": "^5.4"
     },
     "require-dev": {
         "phpunit/phpunit": "5.*"

src/Exceptions/MusicException.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace Utvarp\MusicHelper\Exceptions;
+
+use Exception;
+
+class MusicException extends Exception
+{
+    public static function unsupportedSource()
+    {
+        return new static('One or all of the given sources are unsupported.');
+    }
+
+    public static function sourceNotFoundInResults()
+    {
+        return new static("We could not find the requested source in the results.");
+    }
+}

src/Helpers.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace Utvarp\MusicHelper;
+
+use Illuminate\Support\Collection;
+
+class Helpers
+{
+    public static function collect($value = [])
+    {
+        return new Collection($value);
+    }
+}

src/Models/DeezerResult.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace Utvarp\MusicHelper\Models;
+
+use Illuminate\Support\Collection;
+use Utvarp\MusicHelper\Models\Result;
+
+class DeezerResult
+{
+
+    public $count;
+
+    public function __construct($results, $searchedTrack = null, $searchedArtist = null)
+    {
+        $this->searchStrings = (object) [
+            'track' => $searchedTrack,
+            'artist' => $searchedArtist,
+        ];
+
+        $this->count = count($results);
+        $this->formatResults($results);
+    }
+
+    public function formatResults($results)
+    {
+        $this->results = collect($results)->map(function ($result) {
+            $model = new Result('deezer');
+            $model->setTrack($result->id, $result->title);
+            $model->setArtist($result->artist->id, $result->artist->name);
+            $model->setAlbum($result->album->id, $result->album->title);
+            $model->calculateSimilarities($this->searchStrings);
+
+            return $model;
+        });
+    }
+}

src/Models/Result.php

@@ -0,0 +1,57 @@
+<?php
+
+namespace Utvarp\MusicHelper\Models;
+
+use Atomescrochus\StringSimilarities\Compare;
+
+class Result
+{
+
+    public function __construct($source)
+    {
+        $this->source = $source;
+    }
+
+    public function setTrack($id, $name = null)
+    {
+        $this->track = (object) [
+            'id' => $id,
+            'name' => $name,
+        ];
+    }
+
+    public function setArtist($id, $name = null)
+    {
+        $this->artist = (object) [
+            'id' => $id,
+            'name' => $name,
+        ];
+    }
+
+    public function setAlbum($id, $name = null)
+    {
+        $this->album = (object) [
+            'id' => $id,
+            'name' => $name,
+        ];
+    }
+
+    public function calculateSimilarities($searchedStrings)
+    {
+        if (!is_null($searchedStrings->track)) {
+            $compare = new Compare();
+            $this->track->similarityScores = (object) $compare->all($this->track->name, $searchedStrings->track);
+        } else {
+            $this->track->similarityScores = null;
+        }
+
+        if (!is_null($searchedStrings->artist)) {
+            $compare = new Compare();
+            $this->artist->similarityScores = (object) $compare->all($this->artist->name, $searchedStrings->artist);
+        } else {
+            $this->track->similarityScores = null;
+        }
+
+        $this->album->similarityScores = null;
+    }
+}