Download the PHP package dive-be/laravel-wishlist without Composer

❤️ - Manage your users' wishes in a Laravel app

What problem does this package solve?

This package provides solutions to common problems when managing a user's wishlist. It also allows for seamless transitions between storage drivers depending on a user's authentication state.

Installation

You can install the package via composer:

You can publish the config file and migrations with:

This is the contents of the published config file:

Usage

Configuration

First things first, you should take a look at the published configuration file and adjust the values to your needs. If you need additional information about the available options, read on.

Drivers

Array ⏳

This driver is meant for use in testing. Its contents are ephemeral and should not be used in production.

See Testing section below for additional information regarding unit tests.

Cookie 🍪

The user's wishlist will be persisted client-side as a stringified JSON. You should make use of Laravel's cookie encryption (enabled by default) or any user will be able to crash your application (because there is no validation) when the cookie values are tampered with. The internal structure of your code base will be leaked partially as well if you do not make use of relation morph maps.

Note: make sure the name of the cookie you wish to use (pun intended) is not excluded for encryption in the \App\Http\Middleware\EncryptCookies::$excluded array.

Eloquent 🧑‍🎨

The user's wishlist will be persisted server-side in the wishes table. You can only use this driver inside routes that are protected by the auth middleware as it requires an instance of an authenticated user.

Note: do not forget to publish and run the migrations if you opt to use this driver.

Upgrade 🚀

> This < is the driver that makes this package shine.

• When a guest (an unauthenticated user) is browsing your app, the Cookie driver will be used to persist the wishlist.
• When the user is authenticated, the Eloquent driver will be used.

🤌 Best of all? You don't have to change anything in your code.

But hold on, there is more! When the user logs in, the wishes can be carried over to the database automatically! 🙀 See Migrating wishes section below for additional information.

Preparing Wishable models

Next, you must make the Eloquent models that can be wished for Wishable i.e. implement the contract and use the CanBeWished trait.

An example:

Preparing User model (optional)

For convenience, this package also provides an InteractsWithWishlist trait which you can use in your User model to interact with the wishlist.

You can now do the following:

Resolving the wishlist

This package provides every possible way to resolve a Wishlist instance out of the IoC container. We've got you covered!

Facade

or using the alias (particularly helpful in Blade views)

Helper

Dependency injection

Service Location

Capabilities 💪

You can refer to the Wishlist contract for an exhaustive list.

Adding a wish

You will receive an instance of Dive\Wishlist\Wish.

Retrieving all wishes

You will receive an instance of Dive\Wishlist\WishCollection<Wish>. Refer to the class definition for all convenience methods.

Finding a wish

Eager loading wish relations

When there is only a single type of Wishable (and you know for sure there won't be any other), you may omit the morph types entirely:

In other cases, you must provide a type-relation map:

A LogicException will be thrown in case of ambiguity:

Retrieving total count

Existence checks

Emptiness checks

Purging

Wish removal

You can remove a wish either by its id

or by its underlying Wishable

Migrating wishes 🚚

While using the Upgrade driver, you may want to carry over the user's cookie wishlist to the database. This is not enabled by default, but you have 2 options to opt into this behavior:

Event listener

Listen to the Login event in EventServiceProvider:

Middleware

Add the MigrateWishes middleware to your application's middleware stack:

Note: make sure to place the middleware after EncryptCookies

Route model binding

Wouldn't it be nice to have a wish automatically resolved from a route parameter?

Well, say no more! 👇

• As this is not an Eloquent model, you can still use this syntax even if you only use the Cookie driver! 🎉
• Just like Eloquent models, a ModelNotFoundException will be thrown if the requested wish cannot be found.

Note: you cannot make the wish parameter a child of a parent parameter because it does not make sense. An exception will be thrown if you attempt to do so.

Retrieving a particular user's wishlist 👱🏻‍♂️

You may want to modify a user's wishlist in e.g. an Artisan command where no auth context is available. For these cases, you can invoke the forUser method with a User instance to retrieve a wishlist scoped to that user:

Note: this is only available for the Eloquent driver

Extending the wishlist 👣

If the default drivers do not fulfill your needs, you may extend the WishlistManager with your own custom drivers:

Testing 🔎

This package offers a fake implementation of the Wishlist contract so you can make assertions in your unit tests and make sure you ship that bug-free code 💪.

Testing (package)

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• Muhammed Sari
• All Contributors

License

The MIT License (MIT). Please see License File for more information.