Events

Events added to package.

README.md

@@ -48,6 +48,8 @@ Laravel shop adds shopping cart, orders and payments to your new or existing pro
     - [Order](#order-1)
         - [Placing Transactions](#placing-transactions)
         - [Order Methods](#order-methods)
+    - [Events](#events)
+        - [Handler Example](#event-handler-example)
 - [Payment Gateway Development](#payment-gateway-development)
   - [Transaction](#transaction-1)
   - [Callbacks](#callbacks)
@@ -65,9 +67,6 @@ Current version includes:
 - Transactions
 - Payment gateways support
 - PayPal
-
-Under development:
-
 - Events
 
 On the horizon:
@@ -118,7 +117,7 @@ Set the configuration values in the `config/auth.php` file. This package will us
 Publish the configuration for this package to further customize table names, model namespaces, currencies and other values. Run the following command:
 
 ```bash
-php artisan laravel-shop:publish
+php artisan vendor:publish
 ```
 
 A `shop.php` file will be created in your app/config directory.
@@ -926,6 +925,72 @@ if ($order->is($myStatusCode)) {
 }
 ```
 
+### Events
+
+Laravel Shop follows [Laravel 5 guidelines](http://laravel.com/docs/5.1/events) to fire events, create your handlers and listeners like you would normally do to use them.
+
+| Event  | Description | Data passed |
+| ------------- | ------------- | ------------- |
+| Cart checkout | Event fired after a shop has checkout a cart. | `id` - Cart Id `success` - Checkout result (boolean) |
+| Order placed | Event fired when an order has been placed. | `id` - Order Id |
+| Order completed | Event fired when an order has been completed. | `id` - Order Id |
+| Order status changed | Event fired when an order's status has been changed. | `id` - Order Id `statusCode` - New status `previousStatusCode` - Prev status |
+
+Here are event references:
+
+| Event  | Reference |
+| ------------- | ------------- |
+| Cart checkout | `Amsgames\LaravelShop\Events\CartCheckout` |
+| Order placed | `Amsgames\LaravelShop\Events\OrderPlaced` |
+| Order completed | `Amsgames\LaravelShop\Events\OrderCompleted` |
+| Order status changed | `Amsgames\LaravelShop\Events\OrderStatusChanged` |
+
+#### Event Handler Example
+
+An example of how to use the event in a handler:
+
+```php
+<?php
+
+namespace App\Handlers\Events;
+
+use App\Order;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Contracts\Queue\ShouldQueue;
+
+use Amsgames\LaravelShop\Events\OrderCompleted;
+
+class NotifyPurchase implements ShouldQueue
+{
+    use InteractsWithQueue;
+
+    /**
+     * Handle the event.
+     *
+     * @param  OrderPurchased $event
+     * @return void
+     */
+    public function handle(OrderCompleted $event)
+    {
+        // The order ID
+        echo $event->id;
+
+        // Get order model object
+        $order = Order::find($event->id);
+
+        // My code here...
+    }
+}
+```
+
+Remember to register your handles and listeners at the Event Provider:
+
+```php
+        'Amsgames\LaravelShop\Events\OrderCompleted' => [
+            'App\Handlers\Events\NotifyPurchase',
+        ],
+```
+
 ## Payment Gateway Development
 Laravel Shop has been developed for customization in mind. Allowing the community to expand its capabilities.
 

src/LaravelShop.php

@@ -20,6 +20,10 @@
 use Amsgames\LaravelShop\Exceptions\CheckoutException;
 use Amsgames\LaravelShop\Exceptions\GatewayException;
 use Amsgames\LaravelShop\Exceptions\ShopException;
+use Amsgames\LaravelShop\Events\CartCheckout;
+use Amsgames\LaravelShop\Events\OrderCompleted;
+use Amsgames\LaravelShop\Events\OrderPlaced;
+use Amsgames\LaravelShop\Events\OrderStatusChanged;
 
 class LaravelShop
 {
@@ -115,6 +119,7 @@ public static function getGateway()
      */
     public static function checkout($cart = null)
     {
+        $success = true;
         try {
             if (empty(static::$gatewayKey)) {
                 throw new ShopException('Payment gateway not selected.');
@@ -123,15 +128,17 @@ public static function checkout($cart = null)
             static::$gateway->onCheckout($cart);
         } catch (ShopException $e) {
             static::setException($e);
-            return false;
+            $success = false;
         } catch (CheckoutException $e) {
             static::$exception = $e;
-            return false;
+            $success = false;
         } catch (GatewayException $e) {
             static::$exception = $e;
-            return false;
+            $success = false;
         }
-        return true;
+        if ($cart)
+            \event(new CartCheckout($cart->id, $success));
+        return $success;
     }
 
     /**
@@ -148,6 +155,8 @@ public static function placeOrder($cart = null)
                 throw new ShopException('Payment gateway not selected.');
             if (empty($cart)) $cart = Auth::user()->cart;
             $order = $cart->placeOrder();
+            $statusCode = $order->statusCode;
+            \event(new OrderPlaced($order->id));
             static::$gateway->setCallbacks($order);
             if (static::$gateway->onCharge($order)) {
                 $order->statusCode = static::$gateway->getTransactionStatusCode();
@@ -159,6 +168,9 @@ public static function placeOrder($cart = null)
                     static::$gateway->getTransactionDetail(),
                     static::$gateway->getTransactionToken()
                 );
+                // Fire event
+                if ($order->isCompleted)
+                    \event(new OrderCompleted($order->id));
             } else {
                 $order->statusCode = 'failed';
                 $order->save();
@@ -176,7 +188,12 @@ public static function placeOrder($cart = null)
                 $order->save();
             }
         }
-        return $order;
+        if ($order) {
+            static::checkStatusChange($order, $statusCode);
+            return $order;
+        } else {
+            return;
+        }
     }
 
     /**
@@ -187,6 +204,7 @@ public static function placeOrder($cart = null)
      */
     public static function callback($order, $transaction, $status, $data = null)
     {
+        $statusCode = $order->statusCode;
         try {
             if (in_array($status, ['success', 'fail'])) {
                 static::$gatewayKey = $transaction->gateway;
@@ -201,6 +219,9 @@ public static function callback($order, $transaction, $status, $data = null)
                         static::$gateway->getTransactionDetail(),
                         static::$gateway->getTransactionToken()
                     );
+                    // Fire event
+                    if ($order->isCompleted)
+                        \event(new OrderCompleted($order->id));
                 } else if ($status == 'fail') {
                     static::$gateway->onCallbackFail($order, $data);
                     $order->statusCode = 'failed';
@@ -216,6 +237,7 @@ public static function callback($order, $transaction, $status, $data = null)
             $order->statusCode = 'failed';
             $order->save();
         }
+        static::checkStatusChange($order, $statusCode);
     } 
 
     /**
@@ -283,4 +305,16 @@ protected static function instanceGateway()
         $className = '\\' . Config::get('shop.gateways')[static::$gatewayKey];
         return new $className(static::$gatewayKey);
     }
+
+    /**
+     * Check on order status differences and fires event.
+     * @param object $order Order.
+     * @param string $prevStatusCode Previous status code.
+     * @return void 
+     */
+    protected static function checkStatusChange($order, $prevStatusCode)
+    {
+        if (!empty($prevStatusCode) && $order->statusCode != $prevStatusCode)
+            \event(new OrderStatusChanged($order->id, $order->statusCode, $prevStatusCode));
+    }
 }

src/events/CartCheckout.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace Amsgames\LaravelShop\Events;
+
+use Illuminate\Queue\SerializesModels;
+
+/**
+ * Event fired when an order has been completed.
+ *
+ * @author Alejandro Mostajo
+ * @copyright Amsgames, LLC
+ * @license MIT
+ * @package Amsgames\LaravelShop
+ */
+class CartCheckout
+{
+	use SerializesModels;
+
+	/**
+     * Cart ID.
+     * @var int
+     */
+	public $id;
+
+     /**
+     * Flag that indicates if the checkout was successful or not.
+     * @var bool
+     */
+     public $success;
+
+	/**
+     * Create a new event instance.
+     *
+     * @param int  $id      Order ID.
+     * @param bool $success Checkout flag result.
+     *
+     * @return void
+     */
+	public function __construct($id, $success)
+	{
+		$this->id = $id;
+          $this->success = $success;
+	}
+}

src/events/OrderCompleted.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace Amsgames\LaravelShop\Events;
+
+use Illuminate\Queue\SerializesModels;
+
+/**
+ * Event fired when an order has been completed.
+ *
+ * @author Alejandro Mostajo
+ * @copyright Amsgames, LLC
+ * @license MIT
+ * @package Amsgames\LaravelShop
+ */
+class OrderCompleted
+{
+	use SerializesModels;
+
+	/**
+     * Order ID.
+     * @var int
+     */
+	public $id;
+
+	/**
+     * Create a new event instance.
+     *
+     * @param int $id Order ID.
+     *
+     * @return void
+     */
+	public function __construct($id)
+	{
+		$this->id = $id;
+	}
+}

src/events/OrderPlaced.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace Amsgames\LaravelShop\Events;
+
+use Illuminate\Queue\SerializesModels;
+
+/**
+ * Event fired when an order is placed.
+ *
+ * @author Alejandro Mostajo
+ * @copyright Amsgames, LLC
+ * @license MIT
+ * @package Amsgames\LaravelShop
+ */
+class OrderPlaced
+{
+	use SerializesModels;
+
+	/**
+     * Order ID.
+     * @var int
+     */
+	public $id;
+
+	/**
+     * Create a new event instance.
+     *
+     * @param int $id Order ID.
+     *
+     * @return void
+     */
+	public function __construct($id)
+	{
+		$this->id = $id;
+	}
+}

src/events/OrderStatusChanged.php

@@ -0,0 +1,51 @@
+<?php
+
+namespace Amsgames\LaravelShop\Events;
+
+use Illuminate\Queue\SerializesModels;
+
+/**
+ * Event fired when an order has changed status code.
+ *
+ * @author Alejandro Mostajo
+ * @copyright Amsgames, LLC
+ * @license MIT
+ * @package Amsgames\LaravelShop
+ */
+class OrderStatusChanged
+{
+	use SerializesModels;
+
+	/**
+     * Order ID.
+     * @var int
+     */
+	public $id;
+
+     /**
+     * Order status code.
+     * @var string
+     */
+     public $statusCode;
+
+     /**
+     * Previous order status code.
+     * @var string
+     */
+     public $previousStatusCode;
+
+	/**
+     * Create a new event instance.
+     *
+     * @param int    $id         Order ID.
+     * @param string $statusCode Order status code.
+     *
+     * @return void
+     */
+	public function __construct($id, $statusCode, $previousStatusCode)
+	{
+		$this->id = $id;
+          $this->statusCode = $statusCode;
+          $this->previousStatusCode = $previousStatusCode;
+	}
+}