README

OFFLINE.MicroCart 插件旨在提供简单的购物车和支付功能。

此插件适用于在线销售简单商品的项目（门票、优惠券等）。您需要自己实现“商品部分”（如 门票 模型）。您可以将插件用作购物车和支付解决方案。

特性

OFFLINE.MicroCart 插件提供以下特性：

• 具有添加和删除 购物车项 的良好 API 的 购物车 模型
• 一个用于扩展的 购物车 组件基类
• 支持 Stripe、PayPal 和 SIX SaferPay 支付集成
• 支持添加自定义支付网关
• 提供多个事件供您挂钩

它 不 提供以下任何功能：

• 产品数据管理
• 电子邮件通知
• 支持多货币
• 库存管理
• 配送规则
• 以及许多其他扩展的电子商务功能...

如果您正在寻找适用于 October CMS 的功能齐全的电子商务解决方案，请查看 OFFLINE.Mall。

启动和运行

创建一个扩展 MicroCart 的插件

MicroCart 插件旨在由您的插件扩展。有关所有扩展可能性的列表，请参阅 官方 October CMS 文档。

php artisan create:plugin YourVendor.PluginName

后端菜单

默认情况下，插件不会注册任何后端菜单项。您可以在自己的 Plugin.php 中使用以下片段来使用默认订单概览。

    public function registerNavigation()
    {
        return [
            'main-menu-item' => [
                'label'        => 'Your Plugin', // Your label
                'url'          => \Backend::url('offline/microcart/carts'),
                'iconSvg'      => 'plugins/offline/microcart/assets/icon.svg',
            ],
        ];
    }

购物车组件

插件默认不注册任何组件，但它提供了一个可扩展的 购物车 基组件。

只需注册自己的组件并在此基础上构建。

php artisan create:component YourVendor.PluginName Cart

在您的 Plugin.php 中注册您的组件。

    public function registerComponents()
    {
        return [
            \YourVendor\YourPlugin\Components\Cart::class => 'cart',
        ];
    }

确保组件扩展 MicroCart 的基组件。

<?php namespace YourVendor\YourPlugin\Components;

use OFFLINE\MicroCart\Models\CartItem;
use OFFLINE\MicroCart\Classes\Payments\PaymentRedirector;

class Cart extends \OFFLINE\MicroCart\Components\Cart
{        
    public function onRun()
    {
        // An off-site payment has been completed. Important, this code
        // needs to be present if you are using PayPal or Six. 
        if ($type = request()->input('return')) {
            return (new PaymentRedirector($this->page->page->fileName))->handleOffSiteReturn($type);
        }

        // Do something.
    }

    public function onAdd()
    {
        $item           = new CartItem();
        $item->name     = 'Your product';
        $item->quantity = random_int(1, 4);
        $item->price    = 100.00;

        $this->cart->add($item);

        return $this->refreshCart();
    }
}

要修改验证规则和消息，请查看基 购物车 类上的 getValidationRules、getFieldNames 和 getValidationMessages 方法。

将 MicroCart 基组件的默认部分从 此处 复制到您的组件。根据需要修改它们。

