Support Laravel 13 and improve basket operations (#6)

* Support Laravel 13 and improve basket operations

* Fix cross-version test fixture setup

* Allow intentional historical Laravel CI rows

* Use PHPUnit 6 for Laravel 5.5 tests

* Use cross-version artisan test calls

Author: Jord-JD

.coveralls.yml

@@ -0,0 +1,85 @@
+name: Tests
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: PHP ${{ matrix.php }} / Laravel ${{ matrix.laravel }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - php: '7.1'
+            laravel: '5.5'
+            testbench: '~3.5.0'
+            phpunit: '^6.5'
+            dbal: '^2.13'
+            composer: v2.2
+          - php: '7.2'
+            laravel: '6'
+            testbench: '^4.0'
+            phpunit: '^8.5'
+            dbal: '^2.13'
+            composer: v2.2
+          - php: '7.2'
+            laravel: '7'
+            testbench: '^5.0'
+            phpunit: '^8.5'
+            dbal: '^2.13'
+            composer: v2.2
+          - php: '7.3'
+            laravel: '8'
+            testbench: '^6.0'
+            phpunit: '^9.6'
+            dbal: '^2.13'
+            composer: v2.2
+          - php: '8.0'
+            laravel: '9'
+            testbench: '^7.0'
+            phpunit: '^9.6'
+            dbal: '^3.0'
+            composer: latest
+          - php: '8.1'
+            laravel: '10'
+            testbench: '^8.0'
+            phpunit: '^10.5'
+            dbal: '^3.0'
+            composer: latest
+          - php: '8.2'
+            laravel: '11'
+            testbench: '^9.0'
+            phpunit: '^11.5'
+            dbal: '^3.0'
+            composer: latest
+          - php: '8.2'
+            laravel: '12'
+            testbench: '^10.0'
+            phpunit: '^11.5'
+            dbal: '^4.0'
+            composer: latest
+          - php: '8.5'
+            laravel: '13'
+            testbench: '^11.0'
+            phpunit: '^12.5'
+            dbal: '^4.0'
+            composer: latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          extensions: mbstring, pdo_sqlite
+          tools: composer:${{ matrix.composer }}
+          coverage: none
+      - name: Allow intentional historical Laravel test rows
+        if: matrix.composer == 'latest'
+        run: composer config audit.block-insecure false
+      - run: composer require --dev orchestra/testbench:${{ matrix.testbench }} phpunit/phpunit:${{ matrix.phpunit }} doctrine/dbal:${{ matrix.dbal }} --no-update --no-interaction
+      - run: composer update --with-all-dependencies --prefer-dist --no-interaction --no-progress
+      - run: vendor/bin/phpunit

.github/workflows/tests.yml

@@ -1,7 +1,6 @@
 # 🛒 Laravel Extendable Basket
 
-[![Build Status](https://travis-ci.com/Jord-JD/laravel-extendable-basket.svg?branch=master)](https://travis-ci.com/Jord-JD/laravel-extendable-basket)
-[![Coverage Status](https://coveralls.io/repos/github/Jord-JD/laravel-extendable-basket/badge.svg?branch=master)](https://coveralls.io/github/Jord-JD/laravel-extendable-basket?branch=master)
+[![Tests](https://github.com/Jord-JD/laravel-extendable-basket/actions/workflows/tests.yml/badge.svg)](https://github.com/Jord-JD/laravel-extendable-basket/actions/workflows/tests.yml)
 [![](https://img.shields.io/packagist/dt/jord-jd/laravel-extendable-basket.svg)](https://packagist.org/packages/jord-jd/laravel-extendable-basket/stats)
 
 Laravel Extendable Basket provides several abstract classes that implement basic ecommerce basket functionality.
@@ -17,7 +16,9 @@ composer require jord-jd/laravel-extendable-basket
 
 ## Compatibility
 
-This package supports Laravel versions 5.5 through 10 and requires PHP 8.1 or higher.
+This package supports Laravel 5.5 through 13. Its own runtime syntax supports PHP
+7.1 and later; Composer will also enforce the higher PHP minimum required by the
+Laravel version selected by your application.
 
 ## Setup
 
@@ -45,6 +46,7 @@ Create a Basket model.
 <?php
 namespace App;
 
+use Illuminate\Database\Eloquent\Relations\HasMany;
 use JordJD\LaravelExtendableBasket\Models\Basket as BasketModel;
 
 class Basket extends BasketModel
@@ -64,6 +66,7 @@ Create a BasketItem model.
 <?php
 namespace App;
 
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
 use JordJD\LaravelExtendableBasket\Models\BasketItem as BasketItemModel;
 
 class BasketItem extends BasketItemModel
@@ -92,7 +95,8 @@ namespace App;
 use Illuminate\Database\Eloquent\Model;
 use JordJD\LaravelExtendableBasket\Interfaces\Basketable;
 
-class Product extends Model implements Basketable {
+class Product extends Model implements Basketable
+{
 
     // ...
 
@@ -139,7 +143,7 @@ with any Eloquent model.
 
 ```php
 // Get new basket
-$basket = new Basket();
+$basket = new Basket(); // Saved automatically when its first item is added.
 
 // Get current basket
 $userBasketId = Auth::user()->basket_id;
@@ -156,12 +160,18 @@ used to store information about variations on a product.
 
 ```php
 $quantity = 5;
-$product = Product::FindOrFail(1);
+$product = Product::findOrFail(1);
 
-$basket->add($quantity, $product);
-$basket->add($quantity, $product, ['colour' => 'red', 'size' => 'medium']);
+$item = $basket->add($quantity, $product);
+$variantItem = $basket->add($quantity, $product, ['colour' => 'red', 'size' => 'medium']);
 ```
 
+`add()` returns the created basket item. If the same model and identical metadata
+already exist in the basket, its quantity is increased and that existing item is
+returned. Laravel morph-map aliases are stored when the basketable model provides
+one. Basketable models must be saved before they are added; otherwise an
+`InvalidArgumentException` is thrown instead of creating an orphaned item.
+
 ### Getting basket items
 
 Getting items from the basket and the basketable model they contain can be easily 
@@ -194,6 +204,13 @@ $item = $basket->items->first();
 $item->delete();
 ```
 
+To remove every item in one query, call `clear()`. It returns the number of rows
+deleted and keeps the basket itself available for reuse.
+
+```php
+$deletedItemCount = $basket->clear();
+```
+
 ## Getting the unit cost of a basket item
 
 Getting the unit cost of a basket item just involves calling the `getPrice` method of
@@ -230,7 +247,7 @@ A `getSubtotal` method is provided in the basket class that provides the total o
 items in the basket. See the following example.
 
 ```php
-$subtotal = $basket->getSubtotal()
+$subtotal = $basket->getSubtotal();
 ```
 
 If you wish to add delivery costs or discounts, you can create a new `getTotal` method

.travis.yml

@@ -3,14 +3,13 @@
   "description": "🛒 Laravel Extendable Basket provides several abstract classes that implement basic ecommerce basket functionality",
   "type": "library",
   "require": {
-    "php": ">=8.1",
-    "laravel/framework": "^5.5||^6.0||^7.0||^8.0||^9.0||^10.0"
+    "php": ">=7.1",
+    "laravel/framework": "^5.5||^6.0||^7.0||^8.0||^9.0||^10.0||^11.0||^12.0||^13.0"
   },
   "require-dev": {
-    "orchestra/testbench": "^8.0",
-    "phpunit/phpunit": "^9.0",
-    "php-coveralls/php-coveralls": "^2.1",
-    "doctrine/dbal": "^1.0||^2.0||^3.0"
+    "orchestra/testbench": "^3.5||^4.0||^5.0||^6.0||^7.0||^8.0||^9.0||^10.0||^11.0",
+    "phpunit/phpunit": "^6.5||^7.5||^8.5||^9.6||^10.5||^11.5||^12.5",
+    "doctrine/dbal": "^2.13||^3.0||^4.0"
   },
   "license": "LGPL-3.0-only",
   "authors": [
@@ -34,12 +33,17 @@
       "providers": [
         "JordJD\\LaravelExtendableBasket\\Providers\\LaravelExtendableBasketServiceProvider"
       ]
-    },
-    "branch-alias": {
-      "dev-master": "6.0-dev"
-    }
+      },
+      "branch-alias": {
+        "dev-master": "6.1-dev"
+      }
   },
   "replace": {
     "divineomega/laravel-extendable-basket": "self.version"
+  },
+  "config": {
+    "allow-plugins": {
+      "kylekatarnls/update-helper": false
+    }
   }
 }

README.md

@@ -1,28 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<phpunit backupGlobals="false"
-         backupStaticAttributes="false"
-         bootstrap="vendor/autoload.php"
-         colors="true"
-         convertErrorsToExceptions="true"
-         convertNoticesToExceptions="true"
-         convertWarningsToExceptions="true"
-         processIsolation="false"
-         stopOnFailure="false">
+<phpunit bootstrap="vendor/autoload.php" colors="true">
     <testsuites>
         <testsuite name="Unit Tests">
             <directory suffix="Test.php">./tests/Unit</directory>
-            <directory suffix="Test.php">./tests/Integration</directory>
         </testsuite>
     </testsuites>
-    <filter>
-        <whitelist>
-            <directory suffix=".php">src</directory>
-            <exclude>
-                <directory suffix=".php">src/Examples</directory>
-            </exclude>
-        </whitelist>
-    </filter>
-    <php>
-        
-    </php>
-</phpunit>
+</phpunit>

composer.json

@@ -12,6 +12,9 @@ public static function getNew(): self;
 
     public function items(): HasMany;
 
+    /**
+     * @return BasketItemInterface
+     */
     public function add(int $quantity, Basketable $basketable, array $meta = []);
 
     public function getSubtotal();

phpunit.xml

@@ -2,10 +2,10 @@
 
 namespace JordJD\LaravelExtendableBasket\Models;
 
+use Illuminate\Database\Eloquent\Model;
+use InvalidArgumentException;
 use JordJD\LaravelExtendableBasket\Interfaces\Basketable;
 use JordJD\LaravelExtendableBasket\Interfaces\BasketInterface;
-use Exception;
-use Illuminate\Database\Eloquent\Model;
 
 abstract class Basket extends Model implements BasketInterface
 {
@@ -34,17 +34,29 @@ public static function getNew(): BasketInterface
     public function add(int $quantity, Basketable $basketable, array $meta = [])
     {
         if ($quantity < 1) {
-            throw new Exception('Quantity is less than one.');
+            throw new InvalidArgumentException('Quantity must be at least one.');
+        }
+
+        if (!method_exists($basketable, 'getKey') || $basketable->getKey() === null) {
+            throw new InvalidArgumentException('The basketable model must be persisted before it can be added.');
+        }
+
+        if (!$this->exists) {
+            if (!$this->save()) {
+                throw new \RuntimeException('Unable to persist the basket before adding an item.');
+            }
         }
 
         foreach ($this->items as $item) {
-            if (get_class($item->basketable) === get_class($basketable)
-                && $item->basketable->getKey() === $basketable->getKey()
+            $existingBasketable = $item->basketable;
+            if ($existingBasketable !== null
+                && get_class($existingBasketable) === get_class($basketable)
+                && $existingBasketable->getKey() === $basketable->getKey()
                 && $item->meta === $meta) {
                 $item->quantity += $quantity;
                 $item->save();
 
-                return;
+                return $item;
             }
         }
 
@@ -53,12 +65,29 @@ public function add(int $quantity, Basketable $basketable, array $meta = [])
         $item = new $basketItem();
         $item->basket_id = $this->id;
         $item->quantity = $quantity;
-        $item->basketable_type = get_class($basketable);
+        $item->basketable_type = method_exists($basketable, 'getMorphClass')
+            ? $basketable->getMorphClass()
+            : get_class($basketable);
         $item->basketable_id = $basketable->getKey();
         $item->meta = $meta;
         $item->save();
 
         unset($this->items);
+
+        return $item;
+    }
+
+    /**
+     * Remove every item from this basket.
+     *
+     * @return int Number of deleted basket items.
+     */
+    public function clear(): int
+    {
+        $deleted = $this->items()->delete();
+        unset($this->items);
+
+        return (int) $deleted;
     }
 
     public function getSubtotal()

src/Interfaces/BasketInterface.php

@@ -29,6 +29,11 @@ public function setQuantity(int $quantity)
 
     public function getPrice()
     {
-        return $this->quantity * $this->basketable->getPrice($this->meta);
+        $basketable = $this->basketable;
+        if ($basketable === null) {
+            throw new \LogicException('Cannot calculate a basket item price because its basketable model no longer exists.');
+        }
+
+        return $this->quantity * $basketable->getPrice($this->meta);
     }
 }