Merge pull request #6 from neelkanthk/v1.1.0

V1.1.0

README.md

@@ -11,15 +11,20 @@
 
 ## Salient Features:
 
-> 1. __Turn any Eloquent Model into a schedulable__ one by using ```Schedulable``` trait in the model.
-> 2. __Schedule Models to a time in future__ and they will be returned in query results at specified date and time.
-> 3. __Reschedule__ and __Unschedule__ at any time using simple methods.
-> 4. Hook into the model's life cycle via __custom model events__ provided by the package.
-> 5. __Override the default column name__ and use your own custom column name.
+1. __Turn any Eloquent Model into a schedulable__ one by using ```Schedulable``` trait in the model.
+
+2. __Schedule Models to a time in future__ and they will be returned in query results at specified date and time.
+
+3. __Reschedule__ and __Unschedule__ at any time using simple methods.
+
+4. Hook into the model's life cycle via __custom model events__ provided by the package.
+
+5. __Override the default column name__ and use your own custom column name.
+
 
 __*Some example use cases when this package can be useful:*__
 
-1. A Blog like application which allows bloggers to schedule their post to go public on a future date and time.
+1. A Blog type application which allows bloggers to schedule their post to go public on a future date and time.
 
 2. An E-commerce website where the items in the inventory can be added at any time from the admin panel but they can be scheduled to be made available to the customers at a particular date and time.
 
@@ -57,7 +62,7 @@ class AddScheduleAtColumnInPosts extends Migration
         Schema::table('posts', function (Blueprint $table) {
             $table->scheduleAt(); //Using default schedule_at column
 			//or
-            $table->timestamp('publish_at', 0); //Using custom column name
+            $table->timestamp('publish_at', 0)->nullable(); //Using custom column name
         });
     }
 
@@ -99,7 +104,7 @@ class Post extends Model
 
 ```php
 $scheduleAt = Carbon::now()->addDays(10); //Carbon is just an example. You can pass any object which is implementing DateTimeInterface.
-$post = new Post();
+$post = new App\Post();
 //Add values to other attributes
 $post->scheduleWithoutSaving($scheduleAt); // Modifies the schedule_at attribute and returns the current model object without saving it.
 $post->schedule($scheduleAt); //Saves the model in the database and returns boolean true or false
@@ -108,7 +113,7 @@ $post->schedule($scheduleAt); //Saves the model in the database and returns bool
 ### 2. Unscheduling a model
 
 ```php
-$post = Post::find(1);
+$post = App\Post::find(1);
 $post->unscheduleWithoutSaving(); // Modifies the schedule_at attribute and returns the current model object without saving it.
 $post->unschedule(); //Saves the model in the database and returns boolean true or false
 ```
@@ -171,7 +176,7 @@ By default all those models are fetched in which the ```schedule_at``` column is
 
 So a eloquent query 
 ```php
-$posts = Post::get();
+$posts = App\Post::get();
 ``` 
 will return Toy Story 1 and Toy Story 2
 
@@ -181,7 +186,7 @@ will return Toy Story 1 and Toy Story 2
 To retrieve scheduled models in addition to the normal models, use the ```withScheduled()``` method.
 
 ```php
-$posts = Post::withScheduled()->get();
+$posts = App\Post::withScheduled()->get();
 ```
 
 The above query will return all the four rows in the above table.
@@ -191,11 +196,65 @@ The above query will return all the four rows in the above table.
 To retrieve only scheduled models use the ```onlyScheduled()``` method.
 
 ```php
-$posts = Post::onlyScheduled()->get();
+$posts = App\Post::onlyScheduled()->get();
 ```
 
 The above query will return Toy Story 3 and Terminator 2.
 
+#### 4. Do not apply any functionality provided by ```Schedulable```.
+
+In some cases you may not want to apply the ```Schedulable``` trait at all. In those cases use the ```withoutGlobalScope()``` method in your query.
+
+```php
+use Neelkanth\Laravel\Schedulable\Scopes\SchedulableScope;
+
+$posts = App\Post::withoutGlobalScope(SchedulableScope::class)->get();
+```
+
+## A general use case example.
+
+```
+// routes/web.php
+use Illuminate\Support\Facades\Route;
+use Neelkanth\Laravel\Schedulable\Scopes\SchedulableScope;
+
+/*
+|--------------------------------------------------------------------------
+| Web Routes
+|--------------------------------------------------------------------------
+|
+| Here is where you can register web routes for your application. These
+| routes are loaded by the RouteServiceProvider within a group which
+| contains the "web" middleware group. Now create something great!
+|
+*/
+
+Route::get('/schedule/post', function () {
+    $post = new App\Post();
+    $post->title = "My scheduled post";
+    $scheduleAt = Carbon\Carbon::now()->addDays(10);
+    $post->schedule($scheduleAt);
+    return $post; //The scheduled post's ID is 1
+});
+
+
+Route::get('/unschedule/post', function () {
+
+    // To unschedule a post you have to fetch the scheduled post first.
+    // But becuase the Schedulable trait is used in App\Post model it will not a fetch a post whose schedule_at column value is in future.
+    
+    $post = App\Post::find(1);  //This will return null for a scheduled post whose id is 1.
+    
+    //To retreive a scheduled post you can use any of the two methods given below.
+
+    $post = App\Post::withScheduled()->find(1); //1. Using withScheduled() [Recommended]
+
+    $post = App\Post::withoutGlobalScope(SchedulableScope::class)->find(1); //2. Using withoutGlobalScope()
+    
+    $post->unschedule();
+});
+```
+
 
 ## Contributing
 Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.