Updated readme with exceptions

.travis.yml

@@ -0,0 +1,19 @@
+language: php
+
+php:
+  - 5.4
+  - 5.5
+  - 5.6
+  - 7.0
+  - hhvm
+
+#branches:
+#  only:
+#    - master
+
+before_script:
+  - travis_retry composer self-update
+  - travis_retry composer install --no-interaction --prefer-source
+
+script:
+  - ./vendor/bin/phpunit

README.md

@@ -1,4 +1,4 @@
-# Social Media Submitter for Laravel 5
+# Submission Billing for Laravel 5
 
 [![Build Status](https://travis-ci.org/navneetrai/laravel-submitter.svg)](https://travis-ci.org/navneetrai/laravel-submitter)
 [![Coverage Status](https://coveralls.io/repos/navneetrai/laravel-submitter/badge.svg)](https://coveralls.io/r/navneetrai/laravel-submitter)
@@ -47,7 +47,7 @@ Use composer to install this package.
 $ composer update
 ```
 
-### Registering the Package
+## Registering the Package
 
 Register the service provider within the ```providers``` array found in ```config/app.php```:
 
@@ -74,15 +74,15 @@ Add an alias within the ```aliases``` array found in ```config/app.php```:
 
 There are two ways to configure laravel-submitter.
 
-#### Option 1
+### Option 1
 
 Create configuration file for package using artisan command
 
 ```
 $ php artisan vendor:publish --provider="Userdesk\Submission\SubmissionServiceProvider"
 ```
 
-#### Option 2
+### Option 2
 
 Create configuration file manually in config directory ``config/subscription.php`` and put there code from below.
 
@@ -130,7 +130,7 @@ return [
 ];
 ```
 
-### Credentials
+## Credentials
 
 Add your credentials to ``config/submission.php`` (depending on which option of configuration you choose)
 
@@ -145,7 +145,10 @@ Just follow the steps below and you will be able to get a submitter instance:
 $submitter = Submission::submitter('twitter');
 ```
 
-#### Redirecting Users to Website for authentication
+You'll get an ``SubmissionException`` if the service you are invoking if not present of it the configuration is missing for this service.
+
+
+### Redirecting Users to Website for authentication
 
 To start the authentication process you can call the authenticate method of your submitter instance:
 
@@ -158,7 +161,7 @@ You should also pass an integer as ``$state`` to this method. This variable will
 
 You will get a Redirect Response which will take user to Website for Authentication.
 
-#### Completing Submission
+### Completing Submission
 
 User authentication is an oauth based two-step process. Also the process for authentication differs from site to site. This package is designed to encapsulate these differences any provide a uniform interface across both Oauth 1 sites (like Twitter) and Oauth 2 sites (like Facebook)
 
@@ -179,9 +182,16 @@ To complete the authentication process the ``authenticate`` function in ``YourSu
 ```php
 public function authenticate(Request $request, String $website, int $state = 0){
 	$submitter = Submission::submitter($website);
-	$credentials = $submitter->completeAuthentication($request, $state);
+	try{
+		$credentials = $submitter->completeAuthentication($request, $state);
+	}catch(InvalidTokenException $e){
+		\\Check configuration variables.
+	}catch(InvalidPrivilegeException $e){
+		\\Flash message to user that he needs to provide required privileges for submission to be successful.
+	}
+
 
-	//Fetch Information from Credentials Object
+	#####Fetch Information from Credentials Object
 
 	$state = $credentials->getState();
 	$user = $credentials->getUser();
@@ -195,28 +205,51 @@ public function authenticate(Request $request, String $website, int $state = 0){
 	//You can now save tokenArray to your database for later use
 }
 ```
+If you have not defined route ``package.Userdesk.submission.authenticate`` before calling the authenticate method you'll get a ``MissingRouteException``
 
-#### Using Stored Token to Submit Videos
+If authentication process failed because of configuration you'll get an ``InvalidTokenException``. If user has not provided required priveleges for submission you'll get an ``InvalidPrivilegeException``. In this case you can inform user that he must provide the required privileges.
 
-You can use the token stored above to submit videos on the target website using this code:
+
+### Using Stored Token to Upload Items
+
+You can use the token stored above to submit media and push updates on the target website. For this you'll first need to create a submitter object and add the stored token to it.
 
 ```php
 $submitter = Submitter::submitter($website);
+
+$token = new SubmissionToken();
+$token->addTokenArray($tokenArray);
 
-try{	
+$submitter->addToken($token);
+```
+
+If you'll try to upload items without adding a stored token you'll get a ``MissingTokenException``. If the Token has expired or has been revoked by the User then you'll get an ``InvalidTokenException``.
+
+This library also aims to unify different exceptions thrown by apis of different websites. You'll get an ``InvalidUploadException`` in case an Exception is generated by the api of target website.
+
+
+#### Uploading Video
+
+You can use the token stored above to submit videos on the target website using this code:
+
+```php
+try{
+	$submitter = Submitter::submitter($website);
+
 	$token = new SubmissionToken();
 	$token->addTokenArray($tokenArray);
 
 	$video = new SubmissionVideoItem($title, $description, $localThumb, $localVideo, $keywords);
 
 	$submitter->addToken($token);
 	$result = $submitter->uploadVideo($video);
-	
+
 	$status = $result->getStaus();
-	$url = $result->getUrl();
-}catch(Exception $e){
+	$url = $result->getUrl();	
+}catch(InvalidUploadException $e){
+	Log::error($e->getMessage());
+}
 
-}			
 ```
 
 Keywords should be a comma separated string. Not all website uses keywords for Video Submission.
@@ -225,8 +258,10 @@ Each website has its own policy for video uploads. Your video should confirm to
 
 e.g. [For Twitter videos can't be longer than 30 seconds](https://dev.twitter.com/rest/media/uploading-media#videorecs)
 
+To Upload a Video you'll need to pass a ``SubmissionVideoItem`` to ``uploadVideo`` method.
+
 
-#### Using Stored Token to Submit Images
+### Using Stored Token to Submit Images
 
 You can use the token stored above to submit images on the target website using this code:
 
@@ -244,8 +279,8 @@ try{
 
 	$status = $result->getStaus();
 	$url = $result->getUrl();
-}catch(Exception $e){
-
+}catch(InvalidUploadException $e){
+	Log::error($e->getMessage());
 }			
 ```
 Keywords should be a comma separated string. Not all website uses keywords for Image Submission.
@@ -254,8 +289,9 @@ Some websites like Youtube do not support image uploads.
 
 Each website has its own policy for image uploads. Your image should confirm to website policy for upload to be successful.
 
+To Upload an image you'll need to pass a ``SubmissionImageItem`` to ``uploadImage`` method.
 
-#### Using Stored Token to Submit Links
+### Using Stored Token to Submit Links
 
 You can use the token stored above to submit links on the target website using this code:
 
@@ -273,16 +309,18 @@ try{
 
 	$status = $result->getStaus();
 	$url = $result->getUrl();
-}catch(Exception $e){
-
+}catch(InvalidUploadException $e){
+	Log::error($e->getMessage());
 }			
 ```
 Keywords should be a comma separated string. Off the current websites only Facebook support link submission.
 
 Each website has its own policy for link submission. Your link should confirm to website policy for upload to be successful.
 
+To Upload a link you'll need to pass a ``SubmissionLinkItem`` to ``addLink`` method.
 
-#### Using Stored Token to Add Status updates/Tweets
+
+### Using Stored Token to Add Status updates/Tweets
 
 You can use the token stored above to add status update/tweet on the target website using this code:
 
@@ -300,13 +338,15 @@ try{
 
 	$status = $result->getStaus();
 	$url = $result->getUrl();
-}catch(Exception $e){
-
+}catch(InvalidUploadException $e){
+	Log::error($e->getMessage());
 }			
 ```
 
 Some websites like Youtube do not support status updates.
 
 Each website has its own policy for status updates. Your link should confirm to website policy for upload to be successful.
 
-e.g. Twitter needs status to be within 140 characters.
+e.g. Twitter needs status to be within 140 characters.
+
+To add a status update you'll need to pass a ``SubmissionStatusItem`` to ``addStatus`` method.

src/Exceptions/MissingRouteException.php

@@ -0,0 +1,9 @@
+<?php namespace Userdesk\Submission\Exceptions;
+
+use Exception;
+
+/**
+ * Generic library-level exception.
+ */
+class MissingRouteException extends Exception{
+}

src/Services/AbstractService.php

@@ -14,12 +14,14 @@
 
 use Userdesk\Submission\Contracts\Service as SubmitterContract;
 
+use Userdesk\Submission\Exceptions\MissingRouteException;
 use Userdesk\Submission\Exceptions\InvalidUploadException;
 
 use Illuminate\Http\Request;
 
 use Config;
 use URL;
+use Route;
 
 abstract class AbstractService implements SubmitterContract{
     protected $config = [];
@@ -91,15 +93,6 @@ abstract public function provider(String $redirUrl = '');
      */
     abstract public function completeAuthentication(Request $request, int $state = 0);
 
-    /**
-     * Redirect to Authentication URL.
-     *
-     * @param int $state;
-     *
-     * @return \Illuminate\Http\Response;;
-     */
-    abstract public function authenticate(int $state);
-
     /**
      * Upload Video.
      *
@@ -209,4 +202,17 @@ protected function getCredentials($credentials = array(), $url = null){
             $url ? : URL::current()
         );
     }
+
+    /**
+     * Redirect to Authentication URL.
+     *
+     * @param int $state;
+     *
+     * @return \Illuminate\Http\Response;
+     */
+    public function authenticate(int $state){
+        if(!Route::has('package.Userdesk.submission.authenticate')) {
+            throw new MissingRouteException();
+        }     
+    }
 }

src/Services/Facebook.php

@@ -242,6 +242,8 @@ public function completeAuthentication(Request $request, int $state = 0){
 	 * @return \Illuminate\Http\Response;;
 	 */
 	public function authenticate(int $state){
+		parent::authenticate($state);
+
 		$redirUrl = route('package.Userdesk.submission.authenticate', ['website'=>'facebook']);
     	$fb = $this->provider($redirUrl);
 	   	$url = $fb->getAuthorizationUri(['state'=>$state]);

src/Services/Twitter.php

@@ -12,7 +12,7 @@
 use Userdesk\Submission\Classes\Items\SubmissionImageItem;
 use Userdesk\Submission\Classes\Items\SubmissionStatusItem;
 
-use Userdesk\Submission\Exceptions\MissingTokenException;
+use Userdesk\Submission\Exceptions\MissingRouteException;
 use Userdesk\Submission\Exceptions\InvalidTokenException;
 use Userdesk\Submission\Exceptions\InvalidPrivilegeException;
 use Userdesk\Submission\Exceptions\InvalidUploadException;
@@ -185,8 +185,10 @@ public function completeAuthentication(Request $request, int $state = 0){
 	 *
 	 * @return \Illuminate\Http\Response;
 	 */
-	public function authenticate(int $state){        
-		$redirUrl = route('package.Userdesk.submission.authenticate', ['website'=>'twitter', 'state'=>$state]);
+	public function authenticate(int $state){
+		parent::authenticate($state);
+
+		$redirUrl = \URL::route('package.Userdesk.submission.authenticate', ['website'=>'twitter', 'state'=>$state]);
 
     	$tw = $this->provider($redirUrl);    		
 

src/Services/Youtube.php

@@ -165,6 +165,8 @@ public function completeAuthentication(Request $request, int $state = 0){
 	 * @return \Illuminate\Http\Response;;
 	 */
 	public function authenticate(int $state){
+		parent::authenticate($state);
+
 		$redirUrl = route('package.Userdesk.submission.authenticate', ['website'=>'youtube']);
     	$googleService = $this->provider($redirUrl);
 	    $googleService->setAccessType('offline');

src/SubmissionServiceProvider.php

@@ -12,6 +12,9 @@ class SubmissionServiceProvider extends ServiceProvider
      */
     public function boot()
     {
+        $this->publishes([
+            __DIR__.'/resources/config/submission.php' => config_path('submission.php'),
+        ], 'config');
     }
 
     /**