آموزش کامل نصب و استفاده از پکیج سبد خرید در لاراول Darryldecode Cart

یکی از چالش‌های اصلی در طراحی فروشگاه اینترنتی یا پلتفرم‌های خدماتی، مدیریت هوشمندانه و بهینه‌ی سبد خرید (Shopping Cart) کاربران است. ذخیره، به‌روزرسانی و محاسبه مبالغ اقلام سبد خرید باید با دقت بالا و سرعت عالی انجام شود. پکیج Darryldecode/Cart یکی از قوی‌ترین و پایدارترین ابزارها برای پیاده‌سازی سبد خرید در فریم‌ورک لاراول است. در این مقاله یاد می‌گیریم چطور این پکیج را از صفر نصب، کانفیگ و در کدهای خود مدیریت کنیم تا زیرساخت مناسبی برای توسعه وب فراهم شود.

🛠️ بخش اول: نصب و پیکربندی پکیج (Installation)

برای شروع کار, ابتدا ترمینال خود را در مسیر اصلی پروژه باز کرده و با استفاده از کامپوزر، پکیج را به وابستگی‌های پروژه خود اضافه کنید:

composer require "darryldecode/cart:~4.0"

پس از نصب موفقیت‌آمیز پکیج، باید آن را به هسته لاراول معرفی کنیم. فایل تنظیمات اصلی برنامه یعنی config/app.php را باز کنید و تغییرات زیر را در آن اعمال کنید:

۱. ابتدا به آرایه Service Providers بروید و کلاس ارائه‌دهنده خدمات پکیج را در انتهای آن تزریق کنید:

Darryldecode\Cart\CartServiceProvider::class

۲. سپس کمی پایین‌تر بیایید و در بخش Aliases (نام‌های مستعار)، فیساد (Facade) اختصاصی پکیج را ست کنید تا بتوانید در سراسر کدهای خود به راحتی به آن دسترسی داشته باشید:

'Cart' => Darryldecode\Cart\Facades\CartFacade::class

در نهایت، برای اینکه مطمئن شویم لاراول تغییرات و کلاس‌های جدید را به طور کامل شناسایی کرده است، دستور بهینه‌سازی نقشه اتولود کامپوزر را در ترمینال اجرا کنید:

composer dump-autoload

🚀 بخش دوم: راهنمای عملی و نمونه کدهای کاربردی

این پکیج به شما اجازه می‌دهد سبد خرید را بر اساس سشن یا آیدی هر کاربر (حتی کاربران مهمان) تفکیک کنید. بیایید متدهای اصلی را بررسی کنیم؛ تسلط بر این بخش به هر توسعه دهنده Laravel کمک می‌کند تا سیستم‌های مالی پیچیده‌تری را در طراحی پنل مدیریت یا ماژول‌های اختصاصی پیاده کند.

◈۱. افزودن محصول به سبد خرید (Add)

برای اضافه کردن یک آیتم به سبد خرید، مشخصات محصول را به صورت یک آرایه به متد add پاس می‌دهیم. در کدهای زیر، ابتدا وضعیت لاگین بودن کاربر را چک می‌کنیم تا سبد خرید دقیقاً متعلق به خود او باشد:

// ۱. تشخیص هویت کاربر: اگر لاگین کرده باشد ID او را می‌گیرد، در غیر این صورت Session ID کاربر مهمان را اختصاص می‌دهد
$userID = auth()->check() ? auth()->id() : session()->getId();
// ۲. متصل کردن سبد خرید به شناسه کاربر و اضافه کردن مشخصات محصول به آن
\Cart::session($userID)->add(array(
    // شناسه منحصربه‌فرد تنوع محصول (مثلا ترکیب رنگ و سایز)
    'id' => $request->attribute_id,
    // عنوان اصلی محصول از طریق رابطه دیتابیس
    'name' => $attribute->product->title,
    // قیمت نهایی و قابل پرداخت (تبدیل شده به عدد صحیح Integer)
    'price' => (int)$attribute->price_discount,
    // تعداد محصول اضافه شده در هر بار کلیک (پیش‌فرض ۱ عدد)
    'quantity' => 1,
    // آرایه‌ای از ویژگی‌های جانبی محصول برای نمایش در فاکتور
    'attributes' => [
        'original_price' => (int)$attribute->price, // قیمت اصلی بدون تخفیف
        'price_discount' => (int)$attribute->price_discount, // مبلغ تخفیف
        'color' => optional($attribute->color)->title, // نام رنگ (با متد optional برای جلوگیری از خطا در صورت خالی بودن)
    ],
));

◈۲. به‌روزرسانی مستقیم آیتم (Update)

اگر بخواهید قیمت یا تعداد یک آیتم مشخص (بر اساس rowId) را در سبد خرید به یک عدد ثابت تغییر دهید، متد update را به شکل زیر صدا می‌زنید:

\Cart::session($userID)->update($rowId, [
  'quantity' => 2,
  'price' => 98.67
]);

◈۳. جادوی مدیریت موجودی و تعداد (Relative Quantity)

یکی از جذاب‌ترین ویژگی‌های این پکیج، نحوه افزایش یا کاهش تعداد محصول است. اگر فیلد relative برابر با true باشد، مقداری که وارد می‌کنید با تعداد قبلی جمع یا تفریق می‌شود. اما اگر false باشد، دقیقاً همان مقدار جایگزین تعداد قبلی می‌شود.