cp -rv plugins/offline/microcart/components/cart/* plugins/yourvendor/yourplugin/components/cart/

更新购物车部分

您可以从您的购物车组件的方法中返回 $this->refreshCart(); 以刷新购物车显示。

使用支付提供商

支持三种开箱即用的支付提供商

• PayPal (composer require omnipay/stripe)
• Stripe (composer require omnipay/paypal)
• Six SaferPay (composer require ticketpark/saferpay-json-api)

运行每个计划使用的提供商旁边的 composer 命令。您可以通过 October 的后端设置配置提供商。

自定义支付提供商

要注册自定义 PaymentProvider，请创建一个扩展 MicroCart 的 PaymentProvider 类的类。查看现有的提供商以获取一些创建自己的灵感。

<?php

namespace YourVendor\YourPlugin\Classes;

use OFFLINE\MicroCart\Classes\Payments\PaymentProvider;

class YourCustomProvider extends PaymentProvider
{
    // Implement all abstract methods.
}

在您的 Plugin.php 中通过从 registerPaymentProviders 方法返回它们来注册此自定义提供商。

use OFFLINE\MicroCart\Classes\Payments\PaymentGateway;

class Plugin extends PluginBase
{
    public function registerPaymentProviders()
    {
        return [
            new YourCustomProvider(),
        ];
    }
}

将模型链接到购物车项

将模型链接到 CartItem 的最简单方法是添加一个简单的 belongsTo 关系。

// Voucher is the thing we are selling (the CartItem)
class Voucher extends Model
{
    public $belongsTo = [
        'cartitem' => CartItem::class
    ];
}

API

购物车

获取用户的购物车

// This cart will be unique to the current user.
$cart = Cart::fromSession();

向购物车添加商品

$item           = new CartItem();
$item->name     = 'An item'; // The only required field
$item->quantity = 2;
$item->price    = 20.00;

$cart->add($item);

确保商品在购物车中

$item = new CartItem(['name' => 'Shipping fee', 'kind' => CartItem::KIND_SERVICE]);

// A code property is required! A product with the specified
// code is ensured to be present in the Cart.
$item->code = 'shipping'; 

// ensure the item is in the cart. If it's not, it will be added.
$cart->ensure($item);
// A second call will not add the item again.
$cart->ensure($item);
// You can force a new quantity by passing a second parameter.
$cart->ensure($item, 4);

从购物车中移除商品

$item = new CartItem(['name' => 'An item']);

// You can remove an item by passing in a CartItem object or an id.
$cart->remove($item);
$cart->remove($item->id);

从购物车中移除指定代码的所有商品

$item = new CartItem(['name' => 'Shipping fee', 'code' => 'shipping', 'kind' => CartItem::KIND_SERVICE]);

// Removes all items with a given code (reverse of the `ensure` method).
$cart->removeByCode('shipping');

更新商品数量

$item = new CartItem(['name' => 'An item']);

// You can set the quantity by passing in a CartItem object or an id.
$cart->setQuantity($item, 4);
$cart->setQuantity($item->id, 4);

服务费和折扣

如果商品是服务费（运输、处理）或折扣，将kind属性设置为CartItem::KIND_SERVICE或CartItem::KIND_DISCOUNT。使用ensure方法确保它只添加一次到购物车中。

$item = new CartItem(['name' => 'Shipping fee', 'kind' => CartItem::KIND_SERVICE, 'price' => 10]);

// The code is required to use the `ensure` method.
$item->code = 'shipping'; 

$cart->ensure($item);


$item = new CartItem(['name' => 'Discount', 'kind' => CartItem::KIND_DISCOUNT, 'price' => -100]);
$item->code = 'discount'; 

$cart->ensure($item);

访问购物车内容

您可以使用$cart->items关系访问所有购物车商品。

您还可以访问过滤后的list_items、service_fees和discounts属性，这些属性只包含指定的商品类型。

$item     = new CartItem(['name' => 'A product']);
$shipping = new CartItem(['name' => 'Shipping fee', 'kind' => CartItem::KIND_SERVICE]);
$discount = new CartItem(['name' => 'Discount',     'kind' => CartItem::KIND_DISCOUNT]);

$cart->addMany($item, $shipping, $discount);

$cart->list_items->first()   === $item;     // true
$cart->service_fees->first() === $shipping; // true
$cart->discounts->first()    === $discount; // true

打印客户的地址

在购物车结账成功后，您可以使用以下辅助工具获取客户地址作为数组或转义的HTML字符串。

$cart->getShippingAddressArray();
// ['Company', 'Firstname Lastname', ...];

$cart->getBillingAddressHtml();
// Company<br />
// Firstname Lastname<br />
// Street 123<br />
// ZIP City

$cart->getBillingAddressHtmlZipReversed();
// Company<br />
// Firstname Lastname<br />
// Street 123<br />
// City ZIP

CartItem

创建商品

// Short format
$item = new CartItem(['name' => 'An item']);

// Or long format
$item = new CartItem();
$item->name = 'An item';
$item->description = 'The description to this item';
$item->price = 20.00; // Includes tax by default.
$item->quantity = 10;
$item->meta = [
    'any' => 'additional',
    'data' => true,
];
// $item->tax_id = 2;           // If not specified the default tax will be used. 
// $item->tax_free = true;      // Don't add taxes to this item, not even the default tax. 
// $item->is_before_tax = true; // The specified price does not include taxes. 

访问商品信息

// Create an example item
$item           = new CartItem(['name' => 'An item']);
$item->price    = 10.00;
$item->quantity = 2;
$item->tax_id   = 1; // 10% tax

// Access the item's information
$item->price;        // 10.00
$item->quantity;     // 2
$item->subtotal;     // 20.00 => price * quantity
$item->tax_amount;   //  2.00 => 10 % on price 
$item->total;        // 22.00 => (price * quantity) + tax_amount

货币

有一个名为Money的单例类可用于将分转换为字符串。还注册了一个名为microcart_money的Twig辅助工具。

Money::instance()->format(12000); // 120.00 USD

// or in Twig
{{ 120000 | microcart_money }}   // 120.00 USD

更改默认货币格式化程序

您可以通过将以下代码添加到插件中的register方法来注册自己的格式化函数。

    public function register()
    {
        \Event::listen('offline.microcart.moneyformatter', function () {
            return function ($cents): string {
                return 'Your custom implementation to format: ' . $cents;
            };
        });
    }

事件

购物车

offline.microcart.cart.beforeAdd

在商品添加到购物车之前触发。它接收以下参数

• $cart：当前用户的Cart
• $item：正在添加的CartItem

offline.microcart.cart.afterAdd

在商品添加到购物车后触发。它接收以下参数

• $cart：当前用户的Cart
• $item：已添加的CartItem

offline.microcart.cart.beforeRemove

在商品从购物车中移除之前触发。它接收以下参数

• $cart：当前用户的Cart
• $item：正在移除的CartItem

offline.microcart.cart.afterRemove

在商品从购物车中移除后触发。它接收以下参数

• $cart：当前用户的Cart
• $item：已移除的CartItem

offline.microcart.cart.quantityChanged

在购物车商品数量更改后触发。

• $cart：当前用户的Cart
• $item：已更新的CartItem

结账

offline.microcart.checkout.succeeded

结账成功后触发。

• $result：一个PaymentResult实例

offline.microcart.checkout.failed

结账失败后触发。

• $result：一个?PaymentResult实例（可以为空）

offline.microcart.checkout.cancelled

结账取消后触发。