Package: cart

Source: api/packages/cart · imported version 0.4.81. The sections after the README are extracted from the code on every docs build.

README

Purpose

This package lets you manage user Shopping Cart, and defines what is a buyable Product (and what are Productables, that is sellable things), that can be then added to the Cart. This package also lets your users create Orders and buy content of their Carts.

Installation

• composer require ulams/cart
• php artisan migrate
• php artisan db:seed --class="Ulams\Cart\Database\Seeders\CartPermissionSeeder"

Dependencies

This package depends on Ulams/Payments package for creating and processing Payments for Orders.

Usage

Product

Ulams\Cart\Models\Product is a Model that represents abstract buyable thing that can be added to Cart and bought. Product by itself has no additional functionality than being bought and assigned to Users.

Products consist of one (Single type products) or more (Bundle type products) Productables - that is, Models representing concrete things that are sold in your (LMS) application, for example Courses. Productables must implement Productable interface.

Productable

Ulams\Cart\Contracts\Productable interface defines how Model representing sellable things behave and which methods and relations they must contain.

Defining Productables

To create (and sell) Products, you need to define Productables. A Productable is a Model implementing Ulams\Cart\Models\Contracts interface (and possibly using Ulams\Cart\Contracts\ProductableTrait). After adding this interface to your Model, you need to call Ulams\Cart\Facades\Shop::registerProductableClass(Productable::class) in one of your Service Providers boot method. This will enable using this Productable Model as a (part of) Product which can then be sold.

Shop Facade

Shop Facade wraps Ulams\Cart\Services\ProductService giving access to methods related to registering Productables and managing Products.

Cart Model

Ulams\Cart\Models\Cart is a model representing User Cart. Every User can have one active (existing) Cart at given time.

To create Cart (or retrieve current active Cart) for a given user, you need to call Ulams\Cart\Services\ShopService::cartForUser($user) method.

Cart Manager

Cart and its content is managed using Ulams\Cart\Services\CartManager class instance attached to that Cart, instead of manipulating Cart object directly. CartManager is used by Ulams\Cart\Services\ShopService (and you probably don’t need to use it directly, as methods in ShopService represent all sensible use cases).

Shop Service

Shop Service contains functionality related to managing Cart content (adding/removing Products), and purchasing Cart (storing Cart data as an Order and processing payment flow).

Endpoints

All the endpoints are defined in .

Tests

Run ./vendor/bin/phpunit to run tests. See tests directory as it’s a quite good starting point for understanding how this package works. Especially pay attention to tests/Mocks directory, as it represents core concepts of Productable and use of Productable Trait & Interface.

Test details

Events

• Ulams\Cart\Events\AbandonedCartEvent - emited when scheduled job finds a non-empty Cart older than 24 hours
• Ulams\Cart\Events\OrderCancelled - emited after payment processing is cancelled, which marks Order as cancelled
• Ulams\Cart\Events\OrderCreated - emited when new Order is created
• Ulams\Cart\Events\OrderPaid - emited after order was paid
• Ulams\Cart\Events\ProductableAttached - emited after Productable is attached to an User (for example after Product containing that Productable is attached to User, or admin endpoints for managing Productable attachments is used)
• Ulams\Cart\Events\ProductableDetached - analogous to ProductableAttached
• Ulams\Cart\Events\ProductAddedToCart - emitted when Product is added to Cart
• Ulams\Cart\Events\ProductAttached - emitted when Product is attached to User (after buying it or adding it using admin endpoint)
• Ulams\Cart\Events\ProductBought - emited after Product is bought by User
• Ulams\Cart\Events\ProductDetached - analogous to ProductAttached
• Ulams\Cart\Events\ProductRemovedFromCart - analogous to ProductAdded

Listeners

• Ulams\Cart\Listeners\PaymentSuccessListener - this listener handles marking Orders as Paid after a Payment created for given Order is marked as Paid (listens to Ulams\Payments\Events\PaymentSuccess event)

How to use this on frontend

Admin panel

Left menu

List of Products

Creating/editing Product

List of Orders

Details of Order

Permissions