برای اضافه کردن ۲ عدد به تعداد قبلی محصول:

Cart::update(456, array(
  'quantity' => 2,
));

برای کم کردن ۱ عدد از تعداد قبلی محصول (کاهش موجودی در سبد):

Cart::update(456, array(
  'quantity' => -1,
));

تنظیم دقیق تعداد روی یک عدد مشخص (مثلاً تحت هر شرایطی تعداد بشود ۵ عدد):

Cart::update(456, array(
  'quantity' => array(
      'relative' => false,
      'value' => 5
  ),
));

◈۴. حذف یک محصول (Remove) و دریافت کل لیست (Get Content)

برای حذف یک ردیف کالا از سبد خرید و یا گرفتن تمام اقلام موجود در سبد برای نمایش در فرانت‌اَند، از دو دستور زیر استفاده می‌شود:

\Cart::session($userID)->remove($rowId);
$items = \Cart::getContent();

💡 بخش سوم: چالش بزرگ؛ آپدیت کردن ویژگی‌ها بدون پاک شدن اطلاعات قبلی

یک نکته بسیار حیاتی که هنگام کار با متد `update` پکیج دارکارت باید به آن دقت کنید، نحوه رفتار فیلد `attributes` است. اگر شما بخواهید فقط یکی از ویژگی‌های محصول (مثلاً قیمت تخفیف خورده جدید) را تغییر دهید و آن را مستقیماً به متد آپدیت پاس بدهید، پکیج تمام ویژگی‌های قبلی (مثل رنگ، سایز و...) را پاک کرده و آرایه جدید را کاملاً جایگزین می‌کند!

◈راه حل چیست؟

برای اینکه ویژگی‌های قبلی حفظ شوند و فقط فیلد مدنظر شما تغییر کند یا فیلد جدیدی به آن اضافه شود، باید ابتدا ویژگی‌های فعلی آن آیتم را از سبد خرید بخوانید، تغییرات را روی آن آرایه اعمال کنید و سپس کل آرایه آپدیت شده را برگردانید:

// ۱. دریافت ویژگی‌های فعلی آیتم موجود در سبد خرید
$attrs = $item->attributes;

// ۲. اعمال تغییرات یا اضافه کردن ویژگی‌های جدید به آرایه قبلی
$attrs['price'] = (int)$product->price;
$attrs['price_discounted'] = (int)$product->price_discounted;

// ۳. بروزرسانی کل آیتم با حفظ سایر ویژگی‌ها در دیتابیس یا سشن سله
\Cart::session($sessionId)->update($item->id, [
    'price' => (int)$product->price,
    'attributes' => $attrs // پاس دادن آرایه کامل و ترکیب شده
]);

با این روش هوشمندانه، بدون اینکه اطلاعات مربوط به رنگ، سایز یا مشخصات دیگر محصول در سبد خرید کاربر از بین برود، قیمت و ویژگی‌های خاص آن را به روزرسانی می‌کنید. این موضوع در پروژه‌های بزرگ مقیاس تاثیر مستقیمی روی حفظ شاخص‌های کلیدی توسعه بیزینس دارد.

📋 بخش چهارم: مرجع سریع و کدهای یکپارچه پکیج

برای اینکه همیشه یک تقلب‌نامه سریع و آماده دم دست خود داشته باشید، تمام متدهای کلیدی پکیج Darryldecode Cart به همراه توضیحات کاربردی آن‌ها را در یک باکس کد یکپارچه برای شما جمع‌آوری کرده‌ام. می‌توانید از این متدها در کنترلرهای خود استفاده کنید:

// ۱. اضافه کردن یک کالا یا آرایه‌ای از کالاها به سبد خرید
Cart::add();
// ۲. به‌روزرسانی تعداد, قیمت یا ویژگی‌های یک کالا در سبد خرید
Cart::update();
// ۳. حذف کامل یک کالای خاص از سبد خرید بر اساس آیدی (rowId) آن
Cart::remove();
// ۴. اعمال یک شرط کلی (مثل مالیات، هزینه ارسال یا کوپن کلی) روی کل سبد خرید
Cart::condition($condition);
// ۵. محاسبه و دریافت مبلغ نهایی کل سبد خرید (با احتساب تخفیف‌ها و تمام شرایط)
Cart::getTotal();
// ۶. دریافت مجموع مبالغ اقلام سبد خرید قبل از اعمال شرایط و تخفیف‌های نهایی
Cart::getSubTotal();
// ۷. محاسبه قیمت خالص و واقعی اقلام بدون در نظر گرفتن هیچ‌گونه تخفیف یا کوپنی
Cart::getSubTotalWithoutConditions();
// ۸. اعمال یک شرط یا کوپن تخفیف اختصاصی فقط و حداقل روی یک محصول خاص در سبد خرید
Cart::addItemCondition($productID, $coupon);

با استفاده از این ابزارها، شما می‌توانید پیچیده‌ترین سیستم‌های سبد خرید فروشگاهی را با امنیت بالا و در کوتاه‌ترین زمان ممکن در پروژه‌های لاراول پیاده‌سازی کنید.