با سلام و احترام خدمت همکاران گرامی و توسعه دهندگان محترم پرستاشاپ
یکی از مزایای مهم و ارزشمند فروشگاه ساز پرستاشاپ امکان توسعه این سیستم فروشگاه ساز قدرتمند با افزونه ها و ماژولهای جانبی است. در پرستاشاپ این ویژگی آنقدر گسترده و شاخص است که به نوعی میتوان گفت بخشهای مهمی از امکانات این سیستم فروشگاهساز به کمک افزونه ها و ماژولها فراهم شده است.
خوشحالیم که در پرستافا تمام تلاش ما توسعه ماژولهای و افزونه های کارآمد و ارزشمند برای این سیستم فروشگاه ساز قدرتمند بوده و امیدواریم در این زمینه در آینده نیز بتوانیم عملکرد مطلوبی را ارائه کنیم.
در این مقاله قصد داریم به ویژگی رویدادها در ماژول پرستامارکت بپردازیم، این ویژگی به این منظور در ماژول پرستامارکت تعریف شده است تا بتوان در شرایط خاص اقداماتی متناسب با نیاز آن شرایط توسط ماژولهای جانبی دیگر انجام داد.
ثبت و فراخوانی هوک رویداد پرستامارکت در ماژولهای دیگر
به طور پیشفرض امکان اطلاع رسانی ایمیلی در ماژول پرستامارکت پیاده سازی شده است با این حال ممکن است نیاز به سرویس ها و امکانات پیشرفته تر مانند ارسال پیامک داشته باشید که در این حالت امکان رویدادها که طبق توضیحات زیر شرح داده میشود میتواند به سرویس دهندگان و ماژولهای جانبی برای پیاده سازی و مدیریت رویدادها و وقایع پرستامارکت کمک کند.
به عنوان مثال وقتی میخواهیم ایمیل یا پیامکی ارسال کنیم، یک رویداد میتواند ما را از به وقوع پیوستن اتفاق مورد نظر، آگاه سازد که این موضوع به سادگی میتواند به ما در انجام کاری که میخواهیم کمک کند.
رویدادها در ماژول پرستامارکت به کمک ویژگی هوکها پیاده سازی شده است. بدین منظور ماژول میبایست حتما هوک رویدادها در ماژول جانبی دیگر ثبت و فراخوانی شود.
همچنین توصیه میکنیم حتما در ماژولهایی که میخواهید رویدادهای پرستامارکت را مدیریت کنند، یک آپشن فعال و غیر فعال کردن پیاده سازی شود چرا که ممکن است همان امکان (مثلا پیامک یا ایمیل یا هر سرویس دیگر) توسط ماژولی دیگر برای پرستامارکت پیاده سازی شده و برروی فروشگاه کاربر نصب و فعال باشد که در نتیجه باعث تکرار یا تداخل یک امکان (مثلا ارسال چندباره پیامک جداگانه توسط هر ماژول) شود.
این هوک باید در ماژولهایی که میخواهند رویدادها را مدیریت کنند ثبت و فراخوانی شود:
1 |
actionPrestaMarketEvent |
اطلاعات ارسال شده در هوک رویداد ماژول پرستامارکت
در تمامی رویدادها فهرست تمام رویدادها و جزییات آنها با متغیر all_eventsارسال شده و همچنین به صورت اختصاصی در هر رویداد کلید رویداد با نام متغیر current_event ارسال میشود و در نهایت سعی شده یک شی از فروشنده (object) به نام متغیر seller ارسال شود. البته ممکن است در آپدیتهای آتی رویدادهایی بدون شی فروشنده نیز قرار داده شود که در این صورت با توجه به شرایط و نیاز باید این شی بررسی و صحت سنجی شود.
1 2 3 |
$args['all_events'] // فهرست تمامی رویدادها $args['current_event'] // کلید رویداد جاری $args['seller'] // شی (آبجکت) فروشنده |
و همچنین برای دسترسی به فهرست تمامی رویدادهای ماژول با جزییات متغیرهای هر رویداد (به عنوان مثال برای استفاده در فرم تنظیمات ماژول) از متد زیر استفاده کنید که این مقدار همان مقداری است که در all_events در هر رویداد ارسال میشود.
1 2 3 4 5 6 7 |
$module = Module::getInstanceByName('psf_prestamarket'); if (is_object($module) && method_exists($module, 'getModuleEvents')) { $eventList = $module->getModuleEvents(); } |
که خروجی این متد یک آرایه مشابه زیر است :
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 |
array( 'seller_created' => array( 'title' => 'ثبت فروشنده جدید', 'args' => array( 'all_events' => 'array', 'current_event' => 'string', 'seller' => 'object' ), ), 'withdraw_changed_status' => array( 'title' => 'تغییر وضعیت درخواست تسویه (امور مالی)', 'args' => array( 'all_events' => 'array', 'current_event' => 'string', 'seller' => 'object', 'withdraw' => 'object' ), ), 'draft_published' => array( 'title' => 'تایید و انتشار پیشنویس محصول', 'args' => array( 'all_events' => 'array', 'current_event' => 'string', 'seller' => 'object', 'draft' => 'object', 'is_new_product' => 'bool' ), ), // ... ); |
کد زیر نمونه ای از فراخوانی هوک رویدادهای پرستامارکت و بررسی اولیه دو متغیر اصلی یعنی شی seller و کلید رویداد current_event است:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
public function hookActionPrestaMarketEvent($args) { if (! Configuration::get('YOURMODULE_IS_ACTIVE_EVENTS')) { return false; // پیاده سازی و بررسی آپشن فعال و غیر فعال کردن مدیریت رویداد در ماژول جانبی } $eventKey = !empty($args['current_event']) ? $args['current_event'] : false; $seller = !empty($args['seller']) && is_object($args['seller']) ? $args['seller'] : false; if (!$eventKey || !$seller) { return false; // در صورتی که نیاز به شی فروشنده و نام رویداد دارید، صحت این دو را بررسی کنید } // ادامه کدها } |
تمامی اشیا و آبجکتهایی که درون رویدادها وجود خواهند داشت دسترسی به مقادیر دیتابیس دارند با این حال میتوان به مرور در صورت نیاز متدهای عمومی در اینجا فهرست خواهند شد که بهتر است از این متدها استفاده شوند.
رویدادهای مربوط به فروشنده :
1 2 |
seller_created // زمانی که فروشنده ایجاد میشود seller_changed_status // زمانی که وضعیت فروشنده تغییر میکند |
همانطور که قبلا گفته ایم شی seller در تمام رویدادهای فعلی ارسال میشود (البته ممکن است در آینده اینطور نباشد) بنابر این (به شرط بررسی وجود این شی) میتوانید در همه رویدادها از آن استفاده کنید.
در دو متد اول (ایمیل و موبایل) کلید رویداد نیز باید ارسال شود زیرا ممکن است در آپدیتهای آتی ماژول امکان تعیین اطلاع رسانی بر اساس رویداد به کارمندان و اشخاص خاص افزوده شود بنابر این حتما برای دریافت موبایل یا ایمیل از این دو متد به همراه نام رویداد استفاده کنید.
1 2 3 4 5 6 7 |
$seller->getEmail($eventKey) // دریافت ایمیل متناسب با رویداد $seller->getMobile($eventKey) // دریافت شماره موبایل متناسب با رویداد $seller->getDisplayName() // دریافت نام فروشنده $seller->getLevel() // دریافت یک شی از سطح (گروه) فروشنده $seller->isBanned() // برای بررسی وضعیت محروم یا غیر فعال بودن فروشنده $seller->isPending() // برای بررسی وضعیت در انتظار تایید بودن فروشنده $seller->isActive() // برای بررسی وضعیت فعال بودن فروشنده |
رویدادهای مربوط به فروش :
1 2 |
sale_created // زمانی که یک فروش برای فروشنده ثبت میشود sale_changed_state // زمانی که وضعیت فروش تغییر میکند |
در رویدادهای فروش که در بالا ذکر شد، یک شی از جدول sale نیز ارسال میشود که البته یک متد مهم برای دریافت شی از جدول state را نیز دارد که در صورتی که فروش در وضعیت خاصی نباشد این متد مقدار null را برمیگرداند.
1 |
$sale->getState() |
منظور از وضعیت یا state وضعیتهای داخلی ماژول پرستامارکت هستند که برای فروش های فروشندگان استفاده میشوند که در صورتی که این شی وجود داشته باشد و مقدارش null نباشد، به طور کلی سه حالت خواهند داشت ، یا نیاز به پیگیری دارند یا موفق بودند (مثلا ارسال شده و به دست مشتری رسیده) و یا ناموفق (مثلا لغو شده یا ارسال نشده) که میتوان از متدهای زیر برای بررسی حالت کلی این state استفاده کرد.
1 2 3 4 5 6 7 8 |
$state = $sale->getState(); if (!empty($state) && is_object($state)) { $state->isPending(); // اگر فروش نیاز به پیگیری دارد $state->isFailed(); // اگر فروش ناموفق بوده و دیگر نیاز به پیگیری ندارد $state->isSuccess(); // اگر فروش موفق بوده و دیگر نیاز به پیگیری ندارد } |
رویدادهای مربوط به امور مالی و درخواست های تسویه :
1 2 |
withdraw_created // زمانی که درخواست مالی ایجاد میشود withdraw_changed_status // زمانی که وضعیت درخواست مالی تغییر میکند |
در این رویدادها نیز یک شی با نام متغیر withdraw ارسال میگردد که علاوه بر اطلاعات درون جدول، وضعیت آن را میتوان از طریق متدهای زیر بررسی کرد.
1 2 3 4 5 |
$withdraw->isPending(); // درخواست جدید و در انتظار پیگیری است $withdraw->isInProgress(); // درخواست در حال پیگیری است $withdraw->isPaid(); // درخواست پرداخت شده است $withdraw->isRejected(); // درخواست مورد قبول نبوده و رد شده است $withdraw->isCanceled(); // درخواست توسط فروشنده لغو شده است |
رویدادهای مربوط به ثبت محصول و پیشنویس :
1 2 |
draft_published // پیشنویس توسط ناظر تایید و منتشر شده است draft_rejected // پیشنویس توسط ناظر تایید نشده است |
در این رویدادها نیز یک شی با نام متغیر draft ارسال میگردد. ضمنا در رویداد اول که پیشنویس تایید و منتشر میشود یک مقدار دیگر نیز ممکن است ارسال شود که مشخص میکند این پیشنویس برای یک محصول جدید بوده یا تنها به روز رسانی اطلاعات محصولات قبلی
1 2 |
$args['is_new_product'] $draft->getProduct() // بازگردانی یک شی از محصول منتسب شده و یا مقدار هیچ |
نمونه کد نهایی برای یک رویداد :
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 |
public function hookActionPrestaMarketEvent($args) { if (! Configuration::get('YOURMODULE_IS_ACTIVE_EVENTS')) { return false; } $eventKey = !empty($args['current_event']) ? $args['current_event'] : false; $seller = !empty($args['seller']) && is_object($args['seller']) ? $args['seller'] : false; if (!$eventKey || !$seller) { return false; } if ($eventKey == 'draft_published') { $draft = !empty($args['draft']) && is_object($args['draft']) ? $args['draft'] : false; if (empty($draft)) { return false; } $sms = new ExampleSms(); $sms->mobileNumber = $seller->getMobile($eventKey); $sms->messageHeader = 'فروشنده گرامی ' . $seller->getDisplayName(); if (!empty($args['is_new_product']) { $sms->messageBody = 'محصول جدید توسط ناظر تایید و منتشر شد'; } else { $sms->messageBody = 'به روز رسانی اطلاعات محصول توسط ناظر تایید شد'; } $product = $draft->getProduct(); if (!empty($product->id)) { $sms->messageFooter = 'شناسه محصول: ' . $product->id; } $sms->send(); } } |
توجه داشته باشید که این مقاله ، ممکن است در آینده به روز رسانی و تغییراتی را شامل شود. با این حال متد فهرست رویدادها یعنی getModuleEvents همیشه به روز خواهد بود و میتواند به فهرست رویدادها و متغیرهای آن اکتفا کرد.
در نهایت همکاران توسعه دهنده گرامی در صورت وجود هر گونه مشکل یا سوال ، میتوانید از طریق راههای ارتباطی موجود با ما ارتباط برقرار نمایید.
با احترام و آرزوی موفقیت.