Permissions are defined in Enum and seeded in Seeder.

Roadmap. Todo. Troubleshooting

• ???

More documentation in the package

• api/packages/cart/ADMIN.md
• api/packages/cart/docs/menu.png
• api/packages/cart/docs/orders-list.png
• api/packages/cart/docs/products-edit.png
• api/packages/cart/docs/products-list.png

API endpoints

Method	Path	Auth	Action
GET	/api/admin/orders	yes	OrderAdminApiController@index
GET	/api/admin/orders/export	yes	OrderAdminApiController@export
GET	/api/admin/orders/{id}	yes	OrderAdminApiController@read
GET	/api/admin/products	yes	ProductAdminApiController@index
POST	/api/admin/products	yes	ProductAdminApiController@create
GET	/api/admin/products/{id}	yes	ProductAdminApiController@read
PUT	/api/admin/products/{id}	yes	ProductAdminApiController@update
DELETE	/api/admin/products/{id}	yes	ProductAdminApiController@delete
POST	/api/admin/products/{id}/trigger-event-manually/{idTemplate}	yes	ProductAdminApiController@triggerEventManuallyForUsers
POST	/api/admin/products/{id}/attach	yes	ProductAdminApiController@attach
POST	/api/admin/products/{id}/detach	yes	ProductAdminApiController@detach
GET	/api/admin/productables	yes	ProductableAdminApiController@index
GET	/api/admin/productables/registered	yes	ProductableAdminApiController@registered
GET	/api/admin/productables/product	yes	ProductableAdminApiController@product
POST	/api/admin/productables/attach	yes	ProductableAdminApiController@attach
POST	/api/admin/productables/detach	yes	ProductableAdminApiController@detach
GET	/api/cart	yes	CartApiController@index
POST	/api/cart/products	yes	CartApiController@setProductQuantity
POST	/api/cart/missing	yes	CartApiController@addMissingProducts
DELETE	/api/cart/products/{id}	yes	CartApiController@remove
POST	/api/cart/add	yes	CartApiController@addProductable
POST	/api/cart/pay	yes	PaymentApiController@pay
POST	/api/product/{id}/pay	yes	PaymentApiController@payProduct
GET	/api/products/my	yes	ProductApiController@indexMy
GET	/api/products/{id}		ProductApiController@read
GET	/api/products		ProductApiController@index
POST	/api/products/cancel/{id}	yes	ProductApiController@cancel
POST	/api/productables/attach	yes	ProductablesApiController@attach
GET	/api/orders	yes	OrderApiController@index
GET	/api/orders/{id}	yes	OrderApiController@read

Permissions

Permission	Seeded for roles	Constant
cart_order_list	admin	CartPermissionsEnum::LIST_ALL_ORDERS
products_list	admin, tutor	CartPermissionsEnum::LIST_ALL_PRODUCTS
products_manage	admin	CartPermissionsEnum::MANAGE_PRODUCTS
products_list_purchasable	student	CartPermissionsEnum::LIST_PURCHASABLE_PRODUCTS
products_buy	student	CartPermissionsEnum::BUY_PRODUCTS
orders_export	admin	CartPermissionsEnum::ORDERS_EXPORT

Settings

Registered with AdministrableConfig::registerConfig (editable in the admin panel under Configuration → Settings).

Key	Rules	Public	Read-only
ulams_cart.min_product_price	required, numeric, min:0	yes

Events

Event	Description	Notification templates
AbandonedCartEvent
OrderCancelled
OrderCreated		Email
OrderPaid
ProductAddedToCart
ProductAttached		Email
ProductBought
ProductDetached
ProductRemovedFromCart
ProductableAttached
ProductableDetached

Notification templates registered here

None.

Artisan commands

Command	Description	Signature
cart:abandoned-event	Find all abandoned cart in 24-48h and run event	cart:abandoned-event

Scheduled jobs

Kind	Target	Frequency
command	AbandonedCart::class	dailyAt('1:00')
job	RenewRecursiveProduct::class	hourly()
job	ExpireRecursiveProduct::class	daily()

Environment variables read

None.