feature & documentation update

CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2017-08-29
+### Added
+- Ability to set expiration date of promocode while creating.
+- Ability to remove all redundant (expired or used) promocodes from database.
+- Invalid Promocode Exception, Unauthenticated Exception, Already Used Exception.
+- Ability to disable promocode using code string (Promocode will be expired).
+- Support for Laravel 5.5 Package Auto-Discovery.
+
+### Changed
+- Migration & config file. Now promocode & user will be related through pivot table. [#12]
+
+### Fixed
+- Migration problem where database couldn't support json type. [#13]
+
+### Removed
+- Ability of user, that they could create promocodes assigned to them.
+
+[Unreleased]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/zgabievi/laravel-promocodes/compare/v0.5.4...v1.0.0
+
+[#12]: https://github.com/zgabievi/laravel-promocodes/issues/12
+[#13]: https://github.com/zgabievi/laravel-promocodes/issues/13

README.md

@@ -9,14 +9,15 @@
 [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/zgabievi/laravel-promocodes/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/zgabievi/laravel-promocodes/?branch=master)
 [![Build Status](https://scrutinizer-ci.com/g/zgabievi/laravel-promocodes/badges/build.png?b=master)](https://scrutinizer-ci.com/g/zgabievi/laravel-promocodes/build-status/master)
 
-| PR0M0C0D35 |     |
-|:----------:|:----|
-| [![PR0M0C0D35](https://i.imgsafe.org/ff13c6de54.png)](https://github.com/zgabievi/promocodes) | Promocodes generator for [Laravel 5.*](http://laravel.com/). Trying to make the best package in this category. You are welcome to join the party, give me some advices :tada: and make pull requests. |
+> Promocodes generator for [Laravel 5.*](http://laravel.com/). Trying to make the best package in this category. You are welcome to join the party, give me some advices :tada: and make pull requests.
 
 ## Table of Contents
 - [Installation](#installation)
 - [Configuration](#configuration)
 - [Usage](#usage)
+    - [Basic Methods](#usage)
+    - [User Trait](#promocodes-can-be-related-to-users)
+    - [Additional Data](#how-to-use-additional-data)
 - [License](#license)
 
 ### What's new?
@@ -29,7 +30,9 @@ Install this package via Composer:
 $ composer require zgabievi/promocodes
 ```
 
-### Open `config/app.php` and follow steps below:
+> If you are using Laravel 5.5, than installation is done. Otherwise follow next steps.
+
+#### Open `config/app.php` and follow steps below:
 
 Find the `providers` array and add our service provider.
 
@@ -67,32 +70,73 @@ $ php artisan migrate
 
 ## Usage
 
-Generate as many codes as you wish and output them without saving. 
+Generate as many codes as you wish and output them without saving to database. 
+
 You will get array of codes in return:
 
 ```php
 Promocodes::output($amount = 1)
 ```
 
-Create as many codes as you wish, with same reward for each one.
+---
+
+Create as many codes as you wish. Set reward (amount). 
+
+Attach additional data as array. Specify for how many days should this codes stay alive.
+
 They will be saved in database and you will get collection of them in return:
 
 ```php
-Promocodes::create($amount = 1, $reward = null, array $data = [])
+Promocodes::create($amount = 1, $reward = null, array $data = [], $expires_in = null)
 ```
 
-Check if given code exists and isn't used at all:
+---
+
+Check if given code exists, is usable and not yet expired. 
+
+This code may throw `\Gabievi\Promocodes\Exceptions\InvalidPromocodeExceprion` if there is not such promocode in database, with give code.
+
+Returns `Promocode` object if valid, or `false` if not.
 
 ```php
 Promocodes::check($code)
 ```
 
-Apply, that given code is used. Update database record. You will get promocode record back or true/false:
+---
+
+Redeem or apply code. Redeem is alias for apply method. 
+
+User should be authenticated to redeem code or this method will thow an exception (`\Gabievi\Promocodes\Exceptions\UnauthenticatedExceprion`). 
+
+Also if authenticated user will try to apply code twice, it will throw an exception (`\Gabievi\Promocodes\Exceptions\AlreadyUsedExceprion`)
+
+Returns `Promocode` object if applied, or `false` if not.
 
 ```php
+Promocodes::redeem($code)
 Promocodes::apply($code)
 ```
 
+---
+
+You can imediately expire code by calling *disable* function. Returning boolean status of update.
+
+```php
+Promocodes::disable($code)
+```
+
+---
+
+And if you want to delete expired, or non-usable codes you can erase them.
+
+This method will remove redundant codes from database and their relations to users. 
+
+```php
+Promocodes::clearRedundant()
+```
+
+---
+
 ### Promocodes can be related to users
 
 If you want to use user relation open `app/User.php` and make it `Rewardable` as in example:
@@ -111,38 +155,25 @@ class User extends Authenticatable
     // ...
 }
 ```
+---
 
-Get all promocodes of current user:
-
-```php
-User::promocodes()
-```
-
-> There is query scopes for promocodes: `fresh()`, `byCode($code)`:
-> - `User::promocodes()->fresh()` - all not used codes of user
-> - `User::promocodes()->byCode($code)` - record which matches given code
-
-Create promocode(s) for current user. Works exactly same like `create` method of `Promocodes`:
-
-```php
-User::createCode($amount = 1, $reward = null, array $data = [])
-```
+Redeem or apply code are same. *redeemCode* is alias of *applyCode*
 
-Apply, that given code is used by current user. 
-Second argument is optional, if null, it will return promocode record or boolean, or you can pass callback function, which gives you reward or boolean value as argument:
+Pass promotion code you want to be applied by current user.
 
 ```php
+User::redeemCode($code, $callback = null)
 User::applyCode($code, $callback = null)
 ```
 
-Example:
+Example (usage of callback):
 
 ```php
-$user = Auth::user();
-
-$user->applyCode('ABCD-DCBA', function ($promocode) use ($user) {
-    return 'Congratulations, ' . $user->name . '! We have added ' . $promocode->reward . ' points on your account'.
+$redeemMessage = $user->redeemCode('ABCD-DCBA', function ($promocode) use ($user) {
+    return 'Congratulations, ' . $user->name . '! We have added ' . $promocode->reward . ' points on your account';
 });
+
+// Congratulations, Zura! We have added 10 points on your account
 ```
 
 ### How to use additional data?
@@ -153,31 +184,26 @@ $user->applyCode('ABCD-DCBA', function ($promocode) use ($user) {
 Promocodes::create(1, 25, ['foo' => 'bar', 'baz' => 'qux']);
 ```
 
-or
-
-```php
-User::createCode(1, 25, ['foo' => 'bar', 'baz' => 'qux']);
-```
-
 2. Getting data back:
 
 ```php
-Promocodes::apply('ABC-DEF', function($promocode) {
+Promocodes::redeem('ABC-DEF', function($promocode) {
     echo $pomocode->data['foo'];
 });
+
+// bar
 ```
 
 or
 
 ```php
-User::applyCode('ABC-DEF', function($promocode) {
+User::redeemCode('ABC-DEF', function($promocode) {
     echo $pomocode->data['foo'];
 });
+
+// bar
 ```
 
 ## License
 
-laravel-promocodes is licensed under a  [MIT License](https://github.com/zgabievi/laravel-promocodes/blob/master/LICENSE).
-
-## TODO
-- [x] Create tests to check funtionality
+laravel-promocodes is licensed under a [MIT License](https://github.com/zgabievi/laravel-promocodes/blob/master/LICENSE).

composer.json

@@ -25,5 +25,15 @@
 		"psr-4": {
 			"Gabievi\\Promocodes\\": "src/"
 		}
+	},
+	"extra": {
+		"laravel": {
+			"providers": [
+				"Gabievi\\Promocodes\\PromocodesServiceProvider"
+			],
+			"aliases": {
+				"Promocodes": "Gabievi\\Promocodes\\Facades\\Promocodes"
+			}
+		}
 	}
 }

src/Exceptions/AlreadyUsedExceprion.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace Gabievi\Promocodes\Exceptions;
+
+use Exception;
+
+class AlreadyUsedExceprion extends Exception
+{
+    /**
+     * @var string
+     */
+    protected $message = 'Promotion code is already used by current user.';
+
+    /**
+     * @var int
+     */
+    protected $code = 403;
+}

src/Exceptions/InvalidPromocodeExceprion.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace Gabievi\Promocodes\Exceptions;
+
+use Exception;
+
+class InvalidPromocodeExceprion extends Exception
+{
+    /**
+     * @var string
+     */
+    protected $message = 'Invalid promotion code was passed.';
+
+    /**
+     * @var int
+     */
+    protected $code = 404;
+}

src/Exceptions/UnauthenticatedExceprion.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace Gabievi\Promocodes\Exceptions;
+
+use Exception;
+
+class UnauthenticatedExceprion extends Exception
+{
+    /**
+     * @var string
+     */
+    protected $message = 'User is not authenticated, and can not use promotion code.';
+
+    /**
+     * @var int
+     */
+    protected $code = 401;
+}