From a1b11b6e792457ad97f7c8b3ca6ea6467134fa1f Mon Sep 17 00:00:00 2001 From: Navneet Rai Date: Wed, 4 May 2016 18:26:35 +0530 Subject: [PATCH] Updated readme with exceptions --- .travis.yml | 19 +++++ README.md | 92 +++++++++++++++++------- src/Exceptions/MissingRouteException.php | 9 +++ src/Services/AbstractService.php | 24 ++++--- src/Services/Facebook.php | 2 + src/Services/Twitter.php | 8 ++- src/Services/Youtube.php | 2 + src/SubmissionServiceProvider.php | 3 + 8 files changed, 121 insertions(+), 38 deletions(-) create mode 100644 .travis.yml create mode 100644 src/Exceptions/MissingRouteException.php diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..3cf09f4 --- /dev/null +++ b/.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 diff --git a/README.md b/README.md index 50b9522..e9abf13 100644 --- a/README.md +++ b/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,7 +74,7 @@ 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 @@ -82,7 +82,7 @@ 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,15 +205,37 @@ 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); @@ -211,12 +243,13 @@ try{ $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,8 +338,8 @@ try{ $status = $result->getStaus(); $url = $result->getUrl(); -}catch(Exception $e){ - +}catch(InvalidUploadException $e){ + Log::error($e->getMessage()); } ``` @@ -309,4 +347,6 @@ 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. \ No newline at end of file +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. diff --git a/src/Exceptions/MissingRouteException.php b/src/Exceptions/MissingRouteException.php new file mode 100644 index 0000000..62bdd59 --- /dev/null +++ b/src/Exceptions/MissingRouteException.php @@ -0,0 +1,9 @@ +'facebook']); $fb = $this->provider($redirUrl); $url = $fb->getAuthorizationUri(['state'=>$state]); diff --git a/src/Services/Twitter.php b/src/Services/Twitter.php index aa5545c..1fd232b 100644 --- a/src/Services/Twitter.php +++ b/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); diff --git a/src/Services/Youtube.php b/src/Services/Youtube.php index e9cfbdd..eac4e7b 100644 --- a/src/Services/Youtube.php +++ b/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'); diff --git a/src/SubmissionServiceProvider.php b/src/SubmissionServiceProvider.php index 0efacc1..2cd8bc0 100644 --- a/src/SubmissionServiceProvider.php +++ b/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'); } /**